raygeo.ops

Command sequence (Ops) manipulation for CNC motion control.

Ops is a container of ordered commands (move, line, arc, bezier, state changes like power/feed) that defines a complete machining job. It supports building sequences programmatically (move_to, line_to, arc_to, etc.), transforming them (translate, rotate, scale, transform with 4x4 matrices), clipping to rectangles or regions, linearizing curves, estimating processing time, and serializing to dict or numpy arrays for persistence.

The module also provides command-type enumerations (CommandType, CommandCategory, SectionType), machine State tracking (power, feed, coolant, air_assist, head_coolant, frequency), and an Axis bitflag for multi-axis machines.

CommandInfo

Detailed information about a single command in an Ops sequence.

Returned by Ops.inspect and provides the full set of parameters for any command type in a structured form.

air_assist

air_assist: Optional[state.AirAssistMode]

Air assist mode, if a SetAirAssist command.

center_offset

center_offset: Optional[tuple[float, float]]

Arc centre offset from start point, if an arc command.

clockwise

clockwise: Optional[bool]

Whether an arc is clockwise, if an arc command.

control

control: Optional[tuple[float, float, float]]

Quadratic-Bezier control point, if a quad. Bezier command.

control1

control1: Optional[tuple[float, float, float]]

First cubic-Bezier control point, if a Bezier command.

control2

control2: Optional[tuple[float, float, float]]

Second cubic-Bezier control point, if a Bezier command.

coolant

coolant: Optional[state.CoolantMode]

Coolant mode, if a SetCoolant command.

duration_ms

duration_ms: Optional[float]

Dwell duration in ms, if a dwell command.

end

end: Optional[tuple[float, float, float]]

Endpoint of the command in 3D space, if applicable.

extra_axes

extra_axes: Optional[dict]

Extra axis positions, if any.

feed_rate

feed_rate: Optional[int]

Feed rate setting, if a SetFeedRate command.

frequency

frequency: Optional[int]

Laser frequency (Hz), if a frequency-setting command.

head_coolant

head_coolant: Optional[state.HeadCoolantMode]

Head coolant mode, if a SetHeadCoolant command.

head_uid

head_uid: Optional[str]

Unique identifier of the active head, if a head-setting command.

layer_uid

layer_uid: Optional[str]

Unique identifier of the active layer, if a layer-start command.

power

power: Optional[float]

Power level (0–1), if a power-setting command.

power_values

power_values: Optional[bytes]

Per-step power byte values for scan-to commands.

pulse_width

pulse_width: Optional[float]

Laser pulse width (µs), if a pulse-width-setting command.

rapid_rate

rapid_rate: Optional[int]

Rapid rate setting, if a SetRapidRate command.

section_type

section_type: Optional[types.SectionType]

Section type, if a section marker.

spindle_rpm

spindle_rpm: Optional[int]

Spindle RPM, if a SetSpindleRpm command.

state

state: Optional[state.State]

State snapshot at this command, if present.

type_

type_: types.CommandType

The type of this command (e.g. Move, Line, Arc, Bezier, ScanTo, …).

workpiece_uid

workpiece_uid: Optional[str]

Unique identifier of the active workpiece, if a workpiece-start command.

Ops

A sequence of machining operations (commands).

Ops is a container of ordered commands that define a complete machining job. It supports building command sequences programmatically, transforming them, clipping, serializing, and more.

Use the builder methods (move_to, line_to, arc_to, etc.) to construct a sequence, or load from geometry/dict/numpy arrays.

last_move_to

last_move_to: tuple[float, float, float]

The last (x, y, z) endpoint from a MoveTo command.

scanline_count

scanline_count: int

Return the number of scanline commands in the sequence.

air_assist()

air_assist(idx: int) -> state.AirAssistMode

Get the air assist mode from a SetAirAssist command.

Raises: TypeError — If the command is not a SetAirAssist.

Parameter	Type	Description
idx	int	Command index.
Returns	state.AirAssistMode	The air assist mode.
Complexity		O(1) time, O(1) space

apply_bidir_scan_offset()

apply_bidir_scan_offset(offset_mm: float) -> None

Correct X misalignment between left-to-right and right-to-left raster passes.

For every raster pass (a MoveTo followed by a ScanLine), if the pass runs right-to-left, both the entry MoveTo and the ScanLine endpoint are shifted along X by offset_mm. Left-to-right passes are left untouched.

Parameter	Type	Description
offset_mm	float	Offset in millimeters to apply to RTL passes.
Returns	None
Complexity		O(n) time, O(n) space

Bidirectional scan offset correction

apply_lead_in_out()

apply_lead_in_out(lead_in_mm: float, lead_out_mm: float) -> None

Apply lead-in and lead-out to vector contour paths.

For each contour within a VECTOR_OUTLINE section, extends the toolpath with zero-power lead-in and lead-out segments along the tangent direction at the path start and end.

Parameter	Type	Description
lead_in_mm	float	Lead-in distance in millimeters.
lead_out_mm	float	Lead-out distance in millimeters.
Returns	None
Complexity		O(n) time, O(n) space

Lead-in and lead-out paths

apply_multipass()

apply_multipass(passes: int, z_step_down: float) -> None

Repeats the ops sequence multiple times, optionally stepping down the Z axis after each pass.

Parameter	Type	Description
passes	int	Total number of passes (must be >= 1).
z_step_down	float	Z distance to move down after each pass.
Returns	None
Complexity		O(n * passes) time, O(n * passes) space

Multi-pass with Z stepping

apply_overscan()

apply_overscan(distance_mm: float) -> None

Apply overscan to raster lines.

Extends raster line start/end points by distance_mm along the line direction, adding zero-power lead-in and lead-out segments for constant engraving velocity.

Parameter	Type	Description
distance_mm	float	Overscan distance in millimeters.
Returns	None
Complexity		O(n) time, O(n) space

Overscan applied to raster lines

apply_state()

apply_state(state: state.State) -> None

Emit the state commands needed to reach state.

Power is always emitted (default 0.0). All other fields are emitted only when set (non-None). Domain-neutral: does not decide what values to use, just emits them.

Parameter	Type	Description
state	state.State	The target state to apply.
Returns	None
Complexity		O(k) time where k = number of set fields, O(k) space

apply_tab_gaps()

apply_tab_gaps(clips: Sequence[tuple[float, float, float]]) -> None

Apply holding tabs as gaps in the toolpath.

For each clip point, the closest subpath is found and a gap of the specified width is cut at the nearest point on the path. Only VECTOR_OUTLINE sections are modified.

Parameter	Type	Description
clips	Sequence[tuple[float, float, float]]	List of (x, y, width) tuples defining tab positions.
Returns	None
Complexity		O(n * k) time, O(1) space where k is the number of tab clips

Tab operations on a rectangle

apply_tab_power()

apply_tab_power(
    clips: Sequence[tuple[float, float, float]],
    tab_power: float,
    original_power: float,
) -> None

Apply holding tabs by reducing power in tab regions.

