# gather_data

Python API: `depthai_nodes.node.gather_data`

## Classes

### GatherData

Threaded host node that groups (“gathers”) multiple data messages around a single reference message, matched by timestamp.

The node receives two input streams:

 * reference_input: reference messages (e.g., detections) that define a grouping key (timestamp) and determine how many data items
   should be gathered for that reference.
 * data_input: messages to be collected for the nearest reference timestamp within a tolerance derived from the camera FPS.

For each reference timestamp, the node waits until the number of gathered data messages equals `wait_count_fn(reference)`. Once
ready, it emits a `depthai_nodes.GatheredData` message containing the reference message and the gathered items.

The default `wait_count_fn` uses `len(reference.detections)`, which works out-of-the-box for messages that expose a `detections`
attribute (e.g. `dai.ImgDetections`).

> **Note**
> * Timestamp matching uses `Buffer.getTimestamp().total_seconds()` and a tolerance of `1 / (camera_fps * FPS_TOLERANCE_DIVISOR)`.
 * If `wait_count_fn(reference) == 0`, the node emits immediately for that reference (with an empty items list).
 * The node periodically polls inputs using `tryGet()` at a rate derived from `camera_fps` and `INPUT_CHECKS_PER_FPS`.

Inputs:

 * `_data_input : dai.Node.Input`: Stream of data messages to be gathered (type `TGathered`).
 * `_reference_input : dai.Node.Input`: Stream of reference messages used for grouping and deciding how many items to gather (type
   `TReference`).

Outputs:

 * `out : dai.Node.Output`: Emits `depthai_nodes.GatheredData` objects with: `reference_data` (the matched reference) and `items`
   (list of data).

#### Methods

##### init

```python
def __init__(self):
```

Initializes the GatherData node.

##### build

```python
def build(cameraFps: int, inputData: dai.Node.Output, inputReference: dai.Node.Output, waitCountFn: Callable[[TReference], int] | None = None) -> GatherData[TReference, TGathered]:
```

Connect the data and reference streams used for gathering.

Parameters

 * `cameraFps` (`int`): Camera frame rate used to derive timestamp matching tolerance and polling interval.
 * `inputData` (`dai.Node.Output`): Upstream output producing the data messages to gather.
 * `inputReference` (`dai.Node.Output`): Upstream output producing the reference messages.
 * `waitCountFn` (`Callable[[TReference], int] | None`): Optional callback returning the number of data messages expected for a
   given reference. If omitted, defaults to len(reference.detections).

Returns

 * `GatherData[TReference, TGathered]`: The configured node instance.

##### run

```python
def run(self):
```

Poll both inputs, match messages by timestamp, and emit ready groups.

##### setCameraFps

```python
def setCameraFps(fps: int):
```

Set the camera frame rate used for timestamp matching.

Parameters

 * `fps` (`int`): Positive camera frame rate used for matching tolerance and polling.

Raises

 * `ValueError`: If the frame rate is not positive.

##### setWaitCountFn

```python
def setWaitCountFn(fn: Callable[[TReference], int]):
```

Set the expected gathered-item count for each reference.

Parameters

 * `fn` (`Callable[[TReference], int]`): Callback accepting the reference message and returning the number of items to wait for. A
   count of zero emits an empty group immediately.

#### Attributes

##### FPS_TOLERANCE_DIVISOR

Divides the per-frame time interval to compute timestamp matching tolerance. Higher values make matching stricter.

##### INPUT_CHECKS_PER_FPS

Number of polling iterations per frame interval. Effective loop sleep is `1 / (INPUT_CHECKS_PER_FPS * camera_fps)`.

##### out

Return the gathered output stream.

### HasDetections

Protocol for references exposing a list of detections.

#### Attributes

##### detections

Return the detections used to derive the default wait count.

## Attributes

### TGathered

### TReference