lsst::afw::geom::SipApproximation Class Reference

A fitter and results class for approximating a general Transform in a form compatible with FITS WCS persistence. More...

#include <SipApproximation.h>

Classes
struct	FitGrid
struct	Solution
struct	ValidationGrid

Public Member Functions
	SipApproximation (SkyWcs const &target, lsst::geom::Box2D const &bbox, lsst::geom::Extent2I const &gridShape, int order=5, std::optional< lsst::geom::Point2D > const &pixelOrigin=std::nullopt, double svdThreshold=-1)
	Construct a new approximation by fitting on a grid of points.
	SipApproximation (SipApproximation const &)=delete
SipApproximation &	operator= (SipApproximation const &)=delete
	SipApproximation (SipApproximation &&) noexcept=default
SipApproximation &	operator= (SipApproximation &&) noexcept=default
	~SipApproximation () noexcept
int	getOrder () const noexcept
	Return the polynomial order of the current solution (same for forward and reverse).
double	getA (int p, int q) const
	Return a coefficient of the forward transform polynomial.
double	getB (int p, int q) const
	Return a coefficient of the forward transform polynomial.
Eigen::MatrixXd	getA () const
	Return the coefficients of the forward transform polynomial.
Eigen::MatrixXd	getB () const
	Return the coefficients of the forward transform polynomial.
lsst::geom::Box2D	getBBox () const noexcept
	Return the pixel-coordinate bounding box over which the approximation should be valid.
lsst::geom::SpherePoint	getSkyOrigin () const noexcept
	Return the sky-coordinate origin of the WCS.
lsst::geom::Point2D	getPixelOrigin () const noexcept
	Return the pixel origin of the WCS.
Eigen::Matrix2d	getCdMatrix () const noexcept
	Return the CD matrix of the WCS (in degrees).
std::shared_ptr< SkyWcs >	getWcs () const noexcept
	Return a TAN-SIP WCS object that evaluates the approximation.
std::pair< lsst::geom::Angle, double >	computeDeltas () const
	Return the maximum deviations of the solution from the exact transform on a grid offset from the one used in the fit.

Detailed Description

A fitter and results class for approximating a general Transform in a form compatible with FITS WCS persistence.

The Simple Imaging Polynomial (SIP) convention (Shupe et al 2005) adds forward and reverse polynomial mappings to a standard projection FITS WCS projection (e.g. "TAN" for gnomonic) that relate Intermediate World Coordinates (see Calabretta & Greisen 2002) to image pixel coordinates. The SIP "forward" transform is defined by polynomial coefficients \(A\) and \(B\) that map pixel coordinates \((u, v)\) to Intermediate World Coordinates \((x, y)\) via

\[ \boldsymbol{S}\left[\begin{array}{c} x \\ y \end{array}\right] \equiv \left[\begin{array}{c} x_s \\ y_s \end{array}\right] = \left[\begin{array}{c} (u - u_0) + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{A}_{p,q} (u - u_0)^p (v - v_0)^q \\ (v - v_0) + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{B}_{p,q} (u - u_0)^p (v - v_0)^q \end{array}\right] \]

The reverse transform has essentially the same form:

\[ \left[\begin{array}{c} u - u_0 \\ v - v_0 \end{array}\right] = \left[\begin{array}{c} x_s + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{AP}_{p,q} x_s^p y_s^q \\ y_s + \displaystyle\sum_{p,q}^{0 \le p + q \le N} \mathrm{BP}_{p,q} x_s^p y_s^q \end{array}\right] \]

In both cases, \((u_0, v_0)\) is the pixel origin (CRPIX in FITS WCS) and \(\boldsymbol{S}\) is the inverse of the Jacobian "CD" matrix.

Note

In the implementation, we typically refer to \((u-u_0, v-v_0)\) as dpix (for "pixel delta"), and \((x_s, y_s)\) as iwc (for intermediate world coordinates").

While LSST WCSs are in general too complex to be described exactly in FITS WCS, they can generally be closely approximated by standard FITS WCS projection with additional SIP distortions. This class fits such an approximation.

Definition at line 89 of file SipApproximation.h.

Constructor & Destructor Documentation

SipApproximation() [1/3]

lsst::afw::geom::SipApproximation::SipApproximation	(	SkyWcs const &	target,
		lsst::geom::Box2D const &	bbox,
		lsst::geom::Extent2I const &	gridShape,
		int	order = 5,
		std::optional< lsst::geom::Point2D > const &	pixelOrigin = std::nullopt,
		double	svdThreshold = -1 )

Construct a new approximation by fitting on a grid of points.

Parameters

[in]	target	The true WCS to approximate.
[in]	bbox	Pixel-coordinate bounding box over which the approximation should be valid. Used to construct the grid of points to fit.
[in]	gridShape	Number of points in x and y for the grid of points.
[in]	order	Order of the polynomial (same for forward and reverse transforms).
[in]	pixelOrigin	Pixel reference point. If not provided, the center of bbox is used. Must lie within bbox. Note that this is 0-indexed, and is hence one less than the FITS CRPIX value.
[in]	svdThreshold	Fraction of the largest singular value at which to declare smaller singular values zero in the least squares solution. Negative values use Eigen's internal default.

Exceptions

lsst::pex::exceptions::InvalidParameterError

Thrown if order is negative or gridShape is non-positive.

Exception Safety

strong

Definition at line 244 of file SipApproximation.cc.

SipApproximation() [2/3]

lsst::afw::geom::SipApproximation::SipApproximation ( SipApproximation const & )

delete

SipApproximation() [3/3]

lsst::afw::geom::SipApproximation::SipApproximation ( SipApproximation && )

defaultnoexcept

~SipApproximation()

lsst::afw::geom::SipApproximation::~SipApproximation ( )

defaultnoexcept

Member Function Documentation

computeDeltas()

std::pair< lsst::geom::Angle, double > lsst::afw::geom::SipApproximation::computeDeltas

(

)

const

Return the maximum deviations of the solution from the exact transform on a grid offset from the one used in the fit.

The returned quantities are the maxima of:

Angle delta1 = target.pixelToSky(p).separation(approx.pixelToSky(p));
double delta2 = (target.skyToPixel(s) - approx.skyToPixel(s)).computeNorm();

at all pixel points p and sky points s on the offset grid.

Definition at line 329 of file SipApproximation.cc.

getA() [1/2]

Eigen::MatrixXd lsst::afw::geom::SipApproximation::getA

(

)

const

Return the coefficients of the forward transform polynomial.

Definition at line 307 of file SipApproximation.cc.

getA() [2/2]

double lsst::afw::geom::SipApproximation::getA	(	int	p,
		int	q ) const

Return a coefficient of the forward transform polynomial.

Out-of-bounds arguments yields undefined behavior.

Exception Safety

strong

Definition at line 284 of file SipApproximation.cc.

getB() [1/2]

Eigen::MatrixXd lsst::afw::geom::SipApproximation::getB

(

)

const

Return the coefficients of the forward transform polynomial.

Definition at line 314 of file SipApproximation.cc.

getB() [2/2]

double lsst::afw::geom::SipApproximation::getB	(	int	p,
		int	q ) const

Return a coefficient of the forward transform polynomial.

Out-of-bounds arguments yields undefined behavior.

Exception Safety

strong

Definition at line 288 of file SipApproximation.cc.

getBBox()

lsst::geom::Box2D lsst::afw::geom::SipApproximation::getBBox ( ) const

inlinenoexcept

Return the pixel-coordinate bounding box over which the approximation should be valid.

Definition at line 165 of file SipApproximation.h.

getCdMatrix()

Eigen::Matrix2d lsst::afw::geom::SipApproximation::getCdMatrix ( ) const

noexcept

Return the CD matrix of the WCS (in degrees).

Definition at line 321 of file SipApproximation.cc.

getOrder()

int lsst::afw::geom::SipApproximation::getOrder ( ) const

noexcept

Return the polynomial order of the current solution (same for forward and reverse).

Definition at line 280 of file SipApproximation.cc.

getPixelOrigin()

lsst::geom::Point2D lsst::afw::geom::SipApproximation::getPixelOrigin ( ) const

inlinenoexcept

Return the pixel origin of the WCS.

Definition at line 171 of file SipApproximation.h.

getSkyOrigin()

lsst::geom::SpherePoint lsst::afw::geom::SipApproximation::getSkyOrigin ( ) const

inlinenoexcept

Return the sky-coordinate origin of the WCS.

Definition at line 168 of file SipApproximation.h.

getWcs()

std::shared_ptr< SkyWcs > lsst::afw::geom::SipApproximation::getWcs ( ) const

noexcept

Return a TAN-SIP WCS object that evaluates the approximation.

Definition at line 325 of file SipApproximation.cc.

operator=() [1/2]

SipApproximation & lsst::afw::geom::SipApproximation::operator= ( SipApproximation && )

defaultnoexcept

operator=() [2/2]

SipApproximation & lsst::afw::geom::SipApproximation::operator= ( SipApproximation const & )

delete

---

The documentation for this class was generated from the following files:

• include/lsst/afw/geom/SipApproximation.h
• src/geom/SipApproximation.cc