# ImageFilters

ImageFilters 对深度类灰度图像（RAW8/RAW16）应用有序的后处理滤波流水线。目前主要用于 ToF 深度流水线以及主机端回放深度数据。该节点在单一位置提供中值滤波、空间滤波、散斑滤波和时域滤波。如果未配置任何滤波器，则作为直通节点工作。

对于标准实时 StereoDepth 流水线，建议使用内置的 StereoDepthConfig.PostProcessing 而非本节点（参见备注）。

## 如何放置该节点

#### Python

```python
with dai.Pipeline() as pipeline:
    imageFilters = pipeline.create(dai.node.ImageFilters)
```

#### C++

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

## 输入与输出

额外端口：

 * inputConfig — 接收 ImageFiltersConfig 消息，用于运行时配置

## 基本用法

使用单个滤波器过滤 StereoDepth 视差流：

#### Python

```python
with dai.Pipeline() as p:
    left = p.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_B)
    right = p.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_C)
    outL = left.requestOutput((640, 400), fps=20)
    outR = right.requestOutput((640, 400), fps=20)

    stereo = p.create(dai.node.StereoDepth)
    outL.link(stereo.left)
    outR.link(stereo.right)

    filters = p.create(dai.node.ImageFilters)
    filters.setRunOnHost(True)  # 在 RVC2 上必需
    filters.build(stereo.disparity)  # 不使用预置进行构建

    # 仅启用 Spatial 滤波器（其他参数使用默认值）
    spatial = dai.node.ImageFilters.SpatialFilterParams()
    spatial.enable = True
    filters.initialConfig.filterParams = [spatial]
```

#### C++

```cpp
dai::Pipeline p;
auto left  = p.create<dai::node::Camera>()->build(dai::CameraBoardSocket::CAM_B);
auto right = p.create<dai::node::Camera>()->build(dai::CameraBoardSocket::CAM_C);
left->requestOutput({640,400}, 20);
right->requestOutput({640,400}, 20);

auto stereo = p.create<dai::node::StereoDepth>();

auto filters = p.create<dai::node::ImageFilters>();
filters->setRunOnHost(true); // 在 RVC2 上必需
filters->build(stereo->disparity); // 不使用预置进行构建

// 仅启用 Spatial 滤波器
std::vector<dai::FilterParams> params;
dai::filters::params::SpatialFilter sp{}; sp.enable = true;
params.push_back(sp);
filters->initialConfig->filterParams = params;
```

## 预置

dai::ImageFiltersPresetMode / dai.ImageFiltersPresetMode（目前仅有 ToF 调优预置）：

 * TOF_LOW_RANGE — 针对 ~0.2–2 m 范围，更强的时域 + 空间平滑
 * TOF_MID_RANGE — 针对 ~0.2–5 m 范围，平衡默认值
 * TOF_HIGH_RANGE — 长距离下激进的持久性 + 中值滤波

备注：

 * 这些预置针对 ToF 使用场景命名并调优，为可选项。
 * 对于通用 StereoDepth 流水线，建议定义自定义流水线（参见基本用法）并根据场景调整参数。

## 滤波器参数

可用的参数类型（与 StereoDepth 后处理模型相同）：

 * MedianFilterParams — MEDIAN_OFF、KERNEL_3x3、KERNEL_5x5
 * SpatialFilterParams — enable、holeFillingRadius、alpha、delta、numIterations
 * SpeckleFilterParams — enable、speckleRange、differenceThreshold
 * TemporalFilterParams — enable、persistencyMode、alpha、delta

## 备注

 * 支持的输入类型：仅 RAW8 和 RAW16。
 * 本节点中值核最大支持 5×5（不接受 7×7）。
 * 在 RVC2 上不支持设备端执行，需调用 setRunOnHost(True)。
 * 如果未配置任何滤波器，该节点作为直通节点工作。

### 对 StereoDepth（非 ToF）的建议

如果您使用的是实时 StereoDepth，请依赖其内置后处理，并将时域滤波保持保守或禁用。示例（Python）：

#### Python

```python
stereo = p.create(dai.node.StereoDepth)
# … 连接 left/right …
stereo.initialConfig.postProcessing.temporalFilter.enable = False
stereo.initialConfig.postProcessing.temporalFilter.delta = 100
```

## 功能示例

 * [Stereo Depth Filters](https://docs.luxonis.com/software-v3/depthai/examples/stereo_depth/stereo_depth_filters.md) — 使用
   ImageFilters 处理 StereoDepth 视差输出的示例

## 参考

### dai::node::ImageFilters

Kind: class

#### std::shared_ptr< ImageFiltersConfig > initialConfig

Kind: variable

Initial config for image filters.

#### Node::Input input

Kind: variable

Input for image frames to be filtered

#### Node::Output output

Kind: variable

Filtered frame

#### Node::Input inputConfig

Kind: variable

Config to be set for a specific filter

#### std::shared_ptr< ImageFilters > build(Node::Output & input, ImageFiltersPresetMode presetMode)

Kind: function

Build the node. parameters: input: Input for image frames to be filtered; presetMode: Preset mode for image filters return: Shared
pointer to the node

#### std::shared_ptr< ImageFilters > build(ImageFiltersPresetMode presetMode)

Kind: function

Build the node. parameters: presetMode: Preset mode for image filters return: Shared pointer to the node

#### void run()

Kind: function

#### void setRunOnHost(bool runOnHost)

Kind: function

Specify whether to run on host or device By default, the node will run on device.

#### bool runOnHost()

Kind: function

Check if the node is set to run on host

#### void setDefaultProfilePreset(ImageFiltersPresetMode mode)

Kind: function

Set default profile preset for ImageFilters . parameters: mode: Preset mode for ImageFilters .

#### DeviceNodeCRTP()

Kind: function

#### DeviceNodeCRTP(const std::shared_ptr< Device > & device)

Kind: function

#### DeviceNodeCRTP(std::unique_ptr< Properties > props)

Kind: function

#### DeviceNodeCRTP(std::unique_ptr< Properties > props, bool confMode)

Kind: function

#### DeviceNodeCRTP(const std::shared_ptr< Device > & device, std::unique_ptr< Properties > props, bool confMode)

Kind: function

### 需要帮助？

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