# YoloSpatialDetectionNetwork

用于 Yolo 神经网络的空间检测节点。功能类似于
[YoloDetectionNetwork](https://docs.luxonis.com/software/depthai-components/nodes/yolo_detection_network.md) 和
[SpatialLocationCalculator](https://docs.luxonis.com/software/depthai-components/nodes/spatial_location_calculator.md) 的组合。

## 如何放置

#### Python

```python
pipeline = dai.Pipeline()
yoloSpatial = pipeline.create(dai.node.YoloSpatialDetectionNetwork)
```

#### C++

```cpp
dai::Pipeline pipeline;
auto yoloSpatial = pipeline.create<dai::node::YoloSpatialDetectionNetwork>();
```

## 输入与输出

## 配置空间检测

SpatialDetectionNetwork节点的流水线如下图所示：

空间检测节点本质上是检测网络（[YoloDetectionNetwork](https://docs.luxonis.com/software/depthai-components/nodes/yolo_detection_network.md) 和
[MobileNetDetectionNetwork](https://docs.luxonis.com/software/depthai-components/nodes/mobilenet_detection_network.md)）以及[SpatialLocationCalculator](https://docs.luxonis.com/software/depthai-components/nodes/spatial_location_calculator.md)的抽象。

它通过将每个检测到的物体的边界框链接到空间位置计算器来工作。过程如下：

### 检测

检测网络负责在输入帧中检测物体。它输出检测到的物体列表，每个物体由一个边界框、标签和置信度分数表示。

### 对齐

深度图与输入帧对齐。这是必要的，因为DetectionNetwork在输入帧上操作，而SpatialLocationCalculator在深度图上操作。

### BBOX缩放

来自网络的边界框被发送到SpatialLocationCalculator，并根据BoundingBoxScaleFactor进行缩放。这样做是为了确保它包含整个物体。然后，边界框与深度一起用于计算物体的空间坐标。

### 空间坐标计算

 * X和Y坐标取自边界框中心。它们基于与帧中心的偏移以及该点的深度计算。
 * 对于深度（Z），考虑缩放边界框（ROI）内的每个像素。这给我们一组深度值，然后取平均值以获得最终深度值。

### 平均方法

 * 平均值/均值：使用ROI的平均值进行计算。
 * 最小值：使用ROI内的最小值进行计算。
 * 最大值：使用ROI内的最大值进行计算。
 * 众数：使用ROI内最频繁的值进行计算。
 * 中位数：使用ROI内的中位数值进行计算。

默认方法是中位数。

## 常见错误

大多数错误源于不正确的边界框重叠。缩放后的边界框可能包含背景部分，这可能会使深度计算产生偏差。

 * 薄物体（如杆）的空间坐标可能不准确，因为边界框中只有一小部分实际位于检测到的物体上。在这种情况下，最好尽可能使用较小的BoundingBoxScaleFactor。
 * 带孔的物体——圈、环等。为了获得正确的深度，边界框应包含整个物体。不使用中位数深度，而是使用最小值深度方法以排除背景。或者，可以设置深度阈值以在静态环境中忽略背景。

## 用法

#### Python

```python
pipeline = dai.Pipeline()
yoloSpatial = pipeline.create(dai.node.YoloSpatialDetectionNetwork)
yoloSpatial.setBlobPath(nnBlobPath)

# 空间检测特定参数
yoloSpatial.setConfidenceThreshold(0.5)
yoloSpatial.input.setBlocking(False)
yoloSpatial.setBoundingBoxScaleFactor(0.5)
yoloSpatial.setDepthLowerThreshold(100) # 最小10厘米
yoloSpatial.setDepthUpperThreshold(5000) # 最大5米

# Yolo特定参数
yoloSpatial.setNumClasses(80)
yoloSpatial.setCoordinateSize(4)
yoloSpatial.setAnchors([10,14, 23,27, 37,58, 81,82, 135,169, 344,319])
yoloSpatial.setAnchorMasks({ "side26": [1,2,3], "side13": [3,4,5] })
yoloSpatial.setIouThreshold(0.5)
```

#### C++

```cpp
dai::Pipeline pipeline;
auto yoloSpatial = pipeline.create<dai::node::YoloSpatialDetectionNetwork>();
yoloSpatial->setBlobPath(nnBlobPath);

// 空间检测特定参数
yoloSpatial->setConfidenceThreshold(0.5f);
yoloSpatial->input.setBlocking(false);
yoloSpatial->setBoundingBoxScaleFactor(0.5);
yoloSpatial->setDepthLowerThreshold(100); // 最小10厘米
yoloSpatial->setDepthUpperThreshold(5000); // 最大5米

// yolo特定参数
yoloSpatial->setNumClasses(80);
yoloSpatial->setCoordinateSize(4);
yoloSpatial->setAnchors({10, 14, 23, 27, 37, 58, 81, 82, 135, 169, 344, 319});
yoloSpatial->setAnchorMasks({{"side13", {3, 4, 5}}, {"side26", {1, 2, 3}}});
yoloSpatial->setIouThreshold(0.5f);
```

## 功能示例

 * [RGB & TinyYolo with spatial
   data](https://docs.luxonis.com/software/depthai-components/nodes/yolo_spatial_detection_network.md)

## 空间坐标系

OAK 相机使用 左手（笛卡尔）坐标系 处理所有空间坐标。

画面中心为 X、Y 坐标的 0,0 点。向上移动时 Y 值增加，向右移动时 X 值增加。

## 参考

### depthai.node.YoloSpatialDetectionNetwork(depthai.node.SpatialDetectionNetwork)

Kind: Class

YoloSpatialDetectionNetwork node. Yolo-based network with spatial location data.

#### getAnchorMasks(self) -> dict[str, list[int]]: dict[str, list[int]]

Kind: Method

Get anchor masks

#### getAnchors(self) -> list[float]: list[float]

Kind: Method

Get anchors

#### getCoordinateSize(self) -> int: int

Kind: Method

Get coordianate size

#### getIouThreshold(self) -> float: float

Kind: Method

Get Iou threshold

#### getNumClasses(self) -> int: int

Kind: Method

Get num classes

#### setAnchorMasks(self, anchorMasks: collections.abc.Mapping [ str , collections.abc.Sequence [ typing.SupportsInt ] ])

Kind: Method

Set anchor masks

#### setAnchors(self, anchors: collections.abc.Sequence [ typing.SupportsFloat ])

Kind: Method

Set anchors

#### setCoordinateSize(self, coordinates: typing.SupportsInt)

Kind: Method

Set coordianate size

#### setIouThreshold(self, thresh: typing.SupportsFloat)

Kind: Method

Set Iou threshold

#### setNumClasses(self, numClasses: typing.SupportsInt)

Kind: Method

Set num classes

### 需要帮助？

请前往 [OAKChina 官网](https://www.oakchina.cn/) 获取技术支持或解答您的任何疑问。