#include <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)

vpCameraParameters &	operator= (const vpCameraParameters &c)

virtual	~vpCameraParameters ()

void	init ()

void	init (const vpCameraParameters &c)

void	initFromCalibrationMatrix (const vpMatrix &_K)

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	getFovAngleX () const

double	getFovAngleY () const

std::vector< vpColVector >	getFovNormals () 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.

Two kinds of camera modelisation are implemented:

Camera parameters for a perspective projection without distortion model,
Camera parameters for a perspective projection with distortion model.

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})$ .

1. Camera parameters for a perspective projection without distortion model

In this modelisation, only $u_0,v_0,p_x,p_y$ parameters are used. If we denote $(u,v)$ the position of a pixel in the digitized image, this position is related to the corresponding coordinates $(x,y)$ in the normalized space (in meter) by:

$\left\{ \begin{array}{l} u = u_0 + p_x x \\ v = v_0 + p_y y \end{array}\right.$

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.

2. Camera parameters for a perspective projection with distortion model

In this modelisation, $u_0,v_0,p_x,p_y,k_{ud},k_{du}$ parameters are used. If a model with distortion is considered, we got:

$\left\{ \begin{array}{l} u = u_0 + p_x x + \delta_u \\ v = v_0 + p_y y + \delta_v \end{array}\right.$

where $\delta_u$ and $\delta_v$ are geometrical distortions introduced in the camera model. These distortions are due to imperfections in the lenses design and assembly there usually are some positional errors that have to be taken into account. $\delta_u$ and $\delta_v$ can be modeled as follow:

with an undistorted to distorted model
$\left\{ \begin{array}{l} \delta_u(x,y) = k_{ud} \;r^2\; p_x x \\ \\ \delta_v(x,y) = k_{ud}\; r^2\; p_y y \end{array}\right.$
with
$r^2 = x^2 + y^2$
This model is useful to convert meter to pixel coordinates because in this case :
$\left\{ \begin{array}{l} u = f_u(x,y) = u_0 + p_x x\left(1+k_{ud}\left(x^2 + y^2\right)\right) \\ \\ v = f_v(x,y) = v_0 + p_y y\left(1+k_{ud}\left(x^2 + y^2\right)\right) \end{array}\right.$
The conversion from normalized coordinates into pixel is implemented in vpMeterPixelConversion.
or with a distorted to undistorted model
$\left\{ \begin{array}{l} \delta_u(u,v) = -k_{du} \;r^2\; \left(u-u_0\right) \\ \\ \delta_v(u,v) = -k_{du}\; r^2\; \left(v-v_0\right) \end{array}\right.$
with
$r^2 = {\left(\frac{u-u_0}{p_{x}}\right)}^2 + {\left(\frac{v-v_0}{p_{y}}\right)}^2$
This model is useful to convert pixel to meter coordinates because in this case :
$\left\{ \begin{array}{l} x = f_x(u,v) = \frac{u-u_0}{p_x}\left(1+k_{du}\left( {\left(\frac{u-u_0}{p_{x}}\right)}^2 + {\left(\frac{v-v_0}{p_{y}}\right)}^2 \right)\right) \\ \\ y = f_y(u,v) = \frac{v-v_0}{p_y}\left(1+k_{du}\left( {\left(\frac{u-u_0}{p_{x}}\right)}^2 + {\left(\frac{v-v_0}{p_{y}}\right)}^2 \right)\right) \end{array}\right.$
The conversion from pixel coordinates in the normalized space is implemented in vpPixelMeterConversion.

The selection of one of these modelisations is done during vpCameraParameters initialisation.

Here an example of camera initialisation, for a model without distortion:

double px = 600;
double py = 600;
double u0 = 320;
double v0 = 240;
// Create a camera parameter container
vpCameraParameters cam;
// Camera initialization with a perspective projection without distortion model
cam.initPersProjWithoutDistortion(px,py,u0,v0);
// 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:

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
vpCameraParameters cam;
// 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 cam;
...
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.cpp, servoViper850Point2DCamVelocity.cpp, servoViper850Point2DCamVelocityKalman.cpp, simulateCircle2DCamVelocity.cpp, simulateFourPoints2DCartesianCamVelocity.cpp, simulateFourPoints2DPolarCamVelocity.cpp, testAfma6.cpp, testFeatureSegment.cpp, testRobotAfma6.cpp, testRobotAfma6Pose.cpp, testRobotViper850.cpp, testRobotViper850Pose.cpp, testTrackDot.cpp, testUndistortImage.cpp, testViper850.cpp, trackMeLine.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-surf-homography.cpp, tutorial-mb-edge-tracker.cpp, tutorial-mb-hybrid-tracker.cpp, tutorial-mb-klt-tracker.cpp, tutorial-pose-from-points-image.cpp, tutorial-pose-from-points-tracking.cpp, tutorial-undistort.cpp, and wireframeSimulator.cpp.

Definition at line 202 of file vpCameraParameters.h.

Member Enumeration Documentation

enum vpCameraParameters::vpCameraParametersProjType

Enumerator
perspectiveProjWithoutDistortion	Perspective projection without distortion model.
perspectiveProjWithDistortion	Perspective projection with distortion model.

Definition at line 207 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 77 of file vpCameraParameters.cpp.

References init().

vpCameraParameters::vpCameraParameters ( const vpCameraParameters & c )

Copy constructor

Definition at line 93 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 113 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 136 of file vpCameraParameters.cpp.

References initPersProjWithDistortion().

vpCameraParameters::~vpCameraParameters ( )

virtual

destructor

nothing much to destroy...

Definition at line 251 of file vpCameraParameters.cpp.

Member Function Documentation

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

Compute angles and normals of the FOV.

Parameters

w	: Width of the image
h	: Height of the image.

Definition at line 326 of file vpCameraParameters.cpp.

References vpColVector::normalize().

Referenced by vpMbtDistanceLine::display(), vpMbKltTracker::display(), vpMbtDistanceLine::initMovingEdge(), vpMbtKltPolygon::updateMask(), and vpMbtDistanceLine::updateMovingEdge().

vpMatrix vpCameraParameters::get_K ( ) const

Return the calibration matrix $K$ .

$K$ is 3x3 matrix given by:

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

Warning: : this function is useful only in the case of perspective projection without distortion.

See also: get_K_inverse()

Definition at line 388 of file vpCameraParameters.cpp.

References vpException::notImplementedError, perspectiveProjWithDistortion, perspectiveProjWithoutDistortion, vpMatrix::resize(), and vpERROR_TRACE.

Referenced by vpMbEdgeTracker::downScale(), vpPose::poseFromRectangle(), vpHomography::project(), vpMbKltTracker::setPose(), and vpMbEdgeTracker::upScale().

vpMatrix vpCameraParameters::get_K_inverse ( ) const

Return the calibration matrix $K^{-1}$ .

$K^{-1}$ is 3x3 matrix 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)$

Warning: : this function is useful only in the case of perspective projection without distortion.

See also: get_K()

Definition at line 428 of file vpCameraParameters.cpp.

References vpException::notImplementedError, perspectiveProjWithDistortion, perspectiveProjWithoutDistortion, vpMatrix::resize(), and vpERROR_TRACE.

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

double vpCameraParameters::get_kdu ( ) const

inline

Definition at line 292 of file vpCameraParameters.h.

Referenced by vpCalibration::computeStdDeviation_dist().

double vpCameraParameters::get_kud ( ) const

inline

Definition at line 291 of file vpCameraParameters.h.

Referenced by vpCalibration::computeStdDeviation_dist(), vpCalibration::displayGrid(), and vpImageTools::undistort().

vpCameraParametersProjType vpCameraParameters::get_projModel ( ) const

inline

Definition at line 294 of file vpCameraParameters.h.

Referenced by vpXmlParserCamera::save().

double vpCameraParameters::get_px ( ) const

inline

Examples:: servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, and tutorial-matching-surf-homography.cpp.

Definition at line 285 of file vpCameraParameters.h.

Referenced by vpFeatureLuminance::buildFrom(), vpMbtDistanceLine::computeInteractionMatrixError(), vpMbtDistanceCylinder::computeInteractionMatrixError(), vpCalibration::computeStdDeviation(), vpCalibration::computeStdDeviation_dist(), vpMbEdgeKltTracker::computeVVS(), vpMbKltTracker::computeVVS(), vpMbEdgeTracker::computeVVS(), vpCalibration::displayGrid(), vpMomentObject::fromImage(), vpSimulatorAfma6::initDisplay(), vpSimulatorViper850::initDisplay(), vpMbXmlParser::read_camera(), vpMbtEdgeKltXmlParser::readMainClass(), vpMbtXmlParser::readMainClass(), vpMbtKltXmlParser::readMainClass(), vpMbXmlParser::readMainClass(), vpSimulatorAfma6::setCameraParameters(), vpSimulatorViper850::setCameraParameters(), vpSimulator::setExternalCameraParameters(), vpWireFrameSimulator::setExternalCameraParameters(), vpSimulator::setInternalCameraParameters(), vpWireFrameSimulator::setInternalCameraParameters(), vpImageTools::undistort(), and vpAROgre::updateCameraProjection().

double vpCameraParameters::get_px_inverse ( ) const

inline

Definition at line 286 of file vpCameraParameters.h.

double vpCameraParameters::get_py ( ) const

inline

Examples:: servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, and servoPioneerPoint2DDepthWithoutVpServo.cpp.

Definition at line 288 of file vpCameraParameters.h.

Referenced by vpFeatureLuminance::buildFrom(), vpMbtDistanceLine::computeInteractionMatrixError(), vpMbtDistanceCylinder::computeInteractionMatrixError(), vpCalibration::computeStdDeviation(), vpCalibration::computeStdDeviation_dist(), vpCalibration::displayGrid(), vpMomentObject::fromImage(), vpSimulatorAfma6::initDisplay(), vpSimulatorViper850::initDisplay(), vpMbXmlParser::read_camera(), vpMbtEdgeKltXmlParser::readMainClass(), vpMbtXmlParser::readMainClass(), vpMbtKltXmlParser::readMainClass(), vpMbXmlParser::readMainClass(), vpSimulatorAfma6::setCameraParameters(), vpSimulatorViper850::setCameraParameters(), vpSimulator::setExternalCameraParameters(), vpWireFrameSimulator::setExternalCameraParameters(), vpSimulator::setInternalCameraParameters(), vpWireFrameSimulator::setInternalCameraParameters(), vpImageTools::undistort(), and vpAROgre::updateCameraProjection().

double vpCameraParameters::get_py_inverse ( ) const

inline

Definition at line 287 of file vpCameraParameters.h.

double vpCameraParameters::get_u0 ( ) const

inline

Examples:: servoAfma4Point2DCamVelocityKalman.cpp, and servoPioneerPanSegment3D.cpp.

Definition at line 289 of file vpCameraParameters.h.

Referenced by vpMbtDistanceLine::computeInteractionMatrixError(), vpMbtDistanceCylinder::computeInteractionMatrixError(), vpCalibration::computeStdDeviation(), vpCalibration::computeStdDeviation_dist(), vpCalibration::displayGrid(), vpMbXmlParser::read_camera(), vpMbtEdgeKltXmlParser::readMainClass(), vpMbtXmlParser::readMainClass(), vpMbtKltXmlParser::readMainClass(), vpMbXmlParser::readMainClass(), vpImageTools::undistort(), and vpAROgre::updateCameraProjection().

double vpCameraParameters::get_v0 ( ) const

inline

Examples:: servoAfma4Point2DCamVelocityKalman.cpp.

Definition at line 290 of file vpCameraParameters.h.

Referenced by vpMbtDistanceLine::computeInteractionMatrixError(), vpMbtDistanceCylinder::computeInteractionMatrixError(), vpCalibration::computeStdDeviation(), vpCalibration::computeStdDeviation_dist(), vpCalibration::displayGrid(), vpMbXmlParser::read_camera(), vpMbtEdgeKltXmlParser::readMainClass(), vpMbtXmlParser::readMainClass(), vpMbtKltXmlParser::readMainClass(), vpMbXmlParser::readMainClass(), vpImageTools::undistort(), and vpAROgre::updateCameraProjection().

double vpCameraParameters::getFovAngleX ( ) const

inline

Get the horizontal angle of the field of view.

See also: computeFov()

Returns: AngleX computed with px and width.

Definition at line 252 of file vpCameraParameters.h.

References vpTRACE.

double vpCameraParameters::getFovAngleY ( ) const

inline

Get the vertical angle of the field of view.

See also: computeFov()

Returns: AngleY computed with py and height.

Definition at line 264 of file vpCameraParameters.h.

References vpTRACE.

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 280 of file vpCameraParameters.h.

References vpTRACE.

Referenced by vpMbtPolygon::computeRoiClipped().

void vpCameraParameters::init ( )

basic initialization with the default parameters

Examples:: AROgre.cpp, and AROgreBasic.cpp.

Definition at line 155 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 259 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 280 of file vpCameraParameters.cpp.

References vpException::badValue, vpException::dimensionError, vpMatrix::getCols(), vpMatrix::getRows(), and initPersProjWithoutDistortion().

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

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	: pixel size
cam_u0,cam_v0	: principal points
cam_kud	: undistorted to distorted radial distortion
cam_kdu	: distorted to undistorted radial distortion