DOC Skip to main content
Documentation
>
Orbbec Gemini 330 Series Documentation
>
Detailed Filter Reference
Orbbec Gemini 330 Series Documentation

Detailed Filter Reference

Update on 2026-08-11 03:33:03

ON THIS PAGE

1. Transformation

1.1 PointCloudFilter

Applicable Stream: Depth (for XYZ point cloud); Depth + Color (for RGBD point cloud, requires Depth and Color to be aligned (D2C) first, otherwise color mapping will be incorrect)

Function: Converts depth frames to XYZ point clouds (OB_FORMAT_POINT), or aligned depth+color frames to RGBD point clouds (OB_FORMAT_RGB_POINT, each point contains XYZ coordinates and RGB color)

Parameter

Type

Range

Default

Description

pointFormat

OBFormat

OB_FORMAT_POINT / OB_FORMAT_RGB_POINT

OB_FORMAT_POINT

Point cloud format

decimate

int

1 ~ 8

1

Point cloud decimation factor. Values > 1 downsample the output point cloud.

Example 1: XYZ Point Cloud

auto pointCloudFilter = std::make_shared<ob::PointCloudFilter>();

pointCloudFilter->setCreatePointFormat(OB_FORMAT_POINT);

pointCloudFilter->setCoordinateDataScaled(1.0f);

// Can pass a standalone Depth frame or a FrameSet containing a Depth frame

auto pointCloudFrame = pointCloudFilter->process(depthFrame);

if(pointCloudFrame) {

    auto points = pointCloudFrame->as<ob::PointsFrame>();

    // Use point cloud data ...

}

Example 2: RGBD Point Cloud

To generate an RGBD point cloud, the depth and color frames must be spatially aligned before being passed to PointCloudFilter. There are two alignment methods: prefer hardware D2C (better performance); if the resolution does not support hardware D2C, use the software Align Filter.

Method 1: Hardware D2C Alignment (recommended, use when resolution supports it)

auto pointCloudFilter = std::make_shared<ob::PointCloudFilter>();

pointCloudFilter->setCreatePointFormat(OB_FORMAT_RGB_POINT);

// Enable hardware D2C in Config. The FrameSet output by Pipeline is already aligned

std::shared_ptr<ob::Config> config = std::make_shared<ob::Config>();

config->enableVideoStream(OB_STREAM_DEPTH);

config->enableVideoStream(OB_STREAM_COLOR);

config->setAlignMode(ALIGN_D2C_HW_MODE);

pipe.start(config);

auto frameSet = pipe.waitForFrameset(100);

auto rgbdPointCloudFrame = pointCloudFilter->process(frameSet);

if(rgbdPointCloudFrame) {

    auto points = rgbdPointCloudFrame->as<ob::PointsFrame>();

    // Each point contains XYZ coordinates and RGB color ...

}

Method 2: Software Align Filter (use when the resolution does not support hardware D2C)

auto pointCloudFilter = std::make_shared<ob::PointCloudFilter>();

pointCloudFilter->setCreatePointFormat(OB_FORMAT_RGB_POINT);

auto alignFilter = std::make_shared<ob::Align>(OB_STREAM_COLOR);

// frameSet comes from Pipeline (must enable both Depth and Color streams)

auto frameSet = pipe.waitForFrameset(100);

auto alignedFrameSet = alignFilter->process(frameSet);  // FrameSet after software alignment

auto rgbdPointCloudFrame = pointCloudFilter->process(alignedFrameSet);

if(rgbdPointCloudFrame) {

    auto points = rgbdPointCloudFrame->as<ob::PointsFrame>();

    // Each point contains XYZ coordinates and RGB color ...

}

1.2 Align

Applicable Stream: Depth + Color. Function: Performs software-based spatial alignment between two streams, eliminating parallax offset between depth and color images. Unlike hardware D2C alignment, the Align Filter runs on the CPU, requires no hardware support, and offers more flexibility — but with higher platform resource consumption. If your device supports hardware D2C alignment, prefer it for better performance.