Instead of cutting a gap, the power is lowered in the tab area so the material stays connected but weaker. Only VECTOR_OUTLINE sections are modified.

Parameter	Type	Description
clips	Sequence[tuple[float, float, float]]	List of (x, y, width) tuples defining tab positions.
tab_power	float	Power level inside tab regions (0.0–1.0).
original_power	float	Normal cutting power to restore after the tab.
Returns	None
Complexity		O(n * k) time, O(1) space where k is the number of tab clips

apply_transformers()

apply_transformers(
    transformers: Sequence[Any],
    progress_cb: Optional[Any] = None,
) -> None

Apply a batch of transformers in a single call.

The transformers list may contain any of the typed spec objects defined in raygeo.ops.transform (SmoothSpec, OptimizeSpec, MergeLinesSpec, OverscanSpec, LeadInOutSpec, MultiPassSpec, CropSpec, TabsSpec, BidirScanOffsetSpec). The transformers are sorted by execution phase (geometry refinement -> path interruption -> post-processing) and applied in order.

Raises: TypeError — If any element is not a known spec type.

Raises: RuntimeError — If the loop was cancelled.

Parameter	Type	Description
transformers	Sequence[Any]	List of typed spec objects.
progress_cb	Optional[Any] = None	Optional callable (progress, message) that also exposes an is_cancelled() method; called before each transformer. If is_cancelled() returns True the loop aborts before the next transformer.
Returns	None

arc_params()

arc_params(idx: int) -> tuple[float, float, bool]

Get the arc parameters (center offset i, j, and clockwise flag).

Raises: TypeError — If the command is not an ArcTo.

Parameter	Type	Description
idx	int	Command index.
Returns	tuple[float, float, bool]	(i, j, clockwise) tuple.
Complexity		O(1) time, O(1) space

arc_to()

arc_to(
    x: float,
    y: float,
    i: float,
    j: float,
    clockwise: bool = True,
    z: float = 0.0,
    extra: Optional[dict] = None,
) -> None

Add a circular arc to the given coordinates.

Parameter	Type	Description
x	float	End X coordinate.
y	float	End Y coordinate.
i	float	I offset from current point to arc center.
j	float	J offset from current point to arc center.
clockwise	bool = True	Whether the arc is clockwise (default True).
z	float = 0.0	End Z coordinate (default 0.0).
extra	Optional[dict] = None	Optional dict of extra axis values.
Returns	None
Complexity		O(1) time, O(1) space

bezier_params()

bezier_params(
    idx: int,
) -> tuple[tuple[float, float, float], tuple[float, float, float]]

Get the cubic bezier control points.

Raises: TypeError — If the command is not a BezierTo.

Parameter	Type	Description
idx	int	Command index.
Returns	tuple[tuple[float, float, float], tuple[float, float, float]]	((c1x, c1y, c1z), (c2x, c2y, c2z)) control points.
Complexity		O(1) time, O(1) space

bezier_to()

bezier_to(
    control1: tuple[float, float, float],
    control2: tuple[float, float, float],
    end: tuple[float, float, float],
    extra: Optional[dict] = None,
) -> None

Add a cubic bezier curve to the given endpoint.

Parameter	Type	Description
control1	tuple[float, float, float]	First control point (x, y, z).
control2	tuple[float, float, float]	Second control point (x, y, z).
end	tuple[float, float, float]	End point (x, y, z).
extra	Optional[dict] = None	Optional dict of extra axis values.
Returns	None
Complexity		O(1) time, O(1) space

category()

category(idx: int) -> types.CommandCategory

Get the CommandCategory at the given index.

Parameter	Type	Description
idx	int	Command index (negative = from end).
Returns	types.CommandCategory	The category (MOVING, STATE, or MARKER).
Complexity		O(1) time, O(1) space

clear()

clear() -> None

Remove all commands from this Ops sequence.

Parameter	Type	Description
Returns	None
Complexity		O(1) time, O(1) space

clip_at()

clip_at(x: float, y: float, width: float) -> bool

Clip at a single vertical swath, keeping commands that intersect the band.

Parameter	Type	Description
x	float	X coordinate of the left edge.
y	float	Y coordinate (used to find the relevant segment).
width	float	Width of the band.
Returns	bool	True if any commands were kept.
Complexity		O(n) time, O(1) space

clip_ops_to_regions()

clip_ops_to_regions(
    regions: Sequence[Sequence[tuple[float, float]]],
    tolerance: float = 0.3,
) -> None

Clip paths using polygonal regions as boundaries; keeps what is inside.

Parameter	Type	Description
regions	Sequence[Sequence[tuple[float, float]]]	List of polygons, each being a list of (x, y) vertices.
tolerance	float = 0.3	Approximation tolerance (default 0.3).
Returns	None
Complexity		O(n * m) time, O(n) space where m is the number of polygon vertices

clip_rect()

clip_rect(rect: tuple[float, float, float, float]) -> Ops

Clip this sequence to a rectangle, keeping only commands inside.

Parameter	Type	Description
rect	tuple[float, float, float, float]	(x_min, y_min, x_max, y_max).
Returns	Ops	A new Ops sequence containing the clipped commands.
Complexity		O(n) time, O(n) space

Ops paths clipped to a rectangle

clip_to_regions()

clip_to_regions(
    regions: Sequence[Sequence[tuple[float, float]]],
    tolerance: float = 0.3,
) -> None

Clip paths to the given polygonal regions, keeping only what is inside.

Parameter	Type	Description
regions	Sequence[Sequence[tuple[float, float]]]	List of polygons, each being a list of (x, y) vertices.
tolerance	float = 0.3	Approximation tolerance (default 0.3).
Returns	None
Complexity		O(n * m) time, O(n) space where m is the number of polygon vertices

close_path()

close_path() -> None

Close the current sub-path by adding a line back to the start.

Parameter	Type	Description
Returns	None
Complexity		O(1) time, O(1) space

command_type()

command_type(idx: int) -> types.CommandType

Get the CommandType at the given index.

Parameter	Type	Description
idx	int	Command index (negative = from end).
Returns	types.CommandType	The CommandType of the command.
Complexity		O(1) time, O(1) space

coolant()

coolant(idx: int) -> state.CoolantMode

Get the coolant mode from a SetCoolant command.

Raises: TypeError — If the command is not a SetCoolant.

Parameter	Type	Description
idx	int	Command index.
Returns	state.CoolantMode	The coolant mode.
Complexity		O(1) time, O(1) space

copy()

copy() -> Ops

Return a deep copy of this Ops sequence.

Parameter	Type	Description
Returns	Ops	A new Ops instance.
Complexity		O(n) time, O(n) space

copy_command_from()

copy_command_from(source: Ops, idx: int) -> None

Copy a single command from another Ops sequence into this one.

Parameter	Type	Description
source	Ops	The source Ops sequence.
idx	int	Index of the command to copy.
Returns	None
Complexity		O(1) time, O(1) space

count_cutting()

count_cutting() -> int

Return the number of cutting commands in this sequence.

Counts all LineTo, ArcTo, BezierTo, QuadraticBezierTo, and ScanLine commands.

