Visual Servoing Platform  version 3.0.0
vpCameraParameters Class Reference

#include <visp3/core/vpCameraParameters.h>

Public Types

enum  vpCameraParametersProjType { perspectiveProjWithoutDistortion, perspectiveProjWithDistortion }
 

Public Member Functions

 vpCameraParameters ()
 
 vpCameraParameters (const vpCameraParameters &c)
 
 vpCameraParameters (const double px, const double py, const double u0, const double v0)
 
 vpCameraParameters (const double px, const double py, const double u0, const double v0, const double kud, const double kdu)
 
vpCameraParametersoperator= (const vpCameraParameters &c)
 
virtual ~vpCameraParameters ()
 
void init ()
 
void init (const vpCameraParameters &c)
 
void initFromCalibrationMatrix (const vpMatrix &_K)
 
void initFromFov (const unsigned int &w, const unsigned int &h, const double &hfov, const double &vfov)
 
void initPersProjWithoutDistortion (const double px, const double py, const double u0, const double v0)
 
void initPersProjWithDistortion (const double px, const double py, const double u0, const double v0, const double kud, const double kdu)
 
bool isFovComputed () const
 
void computeFov (const unsigned int &w, const unsigned int &h)
 
double getHorizontalFovAngle () const
 
double getVerticalFovAngle () const
 
std::vector< vpColVectorgetFovNormals () const
 
double get_px () const
 
double get_px_inverse () const
 
double get_py_inverse () const
 
double get_py () const
 
double get_u0 () const
 
double get_v0 () const
 
double get_kud () const
 
double get_kdu () const
 
vpCameraParametersProjType get_projModel () const
 
vpMatrix get_K () const
 
vpMatrix get_K_inverse () const
 
void printParameters ()
 

Friends

class vpMeterPixelConversion
 
class vpPixelMeterConversion
 
VISP_EXPORT std::ostream & operator<< (std::ostream &os, const vpCameraParameters &cam)
 

Detailed Description

Generic class defining intrinsic camera parameters.

Let us define the pinhole camera model implemented in ViSP. In this model, a scene view is formed by projecting 3D points into the image plane using a perspective transformation.

\[ \left[ \begin{array}{c} u \\ v \\ 1 \end{array}\right] = \left[ \begin{array}{ccc} u_0 & 0 & p_x \\ 0 & v_0 & p_y \\ 0 & 0 & 1 \end{array}\right] \left[ \begin{array}{c} X_c \\ Y_c \\ Z_c \end{array}\right] \]

where:

  • $(X_c,Y_c,Z_c)$ are the coordinates of a 3D point in the camera frame
  • $(u,v)$ are the coordinates in pixels of the projected 3D point
  • $(u_0,v_0)$ is a principal point that is usually near the image center
  • $(p_x,p_y)$ are the focal lengths expressed in pixel units.

When $Z_c \neq 0$, the previous equation si equivalent to the following:

\[ \begin{array}{lcl} x &=& X_c / Z_c \\ y &=& Y_c / Z_c \\ u &=& u_0 + x \; p_x \\ v &=& v_0 + y \; p_y \end{array} \]

Real lenses usually have some radial distortion. So, the above model is extended as:

\[ \begin{array}{lcl} x &=& X_c / Z_c \\ y &=& Y_c / Z_c \\ x^{'} &=& x (1 + k_{ud} r^2) \\ y^{'} &=& y (1 + k_{ud} r^2) \\ r^2 &=& x^2 + y^2 \\ u &=& u_0 + x^{'} \; p_x \\ v &=& v_0 + y^{'} \; p_y \end{array} \]

where $k_{ud}$ is the first order radial distorsion. Higher order distorsion coefficients are not considered in ViSP.

Now in ViSP we consider also the inverse transformation, where from pixel coordinates we want to compute their normalized coordinates in the image plane. Previous equations could be written like:

\[ \begin{array}{lcl} x &=& (u - u_0) / p_x \\ y &=& (v - v_0) / p_y \end{array} \]

Considering radial distortion, the above model is extended as:

\[ \begin{array}{lcl} (u-u_0)^{'} &=& (u-u_0) (1 + k_{du} r^2) \\ (v-v_0)^{'} &=& (v-v_0) (1 + k_{du} r^2) \\ r^2 &=& ((u-u_0)/p_x)^2 + ((v-v_0)/p_y)^2 \\ x &=& (u - u_0)^{'} / p_x \\ y &=& (v - v_0)^{'} / p_y \end{array} \]

Finally, in ViSP the main intrinsic camera parameters are $(p_x, p_y)$ the ratio between the focal length and the size of a pixel, and $(u_0, v_0)$ the coordinates of the principal point in pixel. The lens distortion can also be considered by two additional parameters $(k_{ud}, k_{du})$.

Note
Tutorial: Camera calibration shows how to calibrate a camera to estimate the parameters corresponding to the model implemented in this class.
Note also that Tutorial: Bridge over OpenCV gives the correspondance between ViSP and OpenCV camera modelization.
The conversion from pixel coordinates $(u,v)$ in the normalized space $(x,y)$ is implemented in vpPixelMeterConversion, whereas the conversion from normalized coordinates into pixel is implemented in vpMeterPixelConversion.

From a practical point of view, two kinds of camera modelisation are implemented in this class:

1. Camera parameters for a perspective projection without distortion model

In this modelisation, only $u_0,v_0,p_x,p_y$ parameters are considered.

Initialization of such a model can be done using:

2. Camera parameters for a perspective projection with distortion model

In this modelisation, all the parameters $u_0,v_0,p_x,p_y,k_{ud},k_{du}$ are considered. Initialization of such a model can be done using:

The selection of the camera model (without or with distorsion) is done during vpCameraParameters initialisation.

Here an example of camera initialisation, for a model without distortion. A complete example is given in initPersProjWithoutDistortion().

double px = 600;
double py = 600;
double u0 = 320;
double v0 = 240;
// Create a camera parameter container
// Camera initialization with a perspective projection without distortion model
// It is also possible to print the current camera parameters
std::cout << cam << std::endl;

Here an example of camera initialisation, for a model with distortion. A complete example is given in initPersProjWithDistortion().

double px = 600;
double py = 600;
double u0 = 320;
double v0 = 240;
double kud = -0.19;
double kdu = 0.20;
// Create a camera parameter container
// Camera initialization with a perspective projection without distortion model
cam.initPersProjWithDistortion(px,py,u0,v0,kud,kdu);

The code below shows how to know the currently used projection model:

...
vpCameraParameters::vpCameraParametersProjType projModel;
projModel = cam.get_projModel(); // Get the projection model type

An XML parser for camera parameters is also provided in vpXmlParserCamera.

