CameraParameters¶

class CameraParameters(*args, **kwargs)¶

Bases: pybind11_object

Generic class defining intrinsic camera parameters.

1. Supported camera models

Two camera models are implemented in ViSP.

1.1. Pinhole camera model

In this model [31] , a scene view is formed by projecting 3D points into the image plane using a perspective transformation.

\[\begin{split}\left[ \begin{array}{c} u \\v \\1 \end{array}\right] = \left[ \begin{array}{ccc} p_x & 0 & u_0 \\0 & p_y & v_0 \\0 & 0 & 1 \end{array}\right] \left[ \begin{array}{c} x \\y \\1 \end{array}\right] \end{split}\]

where:

\((X_c,Y_c,Z_c)\) are the coordinates of a 3D point in the camera frame
\((x,y)\) are the coordinates of the projection of the 3D point in the image plane
\((u,v)\) are the coordinates in pixels of the projected 3D point
\((u_0,v_0)\) are the coordinates of the principal point (the intersection of the optical axes with the image plane) that is usually near the image center
\(p_x\) (resp \(p_y\) ) is the ratio between the focal length of the lens \(f\) in meters and the size of the pixel \(l_x\) in meters: \(p_x=f/l_x\) (resp, \(l_y\) being the height of a pixel, \(p_y=f/l_y\) ).

When \(Z_c \neq 0\) , the previous equation is equivalent to the following:

\[\begin{split}\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} \end{split}\]

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

\[\begin{split}\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} \end{split}\]

where \(k_{ud}\) is the first order radial distortion. Higher order distortion 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{split}\begin{array}{lcl} x &=& (u - u_0) / p_x \\y &=& (v - v_0) / p_y \end{array} \end{split}\]

Considering radial distortion, the above model is extended as:

\[\begin{split}\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} \end{split}\]

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

The tutorial-calibration-intrinsic shows how to calibrate a camera to estimate the parameters corresponding to the model implemented in this class.

Note

Note also that tutorial-bridge-opencv gives the correspondence between ViSP and OpenCV camera modelization.

Note

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 modelization are implemented in this class:

1.1.1. Camera parameters for a perspective projection without distortion model

In this modelization, only \(u_0,v_0,p_x,p_y\) parameters are considered.

Initialization of such a model can be done using:

initPersProjWithoutDistortion() that allows to set \(u_0,v_0,p_x,p_y\) parameters;
initFromFov() that computes the parameters from an image size and a camera field of view.

1.1.2. Camera parameters for a perspective projection with distortion model

In this modelization, 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:

initPersProjWithDistortion() that allows to set \(u_0,v_0,p_x,p_y,k_{ud},k_{du}\) parameters;

The selection of the camera model (without or with distortion) 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
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. 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
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 .

1.2. Kannala-Brandt camera model

This model [20] deals with fish-eye lenses designed to cover the whole hemispherical field in front of the camera and the angle of view is very large. In this case, the inherent distortion of a fish-eye lens should not be considered only as a derivation from the pinhole model.

The following projection in the general form is adapted:

\[\begin{array}{lcl} r(\theta) &=& k_1 \theta + k_2 \theta^3 + k_3 \theta^5 + k_4 \theta^7 + k_5 \theta^9 \end{array} \]

where:

\(\theta\) is the angle in rad between a point in the real world and the optical axis.
\(r\) is the distance between the image point and the principal point.

In ViSP, we only consider radially symmetric distortions (caused by fisheye lenses).

2. JSON serialization

Since ViSP 3.6.0, if ViSP is build with soft_tool_json 3rd-party we introduce JSON serialization capabilities for vpCameraParameters . The following sample code shows how to save camera parameters in a file named cam.json and reload the parameters from this JSON file.

#include <visp3/core/vpCameraParameters.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
#if defined(VISP_HAVE_NLOHMANN_JSON)
  std::string filename = "cam.json";
  {
    // Save camera parameters in a JSON file
    vpCameraParameters cam(801, 802, 325, 245);
    std::ofstream file(filename);
    const nlohmann::json j = cam;
    file << j;
    file.close();
  }
  {
    // Load camera parameters from a JSON file
    std::ifstream file(filename);
    const nlohmann::json j = nlohmann::json::parse(file);
    vpCameraParameters cam;
    cam = j;
    file.close();
    std::cout << "Read camera parameters from " << filename << ":\n" << cam << std::endl;
  }
