---
title: raygeo.ops.assembly.adaptive
sidebar_label: raygeo.ops.assembly.adaptive
---

## AdaptiveClearingSpec

Parameters for the adaptive-clearing assembler.

### `area_tolerance`

```python
area_tolerance: float
```

### `cut_direction`

```python
cut_direction: str
```

`"cw"` or `"ccw"`.

### `expansion_batch_size`

```python
expansion_batch_size: int
```

### `max_deflection_deg`

```python
max_deflection_deg: float
```

### `safe_z`

```python
safe_z: float
```

### `start_heading`

```python
start_heading: Optional[float]
```

### `start_pos`

```python
start_pos: Optional[tuple[float, float]]
```

Optional override start `(x, y)`.

### `step_length`

```python
step_length: float
```

### `step_over`

```python
step_over: float
```

### `target_z`

```python
target_z: float
```

### `tolerance`

```python
tolerance: float
```

### `tool_radius`

```python
tool_radius: float
```

### `trace_path`

```python
trace_path: Optional[str]
```

Optional path to write a binary trace file.

### `wall_margin`

```python
wall_margin: float
```

## ResumePointNotFoundError

Raised when all resume strategies fail to find an engagement point.

## RoutingError

Raised when all route strategies fail to find a path.

## Functions

### `adaptive_clearing()`

```python
adaptive_clearing(
    part: ops.part.Part,
    tool_radius: float = 3,
    step_over: float = 1.5,
    step_length: float = 0.6,
    target_z: float = -5,
    safe_z: float = 2,
    max_deflection_deg: float = 30,
    wall_margin: float = 0,
    area_tolerance: float = 1,
    cut_feed_rate: int = 1200,
    cut_power: float = 1,
    start_pos: tuple[float, float] | None = None,
    start_heading: float | None = None,
    expansion_batch_size: int = 20,
    profile: bool = False,
    cut_direction: str = 'ccw',
    trace_path: str | None = None,
    on_progress: Callable[[dict], None] | None = None,
    batch_size: int = 128,
) -> ops.assembly.AssemblyResult
```

Run forward-stepping adaptive clearing.

Starting from the pre-populated cleared area inside *part*, uses a constant-engagement stepping
solver to generate a continuous spiral toolpath from the seed clearing to the pocket wall.

The caller is responsible for populating the part's cleared area with the entry polygons before
calling this method, and prepending the entry Ops to the result.

| Parameter              | Type                                        | Description                                                                                                                       |
| ---------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `part`                 | `ops.part.Part`                             | The part whose `cleared` field tracks accumulated workpiece state and whose geometry defines the pocket boundary and islands.     |
| `tool_radius`          | `float = 3`                                 | Tool radius in mm (default 3.0).                                                                                                  |
| `step_over`            | `float = 1.5`                               | Step-over distance (default 1.5).                                                                                                 |
| `step_length`          | `float = 0.6`                               | Forward step length in mm (default 0.6).                                                                                          |
| `target_z`             | `float = -5`                                | Cutting Z height (default -5.0).                                                                                                  |
| `safe_z`               | `float = 2`                                 | Retract Z height for travel (default 2.0).                                                                                        |
| `max_deflection_deg`   | `float = 30`                                | Maximum steering deflection per step in degrees (default 30).                                                                     |
| `wall_margin`          | `float = 0`                                 | Extra clearance between tool and boundary (default 0.0).                                                                          |
| `area_tolerance`       | `float = 1`                                 | Stop when remaining uncut area drops below this threshold (default 1.0).                                                          |
| `cut_feed_rate`        | `int = 1200`                                | Feed rate for cutting moves (default 1200).                                                                                       |
| `cut_power`            | `float = 1`                                 | Laser power for cutting moves (0.0-1.0, default 1.0).                                                                             |
| `start_pos`            | `tuple[float, float] &#124; None = None`    | Initial tool position (x, y). When None, auto-detected from the cleared-area frontier.                                            |
| `start_heading`        | `float &#124; None = None`                  | Initial tool heading in radians. When None, auto-detected as the CCW tangent at start_pos.                                        |
| `expansion_batch_size` | `int = 20`                                  | Batch cleared-area expansions every N steps (default 20). Larger values improve performance but may slightly reduce path quality. |
| `profile`              | `bool = False`                              | Print a profiling report to stdout (default False).                                                                               |
| `cut_direction`        | `str = 'ccw'`                               | Rotational direction of all cutting moves. `"cw"` or `"ccw"` (default `"ccw"`).                                                   |
| `trace_path`           | `str &#124; None = None`                    | When set, write a per-step binary trace file for the Python inspector (debug builds only).                                        |
| `on_progress`          | `Callable[[dict], None] &#124; None = None` | Optional callback receiving progress dicts.                                                                                       |
| `batch_size`           | `int = 128`                                 | Ops batch size for on_progress (default 128).                                                                                     |
| _Returns_              | `ops.assembly.AssemblyResult`               | Ops with cutting commands (entry not included).                                                                                   |

![Circle-seed clearing in a square pocket with central island: seed, toolpath, and remaining.](images/ops-assembly-adaptive-adaptive-clearing-centre-island.png)

*Circle-seed clearing in a square pocket with central island: seed, toolpath, and remaining.*

![Narrow pocket — 3D toolpath view (left) and 2D top-down with seed/remaining overlay (right).](images/ops-assembly-adaptive-adaptive-clearing-narrow.png)

*Narrow pocket — 3D toolpath view (left) and 2D top-down with seed/remaining overlay (right).*

![Constant-engagement clearing cuts, MAT-routed travel links, coloured by progress.](images/ops-assembly-adaptive-adaptive-clearing-demo.png)

*Constant-engagement clearing cuts, MAT-routed travel links, coloured by progress.*

### `target_area_per_distance()`

```python
target_area_per_distance(
    radius: float,
    advance: float,
    step_length: float,
) -> float
```

Target cut-area per unit distance for the engagement solver.

| Parameter     | Type    | Description                    |
| ------------- | ------- | ------------------------------ |
| `radius`      | `float` | Tool radius in mm.             |
| `advance`     | `float` | Step-over distance in mm.      |
| `step_length` | `float` | Forward step length in mm.     |
| _Returns_     | `float` | Target area per distance (mm). |

![Left: area/distance vs advance for several step lengths. Right: vs step length for several advances.](images/ops-assembly-adaptive-target-area-curves.png)

*Left: area/distance vs advance for several step lengths. Right: vs step length for several
advances.*

![Two offset disks and a wall at x=R−advance: crescent beyond wall is fresh material.](images/ops-assembly-adaptive-target-area-geometry.png)

*Two offset disks and a wall at x=R−advance: crescent beyond wall is fresh material.*