Parameter	Type	Description
Returns	int	Number of cutting commands.
Complexity		O(n) time, O(1) space

count_travel()

count_travel() -> int

Return the number of travel (MoveTo) commands in this sequence.

Parameter	Type	Description
Returns	int	Number of travel commands.
Complexity		O(n) time, O(1) space

cut_distance()

cut_distance() -> float

Compute the total cutting distance (excluding travel moves).

Parameter	Type	Description
Returns	float	Total cut distance in mm.
Complexity		O(n) time, O(1) space

distance()

distance() -> float

Compute the total distance of all commands.

Parameter	Type	Description
Returns	float	Total path distance in mm.
Complexity		O(n) time, O(1) space

distance_at()

distance_at(
    idx: int,
    last_point: Optional[tuple[float, float, float]] = None,
) -> float

Compute the distance traveled up to command idx.

Parameter	Type	Description
idx	int	Command index.
last_point	Optional[tuple[float, float, float]] = None	Optional starting point override.
Returns	float	Cumulative distance.
Complexity		O(1) time, O(1) space

dump()

dump() -> None

Print a human-readable dump of all commands.

Parameter	Type	Description
Returns	None
Complexity		O(n) time, O(n) space

dwell()

dwell(duration_ms: float) -> None

Pause execution for a given duration.

Parameter	Type	Description
duration_ms	float	Dwell duration in milliseconds.
Returns	None
Complexity		O(1) time, O(1) space

dwell_duration()

dwell_duration(idx: int) -> float

Get the duration (milliseconds) of a Dwell command.

Raises: TypeError — If the command is not a Dwell.

Parameter	Type	Description
idx	int	Command index.
Returns	float	Duration in milliseconds.
Complexity		O(1) time, O(1) space

endpoint()

endpoint(idx: int) -> tuple[float, float, float]

Get the endpoint coordinates of a moving command.

Parameter	Type	Description
idx	int	Command index (negative = from end).
Returns	tuple[float, float, float]	(x, y, z) tuple.
Complexity		O(1) time, O(1) space

estimate_command_times()

estimate_command_times(
    default_feed_rate: float = 1000.0,
    default_rapid_rate: float = 3000.0,
    acceleration: float = 1000.0,
) -> list[float]

Estimate the time of each individual command in the sequence.

Returns a list with one entry per command. Moving commands (MoveTo, LineTo, ArcTo, etc.) yield their estimated execution time in seconds. Non-moving commands (state changes, markers) yield 0.0.

Parameter	Type	Description
default_feed_rate	float = 1000.0	Default feed rate (default 1000.0).
default_rapid_rate	float = 3000.0	Default rapid rate (default 3000.0).
acceleration	float = 1000.0	Acceleration value (default 1000.0).
Returns	list[float]	List of estimated times in seconds, one per command.
Complexity		O(n) time, O(n) space

estimate_time()

estimate_time(
    default_feed_rate: float = 1000.0,
    default_rapid_rate: float = 3000.0,
    acceleration: float = 1000.0,
) -> float

Estimate the total processing time for this sequence.

Parameter	Type	Description
default_feed_rate	float = 1000.0	Default feed rate (default 1000.0).
default_rapid_rate	float = 3000.0	Default rapid rate (default 3000.0).
acceleration	float = 1000.0	Acceleration value (default 1000.0).
Returns	float	Estimated time in seconds.
Complexity		O(n) time, O(1) space

extend()

extend(other: Optional[Ops]) -> None

Extend this Ops sequence with commands from another.

Parameter	Type	Description
other	Optional[Ops]	The other Ops sequence (or None for no-op).
Returns	None
Complexity		O(n) time, O(n) space

extra_axes()

extra_axes(idx: int) -> Optional[dict]

Get the extra axes data for a moving command.

Parameter	Type	Description
idx	int	Command index.
Returns	Optional[dict]	Dict mapping axis names to values, or None.
Complexity		O(1) time, O(1) space

flip_ops()

flip_ops() -> Ops

Reverse the order of subpaths.

Parameter	Type	Description
Returns	Ops	A new Ops with subpath order reversed.
Complexity		O(n) time, O(n) space

frequency()

frequency(idx: int) -> int

Get the frequency of a SetFrequency command.

Raises: TypeError — If the command is not a SetFrequency.

Parameter	Type	Description
idx	int	Command index.
Returns	int	Frequency in Hz.
Complexity		O(1) time, O(1) space

from_dict()

@classmethod from_dict(data: dict) -> Ops

Create an Ops sequence from a dictionary.

Parameter	Type	Description
data	dict	Dictionary as produced by to_dict.
Returns	Ops	A new Ops instance.
Complexity		O(n) time, O(n) space

from_geometry()

@classmethod from_geometry(geometry: geo.Geometry) -> Ops

Create an Ops sequence from a Geometry.

Parameter	Type	Description
geometry	geo.Geometry	The geometry to convert.
Returns	Ops	A new Ops instance.
Complexity		O(n) time, O(n) space

from_mask_lines()

from_mask_lines(
    mask: Any,
    pixels_per_mm: tuple[float, float],
    offset_x_mm: float,
    offset_y_mm: float,
    line_interval_mm: float,
    z: float = 0.0,
    angle: float = 0.0,
    scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED,
) -> Ops

Rasterise a binary mask into line-to commands (no power).

Similar to from_mask_scan but emits move-to/line-to commands with a Z offset instead of scan-to with power values. Useful for simple contour or hatch patterns.

Parameter	Type	Description
mask	Any	2-D binary mask array.
pixels_per_mm	tuple[float, float]	(x, y) pixel density in px/mm.
offset_x_mm	float	Global X offset in mm.
offset_y_mm	float	Global Y offset in mm.
line_interval_mm	float	Spacing between scan lines in mm.
z	float = 0.0	Z offset for the lines in mm.
angle	float = 0.0	Scan angle in degrees.
scan_mode	scan.ScanMode = scan.ScanMode.SEGMENTED	ScanMode.SEGMENTED or ScanMode.FULL_SWEEP.
Returns	Ops	A new Ops container.
Complexity		O(h * w + n * p) where h, w = image dimensions, n = scan lines, p = pixels per line

from_mask_scan()

from_mask_scan(
    mask: Any,
    pixels_per_mm: tuple[float, float],
    offset_x_mm: float,
    offset_y_mm: float,
    line_interval_mm: float,
    step_power: float = 1.0,
    angle: float = 0.0,
    scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED,
) -> Ops

Rasterise a binary mask into scan-to commands.

Generates scan lines covering the mask's bounding box, samples the mask along each line, and emits move-to/scan-to commands for each non-zero segment (or the full sweep).

Parameter	Type	Description
mask	Any	2-D binary mask array.
pixels_per_mm	tuple[float, float]	(x, y) pixel density in px/mm.
offset_x_mm	float	Global X offset in mm.
offset_y_mm	float	Global Y offset in mm.
line_interval_mm	float	Spacing between scan lines in mm.
step_power	float = 1.0	Power value (0-1) for exposed pixels.
angle	float = 0.0	Scan angle in degrees.
scan_mode	scan.ScanMode = scan.ScanMode.SEGMENTED	ScanMode.SEGMENTED or ScanMode.FULL_SWEEP.
Returns	Ops	A new Ops container.
Complexity		O(h * w + n * p) where h, w = image dimensions, n = scan lines, p = pixels per line