Examples:
AROgre.cpp, AROgreBasic.cpp, HelloWorldOgre.cpp, HelloWorldOgreAdvanced.cpp, manGeometricFeatures.cpp, manServo4PointsDisplay.cpp, manSimu4Dots.cpp, manSimu4Points.cpp, mbtEdgeKltTracking.cpp, mbtEdgeTracking.cpp, mbtKltTracking.cpp, photometricVisualServoing.cpp, poseVirtualVS.cpp, servoAfma4Point2DArtVelocity.cpp, servoAfma4Point2DCamVelocity.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoAfma62DhalfCamVelocity.cpp, servoAfma6Cylinder2DCamVelocity.cpp, servoAfma6Cylinder2DCamVelocitySecondaryTask.cpp, servoAfma6Ellipse2DCamVelocity.cpp, servoAfma6FourPoints2DArtVelocity.cpp, servoAfma6FourPoints2DCamVelocityInteractionCurrent.cpp, servoAfma6FourPoints2DCamVelocityInteractionDesired.cpp, servoAfma6Line2DCamVelocity.cpp, servoAfma6Point2DArtVelocity.cpp, servoAfma6Point2DCamVelocity.cpp, servoAfma6Points2DCamVelocityEyeToHand.cpp, servoAfma6Segment2DCamVelocity.cpp, servoAfma6SquareLines2DCamVelocity.cpp, servoAfma6TwoLines2DCamVelocity.cpp, servoBiclopsPoint2DArtVelocity.cpp, servoMomentImage.cpp, servoMomentPoints.cpp, servoMomentPolygon.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, servoPtu46Point2DArtVelocity.cpp, servoSimu4Points.cpp, servoSimuAfma6FourPoints2DCamVelocity.cpp, servoSimuCircle2DCamVelocityDisplay.cpp, servoSimuCylinder.cpp, servoSimuCylinder2DCamVelocityDisplay.cpp, servoSimuCylinder2DCamVelocityDisplaySecondaryTask.cpp, servoSimuFourPoints2DCamVelocityDisplay.cpp, servoSimuFourPoints2DPolarCamVelocityDisplay.cpp, servoSimuLine2DCamVelocityDisplay.cpp, servoSimuSphere.cpp, servoSimuSquareLine2DCamVelocityDisplay.cpp, servoSimuViper850FourPoints2DCamVelocity.cpp, servoViper650FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper650FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper650Point2DCamVelocity.cpp, servoViper850FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper850FourPoints2DArtVelocityInteractionDesired.cpp, servoViper850FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper850FourPointsKinect.cpp, servoViper850Point2DArtVelocity-jointAvoidance-basic.cpp, servoViper850Point2DArtVelocity-jointAvoidance-gpa.cpp, servoViper850Point2DArtVelocity-jointAvoidance-large.cpp, servoViper850Point2DArtVelocity.cpp, servoViper850Point2DCamVelocity.cpp, servoViper850Point2DCamVelocityKalman.cpp, simulateCircle2DCamVelocity.cpp, simulateFourPoints2DCartesianCamVelocity.cpp, simulateFourPoints2DPolarCamVelocity.cpp, testAfma6.cpp, testFeatureSegment.cpp, testKeyPoint-2.cpp, testKeyPoint-4.cpp, testRobotAfma6.cpp, testRobotAfma6Pose.cpp, testRobotViper850.cpp, testRobotViper850Pose.cpp, testTrackDot.cpp, testUndistortImage.cpp, testViper850.cpp, trackMeLine.cpp, tutorial-bridge-opencv.cpp, tutorial-detection-object-mbt.cpp, tutorial-detection-object-mbt2.cpp, tutorial-homography-from-points.cpp, tutorial-ibvs-4pts-display.cpp, tutorial-ibvs-4pts-image-tracking.cpp, tutorial-ibvs-4pts-ogre-tracking.cpp, tutorial-ibvs-4pts-ogre.cpp, tutorial-ibvs-4pts-wireframe-camera.cpp, tutorial-ibvs-4pts-wireframe-robot-afma6.cpp, tutorial-ibvs-4pts-wireframe-robot-viper.cpp, tutorial-image-simulator.cpp, tutorial-matching-keypoint-homography.cpp, tutorial-matching-surf-homography-deprecated.cpp, tutorial-mb-edge-tracker.cpp, tutorial-mb-hybrid-tracker.cpp, tutorial-mb-klt-tracker.cpp, tutorial-mb-tracker-full.cpp, tutorial-mb-tracker.cpp, tutorial-pose-from-points-image.cpp, tutorial-pose-from-points-tracking.cpp, tutorial-undistort.cpp, and wireframeSimulator.cpp.

Definition at line 218 of file vpCameraParameters.h.

Member Enumeration Documentation

Enumerator
perspectiveProjWithoutDistortion 

Perspective projection without distortion model.

perspectiveProjWithDistortion 

Perspective projection with distortion model.

Definition at line 223 of file vpCameraParameters.h.

