RTAB-Map 0.23.10
Real-Time Appearance-Based Mapping
Loading...
Searching...
No Matches
rtabmap::SensorCaptureThread Class Reference

Thread-based sensor data capture and event posting for RTAB-Map. More...

#include <SensorCaptureThread.h>

Inheritance diagram for rtabmap::SensorCaptureThread:
Collaboration diagram for rtabmap::SensorCaptureThread:

Public Member Functions

 SensorCaptureThread (Camera *camera, const ParametersMap &parameters=ParametersMap())
 Constructor for camera-only capture.
 
 SensorCaptureThread (Camera *camera, SensorCapture *odomSensor, const Transform &extrinsics, double poseTimeOffset=0.0, float poseScaleFactor=1.0f, double poseWaitTime=0.1, const ParametersMap &parameters=ParametersMap())
 Constructor for camera with odometry sensor.
 
 SensorCaptureThread (Lidar *lidar, const ParametersMap &parameters=ParametersMap())
 Constructor for lidar-only capture.
 
 SensorCaptureThread (Lidar *lidar, Camera *camera, const ParametersMap &parameters=ParametersMap())
 Constructor for lidar with camera.
 
 SensorCaptureThread (Lidar *lidar, SensorCapture *odomSensor, double poseTimeOffset=0.0, float poseScaleFactor=1.0f, double poseWaitTime=0.1, const ParametersMap &parameters=ParametersMap())
 Constructor for lidar with odometry sensor.
 
 SensorCaptureThread (Lidar *lidar, Camera *camera, SensorCapture *odomSensor, const Transform &extrinsics, double poseTimeOffset=0.0, float poseScaleFactor=1.0f, double poseWaitTime=0.1, const ParametersMap &parameters=ParametersMap())
 Constructor for lidar with camera and odometry sensor.
 
virtual ~SensorCaptureThread ()
 Virtual destructor.
 
void setMirroringEnabled (bool enabled)
 Enables or disables image mirroring (horizontal flip)
 
void setStereoExposureCompensation (bool enabled)
 Enables or disables stereo exposure compensation.
 
void setColorOnly (bool colorOnly)
 Sets whether to capture color images only (skip depth)
 
void setImageDecimation (int decimation)
 Sets image decimation factor.
 
void setHistogramMethod (int histogramMethod)
 Sets histogram equalization method.
 
void setStereoToDepth (bool enabled)
 Enables or disables stereo-to-depth conversion.
 
void setFrameRate (float frameRate)
 Sets the target frame rate for capture.
 
RTABMAP_DEPRECATED void setImageRate (float frameRate)
 Sets the target image capture rate (deprecated)
 
void setDistortionModel (const std::string &path)
 Sets the depth distortion model file path.
 
void setOdomAsGroundTruth (bool enabled)
 Sets whether odometry poses should be treated as ground truth.
 
void enableBilateralFiltering (float sigmaS, float sigmaR)
 Enables bilateral filtering for depth images.
 
void disableBilateralFiltering ()
 Disables bilateral filtering.
 
void enableIMUFiltering (int filteringStrategy=1, const ParametersMap &parameters=ParametersMap(), bool baseFrameConversion=false)
 Enables IMU data filtering.
 
void disableIMUFiltering ()
 Disables IMU data filtering.
 
void enableFeatureDetection (const ParametersMap &parameters=ParametersMap())
 Enables automatic feature detection on captured images.
 
void disableFeatureDetection ()
 Disables automatic feature detection.
 
RTABMAP_DEPRECATED void setScanParameters (bool fromDepth, int downsampleStep, float rangeMin, float rangeMax, float voxelSize, int normalsK, float normalsRadius, bool forceGroundNormalsUp, bool deskewing)
 Sets lidar scan processing parameters (deprecated)
 
void setScanParameters (bool fromDepth, int downsampleStep=1, float rangeMin=0.0f, float rangeMax=0.0f, float voxelSize=0.0f, int normalsK=0, float normalsRadius=0.0f, float groundNormalsUp=0.0f, bool deskewing=false)
 Sets lidar scan processing parameters.
 