from_multi_pass_image()

from_multi_pass_image(
    gray_image: Any,
    pixels_per_mm: tuple[float, float],
    offset_x_mm: float,
    offset_y_mm: float,
    line_interval_mm: float,
    num_depth_levels: int,
    z_step_down: float,
    angle: float = 0.0,
    angle_increment: float = 0.0,
    scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED,
) -> Ops

Rasterise a grayscale image as multiple Z-depth passes.

Decomposes the grayscale image into num_depth_levels layers by depth-slicing, then rasterises each layer with a progressive Z offset and optional per-pass angle increment.

Parameter	Type	Description
gray_image	Any	2-D grayscale image (0 = black, 255 = white).
pixels_per_mm	tuple[float, float]	(x, y) pixel density in px/mm.
offset_x_mm	float	Global X offset in mm.
offset_y_mm	float	Global Y offset in mm.
line_interval_mm	float	Spacing between scan lines in mm.
num_depth_levels	int	Number of depth layers to produce.
z_step_down	float	Z decrement per depth layer in mm.
angle	float = 0.0	Initial scan angle in degrees.
angle_increment	float = 0.0	Angle added per depth layer in degrees.
scan_mode	scan.ScanMode = scan.ScanMode.SEGMENTED	ScanMode.SEGMENTED or ScanMode.FULL_SWEEP.
Returns	Ops	A new Ops container.
Complexity		O(d * (h * w + n * p)) where d = depth levels, h, w = image dims, n = scan lines, p = pixels per line

from_numpy_arrays()

@classmethod from_numpy_arrays(arrays: dict) -> Ops

Create an Ops sequence from numpy arrays.

Parameter	Type	Description
arrays	dict	Dictionary as produced by to_numpy_arrays.
Returns	Ops	A new Ops instance.
Complexity		O(n) time, O(n) space

from_polyline()

from_polyline(
    points: Sequence[tuple[float, float, float]],
    move_first: bool = True,
    state: Optional[state.State] = None,
) -> Ops

Build an Ops sequence from a 3-D polyline.

When move_first is True the first point is emitted as a MoveTo and subsequent points as LineTo. When move_first is False every point is emitted as a LineTo (useful for appending a polyline to an in-progress cut).

When state is provided, its commands (power, feed rate, etc.) are applied before the polyline points.

Parameter	Type	Description
points	Sequence[tuple[float, float, float]]	List of (x, y, z) tuples.
move_first	bool = True	Whether to emit the first point as a MoveTo.
state	Optional[state.State] = None	Optional machine state to apply before the path.
Returns	Ops	A new Ops instance.
Complexity		O(n) where n = number of points

Ops.from_polyline with move_first=True vs move_first=False

from_power_modulated_image()

from_power_modulated_image(
    gray_image: Any,
    alpha: Any,
    pixels_per_mm: tuple[float, float],
    offset_x_mm: float,
    offset_y_mm: float,
    line_interval_mm: float,
    sample_interval_mm: float,
    min_power: float = 0.0,
    max_power: float = 1.0,
    step_power: float = 1.0,
    num_power_levels: int = 256,
    angle: float = 0.0,
    scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED,
) -> Ops

Rasterise a grayscale image with power-modulated scans.

Samples the image along scan lines and computes per-pixel power values from the grayscale intensity and alpha channel, then emits move-to/scan-to commands with the modulated power.

Parameter	Type	Description
gray_image	Any	2-D grayscale image (0 = black, 255 = white).
alpha	Any	2-D alpha mask (0 = transparent/no emission).
pixels_per_mm	tuple[float, float]	(x, y) pixel density in px/mm.
offset_x_mm	float	Global X offset in mm.
offset_y_mm	float	Global Y offset in mm.
line_interval_mm	float	Spacing between scan lines in mm.
sample_interval_mm	float	Output sample spacing in mm.
min_power	float = 0.0	Minimum power fraction (for white pixels).
max_power	float = 1.0	Maximum power fraction (for black pixels).
step_power	float = 1.0	Global power multiplier.
num_power_levels	int = 256	Number of quantised power levels.
angle	float = 0.0	Scan angle in degrees.
scan_mode	scan.ScanMode = scan.ScanMode.SEGMENTED	ScanMode.SEGMENTED or ScanMode.FULL_SWEEP.
Returns	Ops	A new Ops container.
Complexity		O(h * w + n * p) where h, w = image dimensions, n = scan lines, p = pixels per line

get_frame()

get_frame(
    power: Optional[float] = None,
    feed_rate: Optional[float] = None,
) -> Ops

Extract a frame (first and last endpoints) from the sequence.

Parameter	Type	Description
power	Optional[float] = None	Laser power value (0.0 to 1.0).
feed_rate	Optional[float] = None	Optional feed rate to set on the frame commands.
Returns	Ops	A new Ops containing only the frame endpoints.
Complexity		O(n) time, O(n) space

group_by_auxiliary_state()

group_by_auxiliary_state() -> list[Ops]

Group contiguous commands with the same auxiliary state into separate Ops sequences.

Groups by continuity of auxiliary state (coolant, air_assist, head_coolant) only. For full parameter-regime grouping, use OpsSection.state_blocks with StateBlockStart/StateBlockEnd markers.

Parameter	Type	Description
Returns	list[Ops]	A list of Ops sequences grouped by auxiliary state continuity.
Complexity		O(n) time, O(n) space

head_coolant()

head_coolant(idx: int) -> state.HeadCoolantMode

Get the head coolant mode from a SetHeadCoolant command.

Raises: TypeError — If the command is not a SetHeadCoolant.

Parameter	Type	Description
idx	int	Command index.
Returns	state.HeadCoolantMode	The head coolant mode.
Complexity		O(1) time, O(1) space

head_uid()

head_uid(idx: int) -> str

Get the head UID from a SetHead command.

Raises: TypeError — If the command is not a SetHead.

Parameter	Type	Description
idx	int	Command index.
Returns	str	The head identifier.
Complexity		O(1) time, O(1) space

indices_of()

indices_of(ct: types.CommandType) -> list[int]

Return all indices where the command type matches ct.

Parameter	Type	Description
ct	types.CommandType	The CommandType to search for.
Returns	list[int]	List of matching command indices.
Complexity		O(n) time, O(n) space

inspect()

inspect(idx: int) -> CommandInfo

Return detailed information about a single command.

Parameter	Type	Description
idx	int	The command index.
Returns	CommandInfo	A CommandInfo object with type, endpoint, state, axes, etc.
Complexity		O(1) time, O(1) space

is_cutting()

is_cutting(idx: int) -> bool

Check whether the command at idx is a cutting move.