Constructor & Destructor Documentation

vpCameraParameters::vpCameraParameters ( )

Default constructor. By default, a perspective projection without distortion model is set.

See also
init()

Definition at line 73 of file vpCameraParameters.cpp.

References init().

vpCameraParameters::vpCameraParameters ( const vpCameraParameters c)

Copy constructor

Definition at line 89 of file vpCameraParameters.cpp.

References init().

vpCameraParameters::vpCameraParameters ( const double  cam_px,
const double  cam_py,
const double  cam_u0,
const double  cam_v0 
)

Constructor for perspective projection without distortion model

Parameters
cam_px,cam_py: pixel size
cam_u0,cam_v0: principal points

Definition at line 109 of file vpCameraParameters.cpp.

References initPersProjWithoutDistortion().

vpCameraParameters::vpCameraParameters ( const double  cam_px,
const double  cam_py,
const double  cam_u0,
const double  cam_v0,
const double  cam_kud,
const double  cam_kdu 
)

Constructor for perspective projection with distortion model

Parameters
cam_px,cam_py: pixel size
cam_u0,cam_v0: principal points
cam_kud: undistorted to distorted radial distortion
cam_kdu: distorted to undistorted radial distortion

Definition at line 132 of file vpCameraParameters.cpp.

References initPersProjWithDistortion().

vpCameraParameters::~vpCameraParameters ( )
virtual

destructor

nothing much to destroy...

Definition at line 309 of file vpCameraParameters.cpp.

Member Function Documentation

void vpCameraParameters::computeFov ( const unsigned int &  w,
const unsigned int &  h 
)
vpMatrix vpCameraParameters::get_K ( ) const
vpMatrix vpCameraParameters::get_K_inverse ( ) const

Return the inverted camera matrix $K^{-1}$ given by:

$ K^{-1} = \left[\begin{array}{ccc} 1/p_x & 0 & -u_0/p_x \\ 0 & 1/p_y & -v_0/p_y \\ 0 & 0 & 1 \end{array} \right] $

See also
get_K()

Definition at line 517 of file vpCameraParameters.cpp.

Referenced by vpHomography::project(), and vpMbKltTracker::setPose().

double vpCameraParameters::get_kdu ( ) const
inline

Definition at line 307 of file vpCameraParameters.h.

Referenced by vpCalibration::computeStdDeviation_dist().

double vpCameraParameters::get_kud ( ) const
inline
vpCameraParametersProjType vpCameraParameters::get_projModel ( ) const
inline

Definition at line 309 of file vpCameraParameters.h.

Referenced by vpXmlParserCamera::save().

double vpCameraParameters::get_px_inverse ( ) const
inline

Definition at line 301 of file vpCameraParameters.h.

double vpCameraParameters::get_py_inverse ( ) const
inline

Definition at line 302 of file vpCameraParameters.h.

std::vector<vpColVector> vpCameraParameters::getFovNormals ( ) const
inline

Get the list of the normals corresponding to planes describing the field of view.

  • vector[0] : Left Normal.
  • vector[1] : Right Normal.
  • vector[2] : Up Normal.
  • vector[3] : Down Normal.
See also
computeFov()
Returns
List of the normals.

Definition at line 295 of file vpCameraParameters.h.

References vpTRACE.

Referenced by vpPolygon3D::computePolygonClipped().

double vpCameraParameters::getHorizontalFovAngle ( ) const
inline

Get the horizontal angle in radian of the field of view.

Returns
FOV horizontal angle computed with px and width.
See also
computeFov(), getVerticalFovAngle()

Definition at line 267 of file vpCameraParameters.h.

References vpTRACE.

double vpCameraParameters::getVerticalFovAngle ( ) const
inline

Get the vertical angle in radian of the field of view.

Returns
FOV vertical angle computed with py and height.
See also
computeFov(), getHorizontalFovAngle()

Definition at line 279 of file vpCameraParameters.h.

References vpTRACE.

