概览硬件软件云平台
OAK 应用
DepthAI
AI
软件栈
故障排除

本页目录

  • 如何放置该节点
  • 输入与输出
  • 基本用法
  • 预置
  • 滤波器参数
  • 备注
  • 对 StereoDepth（非 ToF）的建议
  • 功能示例
  • 参考

ImageFilters

Supported on:RVC2RVC4
ImageFilters 对深度类灰度图像（RAW8/RAW16）应用有序的后处理滤波流水线。目前主要用于 ToF 深度流水线以及主机端回放深度数据。该节点在单一位置提供中值滤波、空间滤波、散斑滤波和时域滤波。如果未配置任何滤波器，则作为直通节点工作。对于标准实时 StereoDepth 流水线，建议使用内置的 StereoDepthConfig.PostProcessing 而非本节点（参见备注）。

如何放置该节点

Python

Python
1with dai.Pipeline() as pipeline:
2    imageFilters = pipeline.create(dai.node.ImageFilters)

C++

C++
1dai::Pipeline pipeline;
2auto imageFilters = pipeline.create<dai::node::ImageFilters>();

输入与输出

额外端口：
  • inputConfig — 接收 ImageFiltersConfig 消息，用于运行时配置

基本用法

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

Python

Python
1with dai.Pipeline() as p:
2    left = p.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_B)
3    right = p.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_C)
4    outL = left.requestOutput((640, 400), fps=20)
5    outR = right.requestOutput((640, 400), fps=20)
6
7    stereo = p.create(dai.node.StereoDepth)
8    outL.link(stereo.left)
9    outR.link(stereo.right)
10
11    filters = p.create(dai.node.ImageFilters)
12    filters.setRunOnHost(True)  # 在 RVC2 上必需
13    filters.build(stereo.disparity)  # 不使用预置进行构建
14
15    # 仅启用 Spatial 滤波器（其他参数使用默认值）
16    spatial = dai.node.ImageFilters.SpatialFilterParams()
17    spatial.enable = True
18    filters.initialConfig.filterParams = [spatial]

C++

C++
1dai::Pipeline p;
2auto left  = p.create<dai::node::Camera>()->build(dai::CameraBoardSocket::CAM_B);
3auto right = p.create<dai::node::Camera>()->build(dai::CameraBoardSocket::CAM_C);
4left->requestOutput({640,400}, 20);
5right->requestOutput({640,400}, 20);
6
7auto stereo = p.create<dai::node::StereoDepth>();
8
9auto filters = p.create<dai::node::ImageFilters>();
10filters->setRunOnHost(true); // 在 RVC2 上必需
11filters->build(stereo->disparity); // 不使用预置进行构建
12
13// 仅启用 Spatial 滤波器
14std::vector<dai::FilterParams> params;
15dai::filters::params::SpatialFilter sp{}; sp.enable = true;
16params.push_back(sp);
17filters->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
1stereo = p.create(dai.node.StereoDepth)
2# … 连接 left/right …
3stereo.initialConfig.postProcessing.temporalFilter.enable = False
4stereo.initialConfig.postProcessing.temporalFilter.delta = 100

功能示例

参考

class

dai::node::ImageFilters

variable
std::shared_ptr< ImageFiltersConfig > initialConfig
Initial config for image filters.
variable
Node::Input input
Input for image frames to be filtered
variable
Node::Output output
Filtered frame
variable
Node::Input inputConfig
Config to be set for a specific filter
function
std::shared_ptr< ImageFilters > build(Node::Output & input, ImageFiltersPresetMode presetMode)
Build the node.
Parameters
  • input: Input for image frames to be filtered
  • presetMode: Preset mode for image filters
Returns
Shared pointer to the node
function
std::shared_ptr< ImageFilters > build(ImageFiltersPresetMode presetMode)
Build the node.
Parameters
  • presetMode: Preset mode for image filters
Returns
Shared pointer to the node
function
void run()
function
void setRunOnHost(bool runOnHost)
Specify whether to run on host or device By default, the node will run on device.
function
bool runOnHost()
Check if the node is set to run on host
function
void setDefaultProfilePreset(ImageFiltersPresetMode mode)
Set default profile preset for ImageFilters.
Parameters
inline function
DeviceNodeCRTP()
inline function
DeviceNodeCRTP(const std::shared_ptr< Device > & device)
inline function
DeviceNodeCRTP(std::unique_ptr< Properties > props)
inline function
DeviceNodeCRTP(std::unique_ptr< Properties > props, bool confMode)
inline function
DeviceNodeCRTP(const std::shared_ptr< Device > & device, std::unique_ptr< Properties > props, bool confMode)

需要帮助？

请前往 OAKChina 官网 获取技术支持或解答您的任何疑问。