class mrpt::img::TCamera

Overview

Intrinsic parameters for a pinhole or fisheye camera model, along with the associated lens distortion model.

The camera projection follows the standard pinhole model:

• 3D point in camera frame: P_cam = (X, Y, Z)

• Normalized image coordinates: x = X/Z, y = Y/Z

• Apply distortion to get: (x_d, y_d)

• Project to pixel coordinates: u = fx*x_d + cx, v = fy*y_d + cy

The distortion model is specified by the distortion field and can be:

• DistortionModel::none : No distortion (already rectified images)

• DistortionModel::plumb_bob : Standard radial-tangential distortion (OpenCV model)

• DistortionModel::kannala_brandt : Fish-eye camera model

Parameters calibrated for one camera resolution can be scaled to other resolutions using TCamera::scaleToResolution(), which preserves the aspect ratio.

See also:

The application camera-calib-gui for camera calibration

mrpt::img::camera_geometry for projection and undistortion functions

#include <mrpt/img/TCamera.h>

class TCamera: public mrpt::serialization::CSerializable
{
public:
    // typedefs

    typedef std::shared_ptr<mrpt::img ::TCamera> Ptr;
    typedef std::shared_ptr<const mrpt::img ::TCamera> ConstPtr;
    typedef std::unique_ptr<mrpt::img ::TCamera> UniquePtr;
    typedef std::unique_ptr<const mrpt::img ::TCamera> ConstUniquePtr;

    // fields

    static constexpr const char* className = "mrpt::img" "::" "TCamera";
    uint32_t ncols = 640;
    uint32_t nrows = 480;
    mrpt::math::CMatrixDouble33 intrinsicParams;
    DistortionModel distortion = DistortionModel::none;
    std::array<double, 8> dist {       {.0, .0, .0, .0, .0, .0, .0, .0}   };
    double focalLengthMeters = .0;
    std::string cameraName = "camera1";

    // construction

    TCamera();

    // methods

    static constexpr auto getClassName();
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();
    static std::shared_ptr<CObject> CreateObject();

    template <typename... Args>
    static Ptr Create(Args&&... args);

    template <typename Alloc, typename... Args>
    static Ptr CreateAlloc(
        const Alloc& alloc,
        Args&&... args
        );

    template <typename... Args>
    static UniquePtr CreateUnique(Args&&... args);

    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    virtual mrpt::rtti::CObject* clone() const;
    double cx() const;
    double cy() const;
    double fx() const;
    double fy() const;
    void cx(double val);
    void cy(double val);
    void fx(double val);
    void fy(double val);
    double k1() const;
    double k2() const;
    double p1() const;
    double p2() const;
    double k3() const;
    double k4() const;
    double k5() const;
    double k6() const;
    void k1(double val);
    void k2(double val);
    void p1(double val);
    void p2(double val);
    void k3(double val);
    void k4(double val);
    void k5(double val);
    void k6(double val);
    static TCamera FromYAML(const mrpt::containers::yaml& params);
    mrpt::containers::yaml asYAML() const;
    void scaleToResolution(unsigned int new_ncols, unsigned int new_nrows);
    void saveToConfigFile(const std::string& section, mrpt::config::CConfigFileBase& cfg) const;
    void loadFromConfigFile(const std::string& section, const mrpt::config::CConfigFileBase& cfg);
    void loadFromConfigFile(const mrpt::config::CConfigFileBase& cfg, const std::string& section);
    std::string dumpAsText() const;
    void setIntrinsicParamsFromValues(double fx, double fy, double cx, double cy);
    std::vector<double> getDistortionParamsAsVector() const;
    mrpt::math::CMatrixDouble getDistortionParamsAsRowVector() const;

    template <class VECTORLIKE>
    void setDistortionParamsVector(const VECTORLIKE& distParVector);

    void setDistortionPlumbBob(double k1_, double k2_, double p1_, double p2_, double k3_ = 0);
    void setDistortionKannalaBrandt(double k1_, double k2_, double k3_, double k4_);
};

Inherited Members

public:
    // typedefs

    typedef std::shared_ptr<CObject> Ptr;
    typedef std::shared_ptr<const CObject> ConstPtr;
    typedef std::shared_ptr<CSerializable> Ptr;
    typedef std::shared_ptr<const CSerializable> ConstPtr;

    // methods

    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();
    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();

Typedefs

typedef std::shared_ptr<mrpt::img ::TCamera> Ptr

A type for the associated smart pointer.

Fields

uint32_t ncols = 640

Image resolution in pixels.

mrpt::math::CMatrixDouble33 intrinsicParams

Camera intrinsic matrix (calibration matrix) in the standard form:

    [ fx   0  cx ]
K = [  0  fy  cy ]
    [  0   0   1 ]

where:

• fx, fy: focal length in pixels (horizontal and vertical)

• cx, cy: principal point coordinates in pixels

See: https://www.mrpt.org/Camera_Parameters

DistortionModel distortion = DistortionModel::none

The lens distortion model type.

Determines how to interpret the dist coefficients.

std::array<double, 8> dist {       {.0, .0, .0, .0, .0, .0, .0, .0}   }

Distortion coefficients.

Interpretation depends on distortion:

• DistortionModel::none : Coefficients ignored (rectified image)

