IVT
CCalibration Class Reference

Camera model parameters and functions for a single camera. More...

#include <Calibration.h>

Classes

struct  CCameraParameters
 Struct containing all parameters of the camera model. More...
 

Public Member Functions

 CCalibration ()
 The default constructor. More...
 
 ~CCalibration ()
 The destructor. More...
 
void Set (const CCalibration &calibration)
 Initializes the camera model, given an instance of CCalibration. More...
 
void SetCameraParameters (float fx, float fy, float cx, float cy, float d1, float d2, float d3, float d4, const Mat3d &R, const Vec3d &t, int width, int height)
 Initializes the camera model, given a complete parameter set. More...
 
void SetIntrinsicBase (float cx, float cy, float fx, float fy)
 Sets the principal point and the focal lengths. More...
 
void SetDistortion (float d1, float d2, float d3, float d4)
 Sets the distortion parameters of the distortion model. More...
 
void SetRotation (const Mat3d &R)
 Sets the extrinsic parameter R (rotation matrix). More...
 
void SetTranslation (const Vec3d &t)
 Sets the extrinsic parameter t (translation vector). More...
 
void GetCalibrationMatrix (Mat3d &K) const
 Sets up the calibration matrix K. More...
 
void GetProjectionMatrix (Mat3d &P1, Vec3d &p2) const
 Sets up the projection matrix P. More...
 
const CCameraParametersGetCameraParameters () const
 Gives access to the camera parameters. More...
 
bool LoadCameraParameters (const char *pCameraParameterFileName, int nCamera=0, bool bSetExtrinsicToIdentity=false)
 Initializes the camera model, given a file path to a camera parameter file. More...
 
bool SaveCameraParameters (const char *pCameraParameterFileName) const
 Writes the parameters of the camera model to camera parameter file. More...
 
void PrintCameraParameters () const
 Prints all camera parameters in the console window (STDOUT). More...
 
void WorldToImageCoordinates (const Vec3d &worldPoint, Vec2d &imagePoint, bool bUseDistortionParameters=true) const
 Transforms 3D world coordinates to 2D image coordinates. More...
 
void ImageToWorldCoordinates (const Vec2d &imagePoint, Vec3d &worldPoint, float zc=1.0f, bool bUseDistortionParameters=true) const
 Transforms 2D image coordinates to 3D world coordinates. More...
 
void WorldToCameraCoordinates (const Vec3d &worldPoint, Vec3d &cameraPoint) const
 Transforms 3D world coordinates to 3D camera coordinates. More...
 
void CameraToWorldCoordinates (const Vec3d &cameraPoint, Vec3d &worldPoint) const
 Transforms 3D camera coordinates to 3D world coordinates. More...
 
void CameraToImageCoordinates (const Vec3d &cameraPoint, Vec2d &imagePoint, bool bUseDistortionParameters=true) const
 Transforms 3D camera coordinates to 2D image coordinates. More...
 
void ImageToCameraCoordinates (const Vec2d &imagePoint, Vec3d &cameraPoint, float zc=1.0f, bool bUseDistortionParameters=true) const
 Transforms 2D image coordinates to 3D camera coordinates. More...
 
void UndistortImageCoordinates (const Vec2d &distortedImagePoint, Vec2d &undistortedImagePoint) const
 Transforms 2D distorted image coordinates to 2D undistorted image coordinates. More...
 
void DistortImageCoordinates (const Vec2d &undistortedImagePoint, Vec2d &distortedImagePoint) const
 Transforms 2D undistorted image coordinates to 2D distorted image coordinates. More...
 
void UndistortCameraCoordinates (const Vec2d &distortedCameraPoint, Vec2d &undistortedCameraPoint) const
 Deprecated. More...
 
void DistortCameraCoordinates (const Vec2d &undistortedCameraPoint, Vec2d &distortedCameraPoint) const
 Deprecated. More...
 
void GetCameraCoordinates (const Vec3d &worldPoint, Vec2d &imagePoint, bool bUseDistortionParameters=true) const
 Deprecated. More...
 
void GetWorldCoordinates (const Vec2d &imagePoint, Vec3d &worldPoint, float zc=1.0f, bool bUseDistortionParameters=true) const
 Deprecated. More...
 

Public Attributes

Mat3d m_rotation_inverse
 Rotation matrix of the inverted extrinsic transformation. More...
 
