Brown Distortion Model¶
-
struct BrownCoefficients : public huira::DistortionCoefficients¶
Coefficients for Brown lens distortion model.
Holds the radial (k1, k2, k3) and tangential (p1, p2) distortion coefficients.
-
template<IsSpectral TSpectral>
class BrownDistortion : public huira::Distortion<TSpectral>¶ Brown lens distortion model.
Implements the Brown-Conrady distortion model with radial and tangential coefficients.
- Template Parameters:
TSpectral – The spectral type (e.g., RGB, Visible8)
Public Functions
-
BrownDistortion() = default¶
-
explicit BrownDistortion(BrownCoefficients coefficients)¶
Constructs a BrownDistortion with the given coefficients.
- Parameters:
coefficients – The Brown distortion coefficients (radial and tangential).
- Throws:
std::runtime_error – if any coefficient is not finite.
-
virtual Pixel distort(Pixel homogeneous_coords) const override¶
Applies Brown distortion to the given pixel coordinates.
Computes the distorted coordinates by adding the Brown distortion delta.
- Parameters:
homogeneous_coords – The input pixel coordinates (homogeneous).
- Returns:
The distorted pixel coordinates.
-
virtual Pixel undistort(Pixel homogeneous_coords) const override¶
Removes the Brown 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_¶