lsst.astshim  22.0.0+dfc68d4d09
Public Member Functions | Protected Member Functions | Friends | List of all members
ast::Mapping Class Reference

#include <Mapping.h>

Inheritance diagram for ast::Mapping:
ast::Object ast::ChebyMap ast::CmpMap ast::Frame ast::LutMap ast::MathMap ast::MatrixMap ast::NormMap ast::PcdMap ast::PermMap ast::PolyMap ast::RateMap ast::ShiftMap ast::SlaMap ast::SphMap ast::TimeMap ast::TranMap ast::UnitMap ast::UnitNormMap ast::WcsMap ast::WinMap ast::ZoomMap

Public Member Functions

virtual ~Mapping ()
 
 Mapping (Mapping const &)=default
 Copy constructor: make a deep copy. More...
 
 Mapping (Mapping &&)=default
 
Mappingoperator= (Mapping const &)=delete
 
Mappingoperator= (Mapping &&)=default
 
std::shared_ptr< Mappingcopy () const
 Return a deep copy of this object. More...
 
int getNIn () const
 
int getNOut () const
 
bool getIsSimple () const
 
bool isInverted () const
 
bool getIsLinear () const
 
bool getReport () const
 
bool hasForward () const
 
bool hasInverse () const
 
std::shared_ptr< Mappinginverted () const
 
Array2D linearApprox (PointD const &lbnd, PointD const &ubnd, double tol) const
 
SeriesMap then (Mapping const &next) const
 
ParallelMap under (Mapping const &next) const
 
double rate (PointD const &at, int ax1, int ax2) const
 
void setReport (bool report)
 
std::shared_ptr< Mappingsimplified () const
 
void applyForward (ConstArray2D const &from, Array2D const &to) const
 
Array2D applyForward (ConstArray2D const &from) const
 
std::vector< double > applyForward (std::vector< double > const &from) const
 
void applyInverse (ConstArray2D const &from, Array2D const &to) const
 
Array2D applyInverse (ConstArray2D const &from) const
 
std::vector< double > applyInverse (std::vector< double > const &from) const
 
void tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 
Array2D tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 
void tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 
Array2D tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 
- Public Member Functions inherited from ast::Object
virtual ~Object ()
 
 Object (Object const &object)
 Copy constructor: make a deep copy. More...
 
 Object (Object &&)=default
 
Objectoperator= (Object const &)=delete
 
Objectoperator= (Object &&)=default
 
bool operator== (Object const &rhs) const
 
bool operator!= (Object const &rhs) const
 
std::shared_ptr< Objectcopy () const
 Return a deep copy of this object. More...
 
void clear (std::string const &attrib)
 
bool hasAttribute (std::string const &attrib) const
 
std::string getClassName () const
 
std::string getID () const
 Get ID: object identification string that is not copied. More...
 
std::string getIdent () const
 Get Ident: object identification string that is copied. More...
 
int getNObject () const
 
int getObjSize () const
 Get ObjSize: the in-memory size of the AST object in bytes. More...
 
int getRefCount () const
 
bool getUseDefs () const
 Get UseDefs: allow use of default values for Object attributes? More...
 
void lock (bool wait)
 
bool same (Object const &other) const
 
void setID (std::string const &id)
 Set ID: object identification string that is not copied. More...
 
void setIdent (std::string const &ident)
 Set Ident: object identification string that is copied. More...
 
void setUseDefs (bool usedefs)
 Set UseDefs: allow use of default values for Object attributes? More...
 
void show (std::ostream &os, bool showComments=true) const
 
std::string show (bool showComments=true) const
 
bool test (std::string const &attrib) const
 
void unlock (bool report=false)
 
AstObject const * getRawPtr () const
 
AstObject * getRawPtr ()
 

Protected Member Functions

 Mapping (AstMapping *rawMap)
 
virtual std::shared_ptr< ObjectcopyPolymorphic () const override
 
template<typename Class >
std::shared_ptr< Class > decompose (int i, bool copy) const
 
- Protected Member Functions inherited from ast::Object
 Object (AstObject *object)
 
template<typename T , typename AstT >
std::shared_ptr< T > copyImpl () const
 
bool getB (std::string const &attrib) const
 
std::string const getC (std::string const &attrib) const
 
double getD (std::string const &attrib) const
 
float getF (std::string const &attrib) const
 
int getI (std::string const &attrib) const
 
long int getL (std::string const &attrib) const
 
void set (std::string const &setting)
 
void setB (std::string const &attrib, bool value)
 
void setC (std::string const &attrib, std::string const &value)
 
void setD (std::string const &attrib, double value)
 
void setF (std::string const &attrib, float value)
 
void setI (std::string const &attrib, int value)
 
void setL (std::string const &attrib, long int value)
 

Friends

class Object
 

Additional Inherited Members

- Public Types inherited from ast::Object
using ObjectPtr = std::unique_ptr< AstObject, Deleter >
 unique pointer holding an AST raw pointer More...
 
- Static Public Member Functions inherited from ast::Object
static std::shared_ptr< ObjectfromString (std::string const &str)
 
template<typename Class >
static std::shared_ptr< Class > fromAstObject (AstObject *rawObj, bool copy)
 
- Static Protected Member Functions inherited from ast::Object
template<typename ShimT , typename AstT >
static std::shared_ptr< ShimT > makeShim (AstObject *p)
 

Detailed Description

An abstract base class for objects which transform one set of coordinates to another.

Mapping is used to describe the relationship which exists between two different coordinate systems and to implement operations which make use of this (such as transforming coordinates and resampling grids of data).

Attributes

In addition to those attributes common to Object, Mapping also has the following attributes:

Constructor & Destructor Documentation

◆ ~Mapping()

virtual ast::Mapping::~Mapping ( )
inlinevirtual

◆ Mapping() [1/3]

ast::Mapping::Mapping ( Mapping const &  )
default

Copy constructor: make a deep copy.

◆ Mapping() [2/3]

ast::Mapping::Mapping ( Mapping &&  )
default

◆ Mapping() [3/3]

ast::Mapping::Mapping ( AstMapping *  rawMap)
inlineexplicitprotected

Construct a mapping from a pointer to a raw AST subclass of AstMapping

Member Function Documentation

◆ applyForward() [1/3]

Array2D ast::Mapping::applyForward ( ConstArray2D const &  from) const
inline

Perform a forward transformation on a 2-D array, returning the results as a new array

Parameters
[in]frominput coordinates, with dimensions (nPts, nIn)
Returns
the results as a new array with dimensions (nPts, nOut)

◆ applyForward() [2/3]

void ast::Mapping::applyForward ( ConstArray2D const &  from,
Array2D const &  to 
) const
inline

Perform a forward transformation on 2-D array, putting the results into a pre-allocated 2-D array

Parameters
[in]frominput coordinates, with dimensions (nPts, nIn)
[out]totransformed coordinates, with dimensions (nPts, nOut)

◆ applyForward() [3/3]

std::vector<double> ast::Mapping::applyForward ( std::vector< double > const &  from) const
inline

Perform a forward transformation on a vector, returning the results as a new vector

Parameters
[in]frominput coordinates as a vector, with axes adjacent, e.g. x0, y0, x1, y1...xn, yn
Returns
the results as a new vector

◆ applyInverse() [1/3]

Array2D ast::Mapping::applyInverse ( ConstArray2D const &  from) const
inline

Perform an inverse transformation on a 2-D array, returning the results as a new 2-D array

Parameters
[in]fromoutput coordinates, with dimensions (nPts, nOut)
Returns
the results as a new array with dimensions (nPts, nIn)

◆ applyInverse() [2/3]

void ast::Mapping::applyInverse ( ConstArray2D const &  from,
Array2D const &  to 
) const
inline

Perform an inverse transformation on a 2-D array, putting the results into a pre-allocated 2-D array

Parameters
[in]frominput coordinates, with dimensions (nPts, nOut)
[out]totransformed coordinates, with dimensions (nPts, nIn)

◆ applyInverse() [3/3]

std::vector<double> ast::Mapping::applyInverse ( std::vector< double > const &  from) const
inline

Perform an inverse transformation on a vector, returning the results as a new vector

Parameters
[in]frominput coordinates as a vector, with axes adjacent, e.g. x0, y0, x1, y1...xn, yn
Returns
the results as a new vector

◆ copy()

std::shared_ptr<Mapping> ast::Mapping::copy ( ) const
inline

Return a deep copy of this object.

◆ copyPolymorphic()

virtual std::shared_ptr<Object> ast::Mapping::copyPolymorphic ( ) const
inlineoverrideprotectedvirtual

Return a deep copy of this object. This is called by copy.

Each subclass must override this method. The standard implementation is:

return copyImpl<astshim_class, ast_class>();

for example Frame implements this as:

return copyImpl<Frame, AstFrame>();

Implements ast::Object.

Reimplemented in ast::ZoomMap, ast::WinMap, ast::WcsMap, ast::UnitNormMap, ast::UnitMap, ast::TranMap, ast::TimeMap, ast::TimeFrame, ast::SphMap, ast::SpecFrame, ast::SlaMap, ast::SkyFrame, ast::ShiftMap, ast::SeriesMap, ast::RateMap, ast::PolyMap, ast::PermMap, ast::PcdMap, ast::ParallelMap, ast::NormMap, ast::MatrixMap, ast::MathMap, ast::LutMap, ast::FrameSet, ast::FrameDict, ast::Frame, ast::CmpMap, ast::CmpFrame, and ast::ChebyMap.

◆ decompose()

template<typename Class >
template std::shared_ptr< Mapping > ast::Mapping::decompose ( int  i,
bool  copy 
) const
protected

Return a deep copy of one of the two component mappings.

This is intended to be exposed by classes that need it (e.g. CmpMap, CmpFrame and TranMap) as operator[].

Template Parameters
Classastshim class of returned object, typically Mapping or Frame.
Parameters
[in]iIndex: 0 for the first mapping, 1 for the second
[in]copyIf true make a deep copy, else a shallow copy
Exceptions
std::invalid_argumentif i is not 0 or 1.
std::runtime_errorif this mapping is not a compound mapping.

◆ getIsLinear()

bool ast::Mapping::getIsLinear ( ) const
inline

Get IsLinear: is the Mapping linear?

◆ getIsSimple()

bool ast::Mapping::getIsSimple ( ) const
inline

Get IsSimple: has the mapping been simplified?

◆ getNIn()

int ast::Mapping::getNIn ( ) const
inline

Get NIn: the number of input axes

◆ getNOut()

int ast::Mapping::getNOut ( ) const
inline

Get NOut: the number of output axes

◆ getReport()

bool ast::Mapping::getReport ( ) const
inline

Get Report: report transformed coordinates to stdout?

◆ hasForward()

bool ast::Mapping::hasForward ( ) const
inline

Is the forward transform available?

Note
This gets the TranForward attribute, but is named hasForward instead of getTranForward for clarity, since it does not return a transform.

◆ hasInverse()

bool ast::Mapping::hasInverse ( ) const
inline

Is the inverse transform available?

Note
This gets the TranInverse attribute, but is named hasInverse instead of getTranInverse for clarity, since it does not return a transform.

◆ inverted()

std::shared_ptr< Mapping > ast::Mapping::inverted ( ) const

Get an inverse mapping

An inverse mapping is a deep copy of a mapping whose Invert attribute has been toggled, as indicated by isInverted. This swaps the meaning of "input" and "output", and of "forward" and "inverse". Thus it swaps the behavior of applyForward and applyInverse, getNIn and getNOut, hasForward and hasInverse and so on.

Note that the inverse mapping contains exactly the same model coefficients as the original, but they are used by applyInverse instead of applyForward. Thus for example if a ZoomMap has a zoom factor of 4.0 then its inverse also reports a zoom factor of 4.0 (despite behaving like an uninverted ZoomMap with zoom factor of 0.25).

◆ isInverted()

bool ast::Mapping::isInverted ( ) const
inline

Is this an inverted mapping?

Note: this gets the Invert attribute. This method is not called getInvert because that sounds like it might return the inverse.

◆ linearApprox()

Array2D ast::Mapping::linearApprox ( PointD const &  lbnd,
PointD const &  ubnd,
double  tol 
) const

Compute a linear approximation to the forward transformation.

Parameters
[in]lbndInput point defining the lower bounds of the box over which the linear approximation is computed.
[in]ubndInput point defining the upper bounds of the box over which the linear approximation is computed.
[in]tolThe maximum permitted deviation from linearity, expressed as apositive Cartesian displacement in the output coordinate space. If a linear fit to the forward transformation of the Mapping deviates from the true transformation by more than this amount at any point which is tested, then raise an exception.
Returns
The co-efficients of the linear approximation to the specified transformation, as an 1 + nIn x nOut array. The first index is [constant, gradiant for input 1, gradiant for input 2...] and the second index is [output 1, output 2, ...]. For example, if the Mapping has 2 inputs and 3 outputs then the coefficients are:
X_out = fit[0, 0] + fit[1, 0] X_in + fit[2, 0] Y_in
Y_out = fit[0, 1] + fit[1, 1] X_in + fit[2, 1] Y_in
Z_out = fit[0, 2] + fit[1, 2] X_in + fit[2, 2] Y_in
Exceptions
std::runtime_errorif the forward transformation cannot be modeled to within the specified tol.

◆ operator=() [1/2]

Mapping& ast::Mapping::operator= ( Mapping &&  )
default

◆ operator=() [2/2]

Mapping& ast::Mapping::operator= ( Mapping const &  )
delete

◆ rate()

double ast::Mapping::rate ( PointD const &  at,
int  ax1,
int  ax2 
) const
inline

Evaluate the rate of change of the Mapping with respect to a specified input, at a specified position.

The result is estimated by interpolating the function using a fourth order polynomial in the neighbourhood of the specified position. The size of the neighbourhood used is chosen to minimise the RMS residual per unit length between the interpolating polynomial and the supplied Mapping function. This method produces good accuracy but can involve evaluating the Mapping 100 or more times.

Parameters
[in]atThe input position at which the rate of change is to be evaluated.
[in]ax1The index of the output for which the rate of change is to be found (1 for first output).
[in]ax2The index of the input which is to be varied in order to find the rate of change (1 for the first input).
Returns
The rate of change of Mapping output ax1 with respect to input ax2, evaluated at at, or nan if the value cannot be calculated.

◆ setReport()

void ast::Mapping::setReport ( bool  report)
inline

Set Report: report transformed coordinates to stdout?

◆ simplified()

std::shared_ptr<Mapping> ast::Mapping::simplified ( ) const
inline

Return a simplied version of the mapping (which may be a compound Mapping such as a CmpMap).

Simplification eliminates redundant computational steps and merges separate steps which can be performed more efficiently in a single operation. As a simple example, a Mapping which multiplied coordinates by 5, and then multiplied the result by 10, could be simplified to a single step which multiplied by 50. Similarly, a Mapping which multiplied by 5, and then divided by 5, could be reduced to a simple copying operation.

This function should typically be applied to Mappings which have undergone substantial processing or have been formed by merging other Mappings. It is of potential benefit, for example, in reducing execution time if applied before using a Mapping to transform a large number of coordinates.

Note
If the supplied Mapping is a FrameSet, the returned Mapping will be a deep copy of the supplied FrameSet in which all the inter-Frame Mappings have been simplified. Mappings that have a set value for their ref Object_Ident "Ident" attribute are unchanged by simplification. This is so that their individual identity is preserved. This restriction does not apply to the simplification of Frames. The returned mapping is always independent of the original (a deep copy), unlike astSimplify.

◆ then()

SeriesMap ast::Mapping::then ( Mapping const &  next) const

Return a series compound mapping this(first(input)) containing shallow copies of the original

Parameters
[in]nextthe mapping whose input is the output of this mapping
Exceptions
std::invalid_argumentif the number of input axes of next does not match the number of output axes of this mapping.
Warning
The contained mappings are shallow copies (just like AST); if you want deep copies then make them manually.

◆ tranGridForward() [1/2]

void ast::Mapping::tranGridForward ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
Array2D const &  to 
) const
inline

Transform a grid of points in the forward direction

Parameters
[in]lbndThe coordinates of the centre of the first pixel in the input grid along each dimension, size = nIn
[in]ubndThe coordinates of the centre of the last pixel in the input grid along each dimension, size = nIn
[in]tolThe maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement within the output coordinate system of the Mapping.

If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time.

If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher. If this is a problem, reduce the tolerance value used.

Parameters
[in]maxpixA value which specifies an initial scale size (in input grid points) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed " maxpix" grid points in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 grid points can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting " tol" to zero). Although this may degrade performance, accurate results will still be obtained.
[in]toComputed points, with dimensions (nPts, nOut), where nPts the desired number of points

◆ tranGridForward() [2/2]

Array2D ast::Mapping::tranGridForward ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
int  nPts 
) const
inline

Transform a grid of points in the inverse direction, returning the results as a new Array2D

See the overload of tranGridForward that outputs the data as the last argument for more information

◆ tranGridInverse() [1/2]

void ast::Mapping::tranGridInverse ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
Array2D const &  to 
) const
inline

Transform a grid of points in the inverse direction

See tranGridForward for the arguments, swapping nIn and nOut

◆ tranGridInverse() [2/2]

Array2D ast::Mapping::tranGridInverse ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
int  nPts 
) const
inline

Transform a grid of points in the inverse direction

See tranGridForward for the arguments, swapping nIn and nOut

◆ under()

ParallelMap ast::Mapping::under ( Mapping const &  next) const

Return a parallel compound mapping containing shallow copies of the original

The resulting mapping has getNIn() + next.getNIn() inputs and getNOut() + next.getNOut() outputs. The first getNIn() axes of input are transformed by this mapping, producing the first getNOut() axes of output. The remaining axes of input are processed by next, resulting in the remaining axes of output.

The name comes the way vectors are sometimes shown for matrix multiplication: vertically, with the first axis at the bottom and the last axis at the top.

Parameters
[in]nextthe mapping that processes the final next.getNin() axes of input to produce the final next.getNout() axes of output.
Warning
The contained mappings are shallow copies (just like AST); if you want deep copies then make them manually.

Friends And Related Function Documentation

◆ Object

friend class Object
friend

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