# support_plane_calibration

Python API: `depthai_nodes.message.support_plane_calibration`

Support plane calibration controls and results.

## Classes

### CalibrationOutcome

How a calibration attempt ended.

`SUCCEEDED` attempts found at least one candidate plane, `FAILED` attempts hit the attempt cap (`max_calibration_attempts` in the
calibrator's config) without one, and `CANCELLED` attempts were stopped.

#### Attributes

##### CANCELLED

##### FAILED

##### SUCCEEDED

### SupportPlaneCalibrationControl

A control message for `SupportPlaneCalibrator` carrying one command.

Create controls with
[start](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md),
[stop](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md),
[reset](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md)
and
[verify](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).
Like DepthAI's `DynamicCalibrationControl`, each control carries one command.

Parameters

 * `command`: One of the
   [Commands](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

Raises

 * `TypeError`: If `command` is not one of the
   [Commands](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

#### Classes

##### Commands

The commands a calibration control can carry.

###### Classes

####### Reset

Allow a new attempt after the previous one succeeded or failed.

####### Start

Begin an attempt unless one is running or awaits reset.

####### Stop

Cancel the running attempt and return to idle without reset.

####### Verify

Verify a plane on the next point cloud without affecting any attempt.

Raises

 * `TypeError`: If `plane` is not a
   [SupportPlane](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane.md).

######## Attributes

######### plane

The support plane to check.

#### Methods

##### init

```python
def __init__(command: Command):
```

Create a control carrying `command`.

Parameters

 * `command` (`Command`): One of the
   [Commands](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

Raises

 * `TypeError`: If `command` is not one of the
   [Commands](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

##### reset

```python
def reset(cls) -> SupportPlaneCalibrationControl:
```

Create a control that allows a new attempt after a finished one.

Returns

 * `SupportPlaneCalibrationControl`: A control carrying
   [Commands.Reset](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

##### start

```python
def start(cls) -> SupportPlaneCalibrationControl:
```

Create a control that begins a calibration attempt.

Returns

 * `SupportPlaneCalibrationControl`: A control carrying
   [Commands.Start](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

##### stop

```python
def stop(cls) -> SupportPlaneCalibrationControl:
```

Create a control that cancels the running attempt.

Returns

 * `SupportPlaneCalibrationControl`: A control carrying
   [Commands.Stop](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

##### verify

```python
def verify(plane: SupportPlane) -> SupportPlaneCalibrationControl:
```

Create a control that asks for a plane verification.

Parameters

 * `plane` (`SupportPlane`): The support plane to check.

Returns

 * `SupportPlaneCalibrationControl`: A control carrying
   [Commands.Verify](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

Raises

 * `TypeError`: If `plane` is not a
   [SupportPlane](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane.md).

#### Attributes

##### Command

Any of the
[Commands](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md).

##### command

The command this control carries.

### SupportPlaneCalibrationResult

The end of a calibration attempt.

A result has candidates exactly when calibration succeeded.

Parameters

 * `outcome`: How the attempt ended.
 * `candidates`: Support plane candidates.

Raises

 * `TypeError`: If an argument has the wrong type.
 * `ValueError`: If the result has candidates and did not succeed, or succeeded without candidates.

#### Methods

##### init

```python
def __init__(outcome: CalibrationOutcome, candidates: list[SupportPlaneCandidate] | tuple[SupportPlaneCandidate, ...]):
```

Create a result and check that its fields are consistent.

Parameters

 * `outcome` (`CalibrationOutcome`): How the attempt ended.
 * `candidates` (`list[SupportPlaneCandidate] | tuple[SupportPlaneCandidate, ...]`): Support plane candidates.

Raises

 * `TypeError`: If `outcome` is not a
   [CalibrationOutcome](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane_calibration.md),
   or `candidates` is not a list or tuple of
   [SupportPlaneCandidate](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane.md).
 * `ValueError`: If the result has candidates and did not succeed, or succeeded without candidates.

#### Attributes

##### candidates

Support plane candidates; empty unless calibration succeeded.

##### outcome

How the attempt ended.

### SupportPlaneVerificationResult

How a supplied plane fares against gravity and the current point cloud.

The plane is accepted when it passes the level test and enough of the sampled point cloud lies on it.

Parameters

 * `plane`: The checked support plane, as supplied.
 * `gravity_angle_deg`: Tilt of the plane from horizontal, in degrees, from 0 to 90.
 * `accepted`: Whether the plane was accepted.
 * `on_plane_ratio`: Share of sampled valid points on the plane, from 0 to 1, or `None` when too few were sampled to measure.

Raises

 * `TypeError`: If an argument has the wrong type.
 * `ValueError`: If an argument is out of range, or `accepted` is `True` with no `on_plane_ratio`.

#### Methods

##### init

```python
def __init__(plane: SupportPlane, gravity_angle_deg: float, accepted: bool | np.bool_, on_plane_ratio: float | None):
```

Create a verification result.

Parameters

 * `plane` (`SupportPlane`): The checked support plane, as supplied.
 * `gravity_angle_deg` (`float`): Tilt of the plane from horizontal, in degrees.
 * `accepted` (`bool | np.bool_`): Whether the plane passed the level test and had enough of the point cloud on it. A numpy
   `bool_` is stored as `bool`.
 * `on_plane_ratio` (`float | None`): The on-plane ratio from 0 to 1, or `None` when not measured.

Raises

 * `TypeError`: If `plane` is not a
   [SupportPlane](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/support_plane.md),
   `gravity_angle_deg` is not a real number, `accepted` is not a boolean, or `on_plane_ratio` is neither `None` nor a real number.
 * `ValueError`: If `gravity_angle_deg` is not finite, `on_plane_ratio` is not finite or outside 0 to 1, or `accepted` is `True`
   with no `on_plane_ratio`.

#### Attributes

##### accepted

Whether the plane passed the level test with enough of the cloud on it.

The plane is within `max_gravity_angle_deg` of level, below the camera within any configured camera height range, and has a
measured on-plane ratio of at least `min_on_plane_ratio`.

##### gravity_angle_deg

Tilt of the plane from horizontal, in degrees, from 0 to 90.

##### on_plane_ratio

Share of sampled valid points on the plane, or `None` if not measured.

A point is on the plane within the calibrator's `check_distance_mm`. `None` means too few valid points were sampled to measure.
This is not a candidate's inlier ratio.

##### plane

The checked support plane, as supplied.