void vpCameraParameters::init ( )

basic initialization with the default parameters

Examples:
AROgre.cpp, and AROgreBasic.cpp.

Definition at line 151 of file vpCameraParameters.cpp.

References vpException::divideByZeroError, and vpERROR_TRACE.

Referenced by vpCameraParameters().

void vpCameraParameters::init ( const vpCameraParameters c)

initialization from another vpCameraParameters object

Definition at line 317 of file vpCameraParameters.cpp.

void vpCameraParameters::initFromCalibrationMatrix ( const vpMatrix _K)

initialise the camera from a calibration matrix. Using a calibration matrix leads to a camera without distortion

The K matrix in parameters must be like:

$ K = \left(\begin{array}{ccc} p_x & 0 & u_0 \\ 0 & p_y & v_0 \\ 0 & 0 & 1 \end{array} \right) $

Parameters
_K: the 3by3 calibration matrix

Definition at line 338 of file vpCameraParameters.cpp.

References vpException::badValue, vpException::dimensionError, vpArray2D< Type >::getCols(), vpArray2D< Type >::getRows(), and initPersProjWithoutDistortion().

Referenced by vpMbEdgeTracker::downScale(), and vpMbEdgeTracker::upScale().

void vpCameraParameters::initFromFov ( const unsigned int &  w,
const unsigned int &  h,
const double &  hfov,
const double &  vfov 
)

Initialize the camera model without distorsion from the image dimension and the camera field of view.

Parameters
w: Image width.
h: Image height.
hfov: Camera horizontal field of view angle expressed in radians.
vfov: Camera vertical field of view angle expressed in radians.

The following sample code shows how to use this function:

#include <visp3/core/vpCameraParameters.h>
#include <visp3/core/vpImage.h>
int main()
{
double hfov = vpMath::rad(56);
double vfov = vpMath::rad(43);
cam.initFromFov(I.getWidth(), I.getHeight(), hfov, vfov);
std::cout << cam << std::endl;
std::cout << "Field of view (horizontal: " << vpMath::deg(cam.getHorizontalFovAngle())
<< " and vertical: " << vpMath::deg(cam.getVerticalFovAngle()) << " degrees)" << std::endl;
}

It produces the following output:

Camera parameters for perspective projection without distortion:
px = 601.832 py = 609.275
u0 = 320 v0 = 240
Field of view (horizontal: 56 and vertical: 43 degrees)

Definition at line 384 of file vpCameraParameters.cpp.

References computeFov(), and perspectiveProjWithoutDistortion.

void vpCameraParameters::initPersProjWithDistortion ( const double  cam_px,
const double  cam_py,
const double  cam_u0,
const double  cam_v0,
const double  cam_kud,
const double  cam_kdu 
)

Initialization with specific parameters using perpective projection with distortion model.

Parameters
cam_px,cam_py: the ratio between the focal length and the size of a pixel.
cam_u0,cam_v0: principal points coordinates in pixels.
cam_kud: undistorted to distorted radial distortion.
cam_kdu: distorted to undistorted radial distortion.

The following sample code shows how to use this function:

#include <visp3/core/vpCameraParameters.h>
#include <visp3/core/vpImage.h>
int main()
{
double u0 = I.getWidth() / 2.;
double v0 = I.getHeight() / 2.;
double px = 600;
double py = 600;
double kud = -0.19;
double kdu = 0.20;
cam.initPersProjWithDistortion(px, py, u0, v0, kud, kdu);
cam.computeFov(I.getWidth(), I.getHeight());
std::cout << cam << std::endl;
std::cout << "Field of view (horizontal: " << vpMath::deg(cam.getHorizontalFovAngle())
<< " and vertical: " << vpMath::deg(cam.getVerticalFovAngle()) << " degrees)" << std::endl;
}

It produces the following output:

