|
RTAB-Map 0.23.10
Real-Time Appearance-Based Mapping
|
A class representing a calibrated stereo camera system. More...
#include <StereoCameraModel.h>
Public Member Functions | |
| StereoCameraModel () | |
| Default constructor. Creates an empty stereo model with default suffixes ("left", "right"). | |
| StereoCameraModel (const std::string &name, const cv::Size &imageSize1, const cv::Mat &K1, const cv::Mat &D1, const cv::Mat &R1, const cv::Mat &P1, const cv::Size &imageSize2, const cv::Mat &K2, const cv::Mat &D2, const cv::Mat &R2, const cv::Mat &P2, const cv::Mat &R, const cv::Mat &T, const cv::Mat &E, const cv::Mat &F, const Transform &localTransform=Transform(0, 0, 1, 0, -1, 0, 0, 0, 0,-1, 0, 0)) | |
| Constructs a StereoCameraModel from detailed intrinsic and extrinsic parameters for both cameras. | |
| StereoCameraModel (const std::string &name, const CameraModel &leftCameraModel, const CameraModel &rightCameraModel, const cv::Mat &R=cv::Mat(), const cv::Mat &T=cv::Mat(), const cv::Mat &E=cv::Mat(), const cv::Mat &F=cv::Mat()) | |
| Constructs a StereoCameraModel from two individual camera models and optional stereo extrinsic parameters. | |
| StereoCameraModel (const std::string &name, const CameraModel &leftCameraModel, const CameraModel &rightCameraModel, const Transform &extrinsics) | |
| Constructs a StereoCameraModel from two camera models and an extrinsic Transform between them. | |
| StereoCameraModel (double fx, double fy, double cx, double cy, double baseline, const Transform &localTransform=Transform(0, 0, 1, 0, -1, 0, 0, 0, 0,-1, 0, 0), const cv::Size &imageSize=cv::Size(0, 0)) | |
| Minimal constructor using focal lengths and baseline only. | |
| StereoCameraModel (const std::string &name, double fx, double fy, double cx, double cy, double baseline, const Transform &localTransform=Transform(0, 0, 1, 0, -1, 0, 0, 0, 0,-1, 0, 0), const cv::Size &imageSize=cv::Size(0, 0)) | |
| Minimal constructor that also sets a name, required if we want to save it to a file. | |
| virtual | ~StereoCameraModel () |
| Destructor. | |
| bool | isValidForProjection () const |
| Returns true if both left and right models are valid for projection and the baseline is positive. | |
| bool | isValidForRectification () const |
| Returns true if both left and right models are valid for rectification. | |
| void | initRectificationMap () |
| Initializes the rectification maps for both cameras. | |
| bool | isRectificationMapInitialized () const |
| Returns true if rectification maps are initialized. | |
| void | setName (const std::string &name, const std::string &leftSuffix="left", const std::string &rightSuffix="right") |
| Sets the camera name and optional image suffixes for the left and right cameras. | |
| const std::string & | name () const |
| Gets the camera name. | |
| void | setImageSize (const cv::Size &size) |
| Sets the image size for both left and right cameras. | |
| bool | load (const std::string &directory, const std::string &cameraName, bool ignoreStereoTransform=true, bool initRectificationMaps=true) |
| Loads stereo camera calibration data from disk. | |
| bool | save (const std::string &directory, bool ignoreStereoTransform=true) const |
| Saves stereo camera calibration data to disk. | |
| bool | saveStereoTransform (const std::string &directory) const |
| Saves stereo extrinsic parameters to a YAML file in ROS format. | |
| std::vector< unsigned char > | serialize () const |
| Serializes the stereo camera model into a byte vector. | |
| unsigned int | deserialize (const std::vector< unsigned char > &data) |
| Deserializes stereo camera model data from a byte vector. | |
| unsigned int | deserialize (const unsigned char *data, unsigned int dataSize) |
| Deserializes stereo camera model data from a raw byte array. | |
| double | baseline () const |
| Returns the stereo baseline in meters. | |
| float | computeDepth (float disparity) const |
| Computes the depth (Z coordinate) from a given disparity value. | |
| float | computeDisparity (float depth) const |
| Computes the disparity value from a given depth. | |
| float | computeDisparity (unsigned short depth) const |
| Computes the disparity value from a depth given in unsigned short format (millimeters). | |
| const cv::Mat & | R () const |
| Stereo extrinsic rotation matrix. | |
| const cv::Mat & | T () const |
| Stereo extrinsic translation vector. | |
| const cv::Mat & | E () const |
| Essential matrix. | |
| const cv::Mat & | F () const |
| Fundamental matrix. | |
| void | scale (double scale) |
| Scales both cameras' calibration by a factor. | |
| void | roi (const cv::Rect &roi) |
| Applies region-of-interest (ROI) cropping to both cameras. | |
| void | setLocalTransform (const Transform &transform) |
| Sets the local transform from left camera to robot base. | |
| const Transform & | localTransform () const |
| Gets the local transform from left camera to robot base. | |
| Transform | stereoTransform () const |
| Returns the stereo transform (left camera relative to right camera coordinate system). | |
| const CameraModel & | left () const |
| Returns the left camera model. | |
| const CameraModel & | right () const |
| Returns the right camera model. | |
| const std::string & | getLeftSuffix () const |
| Gets the suffix used for the left camera calibration file. | |
| const std::string & | getRightSuffix () const |
| Gets the suffix used for the right camera calibration file. | |
A class representing a calibrated stereo camera system.
This class encapsulates the calibration data and operations associated with a stereo camera setup, including intrinsic and extrinsic parameters for both left and right cameras, stereo rectification, and methods for computing depth or disparity from stereo images.
It relies internally on two CameraModel instances for the left and right cameras.
Typical uses include:
Definition at line 53 of file StereoCameraModel.h.
|
inline |
Default constructor. Creates an empty stereo model with default suffixes ("left", "right").
Definition at line 59 of file StereoCameraModel.h.
| rtabmap::StereoCameraModel::StereoCameraModel | ( | const std::string & | name, |
| const cv::Size & | imageSize1, | ||
| const cv::Mat & | K1, | ||
| const cv::Mat & | D1, | ||
| const cv::Mat & | R1, | ||
| const cv::Mat & | P1, | ||
| const cv::Size & | imageSize2, | ||
| const cv::Mat & | K2, | ||
| const cv::Mat & | D2, | ||
| const cv::Mat & | R2, | ||
| const cv::Mat & | P2, | ||
| const cv::Mat & | R, | ||
| const cv::Mat & | T, | ||
| const cv::Mat & | E, | ||
| const cv::Mat & | F, | ||
| const Transform & | localTransform = Transform(0, 0, 1, 0, -1, 0, 0, 0, 0,-1, 0, 0) |
||
| ) |
Constructs a StereoCameraModel from detailed intrinsic and extrinsic parameters for both cameras.
Initializes the stereo camera model by specifying the calibration parameters for the left and right cameras, along with the stereo extrinsic parameters.
| name | Name identifier for the stereo camera. |
| imageSize1 | Image size (width, height) of the left camera. |
| K1 | Intrinsic camera matrix (3x3, CV_64FC1) for the left camera. |
| D1 | Distortion coefficients for the left camera. |
| R1 | Rectification matrix (3x3, CV_64FC1) for the left camera. |
| P1 | Projection matrix (3x4, CV_64FC1) for the left camera. |
| imageSize2 | Image size (width, height) of the right camera. |
| K2 | Intrinsic camera matrix (3x3, CV_64FC1) for the right camera. |
| D2 | Distortion coefficients for the right camera. |
| R2 | Rectification matrix (3x3, CV_64FC1) for the right camera. |
| P2 | Projection matrix (3x4, CV_64FC1) for the right camera. |
| R | Rotation matrix (3x3, CV_64FC1) representing the rotation from left to right camera coordinate system. Can be empty if unknown. |
| T | Translation vector (3x1, CV_64FC1) representing the translation from left to right camera coordinate system. Can be empty if unknown. |
| E | Essential matrix (3x3, CV_64FC1) encoding the stereo camera epipolar geometry. Can be empty if unknown. |
| F | Fundamental matrix (3x3, CV_64FC1) encoding the stereo camera epipolar constraints. Can be empty if unknown. |
| localTransform | The local transform associated with the stereo camera model. |
| rtabmap::StereoCameraModel::StereoCameraModel | ( | const std::string & | name, |
| const CameraModel & | leftCameraModel, | ||
| const CameraModel & | rightCameraModel, | ||
| const cv::Mat & | R = cv::Mat(), |
||
| const cv::Mat & | T = cv::Mat(), |
||
| const cv::Mat & | E = cv::Mat(), |
||
| const cv::Mat & | F = cv::Mat() |
||
| ) |
Constructs a StereoCameraModel from two individual camera models and optional stereo extrinsic parameters.
This constructor initializes the stereo camera model by assigning the provided left and right camera models. If the stereo extrinsics (R, T) are provided and valid, stereo rectification will be attempted—provided both cameras are valid for rectification and their image dimensions match.
Each camera model will automatically have its name updated using the name parameter and default suffixes ("left", "right").
| name | The base name for the stereo camera model. |
| leftCameraModel | The camera model representing the left camera. |
| rightCameraModel | The camera model representing the right camera. |
| R | (Optional) Rotation matrix of the left camera relative to the right camera coordinate system (3x3, CV_64FC1). |
| T | (Optional) Translation vector of the left camera relative to the right camera coordinate system (3x1, CV_64FC1). |
| E | (Optional) Essential matrix between the two cameras (3x3, CV_64FC1). |
| F | (Optional) Fundamental matrix between the two cameras (3x3, CV_64FC1). |
| UException | if any of the provided matrices (R, T, E, F) are non-empty and not of the expected type/shape. |
| UException | if R and T are provided but the camera models are not valid for rectification. |
R and T are non-empty, the cameras are valid, and their image sizes match. | rtabmap::StereoCameraModel::StereoCameraModel | ( | const std::string & | name, |
| const CameraModel & | leftCameraModel, | ||
| const CameraModel & | rightCameraModel, | ||
| const Transform & | extrinsics | ||
| ) |
Constructs a StereoCameraModel from two camera models and an extrinsic Transform between them.
This constructor sets up a stereo camera model using the given left and right camera models along with an optional 3D transform (extrinsics) representing the pose of the left camera relative to the right camera coordinate system.
If a valid (non-null) transform is provided, the corresponding rotation and translation matrices are extracted and stored as the stereo extrinsic parameters. Stereo rectification will be attempted if both camera models are valid for rectification and their image sizes match.
Each camera model will be renamed using the provided name and default suffixes ("left", "right").
| name | Base name for the stereo camera model. |
| leftCameraModel | Camera model for the left camera. |
| rightCameraModel | Camera model for the right camera. |
| extrinsics | (Optional) Transform of the left camera relative to the right camera coordinate system. If null, no extrinsics are used. |
| UException | if extrinsics is not null and either camera model is not valid for rectification. |
extrinsics is valid and both camera models are rectifiable with matching image dimensions. | rtabmap::StereoCameraModel::StereoCameraModel | ( | double | fx, |
| double | fy, | ||
| double | cx, | ||
| double | cy, | ||
| double | baseline, | ||
| const Transform & | localTransform = Transform(0, 0, 1, 0, -1, 0, 0, 0, 0,-1, 0, 0), |
||
| const cv::Size & | imageSize = cv::Size(0, 0) |
||
| ) |
Minimal constructor using focal lengths and baseline only.
Creates a simplified stereo camera model using only the essential intrinsic parameters and baseline. This constructor assumes the images are already rectified and both cameras have the same intrinsic parameters.
| fx | Focal length in x direction (pixels). |
| fy | Focal length in y direction (pixels). |
| cx | Principal point x coordinate (pixels). |
| cy | Principal point y coordinate (pixels). |
| baseline | Stereo baseline distance in meters. |
| localTransform | Local transform from camera to robot base frame (default: optical rotation). |
| imageSize | Image size (width, height). Optional, can be set later. |
| rtabmap::StereoCameraModel::StereoCameraModel | ( | const std::string & | name, |
| double | fx, | ||
| double | fy, | ||
| double | cx, | ||
| double | cy, | ||
| double | baseline, | ||
| const Transform & | localTransform = Transform(0, 0, 1, 0, -1, 0, 0, 0, 0,-1, 0, 0), |
||
| const cv::Size & | imageSize = cv::Size(0, 0) |
||
| ) |
Minimal constructor that also sets a name, required if we want to save it to a file.
Same as the minimal constructor but also sets the camera name, which is required when saving the calibration to disk.
| name | Camera name identifier (used for saving calibration files). |
| fx | Focal length in x direction (pixels). |
| fy | Focal length in y direction (pixels). |
| cx | Principal point x coordinate (pixels). |
| cy | Principal point y coordinate (pixels). |
| baseline | Stereo baseline distance in meters. |
| localTransform | Local transform from camera to robot base frame (default: optical rotation). |
| imageSize | Image size (width, height). Optional, can be set later. |
|
inlinevirtual |
Destructor.
Definition at line 219 of file StereoCameraModel.h.
|
inline |
Returns true if both left and right models are valid for projection and the baseline is positive.
Definition at line 224 of file StereoCameraModel.h.
|
inline |
Returns true if both left and right models are valid for rectification.
Definition at line 229 of file StereoCameraModel.h.
|
inline |
Initializes the rectification maps for both cameras.
Definition at line 234 of file StereoCameraModel.h.
|
inline |
Returns true if rectification maps are initialized.
Definition at line 239 of file StereoCameraModel.h.
| void rtabmap::StereoCameraModel::setName | ( | const std::string & | name, |
| const std::string & | leftSuffix = "left", |
||
| const std::string & | rightSuffix = "right" |
||
| ) |
Sets the camera name and optional image suffixes for the left and right cameras.
Updates the stereo camera model name and the suffixes used for identifying left and right camera calibration files. The suffixes are used when loading/saving calibration data from disk.
| name | Base name for the stereo camera model. |
| leftSuffix | Suffix for the left camera (default: "left"). Used in filenames like "cameraName_left.yaml". |
| rightSuffix | Suffix for the right camera (default: "right"). Used in filenames like "cameraName_right.yaml". |
|
inline |
Gets the camera name.
Definition at line 258 of file StereoCameraModel.h.
|
inline |
Sets the image size for both left and right cameras.
Definition at line 263 of file StereoCameraModel.h.
| bool rtabmap::StereoCameraModel::load | ( | const std::string & | directory, |
| const std::string & | cameraName, | ||
| bool | ignoreStereoTransform = true, |
||
| bool | initRectificationMaps = true |
||
| ) |
Loads stereo camera calibration data from disk.
This method loads the intrinsic parameters for both the left and right cameras from files in the specified directory, using the provided camera name and internal suffixes. If ignoreStereoTransform is false, it also attempts to load the stereo extrinsic parameters (rotation, translation, essential, and fundamental matrices) from a YAML file.
The stereo extrinsics are expected in the file: directory/cameraName_pose.yaml, following the ROS calibration format.
| directory | The directory where the calibration files are located. |
| cameraName | The base name of the stereo camera (used to derive filenames). |
| ignoreStereoTransform | If true, skips loading stereo extrinsic parameters. |
| initRectificationMaps | Set to false to skip building the (potentially large) left/right rectification maps when rectification won't be used (saves time and memory). |
| bool rtabmap::StereoCameraModel::save | ( | const std::string & | directory, |
| bool | ignoreStereoTransform = true |
||
| ) | const |
Saves stereo camera calibration data to disk.
This method saves the intrinsic parameters of both left and right cameras to the specified directory. If ignoreStereoTransform is false, it also saves the stereo extrinsic parameters (rotation, translation, essential, and fundamental matrices) in a ROS-compatible YAML file named cameraName_pose.yaml.
| directory | The directory where calibration files should be saved. |
| ignoreStereoTransform | If true, skips saving stereo extrinsic parameters. |
| bool rtabmap::StereoCameraModel::saveStereoTransform | ( | const std::string & | directory | ) | const |
Saves stereo extrinsic parameters to a YAML file in ROS format.
This method exports the stereo transform, including rotation, translation, essential, and fundamental matrices, into a YAML file named cameraName_pose.yaml located in the specified directory. The file format is compatible with ROS camera calibration tools.
| directory | The target directory for saving the calibration file. |
R_, T_, E_, F_) are empty or invalid, nothing will be saved and a warning is printed.| std::vector< unsigned char > rtabmap::StereoCameraModel::serialize | ( | ) | const |
Serializes the stereo camera model into a byte vector.
This method serializes the left and right camera models along with the stereo extrinsic parameters (rotation matrix R_, translation vector T_, essential matrix E_, and fundamental matrix F_) into a contiguous byte array. The serialization format starts with a fixed-size integer header containing version info, stereo type, matrix sizes, and serialized data sizes, followed by the actual matrices and serialized camera data.
The serialized data can later be restored using the corresponding deserialize() method.
| unsigned int rtabmap::StereoCameraModel::deserialize | ( | const std::vector< unsigned char > & | data | ) |
Deserializes stereo camera model data from a byte vector.
This method wraps the pointer-based deserialize() and attempts to restore the stereo camera model from the given serialized byte vector.
| data | The vector of bytes containing previously serialized stereo camera model data. |
| unsigned int rtabmap::StereoCameraModel::deserialize | ( | const unsigned char * | data, |
| unsigned int | dataSize | ||
| ) |
Deserializes stereo camera model data from a raw byte array.
This method reconstructs the stereo camera model from the provided serialized data buffer. It expects the data format to match the one produced by serialize(), including a header with version info, matrix sizes, and data sizes, followed by the serialized extrinsic matrices and serialized left and right camera data.
The method performs various sanity checks on data sizes and matrix dimensions and will fail if the data format or sizes are inconsistent.
| data | Pointer to the raw serialized data buffer. |
| dataSize | Size in bytes of the data buffer. |
|
inline |
Returns the stereo baseline in meters.
Computes the baseline distance between the left and right cameras using the projection matrices. The baseline is calculated as the difference in x-translation (Tx) normalized by the focal length.
Definition at line 378 of file StereoCameraModel.h.
| float rtabmap::StereoCameraModel::computeDepth | ( | float | disparity | ) | const |
Computes the depth (Z coordinate) from a given disparity value.
Uses the stereo camera model parameters to convert disparity to depth using the formula:
where ( f_x ) is the focal length of the left camera and ( c_x ) are principal points.
| disparity | The disparity value (difference in pixel coordinates between left and right images). |
| float rtabmap::StereoCameraModel::computeDisparity | ( | float | depth | ) | const |
Computes the disparity value from a given depth.
Converts depth back to disparity using the inverse formula:
| depth | Depth value in the same unit as the baseline (typically meters). |
| float rtabmap::StereoCameraModel::computeDisparity | ( | unsigned short | depth | ) | const |
Computes the disparity value from a depth given in unsigned short format (millimeters).
Converts depth expressed as an unsigned short (in millimeters) to disparity. The depth is first converted to meters before computing disparity using the formula:
| depth | Depth value in millimeters as an unsigned short. |
|
inline |
Stereo extrinsic rotation matrix.
Definition at line 430 of file StereoCameraModel.h.
|
inline |
Stereo extrinsic translation vector.
Definition at line 431 of file StereoCameraModel.h.
|
inline |
Essential matrix.
Definition at line 432 of file StereoCameraModel.h.
|
inline |
Fundamental matrix.
Definition at line 433 of file StereoCameraModel.h.
| void rtabmap::StereoCameraModel::scale | ( | double | scale | ) |
Scales both cameras' calibration by a factor.
Scales the intrinsic parameters (focal lengths, principal points) and image sizes of both left and right cameras by the given scale factor. This is useful when working with downscaled or upscaled images.
| scale | Scaling factor (> 0). For example, use 0.5 to downscale or 2.0 to upscale. |
| void rtabmap::StereoCameraModel::roi | ( | const cv::Rect & | roi | ) |
Applies region-of-interest (ROI) cropping to both cameras.
Adjusts both camera models for a region of interest by shifting the principal points and updating the image sizes. This is useful when working with cropped or subwindowed images.
| roi | Region of interest rectangle. The top-left corner defines the offset for principal points. |
|
inline |
Sets the local transform from left camera to robot base.
Definition at line 466 of file StereoCameraModel.h.
|
inline |
Gets the local transform from left camera to robot base.
Definition at line 471 of file StereoCameraModel.h.
| Transform rtabmap::StereoCameraModel::stereoTransform | ( | ) | const |
Returns the stereo transform (left camera relative to right camera coordinate system).
The stereo transform brings points given in the first (left) camera's coordinate system to points in the second (right) camera's coordinate system. In more technical terms, it performs a change of basis from the first camera's coordinate system to the second camera's coordinate system. Due to its duality, it is equivalent to the position of the first camera with respect to the second camera coordinate system.
|
inline |
Returns the left camera model.
Definition at line 502 of file StereoCameraModel.h.
|
inline |
Returns the right camera model.
Definition at line 506 of file StereoCameraModel.h.
|
inline |
Gets the suffix used for the left camera calibration file.
Definition at line 511 of file StereoCameraModel.h.
|
inline |
Gets the suffix used for the right camera calibration file.
Definition at line 515 of file StereoCameraModel.h.