feat: mask-based pruning filter (vendor independent)

[mojomex]

PR Type

• New Feature

Related Links

• Better version of feat(hesai): add a ring section filter to Hesai sensors #182

Description

ℹ️ This PR provides only a library, and does not have an effect by itself. Vendor implementations are done in PRs following this one.

ℹ️ Performance measurements are provided on a per-vendor basis (e.g. #251) and are thus not included in this PR.

This PR introduces a mask-based pointcloud filter that allows precise pruning of the pointcloud with different pruning factors for different areas of the pointcloud.

This feature is aimed at reducing computational load later in the pipeline by

• offering a replacement to filters like CropBox
• providing a way to downsample pointcloud angular resolution in certain areas

The filter takes a grayscale PNG image with the x direction representing azimuth, and the y direction representing the channel - a representation for elevation instead of channel will be added once such sensors are in Nebula.

Points falling into

• white regions (255 = 100 %) are all kept
• black regions (0 = 0 %) are all discarded
• gray regions are filtered according to a dithered black-and-white version of the mask computed on startup

The dithering algorithm first quantizes the grayscale image into multiples of 1/10, yielding 11 quantization levels.
Dithering patterns are diagonal lines spaced as uniformally as possible in a 10-pixel period (both horizontally and vertically).

See the docs for images and behavior descriptions.

Review Procedure

• code review
• verify what is being verified with unit tests
• run the filter in one of the upcoming vendor implementations (e.g. feat(hesai): implement mask-based pruning filter for Hesai #251)

Pre-Review Checklist for the PR Author

PR Author should check the checkboxes below when creating the PR.

• Assign PR to reviewer

Checklist for the PR Reviewer

Reviewers should check the checkboxes below before approval.

• Commits are properly organized and messages are according to the guideline
• (Optional) Unit tests have been written for new behavior
• PR title describes the changes

Post-Review Checklist for the PR Author

PR Author should check the checkboxes below before merging.

• All open points are addressed and tracked via issues or tickets

CI Checks

• Build and test for PR: Required to pass before the merge.

[codecov]

Codecov Report

Attention: Patch coverage is 74.25743% with 26 lines in your changes missing coverage. Please review.

Project coverage is 26.15%. Comparing base (97959dd) to head (91fc4b8).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
..._decoders_common/point_filters/downsample_mask.hpp	68.62%	14 Missing and 2 partials ⚠️
...oders/tests/point_filters/test_downsample_mask.cpp	79.59%	0 Missing and 10 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #250      +/-   ##
==========================================
+ Coverage   26.07%   26.15%   +0.08%     
==========================================
  Files         101      107       +6     
  Lines        9232     9477     +245     
  Branches     2213     2276      +63     
==========================================
+ Hits         2407     2479      +72     
- Misses       6436     6598     +162     
- Partials      389      400      +11     

Flag	Coverage Δ
differential	26.15% <74.25%> (?)
total	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.