Distortion Models

RadialDistortion

Brown-Conrady radial+tangential distortion model.

x_d = x · (1 + k1·r² + k2·r⁴ + k3·r⁶) + 2·p1·x·y + p2·(r² + 2·x²) y_d = y · (1 + k1·r² + k2·r⁴ + k3·r⁶) + p1·(r² + 2·y²) + 2·p2·x·y

Coordinates are in pixels, origin at the image center; the model shifts into its own center frame (the optical axis, (0, 0) by default) internally. Tangential coefficients p1, p2 default to 0 — set them to model lens decentering or sensor tilt. On mosaic cameras (e.g. TESS) the optical axis can sit far off the detector center — center carries that offset. Supports pickle serialization.

Example::

d = tetra3rs.RadialDistortion(k1=-7e-9, k2=2e-15)
d = tetra3rs.RadialDistortion(k1=-7e-9, p1=5e-7, p2=-3e-7)
x_undistorted, y_undistorted = d.undistort(100.0, 200.0)

References

• Conrady, A. E. (1919). "Decentred Lens-Systems." Monthly Notices of the Royal Astronomical Society, 79(5): 384-390. — Original derivation of the tangential / decentering form. https://doi.org/10.1093/mnras/79.5.384
• Brown, D. C. (1966). "Decentering Distortion of Lenses." Photogrammetric Engineering, 32(3): 444-462. — Modernized form.
• Brown, D. C. (1971). "Close-Range Camera Calibration." Photogrammetric Engineering, 37(8): 855-866. — Calibration procedure.
• Zhang, Z. (2000). "A Flexible New Technique for Camera Calibration." IEEE TPAMI, 22(11): 1330-1334. — Multi-image planar calibration (the standard method, used in OpenCV calibrateCamera). https://doi.org/10.1109/34.888718
• OpenCV documentation for the equivalent (k1, k2, k3, p1, p2) formulation: https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html

k1 property

First radial coefficient.

k2 property

Second radial coefficient.

k3 property

Third radial coefficient.

p1 property

First tangential / decentering coefficient.

p2 property

Second tangential / decentering coefficient.

center property

Distortion center (optical axis) as (cx, cy) in pixels, image-center-origin frame.

distort(x, y)

Forward distortion: ideal → distorted.

undistort(x, y)

Inverse distortion: distorted → ideal.

PolynomialDistortion

SIP-like polynomial distortion model with independent x,y correction terms.

Forward: x_d = x + Σ A_pq · (x/s)^p · (y/s)^q (0 ≤ p+q ≤ order) Inverse: x_i = x_d + Σ AP_pq · (x_d/s)^p · (y_d/s)^q

Where s = scale = image_width/2.

Includes all polynomial terms from order 0

• (p+q = 0): constant offset — optical center shift
• (p+q = 1): linear terms — residual scale & rotation
• (p+q ≥ 2): higher-order distortion

Total coefficients per axis: (order+1)(order+2)/2.

Typically constructed by SolverDatabase.calibrate_camera() (which fits the polynomial internally and returns it via the camera model), or directly from coefficient arrays (e.g. extracted from a FITS WCS SIP model). Supports pickle serialization.

References

• Shupe, D. L.; Moshir, M.; Li, J.; Makovoz, D.; Narron, R.; Hook, R. N. (2005). "The SIP Convention for Representing Distortion in FITS Image Headers." Astronomical Data Analysis Software and Systems XIV, ASP Conference Series, 347: 491. — Original SIP specification. https://www.adass.org/adass/proceedings/adass04/reprints/P3-1-3.pdf
• FITS WCS SIP convention registry entry: https://fits.gsfc.nasa.gov/registry/sip.html

The convention here is SIP-like — same A_pq, B_pq polynomial basis on normalized pixel coordinates. Standard SIP starts at order 2 (the linear part is absorbed into the WCS CD matrix); this implementation also includes order 0 / 1 terms so a single fit can absorb optical- center offset and residual scale/rotation from the matched-points data.

order property

Polynomial order.

scale property

Normalization scale (typically image_width / 2).

num_coeffs property

Number of polynomial coefficients per axis.

a_coeffs property

Forward A coefficients (x correction, ideal → distorted).

b_coeffs property

Forward B coefficients (y correction, ideal → distorted).

ap_coeffs property

Inverse AP coefficients (x correction, distorted → ideal).

bp_coeffs property

Inverse BP coefficients (y correction, distorted → ideal).

__init__(order, scale, a_coeffs, b_coeffs, ap_coeffs, bp_coeffs)

Create a polynomial distortion model from coefficient arrays.

Each coefficient array must have exactly (order+1)(order+2)/2 elements, covering all terms from p+q=0 (constant offset) through p+q=order.

Parameters:

Name	Type	Description	Default
order	int	Polynomial order (2–6 typical).	required
scale	float	Normalization scale (typically image_width / 2).	required
a_coeffs	list[float]	Forward A coefficients (x correction, ideal → distorted).	required
b_coeffs	list[float]	Forward B coefficients (y correction, ideal → distorted).	required
ap_coeffs	list[float]	Inverse AP coefficients (x correction, distorted → ideal).	required
bp_coeffs	list[float]	Inverse BP coefficients (y correction, distorted → ideal).	required

distort(x, y)

Forward distortion: ideal → distorted.

undistort(x, y)

Inverse distortion: distorted → ideal.