Parameter

Type

Description

AlignType

OBStreamType

Alignment target stream type: OB_STREAM_COLOR (depth aligned to color, D2C), OB_STREAM_DEPTH (color aligned to depth, C2D)

// Specify the alignment target when creating (depth aligned to color)

auto alignFilter = std::make_shared<ob::Align>(OB_STREAM_COLOR);

// Ensure both Depth and Color frames exist in the FrameSet

auto depthFrame = frameSet->getFrame(OB_FRAME_DEPTH);

auto colorFrame = frameSet->getFrame(OB_FRAME_COLOR);

if(!depthFrame || !colorFrame) {

    // Depth or Color frame missing, cannot perform alignment

    continue;

}

// Process the FrameSet

auto alignedFrameSet = alignFilter->process(frameSet);

if(alignedFrameSet) {

    auto alignedDepth = alignedFrameSet->as<ob::FrameSet>()->getFrame(OB_FRAME_DEPTH);

}

1.3 FormatConvertFilter

Applicable Stream: Color (YUYV/MJPG/NV12/NV21 to RGB/BGR, etc.); IR (Y16 to RGB, etc.). Function: Converts a frame's pixel format from one type to another. Commonly used to convert the camera's raw output format into a format directly usable by OpenCV.

Enum Value

Description

FORMAT_YUYV_TO_RGB

YUYV → RGB

FORMAT_MJPG_TO_RGB

MJPG → RGB

FORMAT_MJPG_TO_BGR

MJPG → BGR

FORMAT_MJPG_TO_NV21

MJPG → NV21

FORMAT_MJPG_TO_NV12

MJPG → NV12

FORMAT_NV12_TO_RGB

NV12 → RGB

FORMAT_NV21_TO_RGB

NV21 → RGB

FORMAT_RGB_TO_BGR

RGB → BGR

FORMAT_Y16_TO_RGB

Y16 (IR) → RGB

auto formatConvertFilter = std::make_shared<ob::FormatConvertFilter>();

formatConvertFilter->setFormatConvertType(FORMAT_MJPG_TO_RGB);

auto rgbFrame = formatConvertFilter->process(colorFrame);

if(rgbFrame) {

    // rgbFrame is now in RGB format, directly usable for OpenCV display

}

1.4 DisparityTransform

Applicable Stream: Depth. Function: Converts disparity maps to depth maps. The camera outputs depth data by default. This filter is only needed when you have switched to disparity-format data and need to convert it back to depth format.

⚠ Note: (1) Depth filters like ThresholdFilter only work on Depth data (in mm). (2) If the input is in Disparity format, it must first be converted via DisparityTransform, otherwise the filtering result will be invalid.

auto disparityTransform = std::make_shared<ob::DisparityTransform>();

auto depthFrame = disparityTransform->process(disparityFrame);

2. Flow Control

2.1 SequenceIdFilter

Applicable Stream: Depth / IR. Function: Filters frames from a FrameSet by the specified sequence ID. Used with HDR. Only takes effect when the HDR Merge Filter is disabled. selectSequenceId(0) passes all frames through; selectSequenceId(1) only keeps frames with sequence ID 1.

Parameter

Type

Range

Default

Description

sequenceid

int

-1 ~ 1

0

Frame sequence ID to retain. 0 passes all frames through.

auto seqFilter = std::make_shared<ob::SequenceIdFilter>();

seqFilter->selectSequenceId(1);  // Only keep frames with sequence ID 1

auto filteredFrame = seqFilter->process(frameSet);

3. Sampling / Threshold

3.1 DecimationFilter

Applicable Stream: Depth / IR / Color. Function: Downsamples the image by a specified factor, reducing resolution and lowering computational load for downstream processing. However, higher sampling rates result in more detail loss.

Parameter

Type

Range

Default

Description

decimate

uint8

