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	Grid
struct	Solution

Public Member Functions
	SipApproximation (std::shared_ptr< TransformPoint2ToPoint2 > pixelToIwc, lsst::geom::Point2D const &crpix, Eigen::Matrix2d const &cd, lsst::geom::Box2D const &bbox, lsst::geom::Extent2I const &gridShape, int order, bool useInverse=true, double svdThreshold=-1)
	Construct a new approximation by fitting on a grid of points. More...
	SipApproximation (std::shared_ptr< TransformPoint2ToPoint2 > pixelToIwc, lsst::geom::Point2D const &crpix, Eigen::Matrix2d const &cd, lsst::geom::Box2D const &bbox, lsst::geom::Extent2I const &gridShape, ndarray::Array< double const, 2 > const &a, ndarray::Array< double const, 2 > const &b, ndarray::Array< double const, 2 > const &ap, ndarray::Array< double const, 2 > const &bp, bool useInverse=true)
	Construct from existing SIP coefficients. More...
	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). More...
double	getA (int p, int q) const
	Return a coefficient of the forward transform polynomial. More...
double	getB (int p, int q) const
	Return a coefficient of the forward transform polynomial. More...
double	getAP (int p, int q) const
	Return a coefficient of the reverse transform polynomial. More...
double	getBP (int p, int q) const
	Return a coefficient of the reverse transform polynomial. More...
Eigen::MatrixXd	getA () const noexcept
	Return the coefficients of the forward transform polynomial. More...
Eigen::MatrixXd	getB () const noexcept
	Return the coefficients of the forward transform polynomial. More...
Eigen::MatrixXd	getAP () const noexcept
	Return the coefficients of the reverse transform polynomial. More...
Eigen::MatrixXd	getBP () const noexcept
	Return the coefficients of the reverse transform polynomial. More...
lsst::geom::Point2D	applyForward (lsst::geom::Point2D const &pix) const
	Convert a point from pixels to intermediate world coordinates. More...
std::vector< lsst::geom::Point2D >	applyForward (std::vector< lsst::geom::Point2D > const &pix) const
	Convert an array of points from pixels to intermediate world coordinates. More...
lsst::geom::Point2D	applyInverse (lsst::geom::Point2D const &iwcs) const
	Convert a point from intermediate world coordinates to pixels. More...
std::vector< lsst::geom::Point2D >	applyInverse (std::vector< lsst::geom::Point2D > const &iwcs) const
	Convert an array of points from intermediate world coordinates to pixels. More...
lsst::geom::Extent2D	getGridStep () const noexcept
	Return the distance between grid points in pixels. More...
lsst::geom::Extent2I	getGridShape () const noexcept
	Return the number of grid points in x and y. More...
lsst::geom::Box2D	getBBox () const noexcept
	Return the pixel-coordinate bounding box over which the approximation should be valid. More...
lsst::geom::Point2D	getPixelOrigin () const noexcept
	Return the pixel origin of the WCS being approximated. More...
Eigen::Matrix2d	getCdMatrix () const noexcept
	Return the CD matrix of the WCS being approximated. More...
void	updateGrid (lsst::geom::Extent2I const &shape)
	Update the grid to the given number of points in x and y. More...
void	refineGrid (int factor=2)
	Update the grid by making it finer by a given integer factor. More...
void	fit (int order, double svdThreshold=-1)
	Obtain a new solution at the given order with the current grid. More...
std::pair< double, double >	computeMaxDeviation () const noexcept
	Return the maximum deviation of the solution from the exact transform on the current grid. More...

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 coeffients \(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. Both CRPIX and CD are considered fixed inputs, and we do not attempt to null the zeroth- and first-order terms of \(A\) and \(B\) (as some SIP fitters do); together, these conventions make solving for the coefficients a much simpler linear problem.

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 siwc (for "scaled 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, given a TransformPoint2ToPoint2 object that represents the exact mapping from pixels to Intermediate World Coordinates with a SIP distortion.

Definition at line 94 of file SipApproximation.h.

Constructor & Destructor Documentation

SipApproximation() [1/4]

lsst::afw::geom::SipApproximation::SipApproximation	(	std::shared_ptr< TransformPoint2ToPoint2 >	pixelToIwc,
		lsst::geom::Point2D const &	crpix,
		Eigen::Matrix2d const &	cd,
		lsst::geom::Box2D const &	bbox,
		lsst::geom::Extent2I const &	gridShape,
		int	order,
		bool	useInverse = true,
		double	svdThreshold = -1
	)

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

Parameters

[in]	pixelToIwc	The true Transform to approximate. Should go from pixels to Intermediate World Coordinates when applyForward is called.
[in]	crpix	Pixel origin, using the LSST 0-indexed convention rather than the FITS 1-indexed convention; equal to (CRPIX1 - 1, CRPIX2 - 1).
[in]	cd	Nominal Jacobian ("CD" in FITS WCS).
[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]	useInverse	If true, the inverse SIP transform will be fit and compared to data points generated by calls to pixelToIwc.applyInverse instead of pixelToIwc.applyForward.
[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 210 of file SipApproximation.cc.

  :
    _useInverse(useInverse),
    _pixelToIwc(std::move(pixelToIwc)),
    _bbox(bbox),
    _crpix(crpix),
    _cdInv(lsst::geom::LinearTransform(cd).inverted()),
    _grid(new Grid(gridShape, *this)),
    _solution(Solution::fit(order, svdThreshold, *this))
{}

SipApproximation() [2/4]

lsst::afw::geom::SipApproximation::SipApproximation	(	std::shared_ptr< TransformPoint2ToPoint2 >	pixelToIwc,
		lsst::geom::Point2D const &	crpix,
		Eigen::Matrix2d const &	cd,
		lsst::geom::Box2D const &	bbox,
		lsst::geom::Extent2I const &	gridShape,
		ndarray::Array< double const, 2 > const &	a,
		ndarray::Array< double const, 2 > const &	b,
		ndarray::Array< double const, 2 > const &	ap,
		ndarray::Array< double const, 2 > const &	bp,
		bool	useInverse = true
	)

Construct from existing SIP coefficients.

This constructor is primarily intended for testing purposes.

Parameters

[in]	pixelToIwc	The true Transform to approximate. Should go from pixels to Intermediate World Coordinates when applyForward is called.
[in]	crpix	Pixel origin, using the LSST 0-indexed convention rather than the FITS 1-indexed convention; equal to (CRPIX1 - 1, CRPIX - 1).
[in]	cd	Nominal Jacobian ("CD" in FITS WCS).
[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]	a	Matrix of A coefficients, with the first dimension corresponding to powers of \((u - u_0)\) and the second corresponding to powers of \((v - v_0)\).
[in]	b	Matrix of B coefficients, with the first dimension corresponding to powers of \((u - u_0)\) and the second corresponding to powers of \((v - v_0)\).
[in]	ap	Matrix of AP coefficients, with the first dimension corresponding to powers of \(x_s\) and the second corresponding to powers of \(y_s\).
[in]	bp	Matrix of BP coefficients, with the first dimension corresponding to powers of \(x_s\) and the second corresponding to powers of \(y_s\).
[in]	useInverse	If true, the inverse SIP transform will be compared to data points generated by calls to pixelToIwc.applyInverse instead of pixelToIwc.applyForward.

Exceptions

lsst::pex::exceptions::InvalidParameterError

Thrown if gridShape is non-positive, or any matrix argument is non-square.

Exception Safety

strong

Definition at line 229 of file SipApproximation.cc.

  :
    _useInverse(useInverse),
    _pixelToIwc(std::move(pixelToIwc)),
    _bbox(bbox),
    _crpix(crpix),
    _cdInv(lsst::geom::LinearTransform(cd).inverted()),
    _grid(new Grid(gridShape, *this)),
    _solution(
        new Solution(
            makePolynomialFromCoeffMatrix(a),
            makePolynomialFromCoeffMatrix(b),
            makePolynomialFromCoeffMatrix(ap),
            makePolynomialFromCoeffMatrix(bp)
        )
    )
{}

SipApproximation() [3/4]

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

delete

SipApproximation() [4/4]

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

defaultnoexcept

~SipApproximation()

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

noexcept

Definition at line 257 of file SipApproximation.cc.

{}

Member Function Documentation

applyForward() [1/2]

lsst::geom::Point2D lsst::afw::geom::SipApproximation::applyForward

(

lsst::geom::Point2D const &

pix

)

const

Convert a point from pixels to intermediate world coordinates.

This method is inefficient and should only be used for diagnostic purposes.

Exception Safety

strong

Definition at line 322 of file SipApproximation.cc.

                                                                                {
    auto cd = _cdInv.inverted();
    auto ws = _solution->makeWorkspace();
    return cd(_solution->applyForward(pix - _crpix, ws));
}

applyForward() [2/2]

std::vector< lsst::geom::Point2D > lsst::afw::geom::SipApproximation::applyForward

(

std::vector< lsst::geom::Point2D > const &

pix

)

const

Convert an array of points from pixels to intermediate world coordinates.

Exception Safety

strong

Definition at line 328 of file SipApproximation.cc.

                                                      {
    auto ws = _solution->makeWorkspace();
    std::vector<lsst::geom::Point2D> iwc;
    iwc.reserve(pix.size());
    auto cd = _cdInv.inverted();
    for (auto const & point : pix) {
        iwc.push_back(cd(_solution->applyForward(point - _crpix, ws)));
    }
    return iwc;
}

applyInverse() [1/2]

lsst::geom::Point2D lsst::afw::geom::SipApproximation::applyInverse

(

lsst::geom::Point2D const &

iwcs

)

const

Convert a point from intermediate world coordinates to pixels.

This method is inefficient and should only be used for diagnostic purposes.

Exception Safety

strong

Definition at line 340 of file SipApproximation.cc.

                                                                                {
    auto ws = _solution->makeWorkspace();
    return _solution->applyInverse(_cdInv(iwc), ws) + _crpix;
}

applyInverse() [2/2]

std::vector< lsst::geom::Point2D > lsst::afw::geom::SipApproximation::applyInverse

(

std::vector< lsst::geom::Point2D > const &

iwcs

)

const

Convert an array of points from intermediate world coordinates to pixels.

Exception Safety

strong

Definition at line 345 of file SipApproximation.cc.

                                                      {
    auto ws = _solution->makeWorkspace();
    std::vector<lsst::geom::Point2D> pix;
    pix.reserve(iwc.size());
    for (auto const & point : iwc) {
        pix.push_back(_solution->applyInverse(_cdInv(point), ws) + _crpix);
    }
    return pix;
}

computeMaxDeviation()

std::pair< double, double > lsst::afw::geom::SipApproximation::computeMaxDeviation ( ) const

noexcept

Return the maximum deviation of the solution from the exact transform on the current grid.

The deviations are in scaled intermediate world coordinates \(\sqrt{\delta x_s^2 \delta y_s^2}\) for the forward transform and in pixels \((\delta u^2, \delta v^2)\) for the reverse transform (respectively). Note that in the common case where the CD matrix includes the scaling from angle units to pixel units, the scaled intermediate world coordinate values are also in (nominal) pixel units.

Definition at line 381 of file SipApproximation.cc.

                                                                             {
    std::pair<double, double> maxDiff(0.0, 0.0);
    auto ws = _solution->makeWorkspace();
    for (std::size_t i = 0; i < _grid->dpix1.size(); ++i) {
        auto siwc2 = _solution->applyForward(_grid->dpix1[i], ws);
        auto dpix2 = _solution->applyInverse(_grid->siwc[i], ws);
        maxDiff.first = std::max(maxDiff.first, (_grid->siwc[i] - siwc2).computeNorm());
        maxDiff.second = std::max(maxDiff.second, (_grid->dpix2[i] - dpix2).computeNorm());
    }
    return maxDiff;
}

fit()

void lsst::afw::geom::SipApproximation::fit	(	int	order,
		double	svdThreshold = -1
	)

Obtain a new solution at the given order with the current grid.

Parameters

[in]	order	Polynomial order to fit.
[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

pex::exceptions::LogicError

Thrown if the number of free parameters implied by order is larger than the number of data points defined by the grid.

Exception Safety

strong

Definition at line 377 of file SipApproximation.cc.

                                                         {
    _solution = Solution::fit(order, svdThreshold, *this);
}

getA() [1/2]

Eigen::MatrixXd lsst::afw::geom::SipApproximation::getA ( ) const

noexcept

Return the coefficients of the forward transform polynomial.

Definition at line 294 of file SipApproximation.cc.

                                                    {
    return makeCoefficientMatrix(
        getOrder(),
        [this](int p, int q) { return getA(p, q); }
    );
}

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 263 of file SipApproximation.cc.

                                                {
    return _solution->a[_solution->a.getBasis().index(p, q)];
}

getAP() [1/2]

Eigen::MatrixXd lsst::afw::geom::SipApproximation::getAP ( ) const

noexcept

Return the coefficients of the reverse transform polynomial.

Definition at line 308 of file SipApproximation.cc.

                                                     {
    return makeCoefficientMatrix(
        getOrder(),
        [this](int p, int q) { return getAP(p, q); }
    );
}

getAP() [2/2]

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

Return a coefficient of the reverse transform polynomial.

Out-of-bounds arguments yields undefined behavior.

Exception Safety

strong

Definition at line 271 of file SipApproximation.cc.

                                                 {
    return _solution->ap[_solution->ap.getBasis().index(p, q)];
}

getB() [1/2]

Eigen::MatrixXd lsst::afw::geom::SipApproximation::getB ( ) const

noexcept

Return the coefficients of the forward transform polynomial.

Definition at line 301 of file SipApproximation.cc.

                                                    {
    return makeCoefficientMatrix(
        getOrder(),
        [this](int p, int q) { return getB(p, q); }
    );
}

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 267 of file SipApproximation.cc.

                                                {
    return _solution->b[_solution->b.getBasis().index(p, q)];
}

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 291 of file SipApproximation.h.

{ return _bbox; }

getBP() [1/2]

Eigen::MatrixXd lsst::afw::geom::SipApproximation::getBP ( ) const

noexcept

Return the coefficients of the reverse transform polynomial.

Definition at line 315 of file SipApproximation.cc.

                                                     {
    return makeCoefficientMatrix(
        getOrder(),
        [this](int p, int q) { return getBP(p, q); }
    );
}

getBP() [2/2]

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

Return a coefficient of the reverse transform polynomial.

Out-of-bounds arguments yields undefined behavior.

Exception Safety

strong

Definition at line 275 of file SipApproximation.cc.

                                                 {
    return _solution->bp[_solution->bp.getBasis().index(p, q)];
}

getCdMatrix()

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

inlinenoexcept

Return the CD matrix of the WCS being approximated.

Definition at line 297 of file SipApproximation.h.

{ return _cdInv.inverted().getMatrix(); }

getGridShape()

lsst::geom::Extent2I lsst::afw::geom::SipApproximation::getGridShape ( ) const

noexcept

Return the number of grid points in x and y.

Definition at line 361 of file SipApproximation.cc.

                                                               {
    return _grid->shape;
}

getGridStep()

lsst::geom::Extent2D lsst::afw::geom::SipApproximation::getGridStep ( ) const

noexcept

Return the distance between grid points in pixels.

Definition at line 356 of file SipApproximation.cc.

                                                              {
    return lsst::geom::Extent2D(_bbox.getWidth()/_grid->shape.getX(),
                    _bbox.getHeight()/_grid->shape.getY());
}

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 259 of file SipApproximation.cc.

                                              {
    return _solution->a.getBasis().getOrder();
}

getPixelOrigin()

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

inlinenoexcept

Return the pixel origin of the WCS being approximated.

Definition at line 294 of file SipApproximation.h.

{ return lsst::geom::Point2D(_crpix); }

operator=() [1/2]

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

defaultnoexcept

operator=() [2/2]

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

delete

refineGrid()

void lsst::afw::geom::SipApproximation::refineGrid

(

int

factor = 2

)

Update the grid by making it finer by a given integer factor.

Exceptions

lsst::pex::exceptions::InvalidParameterError

Thrown if factor is non-positive.

Exception Safety

strong

Definition at line 369 of file SipApproximation.cc.

                                       {
    // We shrink the grid spacing by the given factor, which is not the same
    // as increasing the number of grid points by that factor, because there
    // is one more grid point that step in each dimension.
    lsst::geom::Extent2I unit(1);
    updateGrid((_grid->shape - unit)*f + unit);
}

updateGrid()

void lsst::afw::geom::SipApproximation::updateGrid

(

lsst::geom::Extent2I const &

shape

)

Update the grid to the given number of points in x and y.

This does not invalidate or modify the current solution; this allows the user to fit with a coarse grid and then check whether the solution still works well on a finer grid.

Exceptions

lsst::pex::exceptions::InvalidParameterError

Thrown if shape is non-positive.

Exception Safety

strong

Definition at line 365 of file SipApproximation.cc.

                                                                {
    _grid = std::make_unique<Grid>(shape, *this);
}

---

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

• /j/snowflake/release/lsstsw/stack/0.4.3/Linux64/afw/21.0.0-25-g1d57be3cd+e73869a214/include/lsst/afw/geom/SipApproximation.h
• /j/snowflake/release/lsstsw/stack/0.4.3/Linux64/afw/21.0.0-25-g1d57be3cd+e73869a214/src/geom/SipApproximation.cc