Vec3d m_translation_inverse
 Translation vector of the inverted extrinsic transformation. More...
 

Detailed Description

Camera model parameters and functions for a single camera.

The linear projection is modeled as a central perspective projection with the parameters fx, fy and cx, cy.

$\left(\begin{array}{c} u\\ v\\ \end{array}\right)= \left(\begin{array}{c} c_x\\ c_y\\ \end{array}\right)+\frac{1}{z_c} \left(\begin{array}{c} f_x\,x_c\\ f_y\,y_c\\ \end{array}\right)$

where u, v denote image coordinates, fx, fy the focal lengths, cx, cy the principal point, and xc, yc, zc denote camera coordinates.

The relationship between the world coordinate system and the camera coordinate system is modeled as a rigid body coordinate transformation from the world coordinate system into the camera coordinate system:

${\bf x}_c = R \cdot {\bf x}_w + {\bf t}$

where ${\bf x}_w$ denotes world coordinates, ${\bf x}_c$ denotes camera coordinates, R is a 3x3 rotation matrix and t is a translation vector (R, t are the extrinsic camera parameters).

The distortion model is composed of radial lens distortion (parameters d1, d2) and tangential lens distortion (parameters d3, d4). It is modeled as the computation of distorted image coordinates (ud, vd), given undistorted image coordinates (u, v):

$x_n = \frac{u-c_x}{f_x}$ $y_n = \frac{v-c_y}{f_y}$

$r = \sqrt{x_n^2 + y_n^2}$

$\left(\begin{array}{c} x_d\\ y_d\\ \end{array}\right) =(1+d_1r^2+d_2r^4) \left(\begin{array}{c} x_n\\ y_n\\ \end{array}\right)+ \left(\begin{array}{c} d_3(2x_ny_n)+d_4(r^2+2x_n^2)\\ d_3(r^2+2y_n^2)+d_4(2x_ny_n)\\ \end{array}\right)$

$\left(\begin{array}{c} u_d\\ v_d\\ \end{array}\right)= \left(\begin{array}{c} c_x\\ c_y\\ \end{array}\right)+ \left(\begin{array}{c} x_d \cdot f_x\\ y_d \cdot f_y\\ \end{array}\right)$

The camera model is described in detail in (P. Azad, T. Gockel, R. Dillmann, "Computer Vision - Principles and Practice", Elektor, Netherlands). It is the same camera model as used in OpenCV 1.0.

Definition at line 125 of file Calibration.h.

Constructor & Destructor Documentation

CCalibration::CCalibration ( )

The default constructor.

The default constructor initializes the camera model with the values width = 640, height = 480, fx = fy = 580, cx = 320, cy = 240, R = I, t = 0, d1 = d2 = d3 = d4 = 0. See CCameraParameters for further information on these parameters.

Camera parameters computed with calibration algorithms can be loaded by calling the method CCalibration::LoadCameraParameters.

Definition at line 68 of file Calibration.cpp.

CCalibration::~CCalibration ( )

The destructor.

Definition at line 82 of file Calibration.cpp.

Member Function Documentation

void CCalibration::CameraToImageCoordinates ( const Vec3d cameraPoint,
Vec2d imagePoint,
bool  bUseDistortionParameters = true 
) const

Transforms 3D camera coordinates to 2D image coordinates.

Performs the mapping from the camera coordinate system to the image coordinate system, i.e. projection.

Parameters
[in]cameraPointThe 3D camera coordinates.
[out]imagePointThe result parameter for the 2D image coordinates.
[in]bUseDistortionParametersIf set to true, the distortion model will be applied after linear projection, i.e. distorted image coordinates will be written to the parameter imagePoint. If set to false, the distortion model is skipped, i.e. undistorted image coordinates will be written to the parameter imagePoint.

Definition at line 210 of file Calibration.cpp.

void CCalibration::CameraToWorldCoordinates ( const Vec3d cameraPoint,
Vec3d worldPoint 
) const

Transforms 3D camera coordinates to 3D world coordinates.

Performs the coordinate transformation from the camera coordinate system to the world coordinate system, i.e. application of the inverse extrinsic camera parameters.

Parameters
[in]cameraPointThe 3D camera coordinates.
[out]worldPointThe result parameter for the 3D world coordinates.

