raygeo.ops.part.cleared_area

ClearedArea tracking a simulated raster toolpath — cleared fragments in blue, remaining red

ClearedArea tracking a simulated raster toolpath — cleared fragments in blue, remaining red

ClearedArea

`actionable_remaining()`

actionable_remaining(region: part.StockRegion, inset_distance: float) -> float

Uncleared area inside the actionable zone of the pocket.

The actionable zone is the boundary inset by inset_distance, with islands buffered by the same amount. Material outside this zone -- wall-band slivers thinner than inset_distance -- is excluded, so this metric can gate convergence on whether any actionable material remains.

inset_distance is typically step_length: slivers thinner than the per-step advance get skipped by the stepper, so they should not gate convergence.

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
`inset_distance`	`float`	Inset distance (mm) defining the actionable zone (boundary inset, islands buffered).
Returns	`float`	Actionable remaining area in mm2.

`begin_batch()`

begin_batch() -> None

Begin buffering single-segment expansions.

Subsequent calls to expand_batched are queued without a union. Call commit_batch to union all queued sweeps with the stored fragments in a single pass.

Calling this while a batch is already active is a no-op.

Parameter	Type	Description
Returns	`None`

Three segments via / , unioned in a single .

Three segments via begin_batch / expand_batched, unioned in a single commit_batch.

`bites()`

bites(
    region: part.StockRegion,
    step_over: float,
    tool_radius: float,
    simplify_tol: float,
) -> list[list[tuple[float, float]]]

Compute the "bites" — new material reachable by expanding the current frontier outward by step_over, clipping to the tool-centre envelope, and subtracting already-cleared portions.

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
`step_over`	`float`	Lateral step-over in mm.
`tool_radius`	`float`	Tool radius (mm) for computing the envelope.
`simplify_tol`	`float`	Tolerance in mm for frontier simplification.
Returns	`list[list[tuple[float, float]]]`	List of polygons representing the bite regions.
Complexity		O(n log n)

computes the expansible material reachable by expanding the frontier by .

bites computes the expansible material reachable by expanding the frontier by step_over.

`commit_batch()`

commit_batch() -> None

Union all buffered sweeps with stored fragments in a single pass, then rebuild the spatial grid.

After this call the batch is closed (the caller may start a new one).

Parameter	Type	Description
Returns	`None`

`commit_batch_local()`

commit_batch_local() -> None

Union only the buffered sweeps with nearby overlapping fragments, using the spatial grid to avoid touching distant fragments.

After this call the batch is closed (the caller may start a new one).

Parameter	Type	Description
Returns	`None`

Global vs local commit — only overlapping frags updated.

Global vs local commit — only overlapping frags updated.

`compact_if_needed()`

compact_if_needed(region: part.StockRegion, tol: float) -> None

Compact fragments if total vertex count exceeds the default threshold.

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
`tol`	`float`	Vertex simplification tolerance in mm.
Returns	`None`

`compact_if_needed_threshold()`

compact_if_needed_threshold(
    region: part.StockRegion,
    tol: float,
    threshold: int,
) -> None

Compact with an explicit vertex-count threshold.

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
`tol`	`float`	Vertex simplification tolerance in mm.
`threshold`	`int`	Vertex count threshold above which compaction is triggered.
Returns	`None`

`cut()`

cut(polygons: Sequence[Sequence[tuple[float, float]]]) -> None

Add pre-computed polygons to the cleared set.

Parameter	Type	Description
`polygons`	`Sequence[Sequence[tuple[float, float]]]`	List of polygons (each a list of `(x, y)` vertices) to add.
Returns	`None`
Complexity		O(n) where n = total vertices across all polygons

ClearedArea with bulk polygon insertion via — cleared region in blue, remaining area in red

ClearedArea with bulk polygon insertion via cut — cleared region in blue, remaining area in red

`cut_area()`

cut_area(
    c1: tuple[float, float],
    c2: tuple[float, float],
    radius: float,
) -> float

Incremental cut area when the tool moves from c1 to c2.

Computes the fresh material area inside the disk at c2 that is not already cleared (crescent area).