1 ~ 8

2

Downsampling factor. For example, 2 reduces the resolution to 1/2 of the original.

auto decimationFilter = std::make_shared<ob::DecimationFilter>();

// Query the supported scale range

auto scaleRange = decimationFilter->getScaleRange();

std::cout << "scale range: " << (int)scaleRange.min << " ~ "

          << (int)scaleRange.max << std::endl;

decimationFilter->setScaleValue(2);  // Reduce resolution to 1/2 of original

auto outFrame = decimationFilter->process(depthFrame);

⚠ Note: The frame resolution changes after downsampling. Subsequent Filters or algorithms must adapt to the new resolution.

Depth effect before and after 1/2 downsampling:

image.png

3.2 ThresholdFilter

Applicable Stream: Depth. Function: Zeroes out pixels whose depth values fall outside the specified range [min, max] (in mm). Used to filter out invalid depth values that are too close or too far. Only effective on Depth data (mm), not on Disparity data.

Parameter

Type

Range

Default

Description

min

uint32

0 ~ 16000

0

Minimum valid depth value (mm)

max

uint32

0 ~ 16000

16000

Maximum valid depth value (mm)

auto thresholdFilter = std::make_shared<ob::ThresholdFilter>();

// Query the supported range

auto minRange = thresholdFilter->getMinRange();

auto maxRange = thresholdFilter->getMaxRange();

// Only keep depth values in the 300mm~3000mm range

thresholdFilter->setValueRange(300, 3000);

auto outFrame = thresholdFilter->process(depthFrame);

4. Noise Reduction

4.1 NoiseRemovalFilter

Applicable Stream: Depth. Function: Applies clustering to the depth map to identify and filter out noisy regions. As a basic noise reduction filter that runs inside the SDK, it is enabled by default on most devices and does not need to be created manually. Use the "Recommended Filter List" to toggle its state and adjust parameters.

Parameter

Type

Range

Default

Description

min_diff

uint16

1 ~ 51200

256

Depth spatial filtering range. Larger values weaken the denoising effect (retaining more detail); smaller values strengthen denoising.

max_size

uint16

1 ~ 1000

80

Maximum pixel area of noise clusters. Larger values make denoising more aggressive (filtering larger noise clusters), but may reduce depth fill rate.

Depth effect before and after enabling NoiseRemovalFilter:

image.pngimage.png

4.2 FalsePositiveFilter

Applicable Stream: Depth. Function: Filters out erroneous depth values (ghost noise) from the depth map. This filter functionally supersedes NoiseRemovalFilter and consumes more platform resources. It is recommended to disable NoiseRemovalFilter when enabling FalsePositiveFilter.

Because this filter has too many parameters to pass individually when creating it directly, it only supports enable/disable via filter->enable(bool). No additional parameter configuration is needed. It is strongly recommended to use the "Recommended Filter List" approach.

auto fpFilter = std::make_shared<ob::FalsePositiveFilter>();

// Enable the filter

fpFilter->enable(true);

auto outFrame = fpFilter->process(depthFrame);

This filter consists of three sub-filters, each targeting noise in a specific scenario. Since the filtering process may misclassify and remove valid depth data, each sub-filter exposes ROI parameters to precisely control the filter's region of influence, avoiding damage to valid depth. Adjust the ROI range as needed.

4.3 FalsePositiveFilter::EdgeBleedFilter

Function: Filters out laterally extended erroneous depth at object edges. Typical scenarios: semi-outdoor window edges, overexposed outdoor sky, etc. Rule: Within the depth map ROI, when more than fpebfMinBleedLength consecutive pixels have identical depth values in the horizontal direction, the region is classified as edge bleed noise and filtered out. For example, setting fpebfMinBleedLength = 40 triggers filtering when more than 40 consecutive pixels have the same depth value.

Parameter

Type

Range

Default

Description

fpEdgeBleedFilterEnable

bool

0 ~ 1

0

Edge bleed filter toggle