Definition at line 205 of file Calibration.cpp.

void CCalibration::DistortCameraCoordinates ( const Vec2d undistortedCameraPoint,
Vec2d distortedCameraPoint 
) const

Deprecated.

Deprecated:

This method is deprecated. It internally calls DistortImageCoordinates(const Vec2d&, Vec2d&); please refer to the documentation of this function for more information.

Definition at line 305 of file Calibration.cpp.

void CCalibration::DistortImageCoordinates ( const Vec2d undistortedImagePoint,
Vec2d distortedImagePoint 
) const

Transforms 2D undistorted image coordinates to 2D distorted image coordinates.

Applies the distortion model to 2D image coordinates.

Parameters
[in]undistortedImagePointThe 2D undistorted image coordinates.
[out]distortedImagePointThe result parameter for the 2D distorted image coordinates.

Definition at line 266 of file Calibration.cpp.

void CCalibration::GetCalibrationMatrix ( Mat3d K) const

Sets up the calibration matrix K.

The calibration matrix is defined as:

$K = \left(\begin{array}{ccc} f_x & 0 & c_x\\ 0 & f_y & c_y\\ 0 & 0 & 1 \end{array}\right)$

The camera model is described in the general information about the class CCalibration.

Parameters
[out]KThe result parameter for the 3x3 calibration matrix.

Definition at line 91 of file Calibration.cpp.

void CCalibration::GetCameraCoordinates ( const Vec3d worldPoint,
Vec2d imagePoint,
bool  bUseDistortionParameters = true 
) const

Deprecated.

Deprecated:

This method is deprecated. It internally calls WorldToImageCoordinates(const Vec3d&, Vec2d&, bool); please refer to the documentation of this function for more information.

Definition at line 290 of file Calibration.cpp.

const CCameraParameters& CCalibration::GetCameraParameters ( ) const
inline

Gives access to the camera parameters.

Returns
a reference to the internal instance of CCameraParameters.

Definition at line 268 of file Calibration.h.

void CCalibration::GetProjectionMatrix ( Mat3d P1,
Vec3d p2 
) const

Sets up the projection matrix P.

The projection matrix P is a 3x4 matrix defined as:

$P = \left(K \cdot R | K \cdot {\bf t}\right)$, where K denotes the calibration matrix (see CCalibration::GetCalibrationMatrix) and R, t are the extrinsic camera parameters.

The camera model is described in the general information about the class CCalibration.

Parameters
[out]P1The left 3x3 part of the projection matrix, i.e. P1 = K R.
[out]p2The right 3x1 part of the projection matrix, i.e. p2 = K t.

Definition at line 99 of file Calibration.cpp.

void CCalibration::GetWorldCoordinates ( const Vec2d imagePoint,
Vec3d worldPoint,
float  zc = 1.0f,
bool  bUseDistortionParameters = true 
) const

Deprecated.

Deprecated:

This method is deprecated. It internally calls ImageToWorldCoordinates(const Vec2d&, Vec3d&, float, bool); please refer to the documentation of this function for more information.

Definition at line 295 of file Calibration.cpp.

void CCalibration::ImageToCameraCoordinates ( const Vec2d imagePoint,
Vec3d cameraPoint,
float  zc = 1.0f,
bool  bUseDistortionParameters = true 
) const

Transforms 2D image coordinates to 3D camera coordinates.

Performs the mapping from the image coordinate system to the camera coordinate system, i.e. back projection.

This mapping is ambiguous: All points that are mapped to 2D image point are located on straight line through the center of projection.

Parameters
[in]imagePointThe 2D image coordinates.
[out]cameraPointThe result parameter for the 3D camera coordinates.
[in]zcAs the 2D => 3D mapping is ambiguous, this parameter is required as an additional constraint to specify a unique point. zc specifies the z-coordinate of the target point in the camera coordinate system.
[in]bUseDistortionParametersIf set to true, the (inverse) distortion model will be applied before linear back projection, i.e. the input parameter imagePoint must contain distorted image coordinates. If set to false, the distortion model is skipped, i.e. the input parameter imagePoint must contain undistorted image coordinates.

Definition at line 219 of file Calibration.cpp.

void CCalibration::ImageToWorldCoordinates ( const Vec2d imagePoint,
Vec3d worldPoint,
float  zc = 1.0f,
bool  bUseDistortionParameters = true 
) const