Parameter	Type	Description
idx	int	Command index.
Returns	bool	True if the command is a cutting move.
Complexity		O(1) time, O(1) space

is_empty()

is_empty() -> bool

Check if the ops sequence is empty.

Parameter	Type	Description
Returns	bool	True if the container is empty.
Complexity		O(1) time, O(1) space

is_marker()

is_marker(idx: int) -> bool

Check whether the command at idx is a marker command.

Parameter	Type	Description
idx	int	Command index.
Returns	bool	True if the command is a structural marker (JobStart, LayerStart, etc.).
Complexity		O(1) time, O(1) space

is_scanline()

is_scanline(idx: int) -> bool

Check whether the command at idx is a scanline command.

Parameter	Type	Description
idx	int	Command index.
Returns	bool	True if the command is a ScanLine power command.
Complexity		O(1) time, O(1) space

is_state()

is_state(idx: int) -> bool

Check whether the command at idx is a state command.

Parameter	Type	Description
idx	int	Command index.
Returns	bool	True if the command modifies machine state.
Complexity		O(1) time, O(1) space

is_travel()

is_travel(idx: int) -> bool

Check whether the command at idx is a travel (non-cutting) move.

Parameter	Type	Description
idx	int	Command index.
Returns	bool	True if the command is a travel move.
Complexity		O(1) time, O(1) space

job_end()

job_end() -> None

Mark the end of a job.

Parameter	Type	Description
Returns	None
Complexity		O(1) time, O(1) space

job_start()

job_start() -> None

Mark the start of a job.

Parameter	Type	Description
Returns	None
Complexity		O(1) time, O(1) space

layer_end()

layer_end(layer_uid: str) -> None

Mark the end of a layer.

Parameter	Type	Description
layer_uid	str	The layer identifier.
Returns	None
Complexity		O(1) time, O(1) space

layer_start()

layer_start(layer_uid: str) -> None

Mark the start of a layer.

Parameter	Type	Description
layer_uid	str	The layer identifier.
Returns	None
Complexity		O(1) time, O(1) space

layer_uid()

layer_uid(idx: int) -> str

Get the layer UID from a LayerStart or LayerEnd command.

Raises: TypeError — If the command is not a Layer command.

Parameter	Type	Description
idx	int	Command index.
Returns	str	The layer identifier.
Complexity		O(1) time, O(1) space

len()

len() -> int

Return the number of commands.

Parameter	Type	Description
Returns	int	Number of commands in the container.
Complexity		O(1) time, O(1) space

line_to()

line_to(
    x: float,
    y: float,
    z: float = 0.0,
    extra: Optional[dict] = None,
) -> None

Add a cutting line to the given coordinates.

Parameter	Type	Description
x	float	X coordinate.
y	float	Y coordinate.
z	float = 0.0	Z coordinate (default 0.0).
extra	Optional[dict] = None	Optional dict of extra axis values.
Returns	None
Complexity		O(1) time, O(1) space

linearize()

linearize(idx: int, start_point: tuple[float, float, float]) -> Ops

Decompose a curved command into linear segments.

Raises: TypeError — If the command at idx is not a curve or line type.

Parameter	Type	Description
idx	int	Index of the command to linearize.
start_point	tuple[float, float, float]	The (x, y, z) start point of the curve.
Returns	Ops	A new Ops containing the linearized sub-commands.
Complexity		O(n) time, O(n) space

linearize_all()

linearize_all() -> None

Replace all curved commands with linear approximations in-place.

Parameter	Type	Description
Returns	None
Complexity		O(n) time, O(n) space

linearize_arcs()

linearize_arcs() -> None

Replace only arc commands with linear approximations.

Parameter	Type	Description
Returns	None
Complexity		O(n) time, O(n) space

linearize_curves()

linearize_curves() -> None

Replace only bezier and quadratic bezier curves with linear approximations.

Parameter	Type	Description
Returns	None
Complexity		O(n) time, O(n) space

merge_overlapping_lines()

merge_overlapping_lines(tolerance: float) -> None

Merge overlapping line segments across all paths.

Detects line segments that are collinear and overlapping and replaces the covered sub-segments with travel moves to avoid cutting the same line twice.

Parameter	Type	Description
tolerance	float	Maximum distance for considering lines collinear.
Returns	None
Complexity		O(n log n) average time, O(n) space

Line merging before and after

move_to()

move_to(
    x: float,
    y: float,
    z: float = 0.0,
    extra: Optional[dict] = None,
) -> None

Add a rapid (non-cutting) move to the given coordinates.

Parameter	Type	Description
x	float	X coordinate.
y	float	Y coordinate.
z	float = 0.0	Z coordinate (default 0.0).
extra	Optional[dict] = None	Optional dict of extra axis values.
Returns	None
Complexity		O(1) time, O(1) space

ops_section_end()

ops_section_end(
    section_type: types.SectionType,
    *,
    raster_mode: Optional[types.RasterMode] = None,
) -> None

Mark the end of an ops section.

Raises: ValueError — If section_type is RasterFill without a raster_mode,

or VectorOutline with a raster_mode.

Parameter	Type	Description
section_type	types.SectionType	The type of section.
raster_mode	Optional[types.RasterMode]	Optional raster mode.
Returns	None
Complexity		O(1) time, O(1) space

ops_section_start()

ops_section_start(
    section_type: types.SectionType,
    workpiece_uid: str,
    *,
    raster_mode: Optional[types.RasterMode] = None,
) -> None

Mark the start of an ops section.

Raises: ValueError — If section_type is RasterFill without a raster_mode,

or VectorOutline with a raster_mode.

Parameter	Type	Description
section_type	types.SectionType	The type of section.
workpiece_uid	str	The workpiece identifier.
raster_mode	Optional[types.RasterMode]	Optional raster mode.
Returns	None
Complexity		O(1) time, O(1) space

optimize_travel()

optimize_travel(
    allow_flip: bool = True,
    preserve_first: bool = False,
    preserve_order: Sequence[str] = [],
    progress_cb: Optional[Any] = None,
) -> None

Optimize travel distance by reordering segments.

Performs two-level optimization: workpiece-level reordering (when workpiece markers are present) and segment-level nearest-neighbor + 2-opt refinement.

Parameter	Type	Description
allow_flip	bool = True	Whether to allow flipping subpaths.
preserve_first	bool = False	Keep the first workpiece in place.
preserve_order	Sequence[str] = []	Workpiece UIDs whose order to preserve.
progress_cb	Optional[Any] = None	Optional callable(progress, message).
Returns	None
Complexity		O(n²) average time, O(n) space

Travel path before and after optimization

power()

power(idx: int) -> float

Get the power level of a SetPower command.

Raises: TypeError — If the command is not a SetPower.

Parameter	Type	Description
idx	int	Command index.
Returns	float	Power level (0.0–1.0 typically).
Complexity		O(1) time, O(1) space

preload_state()

preload_state() -> None

Pre-compute and store the accumulated state at each moving command.

Parameter	Type	Description
Returns	None
Complexity		O(n) time, O(n) space

pulse_width()

pulse_width(idx: int) -> float