Camera parameters for perspective projection with distortion:
px = 600 py = 600
u0 = 320 v0 = 240
kud = -0.19
kdu = 0.2
Field of view (horizontal: 56.14497387 and vertical: 43.60281897 degrees)
Examples:
testUndistortImage.cpp, and tutorial-undistort.cpp.

Definition at line 275 of file vpCameraParameters.cpp.

References vpException::divideByZeroError, perspectiveProjWithDistortion, and vpERROR_TRACE.

Referenced by vpViper850::getCameraParameters(), vpViper650::getCameraParameters(), vpAfma6::getCameraParameters(), vpKinect::start(), and vpCameraParameters().

void vpCameraParameters::initPersProjWithoutDistortion ( const double  cam_px,
const double  cam_py,
const double  cam_u0,
const double  cam_v0 
)

Initialization with specific parameters using perpective projection without distortion model.

Parameters
cam_px,cam_py: the ratio between the focal length and the size of a pixel.
cam_u0,cam_v0: principal point coordinates in pixels.

The following sample code shows how to use this function:

#include <visp3/core/vpCameraParameters.h>
#include <visp3/core/vpImage.h>
int main()
{
double u0 = I.getWidth() / 2.;
double v0 = I.getHeight() / 2.;
double px = 600;
double py = 600;
cam.initPersProjWithoutDistortion(px, py, u0, v0);
cam.computeFov(I.getWidth(), I.getHeight());
std::cout << cam << std::endl;
std::cout << "Field of view (horizontal: " << vpMath::deg(cam.getHorizontalFovAngle())
<< " and vertical: " << vpMath::deg(cam.getVerticalFovAngle()) << " degrees)" << std::endl;
}

It produces the following output:

Camera parameters for perspective projection without distortion:
px = 600 py = 600
u0 = 320 v0 = 240
Field of view (horizontal: 56.145 and vertical: 43.6028 degrees)
Examples:
mbtEdgeKltTracking.cpp, mbtEdgeTracking.cpp, mbtKltTracking.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, testKeyPoint-2.cpp, testKeyPoint-4.cpp, tutorial-detection-object-mbt.cpp, tutorial-detection-object-mbt2.cpp, tutorial-mb-edge-tracker.cpp, tutorial-mb-hybrid-tracker.cpp, tutorial-mb-klt-tracker.cpp, tutorial-mb-tracker-full.cpp, and tutorial-mb-tracker.cpp.

Definition at line 206 of file vpCameraParameters.cpp.

References vpException::divideByZeroError, perspectiveProjWithoutDistortion, and vpERROR_TRACE.

Referenced by vpViper850::getCameraParameters(), vpViper650::getCameraParameters(), vpServolens::getCameraParameters(), vpAfma6::getCameraParameters(), vpSimulatorAfma6::getCameraParameters(), vpSimulatorViper850::getCameraParameters(), vpSimulatorAfma6::initDisplay(), vpSimulatorViper850::initDisplay(), initFromCalibrationMatrix(), vpMbXmlParser::read_camera(), and vpCameraParameters().

bool vpCameraParameters::isFovComputed ( ) const
inline

Specify if the fov has been computed.

See also
computeFov()
Returns
True if the fov has been computed, False otherwise.

Definition at line 256 of file vpCameraParameters.h.

Referenced by vpPolygon3D::computePolygonClipped().

vpCameraParameters & vpCameraParameters::operator= ( const vpCameraParameters cam)

copy operator

Definition at line 402 of file vpCameraParameters.cpp.

Friends And Related Function Documentation

VISP_EXPORT std::ostream& operator<< ( std::ostream &  os,
const vpCameraParameters cam 
)
friend

Print on the output stream os the camera parameters.

Parameters
os: Output stream.
cam: Camera parameters.

Definition at line 567 of file vpCameraParameters.cpp.

friend class vpMeterPixelConversion
friend

Definition at line 220 of file vpCameraParameters.h.

friend class vpPixelMeterConversion
friend

Definition at line 221 of file vpCameraParameters.h.