Class libCalibGeom::CameraModelBSplineWarp

B-Spline Camera Model with image space warp

This is Calib.io's fast pixel-space B-Spline camera model that operates by warping 2D image coordinates using bicubic B-spline surfaces. It models lens distortion as a smooth 2D deformation field in image space, making it highly efficient for pinhole-like lenses with moderate distortion.

[unprojectPoint()](a00998.md#a00998_1a2ec70d32f07ce3c9c715dc7f6ed47684) returns unit bearing vectors and the unprojection maps expose the same direction as three component images. When nonCentral is enabled, the model remains useful for near-central cameras, but unprojection maps still encode direction only and do not capture any per-pixel ray origin.

The model uses a 2D grid of B-spline control points to define displacement vectors at each pixel location. This provides smooth, continuously differentiable distortion correction with excellent numerical stability and convergence properties during optimization.

Knot Count Configuration:The resolution of the B-spline grid (number of knots) is configurable at construction time via CameraModelConfig: nKnotsX: Number of knots along the horizontal dimension (default: 16) nKnotsY: Number of knots along the vertical dimension (default: 12) nonCentral: Enables two low-order non-central axial coefficients g2, g4, evaluated on the central-model normalized radius, suitable for near-central cameras (default: true)

Higher knot counts provide more flexibility for modeling complex distortions but increase the parameter count. Typical values range from 8-20 knots depending on image resolution and lens complexity. The aspect ratio of the knot grid typically matches the image aspect ratio.

Performance:Faster than CameraModelBSplineRay due to direct image-space operations. Well-suited for standard rectilinear lenses, telecentric lenses, and lenses with moderate barrel or pincushion distortion.

Limitations:Not recommended for extreme wide-angle or fisheye lenses where the image warp may become highly non-linear. For such cases, prefer CameraModelBSplineRay which operates in ray space.

Undistortion maps are produced by rectifying to a close linear virtual camera with origin fixed at (0, 0, 0). The corresponding virtual rays are parameterized by their intersection with the plane Z==1. This is exact when nonCentral is disabled and an approximation otherwise.

CameraModelBSplineRay for a more general ray-based variant

Inherits from: public libCalibGeom::CameraModelCRT< CameraModelBSplineWarp >

Constructors and destructors

CameraModelBSplineWarp()

CameraModelBSplineWarp()

Returns:

void

CameraModelBSplineWarp()

CameraModelBSplineWarp(const ImageSize imageSize,const CameraModelConfig & config = {})

Returns:

void

Public member functions

getUndistortionMaps()

voidgetUndistortionMaps(Image< float > &mapU, Image< float > &mapV, Matrix< double, 3, 3 > &K) const override

Computes undistortion maps and the new camera matrix.

The returned maps define a source-image remap induced by a default virtual linear camera. For each output pixel, K maps the pixel to a point on the virtual camera plane at Z==1, which in turn defines the corresponding virtual camera ray. The maps contain the source-image lookup coordinates produced by projecting that ray through the camera model.

For central models this rectification is exact. For non-central models, a single depth-independent 2D remap is only an approximation, so the result should be interpreted as a convenient best-fit rectification.

Parameters:

mapU	Map for u-coordinates.
mapV	Map for v-coordinates.
K	New camera matrix.

Returns:

void

getUnprojectionMaps()

voidgetUnprojectionMaps(Image< float > &mapX, Image< float > &mapY, Image< float > &mapZ) const override

Computes 3-channel bearing-vector maps.

The returned maps store the unit ray direction (X, Y, Z) associated with each pixel.

For non-central models, these maps describe direction only and do not encode any per-pixel ray origin. Use getRayMaps() for the full geometry.

Parameters:

mapX	Map for X-components.
mapY	Map for Y-components.
mapZ	Map for Z-components.

Returns:

void

regularizationFunction()

std::unique_ptr< ceres::CostFunction >regularizationFunction(const int nResiduals) const override

Creates a regularization cost function.

Parameters:

nResiduals

Number of residuals to regularize over.

Returns:

std::unique_ptr< ceres::CostFunction >

toString()

std::stringtoString() const override

Returns a string representation of the model parameters.

Returns:

std::string

project()

boolproject(const T &X, const T &Y, const T &Z, T &c, T &r, const T *params) const

Returns:

bool

unproject()

boolunproject(const T &u, const T &v, T &X, T &Y, T &Z, const T *params) const

Returns:

bool

project()

boolproject(double X, double Y, double Z, double &u, double &v) const

Returns:

bool

unproject()

boolunproject(double u, double v, double &X, double &Y, double &Z) const

Returns:

bool

nKnotsX()

intnKnotsX() const

Returns:

int

nKnotsY()

intnKnotsY() const

Returns:

int

nonCentral()

boolnonCentral() const

Returns:

bool

config()

CameraModelConfigconfig() const override

Returns the parameters needed to reconstruct this model layout.

Returns:

CameraModelConfig

isCentral()

boolisCentral() const override

Returns whether the model is central.

Central models have a single ray origin at (0, 0, 0) for all pixels. Non-central models may expose per-pixel ray origins via unprojectRay() and getRayMaps().

Returns:

bool

unprojectRay()

boolunprojectRay(const double &u, const double &v, Point3 &origin, Point3 &direction) const override

Unprojects an image point (u, v) into a full 3D ray.

For central models, the ray origin is (0, 0, 0) and the direction is a unit bearing vector. Models with non-zero per-pixel ray origins should override this function to return the full ray geometry.

Parameters:

u	Horizontal image coordinate.
v	Vertical image coordinate.
origin	Ray origin in camera coordinates.
direction	Unit ray direction in camera coordinates.

Returns:

bool	True if unprojection was successful.

initialize()

boolinitialize(const std::vector< std::vector< Point3 >> &worldPoints, const std::vector< std::vector< Point2 >> &imagePoints, std::vector< Rotation > &Rc, std::vector< Translation > &Tc, const InitializationMethod method) override

Initializes the model from calibration observations.

Returns:

bool

Public data members

parameters

CameraParametersparameters

No documentation provided.

Public Static Attributes

hasDynamicParameterCount

constexpr boolhasDynamicParameterCount

No documentation provided.

Public Static Functions

name()

const std::stringname()

Returns:

const std::string