s6.utils.waypoint_utils

Waypoint parsing and two-axis path generation utilities.

This module provides:

  • WaypointUtils to parse waypoints from simple text or JSONL files.

  • PathDriver to drive two robotic axes via the REST API client (s6.robotic.client.RoboticClient) and generate common motion patterns (grid, square spiral, circular spiral, random micro-steps).

All distances and offsets are expressed in axis distance units (e.g., mm) as used by s6.robotic.stepper. Generators yield s6.schema.primitives.Vector2D where indicated.

class s6.utils.waypoint_utils.WaypointUtils

Bases: object

Parse waypoint files in plain-text or JSONL formats.

Each waypoint is a pair (x, y) representing a 2D offset/position.

classmethod parse_txt(file_path: str) → List[Tuple[float, float]]

Parse a whitespace/comma-delimited text file of x y pairs.

Each non-empty, non-comment line contains two numbers separated by whitespace or a comma. Lines beginning with # and empty lines are ignored.

Parameters:

file_path (str) – Path to a text file.

Returns:

Sequence of (x, y) pairs.

Return type:

list of tuple[float, float]

Raises:

ValueError – If a line has invalid format or non-numeric values.

classmethod parse_jsonl(file_path: str) → List[Tuple[float, float]]

Parse a JSONL file of objects with {"x": ..., "y": ...}.

Empty lines are ignored. Each line must parse to a JSON object with numeric x and y fields.

Parameters:

file_path (str) – Path to a JSON lines file.

Returns:

Sequence of (x, y) pairs.

Return type:

list of tuple[float, float]

Raises:

ValueError – If a line cannot be parsed as JSON or lacks required fields.

classmethod parse_file(file_path: str) → List[Tuple[float, float]]

Parse a waypoint file by extension.

Parameters:

file_path (str) – Path to a file ending with .txt or .jsonl.

Returns:

Sequence of (x, y) pairs.

Return type:

list of tuple[float, float]

Raises:

ValueError – If the file extension is not supported.

class s6.utils.waypoint_utils.PathDriver(rpc_host: str = '10.20.0.2', rpc_port: int = 8000)

Bases: object

High-level two-axis driver for grid/spiral/random patterns.

Uses s6.robotic.client.RoboticClient to send motion commands to the running REST API. Maintains a simple internal target position used as the origin for relative patterns.

property current: Tuple[float, float]

Return the current target coordinates (x, y) in axis units.

move(x: float, y: float) → None

Move to an absolute position by zeroing then applying offsets.

Parameters:

  • x (float) – Target coordinates in axis distance units. Values are rounded to integers for the underlying client calls.

  • y (float) – Target coordinates in axis distance units. Values are rounded to integers for the underlying client calls.

zero() → None

Zero both axes and reset the internal position to (0, 0).

to_waypoint(name: str) → None

Move to a named waypoint defined in configuration.

Parameters:

name (str) – Waypoint identifier. The internal current is not modified.

grid(nx: int, ny: int, dx: float, dy: float)

Yield a grid sweep of nx × ny points, spaced by dx, dy.

Starting at the current position, this generates a serpentine scan over a rectangle centered at the origin of the grid. Motion commands are relative; axes are not zeroed.

Parameters:

  • nx (int) – Number of samples along x and y.

  • ny (int) – Number of samples along x and y.

  • dx (float) – Spacing between adjacent samples in axis units.

  • dy (float) – Spacing between adjacent samples in axis units.

Yields:

Vector2D – Each visited coordinate in grid order.

spiral(step_size: float = 1.0, max_radius: float | None = None)

Yield an outward square spiral from the current position.

Parameters:

  • step_size (float, default 1.0) – Distance per step along each leg.

  • max_radius (float, optional) – If provided, stop once the Euclidean distance from the start exceeds this radius.

Yields:

Vector2D – Each visited coordinate.

circular_spiral(step_size: float = 0.1, max_radius: float | None = None, dtheta: float = 0.05)

Yield an outward circular (Archimedean) spiral.

Parameters:

  • step_size (float, default 0.1) – Radial growth per revolution (b in r = b * theta).

  • max_radius (float, optional) – Maximum radius at which to stop emission.

  • dtheta (float, default 0.05) – Angular increment in radians per step.

Yields:

Vector2D – Each visited coordinate along the spiral.

list_waypoints()

Fetch the list of named waypoints from the server.

Returns:

Each item contains keys name and positions.

Return type:

list of dict

random(r: float, repeat: int, waypoint: str | None = None, max_step_size: Vector2D | Tuple[float, float] | None = (0.5, 0.5))

Randomly explore a disc of radius r around a named waypoint.

The driver first moves to waypoint. For each trial, it samples a random offset inside the disc and either moves in micro-steps (bounded by max_step_size per axis) or performs a single jump. It then returns to the waypoint before the next trial.

Parameters:

  • r (float) – Disc radius in axis units.

  • repeat (int) – Number of random targets to sample.

  • waypoint (str, optional) – Name of a waypoint to use as the center. Must exist on the server.

  • max_step_size (Vector2D or (float, float), default (0.5, 0.5)) – Maximum per-step delta along x and y when micro-stepping. If None, performs a single jump to each target.

Yields:

Vector2D – When micro-stepping, yields the cumulative offset from center after each micro-step (forward and return). When jumping, yields the full random offset.

Raises:

ValueError – If the waypoint is not found on the server.