Parameter	Type	Description
`c1`	`tuple[float, float]`	Previous centre `(x, y)`.
`c2`	`tuple[float, float]`	Next centre `(x, y)`.
`radius`	`float`	Disk radius (mm).
Returns	`float`	Fresh cut area (mm2).

`cut_fast()`

cut_fast(
    polygons: Sequence[Sequence[tuple[float, float]]],
) -> list[list[tuple[float, float]]]

Add polygons, returning only the newly-added portion. Faster than cut when inputs don't overlap existing fragments (skips the full union).

         O(n) when inputs are disjoint from existing fragments

Parameter	Type	Description
`polygons`	`Sequence[Sequence[tuple[float, float]]]`	List of polygons to add.
Returns	`list[list[tuple[float, float]]]`	List of polygons representing the newly-added portion.
Complexity		O(n log n) worst case when union required,

adds polygons to the cleared area, returning only the newly-covered region (green).

cut_fast adds polygons to the cleared area, returning only the newly-covered region (green).

`envelope()`

envelope(
    region: part.StockRegion,
    tool_radius: float,
) -> list[list[tuple[float, float]]]

The tool-centre envelope (inset of boundary by tool_radius, minus islands).

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
`tool_radius`	`float`	Tool radius (mm).
Returns	`list[list[tuple[float, float]]]`	List of polygons representing the tool-centre envelope.

`expand()`

expand(path: Sequence[tuple[float, float]], radius: float) -> None

Sweep a disk along a polyline, adding the swept area to the cleared set.

Parameter	Type	Description
`path`	`Sequence[tuple[float, float]]`	List of `(x, y)` points forming the polyline.
`radius`	`float`	Disk radius (mm).
Returns	`None`
Complexity		O(n) where n = number of path points

expand: sweeping a disk along a multi-segment path enlarges the cleared area.

`expand_batched()`

expand_batched(
    prev: tuple[float, float],
    next: tuple[float, float],
    radius: float,
) -> None

Queue a single-segment expansion into the current batch.

The segment swept polygon is stored in the internal buffer. Does not perform a union until commit_batch is called.

.. warning::

Panics if `begin_batch` was not called first.

Parameter	Type	Description
`prev`	`tuple[float, float]`	Start point `(x, y)` of the segment.
`next`	`tuple[float, float]`	End point `(x, y)` of the segment.
`radius`	`float`	Disk radius (mm).
Returns	`None`

`expand_step()`

expand_step(
    prev: tuple[float, float],
    next: tuple[float, float],
    radius: float,
) -> None

Expand the cleared area by sweeping a disk of radius along a single segment from prev to next.

Parameter	Type	Description
`prev`	`tuple[float, float]`	Start point `(x, y)` of the segment.
`next`	`tuple[float, float]`	End point `(x, y)` of the segment.
`radius`	`float`	Disk radius (mm).
Returns	`None`

expand_step sweeps a disk from prev to next, enlarging the cleared area vs initial state.

`fragments()`

fragments() -> list[list[tuple[float, float]]]

Return the union of all polygons currently tracked as cleared.

Each fragment is a closed polygon (list of (x, y) vertices) representing an area that has already been cut. The fragment set grows as cut_fast or cut are called.

This is useful for inspecting which areas have been cleared.

Parameter	Type	Description
Returns	`list[list[tuple[float, float]]]`	List of polygons representing the cleared fragments.
Complexity		O(m) where m = number of fragments

`frontier()`

frontier(
    region: part.StockRegion,
    simplify_tol: float,
) -> list[list[tuple[float, float]]]

Return a unioned, simplified snapshot of the current outer boundary, clipped to the stock.

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
`simplify_tol`	`float`	Tolerance in mm for polyline simplification.
Returns	`list[list[tuple[float, float]]]`	List of polygons representing the outer boundary.
Complexity		O(n log n)

returns the outer boundary of the cleared area after merging overlapping fragments.

frontier returns the outer boundary of the cleared area after merging overlapping fragments.

`get_angular_engagement()`

get_angular_engagement(center: tuple[float, float], radius: float) -> float

Compute angular engagement by exact circle-polygon intersection.

