# gather_data

Python API: `depthai_nodes.node.gather_data`

## 类

### GatherData

线程化的主机节点，它围绕单个参考消息（通过时间戳匹配）对多个数据消息进行分组（“收集”）。

该节点接收两个输入流：

 * reference_input：参考消息（例如，检测），它们定义了分组键（时间戳）并确定应为该参考收集多少数据项。
 * data_input：要为相机 FPS 派生的容差范围内最近的参考时间戳收集的消息。

对于每个参考时间戳，节点会等待，直到收集到的数据消息数量等于 `wait_count_fn(reference)`。一旦准备就绪，它会发出一个 `depthai_nodes.GatheredData` 消息，其中包含参考消息和收集到的项。

默认的 `wait_count_fn` 使用 `len(reference.detections)`，这对于公开 `detections` 属性的消息（例如 `dai.ImgDetections`）开箱即用。

> **注意**
> * 时间戳匹配使用 `Buffer.getTimestamp().total_seconds()` 和 `1 / (camera_fps * FPS_TOLERANCE_DIVISOR)` 的容差。
 * 如果 `wait_count_fn(reference) == 0`，则节点会立即为该参考发出（带有一个空的项目列表）。
 * 节点以 `camera_fps` 和 `INPUT_CHECKS_PER_FPS` 派生的速率使用 `tryGet()` 定期轮询输入。

输入：

 * `_data_input : dai.Node.Input`：要收集的数据消息流（类型 `TGathered`）。
 * `_reference_input : dai.Node.Input`：用于分组和决定收集多少项的参考消息流（类型 `TReference`）。

输出：

 * `out : dai.Node.Output`：发出 `depthai_nodes.GatheredData` 对象，其中包含：`reference_data`（匹配的参考）和 `items`（数据列表）。

#### 方法

##### init

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

初始化 GatherData 节点。

##### build

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

连接用于收集的数据流和参考流。

参数

 * `cameraFps` (`int`)：用于派生时间戳匹配容差和轮询间隔的相机帧率。
 * `inputData` (`dai.Node.Output`)：生成要收集的数据消息的上游输出。
 * `inputReference` (`dai.Node.Output`)：生成参考消息的上游输出。
 * `waitCountFn` (`Callable[[TReference], int] | None`)：可选回调，返回给定参考预期的数据消息数量。如果省略，则默认为 len(reference.detections)。

返回

 * `GatherData[TReference, TGathered]`：配置好的节点实例。

##### run

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

轮询两个输入，按时间戳匹配消息，并发出就绪组。

##### setCameraFps

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

设置用于时间戳匹配的相机帧率。

参数

 * `fps` (`int`)：用于匹配容差和轮询的正相机帧率。

引发

 * `ValueError`：如果帧率不是正数。

##### setWaitCountFn

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

设置每个参考的预期收集项计数。

参数

 * `fn` (`Callable[[TReference], int]`)：接受参考消息并返回要等待的项数的回调。计数为零会立即发出一个空组。

#### 属性

##### FPS_TOLERANCE_DIVISOR

划分每帧时间间隔以计算时间戳匹配容差。值越高，匹配越严格。

##### INPUT_CHECKS_PER_FPS

每帧间隔的轮询迭代次数。有效循环睡眠时间为 `1 / (INPUT_CHECKS_PER_FPS * camera_fps)`。

##### out

返回收集到的输出流。

### HasDetections

公开检测列表的参考协议。

#### 属性

##### detections

返回用于派生默认等待计数的检测。

## 属性

### TGathered

### TReference