Get the pulse width of a SetPulseWidth command.

Raises: TypeError — If the command is not a SetPulseWidth.

Parameter	Type	Description
idx	int	Command index.
Returns	float	Pulse width in microseconds.
Complexity		O(1) time, O(1) space

quadratic_bezier_params()

quadratic_bezier_params(idx: int) -> tuple[float, float, float]

Get the quadratic bezier control point.

Raises: TypeError — If the command is not a QuadraticBezierTo.

Parameter	Type	Description
idx	int	Command index.
Returns	tuple[float, float, float]	(cx, cy, cz) control point.
Complexity		O(1) time, O(1) space

quadratic_bezier_to()

quadratic_bezier_to(
    control: tuple[float, float, float],
    end: tuple[float, float, float],
    extra: Optional[dict] = None,
) -> None

Add a quadratic bezier curve to the given endpoint.

Parameter	Type	Description
control	tuple[float, float, float]	Control point (x, y, z).
end	tuple[float, float, float]	End point (x, y, z).
extra	Optional[dict] = None	Optional dict of extra axis values.
Returns	None
Complexity		O(1) time, O(1) space

rate()

rate(idx: int) -> int

Get the feed/rapid rate from a SetFeedRate or SetRapidRate command.

Raises: TypeError — If the command is not a rate command.

Parameter	Type	Description
idx	int	Command index.
Returns	int	Rate in mm/s.
Complexity		O(1) time, O(1) space

rect()

rect(include_travel: bool = False) -> tuple[float, float, float, float]

Compute the bounding rectangle of all commands.

Parameter	Type	Description
include_travel	bool = False	Whether to include travel moves (default False).
Returns	tuple[float, float, float, float]	(x_min, y_min, x_max, y_max).
Complexity		O(n) time, O(1) space

replace_all()

replace_all(source: Ops) -> None

Replace all commands in this sequence with those from another.

Parameter	Type	Description
source	Ops	The source Ops sequence.
Returns	None
Complexity		O(n) time, O(n) space

replace_with()

replace_with(source: Ops) -> None

Replace the internal buffer of this sequence with a copy from another.

Parameter	Type	Description
source	Ops	The source Ops sequence.
Returns	None
Complexity		O(n) time, O(n) space

rotate()

rotate(angle_deg: float, cx: float, cy: float) -> None

Rotate all coordinates around a pivot point.

Parameter	Type	Description
angle_deg	float	Rotation angle in degrees.
cx	float	Pivot X coordinate.
cy	float	Pivot Y coordinate.
Returns	None
Complexity		O(n) time, O(1) space

scale()

scale(sx: float, sy: float, sz: float = 1.0) -> None

Scale all coordinates by the given factors.

Parameter	Type	Description
sx	float	X scale factor.
sy	float	Y scale factor.
sz	float = 1.0	Z scale factor (default 1.0).
Returns	None
Complexity		O(n) time, O(1) space

scan_to()

scan_to(
    x: float,
    y: float,
    z: float = 0.0,
    power_values: Optional[Sequence[int]] = None,
    extra: Optional[dict] = None,
) -> None

Add a scan-line move with per-pixel power values.

Parameter	Type	Description
x	float	End X coordinate.
y	float	End Y coordinate.
z	float = 0.0	End Z coordinate (default 0.0).
power_values	Optional[Sequence[int]] = None	Optional per-pixel 8-bit power values.
extra	Optional[dict] = None	Optional dict of extra axis values.
Returns	None
Complexity		O(1) time, O(1) space

scanline_data()

scanline_data(idx: int) -> bytes

Get the raw scanline power data for a scanline command.

Parameter	Type	Description
idx	int	Command index.
Returns	bytes	Raw bytes of scanline power data.
Complexity		O(1) time, O(1) space

section_content()

section_content(section: OpsSection) -> Ops

Extract the commands belonging to a section.

Parameter	Type	Description
section	OpsSection	The OpsSection to extract.
Returns	Ops	A new Ops containing only the content of that section.
Complexity		O(n) time, O(n) space

section_params()

section_params(
    idx: int,
) -> tuple[types.SectionType, Optional[str], Optional[types.RasterMode]]

Get the section type, optional workpiece UID, and optional raster mode from an OpsSection command.

Raises: TypeError — If the command is not an OpsSectionStart or OpsSectionEnd.

Parameter	Type	Description
idx	int	Command index.
Returns	tuple[types.SectionType, Optional[str], Optional[types.RasterMode]]	(SectionType, Optional[str], Optional[RasterMode]).
Complexity		O(1) time, O(1) space

section_ranges()

section_ranges() -> list[OpsSectionRange]

Return the section ranges of the ops as index ranges.

Similar to sections but returns contiguous index ranges instead of individual index lists.

Parameter	Type	Description
Returns	list[OpsSectionRange]	List of OpsSectionRange objects.
Complexity		O(n) time, O(n) space

sections()

sections() -> list[OpsSection]

Return the logical sections of the ops.

Sections are delimited by OpsSectionStart/OpsSectionEnd markers and group commands into vector-outline and raster-fill portions.

Parameter	Type	Description
Returns	list[OpsSection]	List of OpsSection objects.
Complexity		O(n) time, O(n) space

sections_by_mode()

sections_by_mode(raster_mode: types.RasterMode) -> list[OpsSection]

Return sections matching a given raster mode.

Parameter	Type	Description
raster_mode	types.RasterMode	The RasterMode to filter by.
Returns	list[OpsSection]	List of matching OpsSection objects.
Complexity		O(n) time, O(n) space

sections_by_type()

sections_by_type(section_type: types.SectionType) -> list[OpsSection]

Return sections matching a given section type.

Parameter	Type	Description
section_type	types.SectionType	The SectionType to filter by.
Returns	list[OpsSection]	List of matching OpsSection objects.
Complexity		O(n) time, O(n) space

segment_indices()

segment_indices() -> list[list[int]]

Return index ranges for each contiguous cutting segment.

Parameter	Type	Description
Returns	list[list[int]]	A list of index lists, one per segment.
Complexity		O(n) time, O(n) space

set_air_assist()

set_air_assist(mode: state.AirAssistMode) -> None

Set the air assist mode for subsequent commands.

Parameter	Type	Description
mode	state.AirAssistMode	Air assist mode.
Returns	None
Complexity		O(1) time, O(1) space

set_coolant()

set_coolant(mode: state.CoolantMode) -> None

Set the coolant mode for subsequent commands.

Parameter	Type	Description
mode	state.CoolantMode	Coolant mode.
Returns	None
Complexity		O(1) time, O(1) space

set_feed_rate()

set_feed_rate(feed_rate: float) -> None

Set the feed rate for subsequent commands.

Parameter	Type	Description
feed_rate	float	Feed rate in units per second.
Returns	None
Complexity		O(1) time, O(1) space

set_frequency()

set_frequency(frequency: int) -> None

Set the laser pulse frequency.

Parameter	Type	Description
frequency	int	Frequency in Hz.
Returns	None
Complexity		O(1) time, O(1) space

