Owen Distortion Model¶
-
struct OwenCoefficients : public huira::DistortionCoefficients¶
Coefficients for Owen lens distortion model.
Holds the coefficients for the Owen distortion model, including both coordinate-aligned and rotated terms.
-
template<IsSpectral TSpectral>
class OwenDistortion : public huira::Distortion<TSpectral>¶ Owen lens distortion model.
Implements the Owen distortion model with both coordinate-aligned and rotated terms.
- Template Parameters:
TSpectral – The spectral type (e.g., RGB, Visible8)
Public Functions
-
OwenDistortion() = default¶
-
explicit OwenDistortion(OwenCoefficients coefficients)¶
Constructs an OwenDistortion with the given coefficients.
- Parameters:
coefficients – The Owen distortion coefficients.
- Throws:
std::runtime_error – if any coefficient is not finite.
-
virtual Pixel distort(Pixel homogeneous_coords) const override¶
Applies Owen distortion to the given pixel coordinates.
Computes the distorted coordinates by adding the Owen 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 Owen 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_¶