fpebfROIMinXRatio

float

0.0 ~ 1.0

0.0

ROI left boundary (proportion of image width, 0.0 = left edge)

fpebfROIMaxXRatio

float

0.0 ~ 1.0

1.0

ROI right boundary (proportion of image width, 1.0 = right edge)

fpebfROIMinYRatio

float

0.0 ~ 1.0

0.0

ROI top boundary (proportion of image height, 0.0 = top edge)

fpebfROIMaxYRatio

float

0.0 ~ 1.0

0.6

ROI bottom boundary (proportion of image height, 1.0 = bottom edge)

fpebfMinBleedLength

int

1 ~ 256

40

Minimum consecutive bleed length (pixels). Filtering is triggered when the number of consecutive identical-depth pixels exceeds this threshold.

Depth effect before and after enabling EdgeBleedFilter (laterally extended noise has been filtered):

image.png

At close range, depth values are more similar. When capturing flat surfaces, false positives may cause lateral depth loss. 

image.png

4.4 FalsePositiveFilter::TextureSparsityFilter

Function: Filters out erroneous depth in low-texture scenes. Typical scenarios: outdoor white walls, non-overexposed sky, etc. Rule: Within the depth map ROI, noise regions that satisfy both of the following conditions will be filtered out:

l Average depth value of noise region < fptsfMaxNoiseLevel

l Pixel area of noise cluster < fptsfMaxSpeckleSize

Parameter

Type

Range

Default

Description

fpTextureSparsityFilterEnable

bool

0 ~ 1

0

Low-texture filter toggle

fptsfROIMinXRatio

float

0.0 ~ 1.0

0.0

ROI left boundary (proportion of image width, 0.0 = left edge)

fptsfROIMaxXRatio

float

0.0 ~ 1.0

1.0

ROI right boundary (proportion of image width, 1.0 = right edge)

fptsfROIMinYRatio

float

0.0 ~ 1.0

0.0

ROI top boundary (proportion of image height, 0.0 = top edge)

fptsfROIMaxYRatio

float

0.0 ~ 1.0

0.45

ROI bottom boundary (proportion of image height, 1.0 = bottom edge)

fptsfMaxNoiseLevel

int

1 ~ 65535

6000

Maximum noise depth value (mm). Only removes noise with depth values below this threshold.

fptsfMaxSpeckleSize

int

1 ~ 65535

1300

Maximum pixel area of noise clusters. Only removes clusters smaller than this value.

Depth effect before and after enabling TextureSparsityFilter (noise in the sky has been filtered):

image.png

4.5 FalsePositiveFilter::PatternAmbiguityFilter

Function: Filters out erroneous depth in repetitive texture scenes. Typical scenarios: fences, building windows, etc. Rule: Within the depth map ROI, noise regions that satisfy ALL of the following conditions will be filtered out:

l Average depth value of noise region < fppafMaxNoiseLevel

l Pixel area of noise cluster < fppafMaxSpeckleSize

l Noise cluster width < image width × fppafMaxWidthRatio

l Noise cluster height < image height × fppafMaxHeightRatio

l Noise Tolerance feature > fppafTolerance

l Noise Score feature > fppafScore

Parameter

Type

Range

Default

Description

fpPatternAmbiguityFilterEnable

bool

0 ~ 1

0

Repetitive texture filter toggle

fppafROIMinXRatio

float

0.0 ~ 1.0

0.0

ROI left boundary (proportion of image width, 0.0 = left edge)

fppafROIMaxXRatio

float

0.0 ~ 1.0

0.99

ROI right boundary (proportion of image width, 1.0 = right edge)

fppafROIMinYRatio

float

0.0 ~ 1.0

0.0

ROI top boundary (proportion of image height, 0.0 = top edge)

fppafROIMaxYRatio

float

0.0 ~ 1.0

0.9

ROI bottom boundary (proportion of image height, 1.0 = bottom edge)

