OpenCV Distortion Model¶

struct OpenCVCoefficients : public huira::DistortionCoefficients ¶

Coefficients for OpenCV lens distortion model.

Holds the radial, tangential, and thin prism distortion coefficients for the OpenCV model.

The constructor takes them grouped by kind (k1 to k6, then p1, p2, then s1 to s4), which is not the order of OpenCV’s distortion vector. For a vector from OpenCV (k1, k2, p1, p2, k3, …), use from_opencv().

Public Functions

OpenCVCoefficients() = default¶

inline constexpr OpenCVCoefficients(double k1_val, double k2_val, double k3_val, double k4_val, double k5_val, double k6_val, double p1_val, double p2_val, double s1_val, double s2_val, double s3_val, double s4_val)¶

Public Members

double k1 = 0¶

double k2 = 0¶

double k3 = 0¶

double k4 = 0¶

double k5 = 0¶

double k6 = 0¶

double p1 = 0¶

double p2 = 0¶

double s1 = 0¶

double s2 = 0¶

double s3 = 0¶

double s4 = 0¶

Public Static Functions

static inline OpenCVCoefficients from_opencv(std::span<const double> coefficients)¶

Coefficients from a distortion vector as OpenCV gives it: (k1, k2, p1, p2[, k3[, k4, k5, k6[, s1, s2, s3, s4[, tau_x, tau_y]]]]), of 4, 5, 8, 12 or 14 elements.

Throws:: std::runtime_error – for any other length, or non-zero tilt terms (tau_x, tau_y), since a tilted sensor is not modelled.

template<IsSpectral TSpectral> class OpenCVDistortion : public huira::Distortion<TSpectral>¶

OpenCV lens distortion model.

Implements the OpenCV distortion model with rational radial, tangential, and thin prism coefficients.

The rational radial factor (1 + k1 r^2 + k2 r^4 + k3 r^6) / (1 + k4 r^2 + k5 r^4 + k6 r^6) has a pole where its denominator reaches 0, which can lie not far beyond the field a calibration with k4 to k6 was fitted to. The lens images nothing past it: distort() and undistort() return NaN there.

Template Parameters:: TSpectral – The spectral type (e.g., RGB, Visible8)

Public Functions

OpenCVDistortion() = default¶

explicit OpenCVDistortion(OpenCVCoefficients coefficients)¶

Constructs an OpenCVDistortion with the given coefficients.

Parameters:: coefficients – The OpenCV distortion coefficients (radial, tangential, thin prism).
Throws:: std::runtime_error – if any coefficient is not finite.

virtual Pixel distort(Pixel homogeneous_coords) const override¶

Applies OpenCV distortion to the given pixel coordinates.

Computes the distorted coordinates by adding the OpenCV distortion delta.

Parameters:: homogeneous_coords – The input pixel coordinates (homogeneous).
Returns:: The distorted pixel coordinates, or NaN in both where the rational radial factor’s denominator is not positive: at or past its pole, where the lens images nothing.

virtual Pixel undistort(Pixel homogeneous_coords) const override¶

Removes the OpenCV distortion from normalized image coordinates.

Inverts distort() by Newton’s method (see Distortion::undistort_newton_()).

Parameters:: homogeneous_coords – The distorted point, in normalized image coordinates.
Returns:: The undistorted point, or NaN in both coordinates where the distortion has no inverse.

inline virtual std::string get_type_name() const override¶

inline virtual DistortionCoefficients *get_coefficients() override¶

inline virtual const DistortionCoefficients *get_coefficients() const override¶

inline void set_max_iterations(std::size_t max_iters)¶: Set the most iterations undistort() takes; at least 1. The default, 50, is more than twice what the hardest points of strongly distorted lenses take; most take 3 or 4.

inline std::size_t get_max_iterations() const¶

inline void set_tolerance(float tol)¶: Set the convergence tolerance of undistort(): how close, in normalized image coordinates, the undistorted point must distort back to the one given. Positive and finite.

inline float get_tolerance() const¶

Protected Functions

template<typename TDistort> inline Pixel undistort_newton_(Pixel target, const TDistort &distort) const¶

Invert a distortion by Newton’s method: find the point that distorts to target.

The inverse is the point in the region the lens images: around the optical axis, out to where the distortion folds over or reaches a pole (see Distortion). So the iteration starts on the axis, (0, 0), and only takes steps that stay in that region. Each step solves the linearized distortion, with the Jacobian taken by forward differences, and is halved until the point it reaches:

is not folded over: the Jacobian determinant there is positive;
has not been carried back through the axis: its distorted point lies away from the axis’s on the same side as the point itself;
is where the linearized distortion said it would be, to within half the step: a Newton step scaled by t leaves (1 - t) of the residual. A step that lands far from that has crossed a fold or a pole, or jumped onto another sheet of the model, where it could converge to a point that distorts to the target but is not in the image. This also makes every step bring the point closer;
and whose midpoint is unfolded and where the linearized distortion puts it, likewise: a step can otherwise jump right across a folded band onto a sheet beyond it that unfolds again (barrel distortion whose higher terms turn it back outwards), and land near the target there.

Starting from the target, as before, failed for pincushion distortion that folds just beyond the image: the image’s edge distorts outwards past the fold, so the iteration started folded over, with no step that brings the point closer, and returned NaN for a point with an inverse. Its fallback, stepping by the residual where the Jacobian was folded, could also cross the fold and converge on the wrong sheet without any sign.

Parameters:

target – The distorted point, in normalized image coordinates.
distort – The distortion in double precision: a callable taking and returning Pixel_d. It may return NaN where the model has no image, e.g. past a pole.

Returns:

The undistorted point, or NaN in both coordinates when there is none: no step gets closer to the target without leaving the region, or the iteration did not converge to within the tolerance in max_iterations_ steps.

Protected Attributes

std::size_t max_iterations_ = 50¶

double tolerance_ = 1e-9¶

double tol_sq_ = tolerance_ * tolerance_¶

Protected Static Functions

static inline void check_coefficients_(std::initializer_list<double> coefficients, const std::string &caller)¶: Throws if any coefficient is not finite, in single precision too, in which distort() takes them.