Creates a disk polygon at center with radius, intersects it with all nearby cleared fragments, and returns the uncleared angular extent in [0, 2*pi].

Parameter	Type	Description
`center`	`tuple[float, float]`	Query point `(x, y)`.
`radius`	`float`	Disk radius (mm).
Returns	`float`	Uncleared angular extent (radians).

`get_point_engagement()`

get_point_engagement(
    center: tuple[float, float],
    radius: float,
) -> tuple[float, float, float]

Evaluate engagement at a point using the signed distance to this cleared area's boundary.

Parameter	Type	Description
`center`	`tuple[float, float]`	Query point `(x, y)`.
`radius`	`float`	Disk radius (mm).
Returns	`tuple[float, float, float]`	`(angle_rad, area, chord_depth)`.

`is_empty()`

is_empty() -> bool

True when no fragments have been recorded.

Parameter	Type	Description
Returns	`bool`	`True` if no fragments have been recorded.

`path_engagement()`

path_engagement(
    path: Sequence[tuple[float, float]],
    radius: float,
) -> list[tuple[float, float, float]]

Evaluate engagement along a polyline.

Parameter	Type	Description
`path`	`Sequence[tuple[float, float]]`	List of `(x, y)` points.
`radius`	`float`	Disk radius (mm).
Returns	`list[tuple[float, float, float]]`	List of `(angle, area, chord_depth)` tuples.

`query_window()`

query_window(
    bbox: tuple[float, float, float, float],
) -> list[list[tuple[float, float]]]

Return fragments whose bounding box overlaps the query window.

         k = output vertices

Parameter	Type	Description
`bbox`	`tuple[float, float, float, float]`	Bounding box `(x_min, y_min, x_max, y_max)`.
Returns	`list[list[tuple[float, float]]]`	Fragments intersecting the bounding box.
Complexity		O(m + k) where m = number of fragments,

returns only the cleared fragments whose bbox overlaps the query (green).

query_window returns only the cleared fragments whose bbox overlaps the query (green).

`remaining()`

remaining(region: part.StockRegion) -> list[list[tuple[float, float]]]

Subtract cleared fragments from the stock, returning the uncut portion.

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
Returns	`list[list[tuple[float, float]]]`	List of polygons representing the uncut portion.
Complexity		O(n * m) where n = stock vertices, m = fragments

subtracts cleared fragments from the boundary, returning the uncut region (red).

remaining subtracts cleared fragments from the boundary, returning the uncut region (red).

`remaining_area()`

remaining_area(region: part.StockRegion) -> float

Remaining uncut area (boundary minus islands minus cleared fragments). Only positive-area (CCW) polygons are counted, so island holes do not inflate the result.

Parameter	Type	Description
`region`	`part.StockRegion`	StockRegion defining the boundary and islands.
Returns	`float`	Remaining uncut area in mm2.

`signed_boundary_distance()`

signed_boundary_distance(x: float, y: float) -> float

Signed perpendicular distance to the nearest cleared boundary.

Returns positive when the point is outside the cleared area (in uncut material), negative when inside.

Parameter	Type	Description
`x`	`float`	X coordinate of the query point.
`y`	`float`	Y coordinate of the query point.
Returns	`float`	Signed distance in mm. `0.0` means exactly on the boundary.

Signed boundary distance around a cleared square: green = inside cleared, red = outside.

Signed boundary distance around a cleared square: green = inside cleared, red = outside.

`total_area()`

total_area() -> float

Total cleared area.

Parameter	Type	Description
Returns	`float`	Total cleared area in mm2.
Complexity		O(1)

ClearedArea​

actionable_remaining()​

begin_batch()​

bites()​

commit_batch()​

commit_batch_local()​

compact_if_needed()​

compact_if_needed_threshold()​

cut()​

cut_area()​

cut_fast()​

envelope()​

expand()​

expand_batched()​

expand_step()​

fragments()​

frontier()​

get_angular_engagement()​

get_point_engagement()​

is_empty()​

path_engagement()​

query_window()​

remaining()​

remaining_area()​

signed_boundary_distance()​

total_area()​