set_head()

set_head(head_uid: str) -> None

Switch to a specific head by UID.

Parameter	Type	Description
head_uid	str	The head identifier.
Returns	None
Complexity		O(1) time, O(1) space

set_head_coolant()

set_head_coolant(mode: state.HeadCoolantMode) -> None

Set the head coolant mode for subsequent commands.

Parameter	Type	Description
mode	state.HeadCoolantMode	Head coolant mode.
Returns	None
Complexity		O(1) time, O(1) space

set_power()

set_power(power: float) -> None

Set the cutting power for subsequent commands.

Parameter	Type	Description
power	float	Power level (0.0–1.0).
Returns	None
Complexity		O(1) time, O(1) space

set_pulse_width()

set_pulse_width(pulse_width: float) -> None

Set the laser pulse width.

Parameter	Type	Description
pulse_width	float	Pulse width in microseconds.
Returns	None
Complexity		O(1) time, O(1) space

set_rapid_rate()

set_rapid_rate(rapid_rate: float) -> None

Set the rapid (traverse) rate for subsequent commands.

Parameter	Type	Description
rapid_rate	float	Rapid rate in units per second.
Returns	None
Complexity		O(1) time, O(1) space

set_spindle_rpm()

set_spindle_rpm(rpm: int) -> None

Set the spindle RPM for subsequent commands.

Parameter	Type	Description
rpm	int	Spindle RPM.
Returns	None
Complexity		O(1) time, O(1) space

set_state_at()

set_state_at(idx: int, state: state.State) -> None

Overwrite the state at a specific command index.

Parameter	Type	Description
idx	int	The command index.
state	state.State	The new state.
Returns	None
Complexity		O(1) time, O(1) space

set_state_on_moving()

set_state_on_moving(state: state.State) -> None

Apply a state to all moving commands without an explicit state.

Parameter	Type	Description
state	state.State	The state to apply.
Returns	None
Complexity		O(n) time, O(1) space

smooth()

smooth(amount: int, corner_angle_threshold: float) -> None

Smooth all line-only segments using a Gaussian filter.

Arcs are linearized first. Segments containing curves are transferred unchanged. The smoothing operates in place.

Parameter	Type	Description
amount	int	Smoothing strength (0-100). 0 is a no-op.
corner_angle_threshold	float	Corners with an internal angle (in degrees) smaller than this are preserved.
Returns	None
Complexity		O(n * k) time, O(n) space where k is the kernel size

Gaussian smoothing applied to a square path

spindle_rpm()

spindle_rpm(idx: int) -> int

Get the spindle RPM from a SetSpindleRpm command.

Raises: TypeError — If the command is not a SetSpindleRpm.

Parameter	Type	Description
idx	int	Command index.
Returns	int	Spindle RPM.
Complexity		O(1) time, O(1) space

split_at()

split_at(command_type: Any) -> list[Ops]

Split the sequence at paired markers of the given type.

Returns a list of Ops sequences. Each matched start/end marker pair yields one Ops containing the markers and their content. Commands that fall outside any pair are returned as additional Ops segments, so concatenating all returned sequences reproduces the original.

Raises: ValueError — If command_type is not a supported start marker.

Parameter	Type	Description
command_type	Any	CommandType.LAYER_START, WORKPIECE_START, OPS_SECTION_START, or JOB_START.
Returns	list[Ops]	A list of Ops sequences.
Complexity		O(n) time, O(n) space

split_into_subpaths()

split_into_subpaths() -> list[Ops]

Split this Ops sequence into separate subpaths.

Parameter	Type	Description
Returns	list[Ops]	A list of Ops sequences, one per subpath.
Complexity		O(n) time, O(n) space

state()

state(idx: int) -> Optional[state.State]

Get the machine state stored on a command (if available).

Parameter	Type	Description
idx	int	Command index.
Returns	Optional[state.State]	The State at that index, or None.
Complexity		O(1) time, O(1) space

state_at()

state_at(idx: int) -> state.State

Return the accumulated state at a given command index.

Raises: IndexError — If the index is out of range.

Parameter	Type	Description
idx	int	The command index.
Returns	state.State	The state at that point.
Complexity		O(1) time, O(1) space

state_block_end()

state_block_end() -> None

Mark the end of a state block.

Parameter	Type	Description
Returns	None
Complexity		O(1) time, O(1) space

state_block_start()

state_block_start(name: Optional[str]) -> None

Mark the start of a state block.

Parameter	Type	Description
name	Optional[str]	Optional block name.
Returns	None
Complexity		O(1) time, O(1) space

state_blocks()

state_blocks() -> list[types.StateBlock]

Return all state blocks across all sections.

Raises: RuntimeError — If state block nesting is invalid.

Parameter	Type	Description
Returns	list[types.StateBlock]	List of StateBlock objects.
Complexity		O(n) time, O(n) space

sub_ops()

sub_ops(indices: Sequence[int]) -> Ops

Extract a subset of commands by index.

Parameter	Type	Description
indices	Sequence[int]	List of command indices to extract.
Returns	Ops	A new Ops sequence containing only the specified commands.
Complexity		O(n) time, O(n) space

subpath_indices()

subpath_indices() -> list[list[int]]

Return index ranges for each subpath.

Parameter	Type	Description
Returns	list[list[int]]	A list of index lists, one per subpath.
Complexity		O(n) time, O(n) space

subtract_regions()

subtract_regions(regions: Sequence[Sequence[tuple[float, float]]]) -> None

Subtract polygonal regions from the cutting paths.

Parameter	Type	Description
regions	Sequence[Sequence[tuple[float, float]]]	List of polygons, each being a list of (x, y) vertices.
Returns	None
Complexity		O(n * m) time, O(n) space where m is the number of polygon vertices

to_dict()

to_dict() -> dict

Serialize this Ops sequence to a dict suitable for JSON export.

Parameter	Type	Description
Returns	dict	A Python dict representation.
Complexity		O(n) time, O(n) space

to_gcode()

to_gcode(dialect: convert.GcodeDialectSpec, context_dict: dict) -> dict

Encode this Ops sequence into G-code text.

Takes a typed dialect specification and an encoding context as a plain dict (JSON-serialisable). Returns a dict with the G-code text and bidirectional op-to-line index maps.

Raises: ValueError — If deserialization fails.

Parameter	Type	Description
dialect	convert.GcodeDialectSpec	A raygeo.ops.convert.GcodeDialectSpec instance.
context_dict	dict	JSON-serialisable dict matching the Rust EncodeContext schema.
Returns	dict	{"text": str, "op_to_machine_code": {int: [int]}, "machine_code_to_op": {int: int}}

to_geometry()

to_geometry() -> geo.Geometry

Convert this Ops sequence back into a Geometry.

Parameter	Type	Description
Returns	geo.Geometry	A Geometry representing the same paths.
Complexity		O(n) time, O(n) space

to_numpy_arrays()

to_numpy_arrays() -> dict

Serialize this Ops sequence to numpy arrays.