#endif
}

If you build and execute the sample code, it will produce the following output:

Read camera parameters from cam.json:
Camera parameters for perspective projection without distortion:
  px = 801   py = 802
  u0 = 325   v0 = 245

The content of the cam.json file is the following:

$ cat cam.json
{"model":"perspectiveWithoutDistortion","px":801.0,"py":802.0,"u0":325.0,"v0":245.0}

Overloaded function.

__init__(self: visp._visp.core.CameraParameters) -> None

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

Note

See init()

__init__(self: visp._visp.core.CameraParameters, c: visp._visp.core.CameraParameters) -> None

Copy constructor

__init__(self: visp._visp.core.CameraParameters, px: float, py: float, u0: float, v0: float) -> None

Constructor for perspective projection without distortion model

__init__(self: visp._visp.core.CameraParameters, px: float, py: float, u0: float, v0: float, kud: float, kdu: float) -> None

Constructor for perspective projection with distortion model

__init__(self: visp._visp.core.CameraParameters, px: float, py: float, u0: float, v0: float, distortion_coefficients: list[float]) -> None

Constructor for projection with Kannala-Brandt distortion model

Methods

`__init__`	Overloaded function.
`computeFov`	Compute angles and normals of the FOV.
`getFovNormals`	Get the list of the normals corresponding to planes describing the field of view.
`getHorizontalFovAngle`	Get the horizontal angle in radian of the field of view.
`getKannalaBrandtDistortionCoefficients`
`getVerticalFovAngle`	Get the vertical angle in radian of the field of view.
`get_K`	Return the camera matrix \(K\) given by:
`get_K_inverse`	Return the inverted camera matrix \(K^{-1}\) given by:
`get_kdu`
`get_kud`
`get_projModel`
`get_px`
`get_px_inverse`
`get_py`
`get_py_inverse`
`get_u0`
`get_v0`
`init`	Overloaded function.
`initFromCalibrationMatrix`	Initialise the camera from a calibration matrix.
`initFromFov`	Initialize the camera model without distortion from the image dimension and the camera field of view.The following sample code shows how to use this function:
`initPersProjWithDistortion`	Initialization with specific parameters using perspective projection with distortion model.
`initPersProjWithoutDistortion`	Initialization with specific parameters using perspective projection without distortion model.
`initProjWithKannalaBrandtDistortion`	Initialization with specific parameters using Kannala-Brandt distortion model
`isFovComputed`	Specify if the fov has been computed.
`printParameters`	Print the camera parameters on the standard output.

Inherited Methods

Operators

`__doc__`
`__eq__`	True if the two objects are absolutely identical.
`__hash__`
`__init__`	Overloaded function.
`__module__`
`__ne__`	False if the two objects are absolutely identical.
`__repr__`

Attributes

`ProjWithKannalaBrandtDistortion`
`__annotations__`
`__hash__`
`perspectiveProjWithDistortion`
`perspectiveProjWithoutDistortion`

class CameraParametersProjType(self, value: int)¶

Bases: pybind11_object

Values:

perspectiveProjWithoutDistortion: Perspective projection without distortion model.
perspectiveProjWithDistortion: Perspective projection with distortion model.
ProjWithKannalaBrandtDistortion: Projection with Kannala-Brandt distortion model.

__and__(self, other: object) → object¶

__eq__(self, other: object) → bool¶

__ge__(self, other: object) → bool¶

__getstate__(self) → int¶

__gt__(self, other: object) → bool¶

__hash__(self) → int¶

__index__(self) → int¶

__init__(self, value: int)¶

__int__(self) → int¶

__invert__(self) → object¶

__le__(self, other: object) → bool¶

__lt__(self, other: object) → bool¶

__ne__(self, other: object) → bool¶

__or__(self, other: object) → object¶

__rand__(self, other: object) → object¶

__ror__(self, other: object) → object¶

__rxor__(self, other: object) → object¶

__setstate__(self, state: int) → None¶

__xor__(self, other: object) → object¶

property name : str¶

__eq__(self, c: visp._visp.core.CameraParameters) → bool¶: True if the two objects are absolutely identical.

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: visp._visp.core.CameraParameters) -> None

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

Note

See init()