Transforms 2D image coordinates to 3D world coordinates.

Performs the mapping from the image coordinate system to the world coordinate system, i.e. back projection and application of the (inverse) extrinsic camera parameters.

This mapping is ambiguous: All points that are mapped to 2D image point are located on straight line through the center of projection.

Parameters
[in]imagePointThe 2D image coordinates.
[out]worldPointThe result parameter for the 3D world coordinates.
[in]zcAs the 2D => 3D mapping is ambiguous, this parameter is required as an additional constraint to specify a unique point. zc specifies the z-coordinate of the target point in the camera coordinate system (not world coordinate system!).
[in]bUseDistortionParametersIf set to true, the (inverse) distortion model will be applied before linear back projection, i.e. the input parameter imagePoint must contain distorted image coordinates. If set to false, the distortion model is skipped, i.e. the input parameter imagePoint must contain undistorted image coordinates.

Definition at line 193 of file Calibration.cpp.

bool CCalibration::LoadCameraParameters ( const char *  pCameraParameterFileName,
int  nCamera = 0,
bool  bSetExtrinsicToIdentity = false 
)

Initializes the camera model, given a file path to a camera parameter file.

The format of the file is the same as the one used in OpenCV 1.0. The file format is described in CStereoCalibration::LoadCameraParameters.

Camera calibration can be performed with the application found in IVT/examples/CalibrationApp (resp. IVT/win32/CalibrationApp). See also the class CDLTCalibration.

Parameters
[in]pCameraParameterFileNameThe file path to the camera parameter file to be loaded.
[in]nCameraIf the camera parameter file contains a stereo calibration, this parameter indicates the parameters of which camera are to be loaded (0: first (usually left) camera, 1 : second (usually right) camera).
[in]bSetExtrinsicToIdentityIf set to true, then the extrinsic camera parameters R and t will be set to the identity transformation, i.e. R will be set to the identity matrix and t will be set to the translation vector.
Returns
true on success and false on failure.

Definition at line 312 of file Calibration.cpp.

void CCalibration::PrintCameraParameters ( ) const

Prints all camera parameters in the console window (STDOUT).

Definition at line 410 of file Calibration.cpp.

bool CCalibration::SaveCameraParameters ( const char *  pCameraParameterFileName) const

Writes the parameters of the camera model to camera parameter file.

The format of the file is the same as the one used in OpenCV 1.0. The file format is described in CStereoCalibration::LoadCameraParameters.

Parameters
[in]pCameraParameterFileNameThe file path to the target camera parameter file.
Returns
true on success and false on failure.

Definition at line 380 of file Calibration.cpp.

void CCalibration::Set ( const CCalibration calibration)

Initializes the camera model, given an instance of CCalibration.

Parameters
calibrationThe template instance.

Definition at line 138 of file Calibration.cpp.

void CCalibration::SetCameraParameters ( float  fx,
float  fy,
float  cx,
float  cy,
float  d1,
float  d2,
float  d3,
float  d4,
const Mat3d R,
const Vec3d t,
int  width,
int  height 
)

Initializes the camera model, given a complete parameter set.

Parameters
[in]fxThe focal length in horizontal direction.
[in]fyThe focal length in vertical direction.
[in]cxThe x-coordinate (or u-coordinate) of the principal point.
[in]cyThe y-coordinate (or v-coordinate) of the principal point.
[in]d1The first radial lens distortion parameter.
[in]d2The second radial lens distortion parameter.
[in]d3The first tangential lens distortion parameter.
[in]d4The second tangential lens distortion parameter.
[in]RThe rotation matrix as part of the extrinsic camera parameters.
[in]tThe translation vector as part of the extrinsic camera parameters.
[in]widthThe width of the image sensor in pixels.
[in]heightThe height of the image sensor in pixels.

Definition at line 117 of file Calibration.cpp.

void CCalibration::SetDistortion ( float  d1,
float  d2,
float  d3,
float  d4 
)

Sets the distortion parameters of the distortion model.

Parameters
[in]d1The first radial lens distortion parameter.
[in]d2The second radial lens distortion parameter.
[in]d3The first tangential lens distortion parameter.
[in]d4The second tangential lens distortion parameter.

Definition at line 177 of file Calibration.cpp.

void CCalibration::SetIntrinsicBase ( float  cx,
float  cy,
float  fx,
float  fy 
)