fppafMaxNoiseLevel

int

1 ~ 65535

6000

Maximum noise depth value (mm). Only removes noise with depth values below this threshold.

fppafMaxSpeckleSize

int

1 ~ 65535

4000

Maximum pixel area of noise clusters. Only removes clusters smaller than this value.

fppafMaxWidthRatio

float

0.0 ~ 1.0

0.3

Maximum noise cluster width as a proportion of image width

fppafMaxHeightRatio

float

0.0 ~ 1.0

0.3

Maximum noise cluster height as a proportion of image height

fppafTolerance

float

0.0 ~ 1.0

0.15

Noise tolerance feature threshold. Only removes noise when Tolerance > this value.

fppafScore

int

1 ~ 65535

50

Noise score threshold. Only removes noise when Score > this value.

Depth effect before and after enabling PatternAmbiguityFilter (noise on building facades from repetitive textures has been filtered)

image.png

4.6 FalsePositiveFilter Tuning Guide:

Parameter

Sub-Filter

Adjustment Direction for Noise Suppression

fpebfMinBleedLength

EdgeBleedFilter

↓ Decrease for more aggressive filtering

fptsfMaxNoiseLevel

TextureSparsityFilter

↑ Increase to cover farther noise

fptsfMaxSpeckleSize

TextureSparsityFilter

↑ Increase to filter larger noise clusters

fppafMaxNoiseLevel

PatternAmbiguityFilter

↑ Increase to cover farther noise

fppafMaxSpeckleSize

PatternAmbiguityFilter

↑ Increase to filter larger noise clusters

fppafMaxWidthRatio

PatternAmbiguityFilter

↑ Increase to filter wider noise clusters

fppafMaxHeightRatio

PatternAmbiguityFilter

↑ Increase to filter taller noise clusters

fppafTolerance

PatternAmbiguityFilter

↓ Decrease for more aggressive filtering

fppafScore

PatternAmbiguityFilter

↓ Decrease for more aggressive filtering

5. Spatial Smoothing

5.1 SpatialAdvancedFilter

Applicable Stream: Depth. Function: Edge-preserving spatial smoothing. Controls smoothing strength and edge preservation through alpha and disp_diff parameters. Smooths depth values in flat areas while preserving object edges. This is the recommended choice for depth map spatial smoothing, but also has the highest resource usage.

Parameter

Type

Range

Default

Description

alpha

float

0.1 ~ 1

0.5

Current pixel weight. Larger values reduce smoothing (preserving original values). Step size: 0.01.

disp_diff

uint16

1 ~ 10000

160

Depth gradient threshold. Pixels exceeding this value are excluded from smoothing (edge protection).

radius

uint16

0 ~ 8

1

Smoothing radius. Affects the smoothing range.

magnitude

int

1 ~ 5

1

Number of iterations. More iterations produce stronger smoothing.

auto spatialFilter = std::make_shared<ob::SpatialAdvancedFilter>();

// Get current parameters (including defaults)

auto params = spatialFilter->getFilterParams();

// Modify parameters as needed

params.alpha     = 0.5f;

params.disp_diff = 160;

params.radius    = 2;

params.magnitude = 1;

spatialFilter->setFilterParams(params);

auto outFrame = spatialFilter->process(depthFrame);

5.2 SpatialFastFilter

Applicable Stream: Depth. Function: Fast spatial filtering based on an enhanced median smoothing algorithm. Low CPU usage, suitable for performance-sensitive scenarios.

Parameter

Type

Range

Default

Description

radius

uint8

3 ~ 5

3

Smoothing radius. Larger values increase the smoothing range. Step size: 2, so valid values are 3 or 5.

auto spatialFastFilter = std::make_shared<ob::SpatialFastFilter>();

// Get current parameters (including defaults)

auto params = spatialFastFilter->getFilterParams();

// Modify parameters as needed

params.radius = 2;

spatialFastFilter->setFilterParams(params);

