# box_detections

Python API: `depthai_nodes.message.box_detections`

Per-frame box detections, before any measurement.

## Classes

### BoxDetection

A tracked box's identity and location in one processed frame.

Its segmentation is the region of the owning
[BoxDetections](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/box_detections.md)
mask labelled with this item's index.

Raises

 * `TypeError`: If a field has the wrong type.
 * `ValueError`: If `confidence` is not finite.

#### Attributes

##### bounding_box

Normalized bounding box in the source frame.

##### confidence

Detection confidence.

##### track_id

Tracker ID of the box.

##### track_status

Tracking status of the box in this frame, `NEW` or `TRACKED`. Lost tracks keep only their last-seen box, so they are not emitted.

### BoxDetections

Box detections sharing one segmentation label mask.

The mask covers the whole source frame, stretched to its own resolution. A pixel value is the index of the item it belongs to; 255
is background.

At most `MAX_DETECTIONS` (255) items fit, since label 255 is background. The mask is checked against the items only at
construction. Assigning `items`, `append()` and `extend()` do not recheck it.

Parameters

 * `items`: Detections, indexed by the mask labels.
 * `segmentation_mask`: 2-D `uint8` label mask.

Raises

 * `TypeError`: If `segmentation_mask` is not a numpy array, or `items` is not a list of one type.
 * `ValueError`: If `segmentation_mask` is not a 2-D `uint8` array, a label does not index an item, or there are more than
   `MAX_DETECTIONS` items.

#### Methods

##### init

```python
def __init__(items: list[BoxDetection], segmentation_mask: np.ndarray):
```

Initialize the detections and check the mask against them.

Parameters

 * `items` (`list[BoxDetection]`): Detections, indexed by the mask labels.
 * `segmentation_mask` (`np.ndarray`): 2-D `uint8` label mask; 255 is background.

Raises

 * `TypeError`: If `segmentation_mask` is not a numpy array, or `items` is not a list of one type.
 * `ValueError`: If `segmentation_mask` is not a 2-D `uint8` array, a label does not index an item, or there are more than
   `MAX_DETECTIONS` items.

##### append

```python
def append(item: BoxDetection):
```

Append one detection.

Raises

 * `TypeError`: If the item is not a `BoxDetection`.
 * `ValueError`: If the collection already holds `MAX_DETECTIONS` items.

##### getMask

```python
def getMask(index: int) -> np.ndarray:
```

Return the segmentation mask of one detection.

Parameters

 * `index` (`int`): Index of the detection in `items`.

Returns

 * `np.ndarray`: Boolean mask, `True` where the pixel belongs to the detection.

Raises

 * `IndexError`: If `index` is outside `items`.

##### getVisualizationMessage

```python
def getVisualizationMessage(self) -> dai.ImgAnnotations:
```

Outline each box, labelled with its track ID and confidence.

Returns

 * `dai.ImgAnnotations`: Annotations with this message's timestamps and sequence number.

##### items.setter

```python
def items.setter(value: list[BoxDetection]):
```

Replace the detections after checking their count and types.

Raises

 * `TypeError`: If the value is not a list of one type.
 * `ValueError`: If there are more than `MAX_DETECTIONS` items.

#### Attributes

##### items

The detections, indexed by the mask labels.

##### segmentation_mask

The shared `uint8` label mask; 255 marks background.

## Attributes

### BACKGROUND_LABEL