• DistortionModel::plumb_bob : Standard radial-tangential model (OpenCV compatible)

  • Format: [k1, k2, p1, p2, k3, k4, k5, k6]

  • k1, k2, k3, k4, k5, k6: Radial distortion coefficients

  • p1, p2: Tangential distortion coefficients

  • Distortion equations:

    • r² = x² + y²

    • x_d = x(1 + k1·r² + k2·r⁴ + k3·r⁶)/(1 + k4·r² + k5·r⁴ + k6·r⁶) + 2p1·xy + p2(r² + 2x²)

    • y_d = y(1 + k1·r² + k2·r⁴ + k3·r⁶)/(1 + k4·r² + k5·r⁴ + k6·r⁶) + p1(r² + 2y²) + 2p2·xy

• DistortionModel::kannala_brandt : Fish-eye model

  • Format: [k1, k2, *, *, k3, k4, *, *] (indices 2,3,6,7 unused)

  • Distortion equations:

    • θ = atan(r), where r = sqrt(x² + y²)

    • θ_d = θ(1 + k1·θ² + k2·θ⁴ + k3·θ⁶ + k4·θ⁸)

    • x_d = (θ_d/r)·x, y_d = (θ_d/r)·y

Recommended : Use getter/setter methods k1(), k2(), p1(), p2(), etc. to avoid indexing errors.

Default: all zeros (no distortion)

double focalLengthMeters = .0

Physical focal length in meters (optional).

Can be used with intrinsicParams to compute physical pixel size.

std::string cameraName = "camera1"

Optional descriptive camera name (e.g., “left_camera”, “front_cam”).

Construction

TCamera()

Default constructor: all intrinsic parameters set to zero.

Methods

virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const

Returns information about the class of an object in runtime.

virtual mrpt::rtti::CObject* clone() const

Returns a deep copy (clone) of the object, indepently of its class.

static TCamera FromYAML(const mrpt::containers::yaml& params)

Parse camera parameters from YAML in OpenCV calibration format.

Refer to this example.

For supported distortion models see mrpt::img::DistortionModel

mrpt::containers::yaml asYAML() const

Export camera parameters as YAML in OpenCV calibration format.

Refer to this example.

void scaleToResolution(unsigned int new_ncols, unsigned int new_nrows)

Scale all parameters to a new image resolution.

Rescale all the parameters for a new camera resolution (it raises an exception if the aspect ratio is modified, which is not permitted).

Throws an exception if the aspect ratio changes, as this would invalidate the calibration.

Parameters:

new_ncols	New image width in pixels
new_nrows	New image height in pixels

void saveToConfigFile(const std::string& section, mrpt::config::CConfigFileBase& cfg) const

Save camera parameters to a configuration file section in the format:

Save as a config block:

[SECTION]
resolution = [NCOLS NROWS]
cx         = CX
cy         = CY
fx         = FX
fy         = FY
dist       = [K1 K2 P1 P2 K3 K4 K5 K6]
camera_name = camera1
distortion = {none|plumb_bob|kannala_brandt}
focal_length = FOCAL_LENGTH  [optional]

[SECTION]
resolution = NCOLS NROWS
cx         = CX
cy         = CY
fx         = FX
fy         = FY
dist       = K1 K2 T1 T2 T3
focal_length = FOCAL_LENGTH

void loadFromConfigFile(const std::string& section, const mrpt::config::CConfigFileBase& cfg)

Load camera parameters from a configuration file section.

Load all the params from a config source, in the format described in saveToConfigFile()

See saveToConfigFile() for the expected format.

Parameters:

std::exception

on missing required fields

void loadFromConfigFile(const mrpt::config::CConfigFileBase& cfg, const std::string& section)

Overload with swapped parameter order (consistent with other MRPT APIs)

std::string dumpAsText() const

Return all parameters as a formatted text block in INI file format.

Dumps all the parameters as a multi-line string, with the same format than saveToConfigFile.

See also:

asYAML()

saveToConfigFile

void setIntrinsicParamsFromValues(double fx, double fy, double cx, double cy)

Set intrinsic matrix from individual focal length and principal point values.

Parameters:

fx	Focal length in pixels (horizontal)
fy	Focal length in pixels (vertical)
cx	Principal point x-coordinate in pixels
cy	Principal point y-coordinate in pixels

std::vector<double> getDistortionParamsAsVector() const

Get distortion coefficients as a vector.

Returns an appropriately-sized vector based on distortion:

• DistortionModel::none : empty vector

• DistortionModel::plumb_bob : 5 or 8 elements

• DistortionModel::kannala_brandt : 4 elements

mrpt::math::CMatrixDouble getDistortionParamsAsRowVector() const

Equivalent to getDistortionParamsAsVector() but returns a row matrix.

template <class VECTORLIKE>
void setDistortionParamsVector(const VECTORLIKE& distParVector)

Set distortion coefficients from a vector.

Parameters:

distParVector

Vector of 4, 5, or 8 distortion coefficients

void setDistortionPlumbBob(
    double k1_,
    double k2_,
    double p1_,
    double p2_,
    double k3_ = 0
    )

Configure plumb_bob distortion model with specified parameters.

Parameters:

k1_	First radial distortion coefficient
k2_	Second radial distortion coefficient
p1_	First tangential distortion coefficient
p2_	Second tangential distortion coefficient
k3_	Third radial distortion coefficient (optional, default=0)

void setDistortionKannalaBrandt(double k1_, double k2_, double k3_, double k4_)

Configure Kannala-Brandt fish-eye distortion model.

Parameters:

k1_	First distortion coefficient
k2_	Second distortion coefficient
k3_	Third distortion coefficient
k4_	Fourth distortion coefficient