Parameter	Type	Description
Returns	dict	A Python dict of numpy arrays.
Complexity		O(n) time, O(n) space

to_vertex_arrays()

to_vertex_arrays() -> Any

Encode all commands into GPU-friendly vertex arrays.

Returns four flat numpy arrays: (powered_vertices, powered_colors, travel_vertices, zero_power_vertices).

Powered vertices and colors are paired (2 vertices + 2 colors per segment). Travel and zero-power vertices are also paired (2 vertices per segment). All vertex data is 3-component (x, y, z); colors are 4-component (r, g, b, a).

Parameter	Type	Description
Returns	Any	Tuple of (powered_vertices[N,3], powered_colors[N,4], travel_vertices[M,3], zero_power_vertices[K,3]) as float32 arrays.
Complexity		O(n) time, O(n) space

transfer_command_from()

transfer_command_from(source: Ops, idx: int) -> None

Transfer (move) a single command from another Ops sequence into this one.

Parameter	Type	Description
source	Ops	The source Ops sequence.
idx	int	Index of the command to transfer.
Returns	None
Complexity		O(1) time, O(1) space

transform()

transform(matrix: geo.types.TransformMatrix) -> None

Apply a 4x4 affine transformation matrix to all geometry.

See geo.types.TransformMatrix for the matrix layout.

Parameter	Type	Description
matrix	geo.types.TransformMatrix	A 4x4 affine transformation matrix.
Returns	None
Complexity		O(n) time, O(n) space

transform_layers()

transform_layers(callback: Any) -> None

Transform each layer by calling a Python callback with the layer UID and ops.

The callback receives (layer_uid: str, layer_ops: Ops) and should mutate the layer_ops in place.

Parameter	Type	Description
callback	Any	A callable accepting (layer_uid, layer_ops).
Returns	None
Complexity		O(n) time, O(n) space

transform_moving()

transform_moving(on_endpoint: Any, on_aux_point: Optional[Any] = None) -> None

Transform moving commands by calling Python callbacks on each endpoint and aux point.

The on_endpoint callback receives (endpoint, extra_axes) and should mutate the endpoint list in-place. The optional on_aux_point callback receives control points for curve commands.

Parameter	Type	Description
on_endpoint	Any	Callable (endpoint, extra_axes) -> None.
on_aux_point	Optional[Any] = None	Optional callable (point,) -> None for curve control points.
Returns	None
Complexity		O(n) time, O(1) space

translate()

translate(dx: float, dy: float, dz: float = 0.0) -> None

Translate all moving commands by the given offset.

Parameter	Type	Description
dx	float	X offset.
dy	float	Y offset.
dz	float = 0.0	Z offset (default 0.0).
Returns	None
Complexity		O(n) time, O(1) space

translate_layers()

translate_layers(
    default_offset: tuple[float, float, float],
    layer_offsets: Optional[dict] = None,
) -> None

Translate each layer by its own offset, with a default fallback.

Parameter	Type	Description
default_offset	tuple[float, float, float]	The (x, y, z) offset for layers not listed in layer_offsets.
layer_offsets	Optional[dict] = None	Optional dict mapping layer UIDs to (x, y, z) offsets.
Returns	None
Complexity		O(n) time, O(1) space

without_state()

without_state() -> Ops

Return a copy with all state commands removed.

Parameter	Type	Description
Returns	Ops	A new Ops containing only moving commands.
Complexity		O(n) time, O(n) space

workpiece_end()

workpiece_end(workpiece_uid: str) -> None

Mark the end of a workpiece.

Parameter	Type	Description
workpiece_uid	str	The workpiece identifier.
Returns	None
Complexity		O(1) time, O(1) space

workpiece_start()

workpiece_start(workpiece_uid: str) -> None

Mark the start of a workpiece.

Parameter	Type	Description
workpiece_uid	str	The workpiece identifier.
Returns	None
Complexity		O(1) time, O(1) space

workpiece_uid()

workpiece_uid(idx: int) -> str

Get the workpiece UID from a WorkpieceStart or WorkpieceEnd command.

Raises: TypeError — If the command is not a Workpiece command.

Parameter	Type	Description
idx	int	Command index.
Returns	str	The workpiece identifier.
Complexity		O(1) time, O(1) space

OpsSection

A section of operations parsed into marker and content index groups.

Produced by Ops.sections when splitting an Ops sequence into logical sections based on OpsSectionStart/OpsSectionEnd markers.

content_indices

content_indices: list[int]

Indices of the content commands belonging to this section.

marker_indices

marker_indices: list[int]

Indices of the section-marker commands (start/end) for this section.

raster_mode

raster_mode: Optional[types.RasterMode]

The raster mode of this section, if any.

section_type

section_type: Optional[types.SectionType]

The type of this section (VectorOutline or RasterFill), if any.

content()

content(ops: Ops) -> Ops

Extract the content commands of this section from an Ops sequence.

Parameter	Type	Description
ops	Ops	The Ops sequence containing this section.
Returns	Ops	A new Ops containing only the content of this section.
Complexity		O(n) time, O(n) space

state_block_content()

state_block_content(ops: Ops, block: types.StateBlock) -> Ops

Extract a specific state block's content as Ops.

Parameter	Type	Description
ops	Ops	The parent Ops sequence.
block	types.StateBlock	The StateBlock to extract.
Returns	Ops	A new Ops containing only the block's content.
Complexity		O(n) time, O(n) space

state_blocks()

state_blocks(ops: Ops) -> list[types.StateBlock]

Return the state blocks within this section.

Raises: RuntimeError — If state block nesting is invalid.

Parameter	Type	Description
ops	Ops	The parent Ops sequence.
Returns	list[types.StateBlock]	List of StateBlock objects.
Complexity		O(n) time, O(n) space

state_blocks_by_name()

state_blocks_by_name(ops: Ops, pattern: str) -> list[types.StateBlock]

Find state blocks by name pattern (* prefix match or exact).

Raises: RuntimeError — If state block nesting is invalid.

Parameter	Type	Description
ops	Ops	The parent Ops sequence.
pattern	str	Name pattern ("cell-*" for prefix, "labels" for exact).
Returns	list[types.StateBlock]	List of matching StateBlock objects.
Complexity		O(n) time, O(n) space

OpsSectionRange

A contiguous range of indices that belong to a section.

Similar to OpsSection but stores start/end index ranges instead of individual index lists. Produced by Ops.section_ranges.

content_indices

content_indices: list[int]

Starting index of the content within this section range.

marker_indices

marker_indices: list[int]

Indices of the section-marker commands that bracket this range.

raster_mode

raster_mode: Optional[types.RasterMode]

The raster mode of this section range, if any.

section_type

section_type: Optional[types.SectionType]

The type of this section range (VectorOutline or RasterFill), if any.

content()

content(ops: Ops) -> Ops

Extract the content commands of this section range from an Ops sequence.

Extract the content commands of this section range from an Ops sequence.

Parameter	Type	Description
ops	Ops	The Ops sequence containing this section.
Returns	Ops	A new Ops containing only the content of this section range.
Complexity		O(n) time, O(n) space