__init__(self: visp._visp.core.CameraParameters, c: visp._visp.core.CameraParameters) -> None

Copy constructor

__init__(self: visp._visp.core.CameraParameters, px: float, py: float, u0: float, v0: float) -> None

Constructor for perspective projection without distortion model

__init__(self: visp._visp.core.CameraParameters, px: float, py: float, u0: float, v0: float, kud: float, kdu: float) -> None

Constructor for perspective projection with distortion model

__init__(self: visp._visp.core.CameraParameters, px: float, py: float, u0: float, v0: float, distortion_coefficients: list[float]) -> None

Constructor for projection with Kannala-Brandt distortion model

__ne__(self, c: visp._visp.core.CameraParameters) → bool¶: False if the two objects are absolutely identical.

computeFov(self, w: int, h: int) → None¶

Compute angles and normals of the FOV.

Parameters:

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

getFovNormals(self) → list[visp._visp.core.ColVector]¶

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.

Returns:: List of the normals.

getHorizontalFovAngle(self) → float¶

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

Note

See computeFov() , getVerticalFovAngle()

Returns:: FOV horizontal angle computed with px and width.

getKannalaBrandtDistortionCoefficients(self) → list[float]¶

getVerticalFovAngle(self) → float¶

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

Note

See computeFov() , getHorizontalFovAngle()

Returns:: FOV vertical angle computed with py and height.

get_K(self) → visp._visp.core.Matrix¶

Return the camera matrix \(K\) given by:

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

Note

See get_K_inverse()

get_K_inverse(self) → visp._visp.core.Matrix¶

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]\)

Note

See get_K()

get_kdu(self) → float¶

get_kud(self) → float¶

get_projModel(self) → visp._visp.core.CameraParameters.CameraParametersProjType¶

get_px(self) → float¶

get_px_inverse(self) → float¶

get_py(self) → float¶

get_py_inverse(self) → float¶

get_u0(self) → float¶

get_v0(self) → float¶

init(*args, **kwargs)¶

Overloaded function.

init(self: visp._visp.core.CameraParameters) -> None

Basic initialization with the default parameters.

init(self: visp._visp.core.CameraParameters, c: visp._visp.core.CameraParameters) -> None

Initialization from another vpCameraParameters object.

initFromCalibrationMatrix(self, _K: visp._visp.core.Matrix) → None¶

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)\)

initFromFov(self, w: int, h: int, hfov: float, vfov: float) → None¶

Initialize the camera model without distortion from the image dimension and the camera field of view.The following sample code shows how to use this function:

#include <visp3/core/vpCameraParameters.h>
#include <visp3/core/vpImage.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpImage<unsigned char> I(480, 640);
  vpCameraParameters cam;
  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)

Parameters:

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

initPersProjWithDistortion(self, px: float, py: float, u0: float, v0: float, kud: float, kdu: float) → None¶

Initialization with specific parameters using perspective projection with distortion model.

The following sample code shows how to use this function:

#include <visp3/core/vpCameraParameters.h>
#include <visp3/core/vpImage.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpImage<unsigned char> I(480, 640);
  double u0 = I.getWidth()  / 2.;
  double v0 = I.getHeight() / 2.;
  double px = 600;
  double py = 600;
  double kud = -0.19;
  double kdu = 0.20;
  vpCameraParameters cam;
  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)

initPersProjWithoutDistortion(self, px: float, py: float, u0: float, v0: float) → None¶

Initialization with specific parameters using perspective projection without distortion model.

The following sample code shows how to use this function:

#include <visp3/core/vpCameraParameters.h>
#include <visp3/core/vpImage.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpImage<unsigned char> I(480, 640);
  double u0 = I.getWidth()  / 2.;
  double v0 = I.getHeight() / 2.;
  double px = 600;
  double py = 600;
  vpCameraParameters cam;
  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)

initProjWithKannalaBrandtDistortion(self, px: float, py: float, u0: float, v0: float, distortion_coefficients: list[float]) → None¶: Initialization with specific parameters using Kannala-Brandt distortion model

isFovComputed(self) → bool¶

Specify if the fov has been computed.

Returns:: True if the fov has been computed, False otherwise.

printParameters(self) → None¶: Print the camera parameters on the standard output.

Note

See operator<<(std::ostream &, const vpCameraParameters &)

__hash__ = None¶