auto outFrame = spatialFastFilter->process(depthFrame);

 

5.3 SpatialModerateFilter

Applicable Stream: Depth. Function: Based on an optimized mean smoothing algorithm, balancing processing speed and smoothing quality.

Parameter

Type

Range

Default

Description

magnitude

uint8

1 ~ 3

1

Number of iterations. More iterations produce stronger smoothing.

radius

uint8

3 ~ 7

5

Smoothing radius. Step size: 2, so valid values are 3, 5, or 7.

disp_diff

uint16

1 ~ 10000

160

Depth gradient threshold. Pixels exceeding this value are excluded from smoothing (edge protection).

auto spatialModFilter = std::make_shared<ob::SpatialModerateFilter>();

// Get current parameters (including defaults)

auto params = spatialModFilter->getFilterParams();

// Modify parameters as needed

params.magnitude = 2;

params.radius    = 2;

params.disp_diff = 64;

spatialModFilter->setFilterParams(params);

auto outFrame = spatialModFilter->process(depthFrame);

5.4 HoleFillingFilter

Applicable Stream: Depth. Function: Fills zero-valued hole pixels in the depth map. The fill value source depends on the selected mode.

Parameter

Type

Range

Default

Description

hole_filling_mode

OBHoleFillingMode

0 ~ 2

0 (TOP)

Fill mode (see table below)

Enum Value

Description

OB_HOLE_FILL_TOP

Fill with the nearest valid depth value directly above the hole

OB_HOLE_FILL_NEAREST

Fill with the nearest valid depth value from the surrounding area

OB_HOLE_FILL_FAREST

Fill with the farthest valid depth value from the surrounding area

auto holeFillingFilter = std::make_shared<ob::HoleFillingFilter>();

holeFillingFilter->setFilterMode(OB_HOLE_FILL_TOP);

auto outFrame = holeFillingFilter->process(depthFrame);

This filter fills all holes, which may introduce false data and is generally not recommended. However, in special scenarios where complete depth is required, you can enable it with the recommended OB_HOLE_FILL_FAREST mode.

Depth effect before and after enabling HoleFillingFilter (zero-depth regions have been filled):

image.pngimage.png

6. Temporal Smoothing

6.1 TemporalFilter

Applicable Stream: Depth. Function: Fuses depth data from the current frame with historical frames for temporal smoothing, effectively suppressing inter-frame jitter noise.

Parameter

Type

Range

Default

Description

diff_scale

float

0.1 ~ 1

0.1

Allowed depth change ratio threshold. Pixels exceeding this ratio are excluded from fusion. Step size: 0.01.

weight

float

0.1 ~ 1

0.4

Fusion weight for the current frame. Larger values favor the original data (weaker smoothing), smaller values produce stronger smoothing. Step size: 0.01.

auto temporalFilter = std::make_shared<ob::TemporalFilter>();

// Query the allowed parameter range

auto diffScaleRange = temporalFilter->getDiffScaleRange();

auto weightRange    = temporalFilter->getWeightRange();

// Set parameters as needed (within the allowed range)

temporalFilter->setDiffScale(0.1f);  // Range: [diffScaleRange.min, diffScaleRange.max]

temporalFilter->setWeight(0.4f);     // Range: [weightRange.min, weightRange.max]

auto outFrame = temporalFilter->process(depthFrame);

// Note: process() may return nullptr when there is insufficient historical data in the first few frames

if(outFrame) {

    // Use the processed frame

}

ON THIS PAGE

Add

  • Name：

  • Link Address：

Cancel

Add

  • Name：

  • Link Address：

Cancel
Questions or
Feedback?

Feedback

  • Your feedback matters! Share your thoughts on this page, report errors, or let us know how we can improve to better support your needs. If applicable, please include the specific sentence or section to help us identify and address the issue.

@2025 Orbbec Inc. All Rights Reserved.

Stay Updated

Be the first to learn about our new products and updates.

Back to top