Sets the principal point and the focal lengths.

Parameters
[in]cxThe x-coordinate (or u-coordinate) of the principal point.
[in]cyThe y-coordinate (or v-coordinate) of the principal point.
[in]fxThe focal length in horizontal direction.
[in]fyThe focal length in vertical direction.

Definition at line 171 of file Calibration.cpp.

void CCalibration::SetRotation ( const Mat3d R)

Sets the extrinsic parameter R (rotation matrix).

The member variables CCalibration::m_rotation_inverse and CCalibration::m_translation_inverse are updated automatically.

Parameters
[in]RThe rotation matrix as part of the extrinsic camera parameters.

Definition at line 159 of file Calibration.cpp.

void CCalibration::SetTranslation ( const Vec3d t)

Sets the extrinsic parameter t (translation vector).

The member variable CCalibration::m_translation_inverse is updated automatically.

Parameters
[in]tThe translation vector as part of the extrinsic camera parameters.

Definition at line 165 of file Calibration.cpp.

void CCalibration::UndistortCameraCoordinates ( const Vec2d distortedCameraPoint,
Vec2d undistortedCameraPoint 
) const

Deprecated.

Deprecated:

This method is deprecated. It internally calls UndistortImageCoordinates(const Vec2d&, Vec2d&); please refer to the documentation of this function for more information.

Definition at line 300 of file Calibration.cpp.

void CCalibration::UndistortImageCoordinates ( const Vec2d distortedImagePoint,
Vec2d undistortedImagePoint 
) const

Transforms 2D distorted image coordinates to 2D undistorted image coordinates.

Applies the inverse distortion model to 2D image coordinates.

Note that the distortion model cannot be inverted algebraically. Therfore, an iterative algorithm is applied.

Parameters
[in]distortedImagePointThe 2D distorted image coordinates.
[out]undistortedImagePointThe result parameter for the 2D undistorted image coordinates.

Definition at line 233 of file Calibration.cpp.

void CCalibration::WorldToCameraCoordinates ( const Vec3d worldPoint,
Vec3d cameraPoint 
) const

Transforms 3D world coordinates to 3D camera coordinates.

Performs the coordinate transformation from the world coordinate system to the camera coordinate system, i.e. application of the extrinsic camera parameters.

Parameters
[in]worldPointThe 3D world coordinates.
[out]cameraPointThe result parameter for the 3D camera coordinates.

Definition at line 200 of file Calibration.cpp.

void CCalibration::WorldToImageCoordinates ( const Vec3d worldPoint,
Vec2d imagePoint,
bool  bUseDistortionParameters = true 
) const

Transforms 3D world coordinates to 2D image coordinates.

Performs the mapping from the world coordinate system to the image coordinate system, i.e. application of the extrinsic camera parameters and the projection.

Parameters
[in]worldPointThe 3D world coordinates.
[out]imagePointThe result parameter for the 2D image coordinates.
[in]bUseDistortionParametersIf set to true, the distortion model will be applied after linear projection, i.e. distorted image coordinates will be written to the parameter imagePoint. If set to false, the distortion model is skipped, i.e. undistorted image coordinates will be written to the parameter imagePoint.

Definition at line 186 of file Calibration.cpp.

Member Data Documentation

Mat3d CCalibration::m_rotation_inverse

Rotation matrix of the inverted extrinsic transformation.

The extrinsic parameters specify the mapping ${\bf x}_c = R \cdot {\bf x}_w + {\bf t}$.

The inverse extrinsic parameters specify ${\bf x}_w = R^{-1} \cdot {\bf x}_c- R^{-1}{\bf t}$.

CCalibration::m_rotation_inverse thus is $R^{-1}$.

Definition at line 443 of file Calibration.h.

Vec3d CCalibration::m_translation_inverse

Translation vector of the inverted extrinsic transformation.

The extrinsic parameters specify the mapping ${\bf x}_c = R \cdot {\bf x}_w + {\bf t}$.

The inverse extrinsic parameters specify ${\bf x}_w = R^{-1} \cdot {\bf x}_c - R^{-1}{\bf t}$.

CCalibration::m_translation_inverse thus is $-R^{-1}{\bf t}$. It also equals the world coordinates of the center of projection.

Definition at line 454 of file Calibration.h.


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