void postUpdate (SensorData *data, SensorCaptureInfo *info=0) const
 Post-processing hook called before posting SensorEvent.
 
bool isPaused () const
 Checks if the capture thread is paused.
 
bool isCapturing () const
 Checks if the capture thread is actively capturing.
 
bool odomProvided () const
 Checks if odometry is provided by the sensors.
 
Cameracamera ()
 Returns the camera pointer.
 
SensorCaptureodomSensor ()
 Returns the odometry sensor pointer.
 
Lidarlidar ()
 Returns the lidar pointer.
 
- Public Member Functions inherited from UThread
 UThread (Priority priority=kPNormal)
 
virtual ~UThread ()
 
void start ()
 
void kill ()
 
void join (bool killFirst=false)
 
void setPriority (Priority priority)
 
void setAffinity (int cpu=0)
 
bool isCreating () const
 
bool isRunning () const
 
bool isIdle () const
 
bool isKilled () const
 
Handle getThreadHandle () const
 
unsigned long getThreadId () const
 
- Public Member Functions inherited from UThreadC< void >
int Create (Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const
 
int Create (unsigned long &ThreadId, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const
 
int Create (Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const
 
int Create (unsigned long &ThreadId, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false) const
 

Additional Inherited Members

- Public Types inherited from UThread
enum  Priority {
  kPLow , kPBelowNormal , kPNormal , kPAboveNormal ,
  kPRealTime
}
 
- Public Types inherited from UThreadC< void >
typedef THREAD_HANDLE Handle
 
typedef void(* Handler) ()
 
typedef THREAD_HANDLE Handle
 
typedef void(* Handler) ()
 
- Static Public Member Functions inherited from UThread
static unsigned long currentThreadId ()
 
- Static Public Member Functions inherited from UThreadC< void >
static int Create (const Handler &Function, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false)
 
static int Join (Handle H)
 
static int Kill (Handle H)
 
static int Detach (Handle H)
 
static int Create (const Handler &Function, Handle *const &H=0, const bool &CreateDetached=false, const unsigned int &StackSize=0, const bool &CancelEnable=false, const bool &CancelAsync=false)
 
static int Join (const Handle &H)
 
static int Kill (const Handle &H)
 
static int Detach (const Handle &H)
 
- Protected Member Functions inherited from UEventsSender
void post (UEvent *event, bool async=true) const
 
- Static Protected Member Functions inherited from UThreadC< void >
static void Exit ()
 
static void TestCancel ()
 
static Handle Self ()
 
static void Exit ()
 
static void TestCancel ()
 
static int Self ()
 

Detailed Description

Thread-based sensor data capture and event posting for RTAB-Map.

SensorCaptureThread is a multi-threaded class that continuously captures sensor data from cameras and/or lidars in a background thread. It processes the data, optionally applies filtering and transformations, and posts SensorEvent events to registered handlers through RTAB-Map's event system.

The class supports various sensor configurations:

  • Camera-only: Single or multiple cameras for RGB-D or stereo imaging
  • Lidar-only: Single lidar for 3D point cloud capture
  • Camera + Lidar: Combined visual and range sensing
  • With odometry: Optional odometry sensor for pose estimation and deskewing

Key features:

  • Automatic data synchronization: Synchronizes camera and lidar data by timestamp
  • Deskewing: Corrects lidar scans using odometry poses
  • Image processing: Supports mirroring, decimation, histogram equalization, stereo-to-depth conversion
  • Depth filtering: Optional bilateral filtering for depth images
  • IMU filtering: Optional IMU data filtering and fusion
  • Feature detection: Optional automatic feature detection on captured images
  • Frame rate control: Configurable capture rate
  • Event-driven architecture: Posts SensorEvent events for downstream processing

The class inherits from UThread (for threading) and UEventsSender (for event posting).

Note
Ownership of Camera, Lidar, and SensorCapture pointers is transferred to this class.
The thread must be started with start() and stopped with kill() or join().
Warning
Thread Safety: All configuration parameters (setters) should be called before starting the thread with start(). Changing configuration after the thread is started is not thread-safe and may lead to race conditions or undefined behavior. If you need to change parameters at runtime, stop the thread first, modify the configuration, then restart it.
See also
Camera
Lidar
SensorCapture
SensorEvent
SensorData
UThread
UEventsSender

Definition at line 97 of file SensorCaptureThread.h.

Constructor & Destructor Documentation

◆ SensorCaptureThread() [1/6]

rtabmap::SensorCaptureThread::SensorCaptureThread ( Camera camera,
const ParametersMap parameters = ParametersMap() 
)

Constructor for camera-only capture.

Creates a SensorCaptureThread that captures images from a single camera. The camera can be RGB-D, stereo, or mono.

Parameters
cameraPointer to the camera to capture from (ownership transferred)
parametersOptional parameters map for configuration
Note
The camera pointer is owned by this class and will be deleted on destruction.

◆ SensorCaptureThread() [2/6]

rtabmap::SensorCaptureThread::SensorCaptureThread ( Camera camera,
SensorCapture odomSensor,
const Transform extrinsics,
double  poseTimeOffset = 0.0,
float  poseScaleFactor = 1.0f,
double  poseWaitTime = 0.1,
const ParametersMap parameters = ParametersMap() 
)

Constructor for camera with odometry sensor.

Creates a SensorCaptureThread that captures images from a camera and uses an odometry sensor for pose estimation. The odometry sensor can be the same as the camera or a different sensor.

Parameters
cameraPointer to the camera to capture images from (ownership transferred)
odomSensorPointer to the odometry sensor for pose estimation (can be the same as camera)
extrinsicsStatic transform from odometry sensor's left lens frame to camera's left lens frame (without optical rotation applied)
poseTimeOffsetTime offset in seconds to add to data timestamp when querying pose (default: 0.0)
poseScaleFactorScale factor to apply to pose translation (default: 1.0, no scaling)
poseWaitTimeMaximum time in seconds to wait for pose data (default: 0.1)
parametersOptional parameters map for configuration
Note
If odomAsGt is set to true via setOdomAsGroundTruth(), the odometry pose will be used as ground truth instead of odometry.

◆ SensorCaptureThread() [3/6]

rtabmap::SensorCaptureThread::SensorCaptureThread ( Lidar lidar,
const ParametersMap parameters = ParametersMap() 
)

Constructor for lidar-only capture.

Creates a SensorCaptureThread that captures 3D point clouds from a lidar.

Parameters
lidarPointer to the lidar to capture scans from (ownership transferred)
parametersOptional parameters map for configuration
Note
The lidar pointer is owned by this class and will be deleted on destruction.

◆ SensorCaptureThread() [4/6]

rtabmap::SensorCaptureThread::SensorCaptureThread ( Lidar lidar,
Camera camera,
const ParametersMap parameters = ParametersMap() 
)

Constructor for lidar with camera.

Creates a SensorCaptureThread that captures both lidar scans and camera images. If the camera provides pose information, it can be used for deskewing lidar scans.

Parameters
lidarPointer to the lidar to capture scans from (ownership transferred)
cameraPointer to the camera to capture images from (ownership transferred). If the camera provides pose, it can be used for deskewing.
parametersOptional parameters map for configuration

◆ SensorCaptureThread() [5/6]

rtabmap::SensorCaptureThread::SensorCaptureThread ( Lidar lidar,
SensorCapture odomSensor,
double  poseTimeOffset = 0.0,
float  poseScaleFactor = 1.0f,
double  poseWaitTime = 0.1,
const ParametersMap parameters = ParametersMap() 
)

Constructor for lidar with odometry sensor.

Creates a SensorCaptureThread that captures lidar scans and uses an odometry sensor for pose estimation and deskewing. The odometry sensor can be the same as the lidar or a different sensor.

Parameters
lidarPointer to the lidar to capture scans from (ownership transferred)
odomSensorPointer to the odometry sensor for pose estimation and deskewing (can be the same as lidar)
poseTimeOffsetTime offset in seconds to add to data timestamp when querying pose (default: 0.0)
poseScaleFactorScale factor to apply to pose translation (default: 1.0, no scaling)
poseWaitTimeMaximum time in seconds to wait for pose data (default: 0.1)
parametersOptional parameters map for configuration
Note
Deskewing is enabled by default when an odometry sensor is provided. Use setScanParameters() to configure deskewing behavior.
The lidar's local transform should be set as the extrinsics between odometry sensor's frame and lidar's frame.

◆ SensorCaptureThread() [6/6]

rtabmap::SensorCaptureThread::SensorCaptureThread ( Lidar lidar,
Camera camera,
SensorCapture odomSensor,
const Transform extrinsics,
double  poseTimeOffset = 0.0,
float  poseScaleFactor = 1.0f,
double  poseWaitTime = 0.1,
const ParametersMap parameters = ParametersMap() 
)

Constructor for lidar with camera and odometry sensor.

Creates a SensorCaptureThread that captures both lidar scans and camera images, and uses an odometry sensor for pose estimation and deskewing. This is the most comprehensive configuration, supporting multi-modal sensing with pose correction.

Parameters
lidarPointer to the lidar to capture scans from (ownership transferred)
cameraPointer to the camera to capture images from (ownership transferred)
odomSensorPointer to the odometry sensor for pose estimation and deskewing (can be the same as camera or lidar)
extrinsicsStatic transform from odometry frame to camera frame (without optical rotation applied)
poseTimeOffsetTime offset in seconds to add to data timestamp when querying pose (default: 0.0)
poseScaleFactorScale factor to apply to pose translation (default: 1.0, no scaling)
poseWaitTimeMaximum time in seconds to wait for pose data (default: 0.1)
parametersOptional parameters map for configuration
Note
The camera and lidar data are synchronized by timestamp, with the camera frame being at least as recent as the lidar frame.
The lidar's local transform should be set as the extrinsics between odometry sensor's frame and lidar's frame.

◆ ~SensorCaptureThread()

virtual rtabmap::SensorCaptureThread::~SensorCaptureThread ( )
virtual

Virtual destructor.

Stops the capture thread if running and deletes owned sensor pointers.

Member Function Documentation

◆ setMirroringEnabled()

void rtabmap::SensorCaptureThread::setMirroringEnabled ( bool  enabled)
inline

Enables or disables image mirroring (horizontal flip)

Parameters
enabledTrue to enable mirroring, false to disable

Definition at line 245 of file SensorCaptureThread.h.

◆ setStereoExposureCompensation()

void rtabmap::SensorCaptureThread::setStereoExposureCompensation ( bool  enabled)
inline

Enables or disables stereo exposure compensation.

When enabled, adjusts exposure between left and right stereo cameras to improve matching quality.

Parameters
enabledTrue to enable exposure compensation, false to disable

Definition at line 255 of file SensorCaptureThread.h.

◆ setColorOnly()

void rtabmap::SensorCaptureThread::setColorOnly ( bool  colorOnly)
inline

Sets whether to capture color images only (skip depth)

Parameters
colorOnlyTrue to capture color only, false to capture both color and depth

Definition at line 261 of file SensorCaptureThread.h.

◆ setImageDecimation()

void rtabmap::SensorCaptureThread::setImageDecimation ( int  decimation)
inline

Sets image decimation factor.

Decimation reduces image resolution by skipping pixels. A decimation of N means every Nth pixel is kept (e.g., 2 = half resolution, 4 = quarter resolution).

Parameters
decimationDecimation factor (1 = no decimation, 2 = half resolution, etc.)

Definition at line 271 of file SensorCaptureThread.h.

◆ setHistogramMethod()

void rtabmap::SensorCaptureThread::setHistogramMethod ( int  histogramMethod)
inline

Sets histogram equalization method.

Controls the type of histogram equalization applied to captured images. Histogram equalization improves image contrast by redistributing pixel intensities.

Parameters
histogramMethodHistogram equalization method:
  • 0 = None (disabled)
  • 1 = Standard histogram equalization (cv::equalizeHist)
  • 2 = CLAHE - Contrast Limited Adaptive Histogram Equalization (cv::createCLAHE)
Note
For color images, histogram equalization is applied only to the luminance channel (Y in YCrCb color space).
For stereo images, histogram equalization is applied to both left and right images.

Definition at line 287 of file SensorCaptureThread.h.

◆ setStereoToDepth()

void rtabmap::SensorCaptureThread::setStereoToDepth ( bool  enabled)
inline

Enables or disables stereo-to-depth conversion.

When enabled, converts stereo images to depth images using dense stereo matching.

Parameters
enabledTrue to enable stereo-to-depth conversion, false to disable

Definition at line 296 of file SensorCaptureThread.h.

◆ setFrameRate()

void rtabmap::SensorCaptureThread::setFrameRate ( float  frameRate)

Sets the target frame rate for capture.

Controls how often the capture loop runs. A frame rate of 0 means capture as fast as possible.

Parameters
frameRateTarget frame rate in Hz (0 = unlimited)

◆ setImageRate()

RTABMAP_DEPRECATED void rtabmap::SensorCaptureThread::setImageRate ( float  frameRate)
inline

Sets the target image capture rate (deprecated)

Deprecated:
Use setFrameRate() instead

Definition at line 312 of file SensorCaptureThread.h.

◆ setDistortionModel()

void rtabmap::SensorCaptureThread::setDistortionModel ( const std::string &  path)

Sets the depth distortion model file path.

Loads a discrete depth distortion model from the specified file path. This is used to correct systematic depth errors at longer ranges using the CLAMS (Calibration, Localization, And Mapping System) approach.

The distortion model is typically created using RTAB-Map's depth calibration tool, which uses visual odometry and 3D mapping to generate ground truth depth for calibration.

Parameters
pathPath to the distortion model file
See also
https://github.com/introlab/rtabmap/wiki/Depth-Calibration for detailed instructions on how to create and use depth distortion models

◆ setOdomAsGroundTruth()

void rtabmap::SensorCaptureThread::setOdomAsGroundTruth ( bool  enabled)
inline

Sets whether odometry poses should be treated as ground truth.

When enabled, odometry poses from the odometry sensor are stored as ground truth poses instead of odometry poses in the SensorData.

Parameters
enabledTrue to use odometry as ground truth, false to use as odometry

Definition at line 340 of file SensorCaptureThread.h.

◆ enableBilateralFiltering()

void rtabmap::SensorCaptureThread::enableBilateralFiltering ( float  sigmaS,
float  sigmaR 
)

Enables bilateral filtering for depth images.

Bilateral filtering reduces noise in depth images while preserving edges.

Parameters
sigmaSSpatial standard deviation (pixels)
sigmaRRange standard deviation (depth units)

◆ disableBilateralFiltering()

void rtabmap::SensorCaptureThread::disableBilateralFiltering ( )
inline

Disables bilateral filtering.

Definition at line 355 of file SensorCaptureThread.h.

◆ enableIMUFiltering()

void rtabmap::SensorCaptureThread::enableIMUFiltering ( int  filteringStrategy = 1,
const ParametersMap parameters = ParametersMap(),
bool  baseFrameConversion = false 
)

Enables IMU data filtering.

Enables filtering and fusion of IMU data from the sensor. The filtering strategy determines how IMU data is processed to estimate orientation.

Parameters
filteringStrategyFiltering strategy:
  • 0 = Madgwick filter (requires RTAB-Map built with RTABMAP_MADGWICK option)
  • 1 = Complementary filter (default)
parametersOptional parameters map for IMU filter configuration
baseFrameConversionIf true, converts IMU data to base frame
Note
If Madgwick filter is requested but RTAB-Map is not built with the option enabled, the Complementary filter will be used instead.
See also
IMUFilter

◆ enableFeatureDetection()

void rtabmap::SensorCaptureThread::enableFeatureDetection ( const ParametersMap parameters = ParametersMap())

Enables automatic feature detection on captured images.

When enabled, automatically detects and extracts visual features (keypoints, descriptors) from captured images.

Parameters
parametersOptional parameters map for feature detector configuration. Parameters from the "Vis/" group (e.g., Vis/FeatureType, Vis/MaxFeatures) are automatically converted to "Kp/" parameters internally. If both Vis/ and Kp/ parameters are provided, Vis/ parameters take precedence.
Note
The function converts Vis/ parameters to Kp/ parameters before creating the Feature2D detector.

◆ setScanParameters() [1/2]

RTABMAP_DEPRECATED void rtabmap::SensorCaptureThread::setScanParameters ( bool  fromDepth,
int  downsampleStep,
float  rangeMin,
float  rangeMax,
float  voxelSize,
int  normalsK,
float  normalsRadius,
bool  forceGroundNormalsUp,
bool  deskewing 
)

Sets lidar scan processing parameters (deprecated)

Deprecated:
Use the new version with groundNormalsUp parameter instead

Use the new version with groundNormalsUp parameter:

  • groundNormalsUp=0.8 for forceGroundNormalsUp=True
  • groundNormalsUp=0.0 for forceGroundNormalsUp=False

◆ setScanParameters() [2/2]

void rtabmap::SensorCaptureThread::setScanParameters ( bool  fromDepth,
int  downsampleStep = 1,
float  rangeMin = 0.0f,
float  rangeMax = 0.0f,
float  voxelSize = 0.0f,
int  normalsK = 0,
float  normalsRadius = 0.0f,
float  groundNormalsUp = 0.0f,
bool  deskewing = false 
)

Sets lidar scan processing parameters.

Configures how lidar scans are processed, including conversion from depth images, filtering, normal estimation, and deskewing.

Parameters
fromDepthIf true, generate scans from depth images instead of raw lidar data
downsampleStepDownsampling step:
  • If fromDepth is true: Image decimation step for depth images (1 = no decimation, 2 = every other pixel in both dimensions, etc.)
  • If fromDepth is false: Point skipping step for laser scan data (1 = no skipping, 2 = every other point, etc.)
rangeMinMinimum range in meters (points closer are filtered out, 0 = no minimum)
rangeMaxMaximum range in meters (points farther are filtered out, 0 = no maximum)
voxelSizeVoxel size in meters for downsampling (0 = no voxelization)
normalsKNumber of neighbors for K-nearest neighbors normal estimation (0 = no normals)
normalsRadiusRadius in meters for radius-based normal estimation (0 = use K-nearest)
groundNormalsUpThreshold for forcing ground normals upward (0.0-1.0, 0.8 = strong, 0.0 = disabled)
deskewingIf true, apply deskewing using odometry poses

◆ postUpdate()

void rtabmap::SensorCaptureThread::postUpdate ( SensorData data,
SensorCaptureInfo info = 0 
) const

Post-processing hook called before posting SensorEvent.

This method is called after all processing is complete but before the SensorEvent is posted. Derived classes can override this to perform additional processing or modifications to the data.

Parameters
dataPointer to the processed sensor data (can be modified)
infoPointer to the sensor capture info (can be modified, may be null)

◆ isPaused()

bool rtabmap::SensorCaptureThread::isPaused ( ) const
inline

Checks if the capture thread is paused.

Returns
True if paused (not running), false if running

Definition at line 469 of file SensorCaptureThread.h.

◆ isCapturing()

bool rtabmap::SensorCaptureThread::isCapturing ( ) const
inline

Checks if the capture thread is actively capturing.

Returns
True if capturing (running), false if not running

Definition at line 475 of file SensorCaptureThread.h.

◆ odomProvided()

bool rtabmap::SensorCaptureThread::odomProvided ( ) const

Checks if odometry is provided by the sensors.

Returns
True if an odometry sensor is configured, false otherwise

◆ camera()

Camera * rtabmap::SensorCaptureThread::camera ( )
inline

Returns the camera pointer.

Returns
Pointer to the camera (null if not set). Valid until SensorCaptureThread is deleted.

Definition at line 487 of file SensorCaptureThread.h.

◆ odomSensor()

SensorCapture * rtabmap::SensorCaptureThread::odomSensor ( )
inline

Returns the odometry sensor pointer.

Returns
Pointer to the odometry sensor (null if not set). Valid until SensorCaptureThread is deleted.

Definition at line 493 of file SensorCaptureThread.h.

◆ lidar()

Lidar * rtabmap::SensorCaptureThread::lidar ( )
inline

Returns the lidar pointer.

Returns
Pointer to the lidar (null if not set). Valid until SensorCaptureThread is deleted.

Definition at line 499 of file SensorCaptureThread.h.


The documentation for this class was generated from the following file: