Distortion¶
-
struct DistortionCoefficients¶
Base class for distortion coefficient sets.
Provides a polymorphic interface for all distortion coefficient types.
Subclassed by huira::BrownCoefficients, huira::OpenCVCoefficients, huira::OwenCoefficients
Public Functions
-
DistortionCoefficients() = default¶
-
DistortionCoefficients(const DistortionCoefficients&) = default¶
-
DistortionCoefficients &operator=(const DistortionCoefficients&) = default¶
-
virtual ~DistortionCoefficients() = default¶
-
DistortionCoefficients() = default¶
-
template<IsSpectral TSpectral>
class Distortion¶ Abstract base class for lens distortion models.
Defines the interface for all distortion models, including distortion/undistortion and coefficient access.
Both work in normalized image coordinates. distort() maps an ideal (pinhole) point to where the lens images it. The lens images the region around the optical axis where the model is one-to-one: out from the axis until the model folds over (its Jacobian determinant is no longer positive) or, for a rational model, reaches a pole. undistort() inverts distort() on that region, and returns NaN in both coordinates where there is no inverse: beyond the furthest point the lens reaches, since no ray images there.
- Template Parameters:
TSpectral – The spectral type (e.g., RGB, Visible8)
Subclassed by huira::BrownDistortion< TSpectral >, huira::OpenCVDistortion< TSpectral >, huira::OwenDistortion< TSpectral >
Public Functions
-
Distortion() = default¶
-
virtual ~Distortion() = default¶
-
virtual DistortionCoefficients *get_coefficients() = 0¶
-
virtual const DistortionCoefficients *get_coefficients() const = 0¶
-
virtual std::string get_type_name() const = 0¶
-
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_¶