LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Friends | List of all members
ast::FrameSet Class Reference

A FrameSet consists of a set of one or more Frames (which describe coordinate systems), connected together by Mappings (which describe how the coordinate systems are inter-related). More...

#include <FrameSet.h>

Inheritance diagram for ast::FrameSet:
ast::Frame ast::Mapping ast::Object ast::FrameDict

Public Types

using ObjectPtr = std::unique_ptr< AstObject, Deleter >
 unique pointer holding an AST raw pointer More...
 

Public Member Functions

 FrameSet (Frame const &frame, std::string const &options="")
 Construct a FrameSet from a Frame. More...
 
 FrameSet (Frame const &baseFrame, Mapping const &mapping, Frame const &currentFrame, std::string const &options="")
 Construct a FrameSet from two frames and a mapping that connects them. More...
 
virtual ~FrameSet ()
 
 FrameSet (FrameSet const &)=default
 Copy constructor: make a deep copy. More...
 
 FrameSet (FrameSet &&)=default
 
FrameSetoperator= (FrameSet const &)=delete
 
FrameSetoperator= (FrameSet &&)=default
 
std::shared_ptr< FrameSetcopy () const
 Return a deep copy of this object. More...
 
void addAxes (Frame const &frame)
 Append the axes from a specified Frame to every existing Frame in this FrameSet. More...
 
virtual void addFrame (int iframe, Mapping const &map, Frame const &frame)
 Add a new Frame and an associated Mapping to this FrameSet so as to define a new coordinate system, derived from one which already exists within this FrameSet. More...
 
void addVariant (Mapping const &map, std::string const &name)
 Store a new variant Mapping with the current Frame. More...
 
std::string getAllVariants () const
 Get AllVariants: a list of all variant mappings stored with the current Frame. More...
 
int getBase () const
 Get Base: index of base Frame. More...
 
int getCurrent () const
 Get Current: index of current Frame, starting from 1. More...
 
std::shared_ptr< FramegetFrame (int iframe, bool copy=true) const
 Obtain a deep copy of the specified Frame. More...
 
std::shared_ptr< MappinggetMapping (int from=BASE, int to=CURRENT) const
 Obtain a Mapping that converts between two Frames in a FrameSet. More...
 
int getNFrame () const
 Get FrameSet_NFrame "NFrame": number of Frames in the FrameSet, starting from 1. More...
 
std::string getVariant () const
 Variant: name of variant mapping in use by current Frame More...
 
void mirrorVariants (int iframe)
 Indicates that all access to the Variant attribute of the current Frame should should be forwarded to some other nominated Frame in the FrameSet. More...
 
void remapFrame (int iframe, Mapping &map)
 Modify the relationship (i.e. More...
 
virtual void removeFrame (int iframe)
 Remove a Frame from a FrameSet. More...
 
void renameVariant (std::string const &name)
 Rename the current Variant of the current Mapping. More...
 
void setBase (int ind)
 Set Base: index of base Frame. More...
 
void setCurrent (int ind)
 Set Current: index of current Frame, starting from 1. More...
 
double angle (PointD const &a, PointD const &b, PointD const &c) const
 Find the angle at point B between the line joining points A and B, and the line joining points C and B. More...
 
double axAngle (PointD const &a, PointD const &b, int axis) const
 Find the angle, as seen from point A, between the positive direction of a specified axis, and the geodesic curve joining point A to point B. More...
 
double axDistance (int axis, double v1, double v2) const
 Return a signed value representing the axis increment from axis value v1 to axis value v2. More...
 
double axOffset (int axis, double v1, double dist) const
 Return an axis value formed by adding a signed axis increment onto a supplied axis value. More...
 
std::shared_ptr< FrameSetconvert (Frame const &to, std::string const &domainlist="")
 Compute a frameset that describes the conversion between this frame and another frame. More...
 
double distance (PointD const &point1, PointD const &point2) const
 Find the distance between two points whose Frame coordinates are given. More...
 
std::shared_ptr< FrameSetfindFrame (Frame const &tmplt, std::string const &domainlist="")
 Find a coordinate system with specified characteristics. More...
 
std::string format (int axis, double value) const
 Return a string containing the formatted (character) version of a coordinate value for a Frame axis. More...
 
bool getActiveUnit () const
 Get ActiveUnit: pay attention to units when one Frame is used to match another? More...
 
std::string getAlignSystem () const
 Get AlignSystem: the coordinate system used by convert and findFrame to align Frames. More...
 
double getBottom (int axis) const
 Get Bottom for one axis: the lowest axis value to display. More...
 
int getDigits () const
 Get Digits: the default used if no specific value specified for an axis. More...
 
int getDigits (int axis) const
 Get Digits for one axis. More...
 
bool getDirection (int axis) const
 Get Direction for one axis: display axis in conventional direction? More...
 
std::string getDomain () const
 Get Domain: coordinate system domain. More...
 
double getDut1 () const
 Get Dut1: difference between the UT1 and UTC timescale (sec) More...
 
double getEpoch () const
 Get Epoch: Epoch of observation. More...
 
std::string getFormat (int axis) const
 Get Format for one axis: format specification for axis values. More...
 
std::string getInternalUnit (int axis) const
 Get InternalUnit(axis) read-only attribute for one axis: physical units for unformated axis values. More...
 
std::string getLabel (int axis) const
 Get Label(axis) for one axis: axis label. More...
 
bool getMatchEnd () const
 Get MatchEnd: match trailing axes? More...
 
int getMaxAxes () const
 Get MaxAxes: the maximum axes a frame found by findFrame may have. More...
 
int getMinAxes () const
 Get MinAxes: the maximum axes a frame found by findFrame may have. More...
 
int getNAxes () const
 Get NAxes: the number of axes in the frame (i.e. More...
 
std::string getNormUnit (int axis) const
 Get NormUnit(axis) read-only attribute for one frame: normalised physical units for formatted axis values. More...
 
double getObsAlt () const
 Get ObsAlt: Geodetic altitude of observer (m). More...
 
std::string getObsLat () const
 Get ObsLat: Geodetic latitude of observer. More...
 
std::string getObsLon () const
 Get ObsLon: Geodetic longitude of observer. More...
 
bool getPermute () const
 Get Permute: allow axis permutation when used as a template? More...
 
bool getPreserveAxes () const
 Get PreserveAxes: preserve axes? More...
 
std::string getSymbol (int axis) const
 Get Symbol(axis) for one axis: axis symbol. More...
 
std::string getSystem () const
 Get System: coordinate system used to describe positions within the domain. More...
 
std::string getTitle () const
 Get Title: frame title. More...
 
double getTop (int axis) const
 Get Top: the highest axis value to display. More...
 
std::string getUnit (int axis) const
 Get Unit(axis) for one axis: physical units for formatted axis values. More...
 
std::vector< double > intersect (std::vector< double > const &a1, std::vector< double > const &a2, std::vector< double > const &b1, std::vector< double > const &b2) const
 Find the point of intersection between two geodesic curves. More...
 
std::vector< int > matchAxes (Frame const &other) const
 Look for corresponding axes between this frame and another. More...
 
CmpFrame under (Frame const &next) const
 Combine this frame with another to form a compound frame (CmpFrame), with the axes of this frame followed by the axes of the next frame. More...
 
ParallelMap under (Mapping const &next) const
 Return a parallel compound mapping containing shallow copies of the original. More...
 
PointD norm (PointD value) const
 Normalise a set of Frame coordinate values which might be unsuitable for display (e.g. More...
 
PointD offset (PointD point1, PointD point2, double offset) const
 Find the point which is offset a specified distance along the geodesic curve between two other points. More...
 
DirectionPoint offset2 (PointD const &point1, double angle, double offset) const
 Find the point which is offset a specified distance along the geodesic curve at a given angle from a specified starting point. More...
 
void permAxes (std::vector< int > perm)
 Permute the order in which a Frame's axes occur. More...
 
FrameMapping pickAxes (std::vector< int > const &axes) const
 Create a new Frame whose axes are copied from an existing Frame along with other Frame attributes, such as its Title. More...
 
ResolvedPoint resolve (std::vector< double > const &point1, std::vector< double > const &point2, std::vector< double > const &point3) const
 Resolve a vector into two orthogonal components. More...
 
void setAlignSystem (std::string const &system)
 Set AlignSystem: the coordinate system used by convert and findFrame to align Frames. More...
 
void setBottom (int axis, double bottom)
 Set Bottom: the lowest axis value to display. More...
 
void setDigits (int digits)
 Set Digits for all axes: number of digits of precision. More...
 
void setDigits (int axis, int digits)
 Set Digits for one axis: number of digits of precision. More...
 
void setDirection (bool direction, int axis)
 Set Direction for one axis: display axis in conventional direction? More...
 
virtual void setDomain (std::string const &domain)
 Set Domain: coordinate system domain. More...
 
void setDut1 (double dut1)
 Set Dut1: difference between the UT1 and UTC timescale (sec) More...
 
void setEpoch (double epoch)
 Set Epoch: Epoch of observation as a double (years) More...
 
void setEpoch (std::string const &epoch)
 Set Epoch: Epoch of observation as a string. More...
 
void setFormat (int axis, std::string const &format)
 Set Format for one axis: format specification for axis values. More...
 
void setLabel (int axis, std::string const &label)
 Set Label(axis) for one axis: axis label. More...
 
void setMatchEnd (bool match)
 Set MatchEnd: match trailing axes? More...
 
void setMaxAxes (int maxAxes)
 Get MaxAxes: the maximum number of axes a frame found by findFrame may have. More...
 
void setMinAxes (int minAxes)
 Get MinAxes: the minimum number of axes a frame found by findFrame may have. More...
 
void setObsAlt (double alt)
 Set ObsAlt: Geodetic altitude of observer (m). More...
 
void setObsLat (std::string const &lat)
 Set ObsLat: frame title. More...
 
void setObsLon (std::string const &lon)
 Set ObsLon: Geodetic longitude of observer. More...
 
void setActiveUnit (bool enable)
 Set ActiveUnit: pay attention to units when one Frame is used to match another? More...
 
void setPermute (bool permute)
 Set Permute: allow axis permutation when used as a template? More...
 
void setPreserveAxes (bool preserve)
 Set PreserveAxes: preserve axes? More...
 
void setSymbol (int axis, std::string const &symbol)
 Set Symbol(axis) for one axis: axis symbol. More...
 
void setSystem (std::string const &system)
 Set System: coordinate system used to describe positions within the domain. More...
 
void setTitle (std::string const &title)
 Set Title: frame title. More...
 
void setTop (int axis, double top)
 Set Top for one axis: the highest axis value to display. More...
 
void setUnit (int axis, std::string const &unit)
 Set Unit(axis) for one axis: physical units for formatted axis values. More...
 
NReadValue unformat (int axis, std::string const &str) const
 Read a formatted coordinate value (given as a character string) for a Frame axis and return the number of characters read and the value. More...
 
int getNIn () const
 Get NIn: the number of input axes. More...
 
int getNOut () const
 Get NOut: the number of output axes. More...
 
bool getIsSimple () const
 Get IsSimple: has the mapping been simplified? More...
 
bool isInverted () const
 Is this an inverted mapping? More...
 
bool getIsLinear () const
 Get IsLinear: is the Mapping linear? More...
 
bool getReport () const
 Get Report: report transformed coordinates to stdout? More...
 
bool hasForward () const
 Is the forward transform available? More...
 
bool hasInverse () const
 Is the inverse transform available? More...
 
std::shared_ptr< Mappinginverted () const
 Get an inverse mapping. More...
 
Array2D linearApprox (PointD const &lbnd, PointD const &ubnd, double tol) const
 Compute a linear approximation to the forward transformation. More...
 
SeriesMap then (Mapping const &next) const
 Return a series compound mapping this(first(input)) containing shallow copies of the original. More...
 
double rate (PointD const &at, int ax1, int ax2) const
 Evaluate the rate of change of the Mapping with respect to a specified input, at a specified position. More...
 
void setReport (bool report)
 Set Report: report transformed coordinates to stdout? More...
 
std::shared_ptr< Mappingsimplified () const
 Return a simplied version of the mapping (which may be a compound Mapping such as a CmpMap). More...
 
void applyForward (ConstArray2D const &from, Array2D const &to) const
 Perform a forward transformation on 2-D array, putting the results into a pre-allocated 2-D array. More...
 
Array2D applyForward (ConstArray2D const &from) const
 Perform a forward transformation on a 2-D array, returning the results as a new array. More...
 
std::vector< double > applyForward (std::vector< double > const &from) const
 Perform a forward transformation on a vector, returning the results as a new vector. More...
 
void applyInverse (ConstArray2D const &from, Array2D const &to) const
 Perform an inverse transformation on a 2-D array, putting the results into a pre-allocated 2-D array. More...
 
Array2D applyInverse (ConstArray2D const &from) const
 Perform an inverse transformation on a 2-D array, returning the results as a new 2-D array. More...
 
std::vector< double > applyInverse (std::vector< double > const &from) const
 Perform an inverse transformation on a vector, returning the results as a new vector. More...
 
void tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 Transform a grid of points in the forward direction. More...
 
Array2D tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 Transform a grid of points in the inverse direction, returning the results as a new Array2D. More...
 
void tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 Transform a grid of points in the inverse direction. More...
 
Array2D tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 Transform a grid of points in the inverse direction. More...
 
bool operator== (Object const &rhs) const
 Return True if this and rhs are the equal. More...
 
bool operator!= (Object const &rhs) const
 Return True if this and rhs are not equal. More...
 
void clear (std::string const &attrib)
 Clear the values of a specified set of attributes for an Object. More...
 
bool hasAttribute (std::string const &attrib) const
 Does this object have an attribute with the specified name? More...
 
std::string getClassName () const
 Get Class: the name of the class (e.g. More...
 
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
 Get NObject: number of AST objects in existence of the same type as the underlying AST class. More...
 
int getObjSize () const
 Get ObjSize: the in-memory size of the AST object in bytes. More...
 
int getRefCount () const
 Get RefCount: number of active pointers to the underlying AST object. More...
 
bool getUseDefs () const
 Get UseDefs: allow use of default values for Object attributes? More...
 
void lock (bool wait)
 Lock this object for exclusive use by the calling thread. More...
 
bool same (Object const &other) const
 Does this contain the same AST object as another? More...
 
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
 Print a textual description the object to an ostream. More...
 
std::string show (bool showComments=true) const
 Return a textual description the object as a string. More...
 
bool test (std::string const &attrib) const
 Has this attribute been explicitly set (and not subsequently cleared)? More...
 
void unlock (bool report=false)
 Unlock this object previously locked using lock, so that other threads can use this object. More...
 
AstObject const * getRawPtr () const
 Get the raw AST pointer. More...
 
AstObject * getRawPtr ()
 Get the raw AST pointer. More...
 

Static Public Member Functions

static std::shared_ptr< ObjectfromString (std::string const &str)
 Construct an Object from a string, using astFromString. More...
 
template<typename Class >
static std::shared_ptr< Class > fromAstObject (AstObject *rawObj, bool copy)
 Given a bare AST object pointer return a shared pointer to an ast::Object of the correct type. More...
 

Static Public Attributes

static constexpr int BASE = AST__BASE
 index of base frame More...
 
static constexpr int CURRENT = AST__CURRENT
 index of current frame More...
 
static constexpr int NOFRAME = AST__NOFRAME
 an invalid frame index More...
 

Protected Member Functions

virtual std::shared_ptr< ObjectcopyPolymorphic () const override
 Return a deep copy of this object. More...
 
 FrameSet (AstFrameSet *rawPtr)
 Construct a FrameSet from a raw AST pointer. More...
 
template<typename Class >
std::shared_ptr< Class > decompose (int i, bool copy) const
 Return a deep copy of one of the two component mappings. More...
 
template<typename T , typename AstT >
std::shared_ptr< T > copyImpl () const
 Implementation of deep copy. More...
 
bool getB (std::string const &attrib) const
 Get the value of an attribute as a bool. More...
 
std::string const getC (std::string const &attrib) const
 Get the value of an attribute as a string. More...
 
double getD (std::string const &attrib) const
 Get the value of an attribute as a double. More...
 
float getF (std::string const &attrib) const
 Get the value of an attribute as a float. More...
 
int getI (std::string const &attrib) const
 Get the value of an attribute as an int. More...
 
long int getL (std::string const &attrib) const
 Get the value of an attribute as a long int. More...
 
void set (std::string const &setting)
 Assign a set of attribute values, over-riding any previous values. More...
 
void setB (std::string const &attrib, bool value)
 Set the value of an attribute as a bool. More...
 
void setC (std::string const &attrib, std::string const &value)
 Set the value of an attribute as a string. More...
 
void setD (std::string const &attrib, double value)
 Set the value of an attribute as a double. More...
 
void setF (std::string const &attrib, float value)
 Set the value of an attribute as a float. More...
 
void setI (std::string const &attrib, int value)
 Set the value of an attribute as an int. More...
 
void setL (std::string const &attrib, long int value)
 Set the value of an attribute as a long int. More...
 

Static Protected Member Functions

template<typename ShimT , typename AstT >
static std::shared_ptr< ShimT > makeShim (AstObject *p)
 Functor to make an astshim instance from a raw AST pointer of the corresponding type. More...
 

Friends

class Frame
 
class Object
 

Detailed Description

A FrameSet consists of a set of one or more Frames (which describe coordinate systems), connected together by Mappings (which describe how the coordinate systems are inter-related).

A FrameSet makes it possible to obtain a Mapping between any pair of these Frames (i.e. to convert between any of the coordinate systems which it describes). The individual Frames are identified within the FrameSet by an integer index, with Frames being numbered consecutively from one as they are added to the FrameSet.

Every FrameSet has a "base" Frame and a "current" Frame (which are allowed to be the same). Any of the Frames may be nominated to hold these positions, and the choice is determined by the values of the FrameSet's Base and Current attributes, which hold the indices of the relevant Frames. By default, the first Frame added to a FrameSet is its base Frame, and the last one added is its current Frame.

The base Frame describes the "native" coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the "apparent" coordinate system in which it should be viewed (e.g. displayed, etc.). Any further Frames represent a library of alternative coordinate systems, which may be selected by making them current.

When a FrameSet is used in a context that requires a Frame, (e.g. obtaining its Title value, or number of axes), the current Frame is used. A FrameSet may therefore be used in place of its current Frame in most situations.

When a FrameSet is used in a context that requires a Mapping, the Mapping used is the one between its base Frame and its current Frame. Thus, a FrameSet may be used to convert "native" coordinates into "apparent" ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see Mapping::inverted), which has the effect of returning a copy with base and current Frames swapped, hence of reversing the Mapping between them.

Regions may be added into a FrameSet (since a Region is a type of Frame), either explicitly or as components within CmpFrames. In this case the Mapping between a pair of Frames within a FrameSet will include the effects of the clipping produced by any Regions included in the path between the Frames.

Attributes

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

Every FrameSet also inherits any further attributes that belong to its current Frame, regardless of that Frame's class. (For example, the Equinox attribute, defined by SkyFrame, is inherited by any FrameSet which has a SkyFrame as its current Frame.) The set of attributes belonging to a FrameSet may therefore change when a new current Frame is selected.

Definition at line 99 of file FrameSet.h.

Member Typedef Documentation

◆ ObjectPtr

using ast::Object::ObjectPtr = std::unique_ptr<AstObject, Deleter>
inherited

unique pointer holding an AST raw pointer

Definition at line 59 of file Object.h.

Constructor & Destructor Documentation

◆ FrameSet() [1/5]

ast::FrameSet::FrameSet ( Frame const &  frame,
std::string const &  options = "" 
)
inlineexplicit

Construct a FrameSet from a Frame.

The frame is deep copied.

Parameters
[in]framethe first Frame to be inserted into the FrameSet. This initially becomes both the base and the current Frame. Further Frames may be added using addFrame
[in]optionsComma-separated list of attribute assignments.

Definition at line 117 of file FrameSet.h.

118  : FrameSet(astFrameSet(frame.copy()->getRawPtr(), "%s", options.c_str())) {
119  assertOK();
120  }
FrameSet(Frame const &frame, std::string const &options="")
Construct a FrameSet from a Frame.
Definition: FrameSet.h:117
void assertOK(AstObject *rawPtr1=nullptr, AstObject *rawPtr2=nullptr)
Throw std::runtime_error if AST's state is bad.
Definition: base.cc:49

◆ FrameSet() [2/5]

ast::FrameSet::FrameSet ( Frame const &  baseFrame,
Mapping const &  mapping,
Frame const &  currentFrame,
std::string const &  options = "" 
)
inlineexplicit

Construct a FrameSet from two frames and a mapping that connects them.

Both frames and the mapping are deep copied.

Parameters
[in]baseFramebase Frame.
[in]mappingmapping connecting baseFrame to currentFrame.
[in]currentFramecurrent Frame.
[in]optionsComma-separated list of attribute assignments.

Definition at line 132 of file FrameSet.h.

134  : FrameSet(baseFrame, options) {
135  _basicAddFrame(1, mapping, currentFrame);
136  }

◆ ~FrameSet()

virtual ast::FrameSet::~FrameSet ( )
inlinevirtual

Definition at line 138 of file FrameSet.h.

138 {}

◆ FrameSet() [3/5]

ast::FrameSet::FrameSet ( FrameSet const &  )
default

Copy constructor: make a deep copy.

◆ FrameSet() [4/5]

ast::FrameSet::FrameSet ( FrameSet &&  )
default

◆ FrameSet() [5/5]

ast::FrameSet::FrameSet ( AstFrameSet *  rawPtr)
inlineexplicitprotected

Construct a FrameSet from a raw AST pointer.

This method is public so Frame can call it.

Exceptions
std::invalid_argumentif rawPtr is not an AstFrameSet.

Definition at line 490 of file FrameSet.h.

490  : Frame(reinterpret_cast<AstFrame *>(rawPtr)) {
491  if (!astIsAFrameSet(getRawPtr())) {
493  os << "this is a " << getClassName() << ", which is not a FrameSet";
494  throw std::invalid_argument(os.str());
495  }
496  }
std::ostream * os
Definition: Schema.cc:557
friend class Frame
Definition: FrameSet.h:100
std::string getClassName() const
Get Class: the name of the class (e.g.
Definition: Object.h:139
AstObject const * getRawPtr() const
Get the raw AST pointer.
Definition: Object.h:292

Member Function Documentation

◆ addAxes()

void ast::FrameSet::addAxes ( Frame const &  frame)
inline

Append the axes from a specified Frame to every existing Frame in this FrameSet.

In detail, each Frame in this FrameSet is replaced by a CmpFrame containing the original Frame and the Frame specified by parameter frame. In addition, each Mapping in the FrameSet is replaced by a CmpMap containing the original Mapping and a UnitMap in parallel. The NIn and NOut attributes of the UnitMap are set equal to the number of axes in the supplied Frame. Each new CmpMap is simplified before being stored in the FrameSet.

Parameters
[in]frameFrame whose axes are to be appended to each Frame in this FrameSet.

Definition at line 160 of file FrameSet.h.

160  {
161  astAddFrame(getRawPtr(), AST__ALLFRAMES, nullptr, frame.getRawPtr());
162  assertOK();
163  }

◆ addFrame()

virtual void ast::FrameSet::addFrame ( int  iframe,
Mapping const &  map,
Frame const &  frame 
)
inlinevirtual

Add a new Frame and an associated Mapping to this FrameSet so as to define a new coordinate system, derived from one which already exists within this FrameSet.

If frame is a Frame then it becomes the current frame and its index is the new number of frames. If frame is a FrameSet then its current frame becomes the new current frame and the indices of all its frames are increased by the number of frames originally in this FrameSet. In both cases the indices of the Frames already in this FrameSet are left unchanged.

Parameters
[in]iframeThe index of the Frame within the FrameSet which describes the coordinate system upon which the new one is to be based. This value should lie in the range from 1 to the number of frames already in this FrameSet (as given by getNFrame). A value of FrameSet::BASE or FrameSet::CURRENT may be given to specify the base Frame or the current Frame respectively. A value of AST__ALLFRAMES is not permitted; call addAllFrames instead.
[in]mapA Mapping which describes how to convert coordinates from the old coordinate system (described by the Frame with index iframe ) into coordinates in the new system. The Mapping's forward transformation should perform this conversion, and its inverse transformation should convert in the opposite direction.
[in]frameA Frame that describes the new coordinate system. Any type of Frame may be supplied (including Regions and FrameSets). This function may also be used to merge two FrameSets by supplying a pointer to a second FrameSet for this parameter (see the Notes section for details).

Notes

  • Deep copies of the supplied map and frame are stored within the modified FrameSet. So any changes made to the FrameSet after calling this method will have no effect on the supplied Mapping and Frame objects.
  • This function sets the value of the Current attribute for the FrameSet so that the new Frame subsequently becomes the current Frame.
  • The number of input coordinate values accepted by the supplied map (its NIn attribute) must match the number of axes in the Frame identified by the iframe parameter. Similarly, the number of output coordinate values generated by map (its NOut attribute) must match the number of axes in frame.
  • As a special case, if a pointer to a FrameSet is given for the frame parameter, this is treated as a request to merge frame into this FrameSet. This is done by appending all the new Frames in the frame FrameSet to this FrameSet, while preserving their order and retaining all the inter-relationships (i.e. Mappings) between them. The two sets of Frames are inter-related within the merged FrameSet by using the Mapping supplied. This should convert between the Frame identified by the iframe parameter (in this FrameSet) and the current Frame of the frame FrameSet. This latter Frame becomes the current Frame in this FrameSet.

Reimplemented in ast::FrameDict.

Definition at line 210 of file FrameSet.h.

210  {
211  _basicAddFrame(iframe, map, frame);
212  }

◆ addVariant()

void ast::FrameSet::addVariant ( Mapping const &  map,
std::string const &  name 
)
inline

Store a new variant Mapping with the current Frame.

The newly added variant becomes the current variant (attribute the Variant is set to name).

See the Variant attribute for more details. See also getVariant, renameVariant and mirrorVariants

Parameters
[in]mapA Mapping which describes how to convert coordinates from the current frame to the new variant of the current Frame.
[in]nameThe name to associate with the new variant Mapping.
Exceptions
std::runtime_errorif:
  • A variant with the supplied name already exists in the current Frame.
  • The current Frame is a mirror for the variant Mappings in another Frame. This is only the case if the astMirrorVariants function has been called to make the current Frame act as a mirror.

Definition at line 234 of file FrameSet.h.

234  {
235  astAddVariant(getRawPtr(), map.getRawPtr(), name.c_str());
236  assertOK();
237  }
table::Key< std::string > name
Definition: Amplifier.cc:116

◆ angle()

double ast::Frame::angle ( PointD const &  a,
PointD const &  b,
PointD const &  c 
) const
inlineinherited

Find the angle at point B between the line joining points A and B, and the line joining points C and B.

These lines will in fact be geodesic curves appropriate to the Frame in use. For instance, in SkyFrame, they will be great circles.

Parameters
[in]athe coordinates of the first point
[in]bthe coordinates of the first second
[in]cthe coordinates of the first third
Returns
The angle in radians, from the line AB to the line CB. If the Frame is 2-dimensional, it will be in the range [-pi, pi], and positive rotation is in the same sense as rotation from the positive direction of axis 2 to the positive direction of axis 1. If the Frame has more than 2 axes, a positive value will always be returned in the range (0, pi].
Exceptions
std::invalid_argumentif a, b or c have the wrong length

Definition at line 201 of file Frame.h.

201  {
202  assertPointLength(a, "a");
203  assertPointLength(b, "b");
204  assertPointLength(c, "c");
205  return detail::safeDouble(astAngle(getRawPtr(), a.data(), b.data(), c.data()));
206  }
table::Key< int > b
table::Key< int > a
double safeDouble(double val)
Return a double value after checking status and replacing AST__BAD with nan
Definition: utils.h:100

◆ applyForward() [1/3]

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

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)

Definition at line 268 of file Mapping.h.

268  {
269  Array2D to = ndarray::allocate(getNOut(), from.getSize<1>());
270  _tran(from, true, to);
271  return to;
272  }
table::Key< int > from
table::Key< int > to
int getNOut() const
Get NOut: the number of output axes.
Definition: Mapping.h:82
ndarray::Array< double, 2, 2 > Array2D
2D array of const double; typically used for lists of const points
Definition: base.h:42

◆ applyForward() [2/3]

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

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)

Definition at line 260 of file Mapping.h.

260 { _tran(from, true, to); }

◆ applyForward() [3/3]

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

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

Definition at line 280 of file Mapping.h.

280  {
281  auto fromArr = arrayFromVector(from, getNIn());
282  std::vector<double> to(fromArr.getSize<1>() * getNOut());
283  auto toArr = arrayFromVector(to, getNOut());
284  _tran(fromArr, true, toArr);
285  return to;
286  }
int getNIn() const
Get NIn: the number of input axes.
Definition: Mapping.h:77
ConstArray2D arrayFromVector(std::vector< double > const &vec, int nAxes)
Reshape a vector as a 2-dimensional array that shares the same memory.
Definition: base.cc:65

◆ applyInverse() [1/3]

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

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)

Definition at line 302 of file Mapping.h.

302  {
303  Array2D to = ndarray::allocate(getNIn(), from.getSize<1>());
304  _tran(from, false, to);
305  return to;
306  }

◆ applyInverse() [2/3]

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

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)

Definition at line 294 of file Mapping.h.

294 { _tran(from, false, to); }

◆ applyInverse() [3/3]

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

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

Definition at line 314 of file Mapping.h.

314  {
315  auto fromArr = arrayFromVector(from, getNOut());
316  std::vector<double> to(fromArr.getSize<1>() * getNIn());
317  auto toArr = arrayFromVector(to, getNIn());
318  _tran(fromArr, false, toArr);
319  return to;
320  }

◆ axAngle()

double ast::Frame::axAngle ( PointD const &  a,
PointD const &  b,
int  axis 
) const
inlineinherited

Find the angle, as seen from point A, between the positive direction of a specified axis, and the geodesic curve joining point A to point B.

Parameters
[in]athe coordinates of the first point
[in]bthe coordinates of the second point
[in]axisthe index of the axis from which the angle is to be measured, where 1 is the first axis
Returns
The angle in radians, from the positive direction of the specified axis, to the line AB. If the Frame is 2-dimensional, it will be in the range [-pi/2, +pi/2], and positive rotation is in the same sense as rotation from the positive direction of axis 2 to the positive direction of axis 1. If the Frame has more than 2 axes, a positive value will always be returned in the range (0, pi]
Exceptions
std::invalid_argumentif a or b have the wrong length

Notes:

  • The geodesic curve used by this function is the path of shortest distance between two points, as defined by the distance method.

Definition at line 229 of file Frame.h.

229  {
230  assertPointLength(a, "a");
231  assertPointLength(b, "b");
232  return detail::safeDouble(astAxAngle(getRawPtr(), a.data(), b.data(), axis));
233  }

◆ axDistance()

double ast::Frame::axDistance ( int  axis,
double  v1,
double  v2 
) const
inlineinherited

Return a signed value representing the axis increment from axis value v1 to axis value v2.

For a simple Frame, this is a trivial operation returning the difference between the two axis values. But for other derived classes of Frame (such as a SkyFrame) this is not the case.

Parameters
[in]axisThe index of the axis to which the supplied values refer. The first axis has index 1.
[in]v1The first axis value.
[in]v2The second axis value.
Returns
The distance from the first to the second axis value.

Definition at line 247 of file Frame.h.

247  {
248  return detail::safeDouble(astAxDistance(getRawPtr(), axis, v1, v2));
249  }

◆ axOffset()

double ast::Frame::axOffset ( int  axis,
double  v1,
double  dist 
) const
inlineinherited

Return an axis value formed by adding a signed axis increment onto a supplied axis value.

For a simple Frame, this is a trivial operation returning the sum of the two supplied values. But for other derived classes of Frame (such as a SkyFrame) this is not the case.

Parameters
[in]axisThe index of the axis to which the supplied values refer. The first axis has index 1.
[in]v1The original axis value.
[in]distThe axis increment to add to the original axis value.
Returns
The incremented axis value

Definition at line 263 of file Frame.h.

263  {
264  return detail::safeDouble(astAxOffset(getRawPtr(), axis, v1, dist));
265  }

◆ clear()

void ast::Object::clear ( std::string const &  attrib)
inlineinherited

Clear the values of a specified set of attributes for an Object.

Clearing an attribute cancels any value that has previously been explicitly set for it, so that the standard default attribute value will subsequently be used instead. This also causes the astTest function to return the value zero for the attribute, indicating that no value has been set.

Definition at line 119 of file Object.h.

119  {
120  astClear(getRawPtr(), attrib.c_str());
121  assertOK();
122  }

◆ convert()

std::shared_ptr< FrameSet > ast::Frame::convert ( Frame const &  to,
std::string const &  domainlist = "" 
)
inherited

Compute a frameset that describes the conversion between this frame and another frame.

If conversion is possible, it returns a shared pointer to a FrameSet which describes the conversion and which may be used (as a Mapping) to transform coordinate values in either direction. Otherwise it returns an empty shared pointer.

The same function may also be used to determine how to convert between two FrameSets (or between a Frame and a FrameSet, or vice versa). This mode is intended for use when (for example) two images have been calibrated by attaching a FrameSet to each. convert might then be used to search for a celestial coordinate system that both images have in common, and the result could then be used to convert between the pixel coordinates of both images – having effectively used their celestial coordinate systems to align them.

When using FrameSets, there may be more than one possible intermediate coordinate system in which to perform the conversion (for instance, two FrameSets might both have celestial coordinates, detector coordinates, pixel coordinates, etc.). A comma-separated list of coordinate system domains may therefore be given which defines a priority order to use when selecting the intermediate coordinate system. The path used for conversion must go via an intermediate coordinate system whose Domain attribute matches one of the domains given. If conversion cannot be achieved using the first domain, the next one is considered, and so on, until success is achieved.

Applicability

  • DSBSpecFrame

    If the AlignSideBand attribute is non-zero, alignment occurs in the upper sideband expressed within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest. If AlignSideBand is zero, the two DSBSpecFrames are aligned as if they were simple SpecFrames (i.e. the SideBand is ignored).

  • Frame

    This function applies to all Frames. Alignment occurs within the coordinate system given by attribute AlignSystem.

  • FrameSet

    If either this object or to is a FrameSet, then this method will attempt to convert from the coordinate system described by the current Frame of the "from" FrameSet to that described by the current Frame of the "to" FrameSet.

    To achieve this, it will consider all of the Frames within each FrameSet as a possible way of reaching an intermediate coordinate system that can be used for the conversion. There is then the possibility that more than one conversion path may exist and, unless the choice is sufficiently restricted by the "domainlist" string, the sequence in which the Frames are considered can be important. In this case, the search for a conversion path proceeds as follows:

    • Each field in the "domainlist" string is considered in turn.
    • The Frames within each FrameSet are considered in a specific order: (1) the base Frame is always considered first, (2) after this come all the other Frames in Frame-index order (but omitting the base and current Frames), (3) the current Frame is always considered last. However, if either FrameSet's Invert attribute is set to a non-zero value (so that the FrameSet is inverted), then its Frames are considered in reverse order. (Note that this still means that the base Frame is considered first and the current Frame last, because the Invert value will also cause these Frames to swap places.)
    • All source Frames are first considered (in the appropriate order) for conversion to the first destination Frame. If no suitable intermediate coordinate system emerges, they are then considered again for conversion to the second destination Frame (in the appropriate order), and so on.
    • Generally, the first suitable intermediate coordinate system found is used. However, the overall Mapping between the source and destination coordinate systems is also examined. Preference is given to cases where both the forward and inverse transformations are defined. If only one transformation is defined, the forward one is preferred.
    • If the domain of the intermediate coordinate system matches the current "domainlist" field, the conversion path is accepted. Otherwise, the next "domainlist" field is considered and the process repeated.

    If conversion is possible, the Base attributes of the two FrameSets will be modified on exit to identify the Frames used to access the intermediate coordinate system which was finally accepted.

    Note that it is possible to force a particular Frame within a FrameSet to be used as the basis for the intermediate coordinate system, if it is suitable, by (a) focussing attention on it by specifying its domain in the "domainlist" string, or (b) making it the base Frame, since this is always considered first.

  • SpecFrame

    Alignment occurs within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest.

  • TimeFrame

    Alignment occurs within the time system and time scale given by attributes AlignSystem and AlignTimeScale.

Examples

  • auto cvt = a.convert(b)

    Obtain a FrameSet that converts between the coordinate systems represented by "a" and "b" (assumed to be Frames).

  • auto cvt = SkyFrame().convert(SkyFrame("Equinox=2005"))

    Create a FrameSet which describes precession in the default FK5 celestial coordinate system between equinoxes J2000 (also the default) and J2005. The returned "cvt" FrameSet may be used to apply this precession correction to any number of coordinate values given in radians.

    Note that the returned FrameSet also contains information about how to format coordinate values. This means that setting its Report attribute to 1 is a simple way to obtain printed output (formatted in sexagesimal notation) to show the coordinate values before and after conversion.

  • auto cvt = a.convert(b, "sky,detector,")

    Create a FrameSet that converts between the coordinate systems represented by the current Frames of "a" and "b" (now assumed to be FrameSets), via the intermediate "SKY" coordinate system. This, by default, is the Domain associated with a celestial coordinate system represented by a SkyFrame.

    If this fails (for example, because either FrameSet lacks celestial coordinate information), then the user-defined "DETECTOR" coordinate system is used instead. If this also fails, then all other possible ways of achieving conversion are considered before giving up.

    The returned "cvt" FrameSet describes the conversion.

    The Base attributes of the two FrameSet will be set by `ref convert to indicate which of their Frames was used for the intermediate coordinate system. This means that you can subsequently determine which coordinate system was used by enquiring the Domain attribute of either base Frame.

Parameters
[in,out]toA Frame which represents the "destination" coordinate system. This is the coordinate system into which you wish to convert your coordinates. If a FrameSet is given, its current Frame (as determined by its Current attribute) is taken to describe the destination coordinate system. Note that the Base attribute of this FrameSet may be modified by this function to indicate which intermediate coordinate system was used.
[in]domainlistA string containing a comma-separated list of Frame domains. This may be used to define a priority order for the different intermediate coordinate systems that might be used to perform the conversion. The function will first try to obtain a conversion by making use only of an intermediate coordinate system whose Domain attribute matches the first domain in this list. If this fails, the second domain in the list will be used, and so on, until conversion is achieved. A blank domain (e.g. two consecutive commas) indicates that all coordinate systems should be considered, regardless of their domains.
Returns
A FrameSet which describes the conversion and contains two Frames, or an empty shared pointer if the conversion is not possible. Frame number 1 (its base Frame) will describe the source coordinate system, corresponding to the "from" parameter. Frame number 2 (its current Frame) will describe the destination coordinate system, corresponding to the "to" parameter. The Mapping which inter-relates these two Frames will perform the required conversion between their respective coordinate systems. Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping then it provides a means of converting coordinates from the source to the destination coordinate system (or vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the destination coordinate system.

Notes

  • The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem attribute of the "to" Frame. See the description of the AlignSystem attribute for further details.
  • When aligning (say) two images, which have been calibrated by attaching FrameSets to them, it is usually necessary to convert between the base Frames (representing "native" pixel coordinates) of both FrameSets. This may be achieved by obtaining the inverses of the FrameSets (using inverted).

Definition at line 31 of file Frame.cc.

31  {
32  auto *rawFrameSet =
33  reinterpret_cast<AstFrameSet *>(astConvert(getRawPtr(), to.getRawPtr(), domainlist.c_str()));
34  assertOK(reinterpret_cast<AstObject *>(rawFrameSet));
35  if (!rawFrameSet) {
37  }
38  return Object::fromAstObject<FrameSet>(reinterpret_cast<AstObject *>(rawFrameSet), false);
39 }

◆ copy()

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

Return a deep copy of this object.

Definition at line 147 of file FrameSet.h.

147 { return std::static_pointer_cast<FrameSet>(copyPolymorphic()); }
virtual std::shared_ptr< Object > copyPolymorphic() const override
Return a deep copy of this object.
Definition: FrameSet.h:479

◆ copyImpl()

template<typename T , typename AstT >
std::shared_ptr<T> ast::Object::copyImpl ( ) const
inlineprotectedinherited

Implementation of deep copy.

Should be called to implement copyPolymorphic by all derived classes.

Definition at line 320 of file Object.h.

320  {
321  auto *rawptr = reinterpret_cast<AstT *>(astCopy(getRawPtr()));
322  auto retptr = std::shared_ptr<T>(new T(rawptr));
323  assertOK();
324  return retptr;
325  }

◆ copyPolymorphic()

virtual std::shared_ptr<Object> ast::FrameSet::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>();

Reimplemented from ast::Frame.

Reimplemented in ast::FrameDict.

Definition at line 479 of file FrameSet.h.

479  {
480  return copyImpl<FrameSet, AstFrameSet>();
481  }

◆ decompose()

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

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.

Definition at line 64 of file Mapping.cc.

64  {
65  if ((i < 0) || (i > 1)) {
67  os << "i =" << i << "; must be 0 or 1";
68  throw std::invalid_argument(os.str());
69  }
70  // Report pre-existing problems now so our later test for "not a compound object" is accurate
71  assertOK();
72 
73  AstMapping *rawMap1;
74  AstMapping *rawMap2;
75  int series, invert1, invert2;
76  astDecompose(getRawPtr(), &rawMap1, &rawMap2, &series, &invert1, &invert2);
77  assertOK();
78 
79  if (!rawMap2) {
80  // Not a compound object; free rawMap1 (rawMap2 is null, so no need to free it) and throw an exception
81  astAnnul(reinterpret_cast<AstObject *>(rawMap1));
83  os << "This " << getClassName() << " is not a compound object";
84  throw std::runtime_error(os.str());
85  }
86 
87  // Make a deep copy of the returned object and free the shallow copies
88  AstMapping *retRawMap;
89  int invert;
90  if (i == 0) {
91  retRawMap = reinterpret_cast<AstMapping *>(astCopy(reinterpret_cast<AstObject *>(rawMap1)));
92  invert = invert1;
93  } else {
94  retRawMap = reinterpret_cast<AstMapping *>(astCopy(reinterpret_cast<AstObject *>(rawMap2)));
95  invert = invert2;
96  }
97  astAnnul(reinterpret_cast<AstObject *>(rawMap1));
98  astAnnul(reinterpret_cast<AstObject *>(rawMap2));
99  assertOK();
100 
101  // If the mapping's internal invert flag does not match the value used when the CmpMap was made
102  // then invert the mapping. Note that it is not possible to create such objects in astshim
103  // but it is possible to read in objects created by other software.
104  if (invert != astGetI(retRawMap, "Invert")) {
105  astInvert(retRawMap);
106  assertOK();
107  }
108 
109  return Object::fromAstObject<Class>(reinterpret_cast<AstObject *>(retRawMap), copy);
110 }
std::shared_ptr< Mapping > copy() const
Return a deep copy of this object.
Definition: Mapping.h:72
Relationship invert(Relationship r)
Given the relationship between two sets A and B (i.e.
Definition: Relationship.h:55

◆ distance()

double ast::Frame::distance ( PointD const &  point1,
PointD const &  point2 
) const
inlineinherited

Find the distance between two points whose Frame coordinates are given.

The distance calculated is that along the geodesic curve that joins the two points. For example, in a basic Frame, the distance calculated will be the Cartesian distance along the straight line joining the two points. For a more specialised Frame describing a sky coordinate system, however, it would be the distance along the great circle passing through two sky positions.

Parameters
[in]point1The coordinates of the first point.
[in]point2The coordinates of the second point.
Returns
The distance between the two points.

Definition at line 474 of file Frame.h.

474  {
475  assertPointLength(point1, "point1");
476  assertPointLength(point2, "point2");
477  return detail::safeDouble(astDistance(getRawPtr(), point1.data(), point2.data()));
478  }

◆ findFrame()

std::shared_ptr< FrameSet > ast::Frame::findFrame ( Frame const &  tmplt,
std::string const &  domainlist = "" 
)
inherited

Find a coordinate system with specified characteristics.

Use a "template" Frame to search another Frame (or FrameSet) to identify a coordinate system which has a specified set of characteristics. If a suitable coordinate system can be found, the function returns a pointer to a FrameSet which describes the required coordinate system and how to convert coordinates to and from it.

This function is provided to help answer general questions about coordinate systems, such as typically arise when coordinate information is imported into a program as part of an initially unknown dataset. For example:

  • Is there a wavelength scale?
  • Is there a 2-dimensional coordinate system?
  • Is there a celestial coordinate system?
  • Can I plot the data in ecliptic coordinates?

You can also use this function as a means of reconciling a user's preference for a particular coordinate system (for example, what type of axes to draw) with what is actually possible given the coordinate information available.

To perform a search, you supply a "target" Frame (or FrameSet) which represents the set of coordinate systems to be searched. If a basic Frame is given as the target, this set of coordinate systems consists of the one described by this Frame, plus all other "virtual" coordinate systems which can potentially be reached from it by applying built-in conversions (for example, any of the celestial coordinate conversions known to the AST library would constitute a "built-in" conversion). If a FrameSet is given as the target, the set of coordinate systems to be searched consists of the union of those represented by all the individual Frames within it.

To select from this large set of possible coordinate systems, you supply a "template" Frame which is an instance of the type of Frame you are looking for. Effectively, you then ask the function to "find a coordinate system that looks like this".

You can make your request more or less specific by setting attribute values for the template Frame. If a particular attribute is set in the template, then the function will only find coordinate systems which have exactly the same value for that attribute. If you leave a template attribute un-set, however, then the function has discretion about the value the attribute should have in any coordinate system it finds. The attribute will then take its value from one of the actual (rather than virtual) coordinate systems in the target. If the target is a FrameSet, its Current attribute will be modified to indicate which of its Frames was used for this purpose.

The result of this process is a coordinate system represented by a hybrid Frame which acquires some attributes from the template (but only if they were set) and the remainder from the target. This represents the "best compromise" between what you asked for and what was available. A Mapping is then generated which converts from the target coordinate system to this hybrid one, and the returned FrameSet encapsulates all of this information.

Applicability to Subclasses

  • FrameSet

    If the target is a FrameSet, the possibility exists that several of the Frames within it might be matched by the template. Unless the choice is sufficiently restricted by the "domainlist" string, the sequence in which Frames are searched can then become important. In this case, the search proceeds as follows:

    • Each field in the "domainlist" string is considered in turn.
    • An attempt is made to match the template to each of the target's Frames in the order: (1) the current Frame (2) the base Frame (3) each remaining Frame in the order of being added to the target FrameSet
    • Generally, the first match found is used. However, the Mapping between the target coordinate system and the resulting Frame is also examined. Preference is given to cases where both the forward and inverse transformations are defined. If only one transformation is defined, the forward one is preferred.
    • If a match is found and the domain of the resulting Frame also matches the current "domainlist" field, it is accepted. Otherwise, the next "domainlist" field is considered and the process repeated.

    If a suitable coordinate system is found, then the FrameSet's Current attribute will be modified to indicate which Frame was used to obtain attribute values which were not specified by the template. This Frame will, in some sense, represent the "closest" non-virtual coordinate system to the one you requested.

Examples

  • auto result = target.findFrame(ast::Frame(3))

    Search for a 3-dimensional coordinate system in the target Frame (or FrameSet). No attributes have been set in the template Frame (created by ast::Frame), so no restriction has been placed on the required coordinate system, other than that it should have 3 dimensions. The first suitable Frame found will be returned as part of the "result" FrameSet.

  • auto result = target.findFrame(astSkyFrame())

    Search for a celestial coordinate system in the target Frame (or FrameSet). The type of celestial coordinate system is unspecified, so astFindFrame will return the first one found as part of the "result" FrameSet. If the target is a FrameSet, then its Current attribute will be updated to identify the Frame that was used.

  • auto result = target.findFrame(astSkyFrame("MaxAxes=100"))

    This is like the last example, except that in the event of the target being a CmpFrame, the component Frames encapsulated by the CmpFrame will be searched for a SkyFrame. If found, the returned Mapping will included a PermMap which selects the required axes from the target CmpFrame.

    This is acomplished by setting the MaxAxes attribute of the template SkyFrame to a large number (larger than or equal to the number of axes in the target CmpFrame). This allows the SkyFrame to be used as a match for Frames containing from 2 to 100 axes.

  • auto result = target.findFrame(astSkyFrame("System=FK5"))

    Search for an equatorial (FK5) coordinate system in the target. The Equinox value for the coordinate system has not been specified, so will be obtained from the target. If the target is a FrameSet, its Current attribute will be updated to indicate which SkyFrame was used to obtain this value.

  • auto result = target.findFrame(astFrame(2), "sky,pixel,")

    Search for a 2-dimensional coordinate system in the target. Initially, a search is made for a suitable coordinate system whose Domain attribute has the value "SKY". If this search fails, a search is then made for one with the domain "PIXEL". If this also fails, then any 2-dimensional coordinate system is returned as part of the "result" FrameSet.

    Only if no 2-dimensional coordinate systems can be reached by applying built-in conversions to any of the Frames in the target will the search fail.

  • auto result = target.findFrame(astFrame(1, "Domain=WAVELENGTH"))

    Searches for any 1-dimensional coordinate system in the target which has the domain "WAVELENGTH".

  • auto result = target.findFrame(astFrame(1), "wavelength")

    This example has exactly the same effect as that above. It illustrates the equivalence of the template's Domain attribute and the fields in the "domainlist" string.

  • auto result = target.findFrame(Frame(1, "MaxAxes=3"))

    This is a more advanced example which will search for any coordinate system in the target having 1, 2 or 3 dimensions. The Frame returned (as part of the "result" FrameSet) will always be 1-dimensional, but will be related to the coordinate system that was found by a suitable Mapping (e.g. a PermMap) which simply extracts the first axis.

    If we had wanted a Frame representing the actual (1, 2 or 3-dimensional) coordinate system found, we could set the PreserveAxes attribute to a non-zero value in the template.

  • auto result = target.findFrame(SkyFrame("Permute=0"))

    Search for any celestial coordinate system in the target, but only finds one if its axes are in the conventional (longitude,latitude) order and have not been permuted (e.g. with astPermAxes).

More on Using Templates

A Frame (describing a coordinate system) will be found by this function if (a) it is "matched" by the template you supply, and (b) the value of its Domain attribute appears in the "domainlist" string (except that a blank field in this string permits any domain). A successful match by the template depends on a number of criteria, as outlined below:

  • In general, a template will only match another Frame which belongs to the same class as the template, or to a derived (more specialised) class. For example, a SkyFrame template will match any other SkyFrame, but will not match a basic Frame. Conversely, a basic Frame template will match any class of Frame.
  • The exception to this is that a Frame of any class can be used to match a CmpFrame, if that CmpFrame contains a Frame of the same class as the template. Note however, the MaxAxes and MinAxes attributes of the template must be set to suitable values to allow it to match the CmpFrame. That is, the MinAxes attribute must be less than or equal to the number of axes in the target, and the MaxAxes attribute must be greater than or equal to the number of axes in the target.
  • If using a CmpFrame as a template frame, the MinAxes and MaxAxes for the template are determined by the MinAxes and MaxAxes values of the component Frames within the template. So if you want a template CmpFrame to be able to match Frames with different numbers of axes, then you must set the MaxAxes and/or MinAxes attributes in the component template Frames, before combining them together into the template CmpFrame.
  • If a template has a value set for any of its main attributes, then it will only match Frames which have an identical value for that attribute (or which can be transformed, using a built-in conversion, so that they have the required value for that attribute). If any attribute in the template is un-set, however, then Frames are matched regardless of the value they may have for that attribute. You may therefore make a template more or less specific by choosing the attributes for which you set values. This requirement does not apply to 'descriptive' attributes such as titles, labels, symbols, etc.
  • An important application of this principle involves the Domain attribute. Setting the Domain attribute of the template has the effect of restricting the search to a particular type of Frame (with the domain you specify). Conversely, if the Domain attribute is not set in the template, then the domain of the Frame found is not relevant, so all Frames are searched. Note that the "domainlist" string provides an alternative way of restricting the search in the same manner, but is a more convenient interface if you wish to search automatically for another domain if the first search fails.
  • Normally, a template will only match a Frame which has the same number of axes as itself. However, for some classes of template, this default behaviour may be changed by means of the MinAxes, MaxAxes and MatchEnd attributes. In addition, the behaviour of a template may be influenced by its Permute and PreserveAxes attributes, which control whether it matches Frames whose axes have been permuted, and whether this permutation is retained in the Frame which is returned (as opposed to returning the axes in the order specified in the template, which is the default behaviour). You should consult the descriptions of these attributes for details of this more advanced use of templates.
Parameters
[in,out]tmpltTemplate Frame, which should be an instance of the type of Frame you wish to find. If you wanted to find a Frame describing a celestial coordinate system, for example, then you might use a SkyFrame here. See the "Examples" section for more ideas.
[in]domainlistString containing a comma-separated list of Frame domains. This may be used to establish a priority order for the different types of coordinate system that might be found. The function will first try to find a suitable coordinate system whose Domain attribute equals the first domain in this list. If this fails, the second domain in the list will be used, and so on, until a result is obtained. A blank domain (e.g. two consecutive commas) indicates that any coordinate system is acceptable (subject to the template) regardless of its domain. This list is case-insensitive and all white space is ignored. If you do not wish to restrict the domain in this way, you should supply an empty string.
Returns
A std::shared_ptr<FrameSet> which contains the Frame found and a description of how to convert to (and from) the coordinate system it represents. If the Frame is not found then return a null pointer.

This FrameSet will contain two Frames. Frame number 1 (its base Frame) represents the target coordinate system and will be the same as the (base Frame of the) target. Frame number 2 (its current Frame) will be a Frame representing the coordinate system which the function found. The Mapping which inter-relates these two Frames will describe how to convert between their respective coordinate systems. Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping, then it provides a means of converting coordinates from the target coordinate system into the new coordinate system that was found (and vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the new coordinate system.

Notes

  • This method is not const because if called on a FrameSet then the BASE frame of the FrameSet may be changed. No other kind of frame will be altered.
  • Similarly the tmpl argument is not const because if it is a FrameSet then the BASE frame of the template may be changed. No other kind of frame will be altered.
  • The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem attribute of the "template" Frame. See the description of the AlignSystem for further details.
  • Beware of setting the Domain attribute of the template and then using a "domainlist" string which does not include the template's domain (or a blank field). If you do so, no coordinate system will be found.

Definition at line 41 of file Frame.cc.

41  {
42  auto *rawFrameSet =
43  reinterpret_cast<AstFrameSet *>(astFindFrame(getRawPtr(), tmplt.getRawPtr(), domainlist.c_str()));
44  assertOK(reinterpret_cast<AstObject *>(rawFrameSet));
45  if (!rawFrameSet) {
47  }
48  return Object::fromAstObject<FrameSet>(reinterpret_cast<AstObject *>(rawFrameSet), false);
49 }

◆ format()

std::string ast::Frame::format ( int  axis,
double  value 
) const
inlineinherited

Return a string containing the formatted (character) version of a coordinate value for a Frame axis.

The formatting applied is determined by the Frame's attributes and, in particular, by any Format attribute string that has been set for the axis. A suitable default format (based on the Digits attribute value) will be applied if necessary.

Parameters
[in]axisThe number of the Frame axis for which formatting is to be performed (axis numbering starts at 1 for the first axis).
[in]valueThe coordinate value to be formatted.

Definition at line 782 of file Frame.h.

782  {
783  char const *rawstr = astFormat(getRawPtr(), axis, value);
784  assertOK();
785  return std::string(rawstr);
786  }

◆ fromAstObject()

template<typename Class >
template std::shared_ptr< Object > ast::Object::fromAstObject< Object > ( AstObject *  rawObj,
bool  copy 
)
staticinherited

Given a bare AST object pointer return a shared pointer to an ast::Object of the correct type.

The returned object takes ownership of the pointer. This is almost always what you want, for instance astDecompose returns shallow copies of the internal pointers.

Template Parameters
ClassThe class of the returned shared pointer. (The actual class will be the correct class of rawPtr.)
Parameters
[in]rawObjA bare AST object pointer
[in]copyIf True then make a deep copy of the pointer (and free the original)

Definition at line 138 of file Object.cc.

138  {
139  AstObject *rawObjCopy = rawObj;
140  if (copy) {
141  rawObjCopy = reinterpret_cast<AstObject *>(astCopy(rawObj));
142  astAnnul(rawObj);
143  }
144  assertOK(rawObjCopy);
145 
146  // Make the appropriate ast shim object and dynamically cast to the desired output type
147  auto retObjectBeforeCast = Object::_basicFromAstObject(rawObjCopy);
148  auto retObject = std::dynamic_pointer_cast<Class>(retObjectBeforeCast);
149  if (!retObject) {
151  os << "The component is of type " << retObject->getClassName()
152  << ", which could not be cast to the desired type " << typeid(Class).name();
153  throw std::runtime_error(os.str());
154  }
155  return retObject;
156 }
std::shared_ptr< Object > copy() const
Return a deep copy of this object.
Definition: Object.h:109

◆ fromString()

static std::shared_ptr<Object> ast::Object::fromString ( std::string const &  str)
inlinestaticinherited

Construct an Object from a string, using astFromString.

Definition at line 88 of file Object.h.

88  {
89  auto *rawPtr = reinterpret_cast<AstObject *>(astFromString(str.c_str()));
90  assertOK(rawPtr);
91  return Object::_basicFromAstObject(rawPtr);
92  }

◆ getActiveUnit()

bool ast::Frame::getActiveUnit ( ) const
inlineinherited

Get ActiveUnit: pay attention to units when one Frame is used to match another?

Definition at line 792 of file Frame.h.

792  {
793  bool ret = astGetActiveUnit(getRawPtr());
794  assertOK();
795  return ret;
796  }

◆ getAlignSystem()

std::string ast::Frame::getAlignSystem ( ) const
inlineinherited

Get AlignSystem: the coordinate system used by convert and findFrame to align Frames.

Definition at line 802 of file Frame.h.

802 { return getC("AlignSystem"); }
std::string const getC(std::string const &attrib) const
Get the value of an attribute as a string.
Definition: Object.h:361

◆ getAllVariants()

std::string ast::FrameSet::getAllVariants ( ) const
inline

Get AllVariants: a list of all variant mappings stored with the current Frame.

Definition at line 243 of file FrameSet.h.

243 { return getC("AllVariants"); }

◆ getB()

bool ast::Object::getB ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a bool.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 348 of file Object.h.

348  {
349  bool val = astGetI(getRawPtr(), attrib.c_str());
350  assertOK();
351  return val;
352  }
ImageT val
Definition: CR.cc:146

◆ getBase()

int ast::FrameSet::getBase ( ) const
inline

Get Base: index of base Frame.

Definition at line 248 of file FrameSet.h.

248 { return getI("Base"); }
int getI(std::string const &attrib) const
Get the value of an attribute as an int.
Definition: Object.h:400

◆ getBottom()

double ast::Frame::getBottom ( int  axis) const
inlineinherited

Get Bottom for one axis: the lowest axis value to display.

Definition at line 807 of file Frame.h.

807 { return getD(detail::formatAxisAttr("Bottom", axis)); }
double getD(std::string const &attrib) const
Get the value of an attribute as a double.
Definition: Object.h:374
std::string formatAxisAttr(std::string const &name, int axis)
Format an axis-specific attribute by appending the axis index.
Definition: utils.h:79

◆ getC()

std::string const ast::Object::getC ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a string.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 361 of file Object.h.

361  {
362  char const *rawval = astGetC(getRawPtr(), attrib.c_str());
363  assertOK();
364  return std::string(rawval);
365  }

◆ getClassName()

std::string ast::Object::getClassName ( ) const
inlineinherited

Get Class: the name of the class (e.g.

ZoomMap)

Note: if AST returns "CmpMap" then the name will be changed to "SeriesMap" or "ParallelMap", as appropriate.

Definition at line 139 of file Object.h.

139 { return detail::getClassName(getRawPtr()); }
std::string getClassName(AstObject const *rawObj)
Get the AST class name, changing CmpMap to SeriesMap or ParallelMap as appropriate.
Definition: utils.cc:37

◆ getCurrent()

int ast::FrameSet::getCurrent ( ) const
inline

Get Current: index of current Frame, starting from 1.

Definition at line 253 of file FrameSet.h.

253 { return getI("Current"); }

◆ getD()

double ast::Object::getD ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a double.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 374 of file Object.h.

374  {
375  double val = astGetD(getRawPtr(), attrib.c_str());
376  assertOK();
377  return val;
378  }

◆ getDigits() [1/2]

int ast::Frame::getDigits ( ) const
inlineinherited

Get Digits: the default used if no specific value specified for an axis.

Definition at line 812 of file Frame.h.

812 { return getI("Digits"); }

◆ getDigits() [2/2]

int ast::Frame::getDigits ( int  axis) const
inlineinherited

Get Digits for one axis.

Definition at line 817 of file Frame.h.

817 { return getI(detail::formatAxisAttr("Digits", axis)); }

◆ getDirection()

bool ast::Frame::getDirection ( int  axis) const
inlineinherited

Get Direction for one axis: display axis in conventional direction?

Definition at line 822 of file Frame.h.

822 { return getB(detail::formatAxisAttr("Direction", axis)); }
bool getB(std::string const &attrib) const
Get the value of an attribute as a bool.
Definition: Object.h:348

◆ getDomain()

std::string ast::Frame::getDomain ( ) const
inlineinherited

Get Domain: coordinate system domain.

Definition at line 827 of file Frame.h.

827 { return getC("Domain"); }

◆ getDut1()

double ast::Frame::getDut1 ( ) const
inlineinherited

Get Dut1: difference between the UT1 and UTC timescale (sec)

Definition at line 832 of file Frame.h.

832 { return getD("Dut1"); }

◆ getEpoch()

double ast::Frame::getEpoch ( ) const
inlineinherited

Get Epoch: Epoch of observation.

Definition at line 837 of file Frame.h.

837 { return getD("Epoch"); }

◆ getF()

float ast::Object::getF ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a float.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 387 of file Object.h.

387  {
388  float val = astGetF(getRawPtr(), attrib.c_str());
389  assertOK();
390  return val;
391  }

◆ getFormat()

std::string ast::Frame::getFormat ( int  axis) const
inlineinherited

Get Format for one axis: format specification for axis values.

Definition at line 842 of file Frame.h.

842 { return getC(detail::formatAxisAttr("Format", axis)); }

◆ getFrame()

std::shared_ptr<Frame> ast::FrameSet::getFrame ( int  iframe,
bool  copy = true 
) const
inline

Obtain a deep copy of the specified Frame.

Parameters
[in]iframeThe index of the required Frame within this FrameSet. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame). A value of FrameSet::Base or FrameSet::CURRENT may be given to specify the base Frame or the current Frame, respectively.
[in]copyIf true return a deep copy, else a shallow copy.
Warning
: to permute axes of a frame in a FrameSet, such that the connecting mappings are updated: set the current frame to the frame in question and call permAxes directly on the FrameSet. Do not call permAxes on a shallow copy of the frame (retrieved by getFrame) as this will not affect the connected mappings.

Definition at line 270 of file FrameSet.h.

270  {
271  auto *rawFrame = reinterpret_cast<AstObject *>(astGetFrame(getRawPtr(), iframe));
272  assertOK(rawFrame);
273  if (!rawFrame) {
274  throw std::runtime_error("getFrame failed (returned a null frame)");
275  }
276  return Object::fromAstObject<Frame>(rawFrame, copy);
277  }
std::shared_ptr< FrameSet > copy() const
Return a deep copy of this object.
Definition: FrameSet.h:147

◆ getI()

int ast::Object::getI ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as an int.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 400 of file Object.h.

400  {
401  int val = astGetI(getRawPtr(), attrib.c_str());
402  assertOK();
403  return val;
404  }

◆ getID()

std::string ast::Object::getID ( ) const
inlineinherited

Get ID: object identification string that is not copied.

Definition at line 142 of file Object.h.

142 { return getC("ID"); }

◆ getIdent()

std::string ast::Object::getIdent ( ) const
inlineinherited

Get Ident: object identification string that is copied.

Definition at line 145 of file Object.h.

145 { return getC("Ident"); }

◆ getInternalUnit()

std::string ast::Frame::getInternalUnit ( int  axis) const
inlineinherited

Get InternalUnit(axis) read-only attribute for one axis: physical units for unformated axis values.

Definition at line 848 of file Frame.h.

848 { return getC(detail::formatAxisAttr("InternalUnit", axis)); }

◆ getIsLinear()

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

Get IsLinear: is the Mapping linear?

Definition at line 100 of file Mapping.h.

100 { return getB("IsLinear"); }

◆ getIsSimple()

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

Get IsSimple: has the mapping been simplified?

Definition at line 87 of file Mapping.h.

87 { return getI("IsSimple"); }

◆ getL()

long int ast::Object::getL ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a long int.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 413 of file Object.h.

413  {
414  long int val = astGetL(getRawPtr(), attrib.c_str());
415  assertOK();
416  return val;
417  }

◆ getLabel()

std::string ast::Frame::getLabel ( int  axis) const
inlineinherited

Get Label(axis) for one axis: axis label.

Definition at line 853 of file Frame.h.

853 { return getC(detail::formatAxisAttr("Label", axis)); }

◆ getMapping()

std::shared_ptr<Mapping> ast::FrameSet::getMapping ( int  from = BASE,
int  to = CURRENT 
) const
inline

Obtain a Mapping that converts between two Frames in a FrameSet.

Parameters
[in]fromThe index of the first Frame in the FrameSet, the frame describing the coordinate system for the "input" end of the Mapping. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame).
[in]toThe index of the second Frame in the FrameSet, the frame describing the coordinate system for the "output" end of the Mapping. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame).
Returns
A Mapping whose forward transformation converts coordinates from the first frame to the second one, and whose inverse transformation converts coordinates in the opposite direction.

Notes

  • The returned Mapping will include the clipping effect of any Regions which occur on the path between the two supplied Frames, including the specified end frames.
  • It should always be possible to generate the Mapping requested, but this does not necessarily guarantee that it will be able to perform the required coordinate conversion. If necessary, call hasForward or hasInverse on the returned Mapping to determine if the required transformation is available.

Definition at line 304 of file FrameSet.h.

304  {
305  AstObject *rawMap = reinterpret_cast<AstObject *>(astGetMapping(getRawPtr(), from, to));
306  assertOK(rawMap);
307  if (!rawMap) {
308  throw std::runtime_error("getMapping failed (returned a null mapping)");
309  }
310  return Object::fromAstObject<Mapping>(rawMap, true);
311  }

◆ getMatchEnd()

bool ast::Frame::getMatchEnd ( ) const
inlineinherited

Get MatchEnd: match trailing axes?

Definition at line 858 of file Frame.h.

858 { return getB("MatchEnd"); }

◆ getMaxAxes()

int ast::Frame::getMaxAxes ( ) const
inlineinherited

Get MaxAxes: the maximum axes a frame found by findFrame may have.

Definition at line 864 of file Frame.h.

864 { return getI("MaxAxes"); }

◆ getMinAxes()

int ast::Frame::getMinAxes ( ) const
inlineinherited

Get MinAxes: the maximum axes a frame found by findFrame may have.

Definition at line 870 of file Frame.h.

870 { return getI("MinAxes"); }

◆ getNAxes()

int ast::Frame::getNAxes ( ) const
inlineinherited

Get NAxes: the number of axes in the frame (i.e.

the number of dimensions of the coordinate space which the Frame describes).

Definition at line 876 of file Frame.h.

876 { return getI("NAxes"); }

◆ getNFrame()

int ast::FrameSet::getNFrame ( ) const
inline

Get FrameSet_NFrame "NFrame": number of Frames in the FrameSet, starting from 1.

Definition at line 316 of file FrameSet.h.

316 { return getI("NFrame"); }

◆ getNIn()

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

Get NIn: the number of input axes.

Definition at line 77 of file Mapping.h.

77 { return getI("NIn"); }

◆ getNObject()

int ast::Object::getNObject ( ) const
inlineinherited

Get NObject: number of AST objects in existence of the same type as the underlying AST class.

Warning
Intended only for debugging astshim.

Definition at line 153 of file Object.h.

153 { return getI("NObject"); }

◆ getNormUnit()

std::string ast::Frame::getNormUnit ( int  axis) const
inlineinherited

Get NormUnit(axis) read-only attribute for one frame: normalised physical units for formatted axis values.

Definition at line 882 of file Frame.h.

882 { return getC(detail::formatAxisAttr("NormUnit", axis)); }

◆ getNOut()

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

Get NOut: the number of output axes.

Definition at line 82 of file Mapping.h.

82 { return getI("NOut"); }

◆ getObjSize()

int ast::Object::getObjSize ( ) const
inlineinherited

Get ObjSize: the in-memory size of the AST object in bytes.

Definition at line 156 of file Object.h.

156 { return getI("ObjSize"); }

◆ getObsAlt()

double ast::Frame::getObsAlt ( ) const
inlineinherited

Get ObsAlt: Geodetic altitude of observer (m).

Definition at line 887 of file Frame.h.

887 { return getD("ObsAlt"); }

◆ getObsLat()

std::string ast::Frame::getObsLat ( ) const
inlineinherited

Get ObsLat: Geodetic latitude of observer.

Definition at line 892 of file Frame.h.

892 { return getC("ObsLat"); }

◆ getObsLon()

std::string ast::Frame::getObsLon ( ) const
inlineinherited

Get ObsLon: Geodetic longitude of observer.

Definition at line 897 of file Frame.h.

897 { return getC("ObsLon"); }

◆ getPermute()

bool ast::Frame::getPermute ( ) const
inlineinherited

Get Permute: allow axis permutation when used as a template?

Definition at line 902 of file Frame.h.

902 { return getB("Permute"); }

◆ getPreserveAxes()

bool ast::Frame::getPreserveAxes ( ) const
inlineinherited

Get PreserveAxes: preserve axes?

Definition at line 907 of file Frame.h.

907 { return getB("PreserveAxes"); }

◆ getRawPtr() [1/2]

AstObject* ast::Object::getRawPtr ( )
inlineinherited

Get the raw AST pointer.

Intended for internal use only, but cannot be made protected without endless "friend class" declarations.

Definition at line 294 of file Object.h.

294 { return &*_objPtr; };

◆ getRawPtr() [2/2]

AstObject const* ast::Object::getRawPtr ( ) const
inlineinherited

Get the raw AST pointer.

Intended for internal use only, but cannot be made protected without endless "friend class" declarations.

Definition at line 292 of file Object.h.

292 { return &*_objPtr; };

◆ getRefCount()

int ast::Object::getRefCount ( ) const
inlineinherited

Get RefCount: number of active pointers to the underlying AST object.

Warning
Intended only for debugging astshim.

Definition at line 163 of file Object.h.

163 { return getI("RefCount"); }

◆ getReport()

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

Get Report: report transformed coordinates to stdout?

Definition at line 105 of file Mapping.h.

105 { return getB("Report"); }

◆ getSymbol()

std::string ast::Frame::getSymbol ( int  axis) const
inlineinherited

Get Symbol(axis) for one axis: axis symbol.

Definition at line 912 of file Frame.h.

912 { return getC(detail::formatAxisAttr("Symbol", axis)); }

◆ getSystem()

std::string ast::Frame::getSystem ( ) const
inlineinherited

Get System: coordinate system used to describe positions within the domain.

Definition at line 918 of file Frame.h.

918 { return getC("System"); }

◆ getTitle()

std::string ast::Frame::getTitle ( ) const
inlineinherited

Get Title: frame title.

Definition at line 923 of file Frame.h.

923 { return getC("Title"); }

◆ getTop()

double ast::Frame::getTop ( int  axis) const
inlineinherited

Get Top: the highest axis value to display.

Definition at line 928 of file Frame.h.

928 { return getD(detail::formatAxisAttr("Top", axis)); }

◆ getUnit()

std::string ast::Frame::getUnit ( int  axis) const
inlineinherited

Get Unit(axis) for one axis: physical units for formatted axis values.

Definition at line 933 of file Frame.h.

933 { return getC(detail::formatAxisAttr("Unit", axis)); }

◆ getUseDefs()

bool ast::Object::getUseDefs ( ) const
inlineinherited

Get UseDefs: allow use of default values for Object attributes?

Definition at line 166 of file Object.h.

166 { return getB("UseDefs"); }

◆ getVariant()

std::string ast::FrameSet::getVariant ( ) const
inline

Variant: name of variant mapping in use by current Frame

See also addVariant, mirrorVariants and renameVariant

Definition at line 323 of file FrameSet.h.

323 { return getC("Variant"); }

◆ hasAttribute()

bool ast::Object::hasAttribute ( std::string const &  attrib) const
inlineinherited

Does this object have an attribute with the specified name?

Definition at line 127 of file Object.h.

127  {
128  bool ret = astHasAttribute(getRawPtr(), attrib.c_str());
129  assertOK();
130  return ret;
131  }

◆ hasForward()

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

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.

Definition at line 114 of file Mapping.h.

114 { return getB("TranForward"); }

◆ hasInverse()

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

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.

Definition at line 123 of file Mapping.h.

123 { return getB("TranInverse"); }

◆ intersect()

std::vector< double > ast::Frame::intersect ( std::vector< double > const &  a1,
std::vector< double > const &  a2,
std::vector< double > const &  b1,
std::vector< double > const &  b2 
) const
inherited

Find the point of intersection between two geodesic curves.

For example, in a basic Frame, it will find the point of intersection between two straight lines. But for a SkyFrame it will find an intersection of two great circles.

Warning
This method can only be used with 2-dimensional Frames.
Parameters
[in]a1Coordinates of the first point on the first geodesic curve.
[in]a2Coordinates of the second point on the first geodesic curve.
[in]b1Coordinates of the first point on the second geodesic curve.
[in]b2Coordinates of the second point on the second geodesic curve.
Returns
the point of intersection between the two geodesic curves.
Exceptions
std::runtime_errorif the frame is not 2-dimensional

Notes

  • For a SkyFrame each curve will be a great circle, and in general each pair of curves will intersect at two diametrically opposite points on the sky. The returned position is the one which is closest to point a1.
  • This method will return nan coordinate values if any of the input coordinates is invalid, or if the two points defining either geodesic are coincident, or if the two curves do not intersect.
  • The geodesic curve used by this method is the path of shortest distance between two points, as defined by distance

Definition at line 51 of file Frame.cc.

52  {
53  int const naxes = 2;
54  detail::assertEqual(getNAxes(), "# axes", naxes, "");
55  detail::assertEqual(a1.size(), "a1.size()", static_cast<std::size_t>(naxes), "");
56  detail::assertEqual(a2.size(), "a2.size()", static_cast<std::size_t>(naxes), "");
57  detail::assertEqual(b1.size(), "b1.size()", static_cast<std::size_t>(naxes), "");
58  detail::assertEqual(b2.size(), "b2.size()", static_cast<std::size_t>(naxes), "");
59  std::vector<double> ret(naxes);
60  astIntersect(getRawPtr(), a1.data(), a2.data(), b1.data(), b2.data(), ret.data());
61  assertOK();
63  return ret;
64 }
int getNAxes() const
Get NAxes: the number of axes in the frame (i.e.
Definition: Frame.h:876
T data(T... args)
void assertEqual(T1 val1, std::string const &descr1, T2 val2, std::string const &descr2)
Definition: utils.h:48
void astBadToNan(std::vector< double > &p)
Replace AST__BAD with a quiet NaN in a vector.
Definition: utils.h:59
T size(T... args)

◆ inverted()

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

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).

Definition at line 41 of file Mapping.cc.

41  {
42  auto rawCopy = reinterpret_cast<AstMapping *>(astCopy(getRawPtr()));
43  astInvert(rawCopy);
44  assertOK(reinterpret_cast<AstObject *>(rawCopy));
45  // use false because the pointer has already been copied
46  return Object::fromAstObject<Mapping>(reinterpret_cast<AstObject *>(rawCopy), false);
47 }

◆ isInverted()

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

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.

Definition at line 95 of file Mapping.h.

95 { return getB("Invert"); }

◆ linearApprox()

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

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.

Definition at line 49 of file Mapping.cc.

49  {
50  int const nIn = getNIn();
51  int const nOut = getNOut();
52  detail::assertEqual(lbnd.size(), "lbnd.size", static_cast<std::size_t>(nIn), "nIn");
53  detail::assertEqual(ubnd.size(), "ubnd.size", static_cast<std::size_t>(nIn), "nIn");
54  Array2D fit = ndarray::allocate(ndarray::makeVector(1 + nIn, nOut));
55  int isOK = astLinearApprox(getRawPtr(), lbnd.data(), ubnd.data(), tol, fit.getData());
56  assertOK();
57  if (!isOK) {
58  throw std::runtime_error("Mapping not sufficiently linear");
59  }
60  return fit;
61 }

◆ lock()

void ast::Object::lock ( bool  wait)
inlineinherited

Lock this object for exclusive use by the calling thread.

The thread-safe public interface to AST is designed so that an error is reported if any thread attempts to use an Object that it has not previously locked for its own exclusive use using this function. When an Object is created, it is initially locked by the thread that creates it, so newly created objects do not need to be explicitly locked. However, if an Object pointer is passed to another thread, the original thread must first unlock it (using astUnlock) and the new thread must then lock it (using astLock) before the new thread can use the Object.

Parameters
[in]waitIf the Object is curently locked by another thread then this function will either report an error or block. If a non-zero value is supplied for "wait", the calling thread waits until the object is available for it to use. Otherwise, an error is reported and the function returns immediately without locking the Object.

Notes

  • The Locked object will belong to the current AST context.
  • This function returns without action if the Object is already locked by the calling thread.
  • If simultaneous use of the same object is required by two or more threads, Object::copy should be used to to produce a deep copy of the Object for each thread. Each copy should then be unlocked by the parent thread (i.e. the thread that created the copy), and then locked by the child thread (i.e. the thread that wants to use the copy).
  • This function returns without action if the AST library has been built without POSIX thread support (i.e. the "-with-pthreads" option was not specified when running the "configure" script).

Definition at line 202 of file Object.h.

202  {
203  astLock(getRawPtr(), static_cast<int>(wait));
204  assertOK();
205  }

◆ makeShim()

template<typename ShimT , typename AstT >
static std::shared_ptr<ShimT> ast::Object::makeShim ( AstObject *  p)
inlinestaticprotectedinherited

Functor to make an astshim instance from a raw AST pointer of the corresponding type.

Template Parameters
ShimTOutput astshim class
AstTOutput AST class

Definition at line 310 of file Object.h.

310  {
311  return std::shared_ptr<ShimT>(new ShimT(reinterpret_cast<AstT *>(p)));
312  }

◆ matchAxes()

std::vector<int> ast::Frame::matchAxes ( Frame const &  other) const
inlineinherited

Look for corresponding axes between this frame and another.

Parameters
[in]otherThe other frame
Returns
The indices of the axes (within this Frame) that correspond to each axis within other. Axis indices start at 1. A value of zero will be stored in the returned array for each axis in other that has no corresponding axis in this frame. The number of elements in the array will be the number of axes in other.

Notes

  • Corresponding axes are identified by the fact that a Mapping can be found between them using findFrame or convert. Thus, "corresponding axes" are not necessarily identical. For instance, SkyFrame axes will match even if they describe different celestial coordinate systems.

Definition at line 985 of file Frame.h.

985  {
986  std::vector<int> ret(other.getNIn());
987  astMatchAxes(getRawPtr(), other.getRawPtr(), ret.data());
988  assertOK();
989  return ret;
990  }

◆ mirrorVariants()

void ast::FrameSet::mirrorVariants ( int  iframe)
inline

Indicates that all access to the Variant attribute of the current Frame should should be forwarded to some other nominated Frame in the FrameSet.

For instance, if a value is set subsequently for the Variant attribute of the current Frame, the current Frame will be left unchanged and the setting is instead applied to the nominated Frame. Likewise, if the value of the Variant attribute is requested, the value returned is the value stored for the nominated Frame rather than the current Frame itself.

This provides a mechanism for propagating the effects of variant Mappings around a FrameSet. If a new Frame is added to a FrameSet by connecting it to an pre-existing Frame that has two or more variant Mappings, then it may be appropriate to set the new Frame so that it mirrors the variants Mappings of the pre-existing Frame. If this is done, then it will be possible to select a specific variant Mapping using either the pre-existing Frame or the new Frame.

See also addVariant, getVariant and renameVariant.

Parameters
[in]iframeThe index of the Frame within the FrameSet which is to be mirrored by the current Frame. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by getNFrame). If AST__NOFRAME is supplied (or the current Frame is specified), then any mirroring established by a previous call to this function is disabled. A value of FrameSet::BASE may be given to specify the base frame.

Notes:

  • Mirrors can be chained. That is, if Frame B is set to be a mirror of Frame A, and Frame C is set to be a mirror of Frame B, then Frame C will act as a mirror of Frame A.
  • Variant Mappings cannot be added to the current Frame if it is mirroring another Frame. So calls to addVariant will cause an error to be reported if the current Frame is mirroring another Frame.
  • Any variant Mappings explicitly added to the current Frame using addVariant will be ignored if the current Frame is mirroring another Frame.

Definition at line 367 of file FrameSet.h.

367  {
368  astMirrorVariants(getRawPtr(), iframe);
369  assertOK();
370  }

◆ norm()

PointD ast::Frame::norm ( PointD  value) const
inlineinherited

Normalise a set of Frame coordinate values which might be unsuitable for display (e.g.

may lie outside the expected range) into a set of acceptable values suitable for display.

Parameters
[in]valueA point in the space which the Frame describes.
Returns
Normalized version of value. If any axes of value lie outside the expected range for the Frame, the corresponding returned value is changed to a acceptable (normalised) value. Otherwise, the axes of value are returned unchanged.

Notes

  • For some classes of Frame, whose coordinate values are not constrained, this function will always return the input unchanged. However, for Frames whose axes represent cyclic quantities (such as angles or positions on the sky), the output coordinates will typically be wrapped into an appropriate standard range, such as [0, 2 pi].
  • The NormMap class is a Mapping which can be used to normalise a set of points using the norm function of a specified Frame.
  • It is intended to be possible to put any set of coordinates into a form suitable for display by using this function to normalise them, followed by appropriate formatting (using astFormat).

Definition at line 1045 of file Frame.h.

1045  {
1046  astNorm(getRawPtr(), value.data());
1047  assertOK();
1048  detail::astBadToNan(value);
1049  return value;
1050  }

◆ offset()

PointD ast::Frame::offset ( PointD  point1,
PointD  point2,
double  offset 
) const
inlineinherited

Find the point which is offset a specified distance along the geodesic curve between two other points.

For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions.

Parameters
[in]point1The point marking the start of the geodesic curve.
[in]point2The point marking the end of the geodesic curve.
[in]offsetThe required offset from the first point along the geodesic curve. If this is positive, it will be towards the second point. If it is negative, it will be in the opposite direction. This offset need not imply a position lying between the two points given, as the curve will be extrapolated if necessary.
Returns
the offset point

Notes:

  • The geodesic curve used by this function is the path of shortest distance between two points, as defined by the distance function.
Exceptions
std::invalid_argumentif:
  • point1 or point2 is the wrong length

Definition at line 1075 of file Frame.h.

1075  {
1076  assertPointLength(point1, "point1");
1077  assertPointLength(point2, "point2");
1078  PointD ret(getNIn());
1079  astOffset(getRawPtr(), point1.data(), point2.data(), offset, ret.data());
1080  assertOK();
1081  detail::astBadToNan(ret);
1082  return ret;
1083  }
PointD offset(PointD point1, PointD point2, double offset) const
Find the point which is offset a specified distance along the geodesic curve between two other points...
Definition: Frame.h:1075
std::vector< double > PointD
Vector of double; used for bounds, points.
Definition: base.h:57

◆ offset2()

DirectionPoint ast::Frame::offset2 ( PointD const &  point1,
double  angle,
double  offset 
) const
inlineinherited

Find the point which is offset a specified distance along the geodesic curve at a given angle from a specified starting point.

This can only be used with 2-dimensional Frames.

For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions.

Parameters
[in]point1The point marking the start of the geodesic curve.
[in]angleThe angle (in radians) from the positive direction of the second axis, to the direction of the required position, as seen from the starting position. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1.
[in]offsetThe required offset from the first point along the geodesic curve. If this is positive, it will be in the direction of the given angle. If it is negative, it will be in the opposite direction.
Returns
a DirectionPoint containing:
  • The direction of the geodesic curve at the end point. That is, the angle (in radians) between the positive direction of the second axis and the continuation of the geodesic curve at the requested end point. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1.
  • The offset point.
Exceptions
std::invalid_argumentif
  • frame does not have naxes = 2
  • point1 or point2 are the wrong length, or point1 has any AST__BAD values

Notes

  • The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistance function

Definition at line 1117 of file Frame.h.

1117  {
1118  detail::assertEqual(getNIn(), "naxes", 2, " cannot call offset2");
1119  assertPointLength(point1, "point1");
1120  PointD point2(getNIn());
1121  double offsetAngle = astOffset2(getRawPtr(), point1.data(), angle, offset, point2.data());
1122  assertOK();
1123  detail::astBadToNan(point2);
1124  return DirectionPoint(detail::safeDouble(offsetAngle), point2);
1125  }
double angle(PointD const &a, PointD const &b, PointD const &c) const
Find the angle at point B between the line joining points A and B, and the line joining points C and ...
Definition: Frame.h:201

◆ operator!=()

bool ast::Object::operator!= ( Object const &  rhs) const
inlineinherited

Return True if this and rhs are not equal.

See operator== for details

Definition at line 82 of file Object.h.

82  {
83  return !(*this == rhs); };

◆ operator=() [1/2]

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

◆ operator=() [2/2]

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

◆ operator==()

bool ast::Object::operator== ( Object const &  rhs) const
inherited

Return True if this and rhs are the equal.

For two objects be equal, they both must have the same attributes and all contained objects must be equal.

Definition at line 85 of file Object.cc.

85  {
86  auto thisStr = this->show(false);
87  auto rhsStr = rhs.show(false);
88  return rhsStr == thisStr;
89 }
void show(std::ostream &os, bool showComments=true) const
Print a textual description the object to an ostream.
Definition: Object.cc:158

◆ permAxes()

void ast::Frame::permAxes ( std::vector< int >  perm)
inlineinherited

Permute the order in which a Frame's axes occur.

Parameters
[in]permA list of axes in their new order, using the current axis numbering. Axis numbers start at 1 for the first axis. Only genuine permutations of the axis order are permitted, so each axis must be referenced exactly once.

When used on a FrameSet, the axes of the current frame are permuted and all connecting mappings are updated accordingly, so that current behavior is preserved (except for the new axis order for output data).

Definition at line 1138 of file Frame.h.

1138  {
1139  detail::assertEqual(perm.size(), "perm.size()", static_cast<std::size_t>(getNAxes()), "naxes");
1140  astPermAxes(getRawPtr(), perm.data());
1141  assertOK();
1142  }

◆ pickAxes()

FrameMapping ast::Frame::pickAxes ( std::vector< int > const &  axes) const
inherited

Create a new Frame whose axes are copied from an existing Frame along with other Frame attributes, such as its Title.

Any number (zero or more) of the original Frame's axes may be copied, in any order, and additional axes with default attributes may also be included in the new Frame.

Parameters
[in]axesthe axes to be copied. These should be given in the order required in the new Frame, using the axis numbering in the original Frame (which starts at 1 for the first axis). Axes may be selected in any order, but each may only be used once. If additional (default) axes are also to be included, the corresponding elements of this array should be set to zero.
Returns
a FrameMapping containing:
  • The new frame.
  • A mapping (usually a PermMap, but may be a UnitMap) that describes the axis permutation that has taken place between the original and new Frames. The Mapping's forward transformation will convert coordinates from the original Frame into the new one, and vice versa.

Definition at line 68 of file Frame.cc.

68  {
69  AstMapping *rawMap;
70  auto *rawFrame =
71  reinterpret_cast<AstFrame *>(astPickAxes(getRawPtr(), axes.size(), axes.data(), &rawMap));
72  assertOK(reinterpret_cast<AstObject *>(rawFrame), reinterpret_cast<AstObject *>(rawMap));
74  try {
75  frame = Object::fromAstObject<Frame>(reinterpret_cast<AstObject *>(rawFrame), false);
76  } catch (...) {
77  astAnnul(rawMap);
78  throw;
79  }
80  auto map = Object::fromAstObject<Mapping>(reinterpret_cast<AstObject *>(rawMap), false);
81  return FrameMapping(frame, map);
82 }

◆ rate()

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

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.

Definition at line 215 of file Mapping.h.

215  {
216  detail::assertEqual(at.size(), "at.size", static_cast<std::size_t>(getNIn()), "nIn");
217  double result = astRate(getRawPtr(), const_cast<double *>(at.data()), ax1, ax2);
218  assertOK();
219  return result;
220  }
py::object result
Definition: _schema.cc:429

◆ remapFrame()

void ast::FrameSet::remapFrame ( int  iframe,
Mapping map 
)
inline

Modify the relationship (i.e.

Mapping) between a specified Frame in a FrameSet and the other Frames in that FrameSet.

Typically, this might be required if the FrameSet has been used to calibrate (say) an image, and that image is re-binned. The Frame describing the image will then have undergone a coordinate transformation, and this should be communicated to the associated FrameSet using this function.

See also addVariant, getVariant and mirrorVariants.

Parameters
[in]iframeThe index within the FrameSet of the Frame to be modified. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame). A value of FrameSet::BASE or FrameSet::CURRENT may be given to specify the base Frame or the current Frame respectively.
[in]mapA Mapping whose forward transformation converts coordinate values from the original coordinate system described by the Frame to the new one, and whose inverse transformation converts in the opposite direction.

Notes

  • The relationship between the selected Frame and any other Frame within the FrameSet will be modified by this function, but the relationship between all other Frames in the FrameSet remains unchanged.
  • The number of input and output coordinate values of the Mapping must be equal and must match the number of axes in the Frame being modified.
  • If a simple change of axis order is required, then permAxes may provide a more straightforward method of making the required changes to the FrameSet.
  • This function cannot be used to change the number of Frame axes. To achieve this, a new Frame must be added to the FrameSet (with addFrame) and the original one removed if necessary (with removeFrame).
  • Any variant Mappings associated with the remapped Frame (except for the current variant) will be lost as a consequence of calling this method (see attribute Variant).

Definition at line 410 of file FrameSet.h.

410  {
411  astRemapFrame(getRawPtr(), iframe, map.copy()->getRawPtr());
412  assertOK();
413  };

◆ removeFrame()

virtual void ast::FrameSet::removeFrame ( int  iframe)
inlinevirtual

Remove a Frame from a FrameSet.

Other Frame indices in the FrameSet are re-numbered as follows: Frame indices greater than iframe are decremented by one; other Frame indeces retain the same index.

Parameters
[in]iframeThe index of the required Frame within this FrameSet. This value should lie in the range 1 to the number of Frames in this FrameSet (as given by getNFrame). A value of FrameSet::BASE or FrameSet::CURRENT may be given to specify the base Frame or the current Frame, respectively.

Notes

  • Removing a Frame from a FrameSet does not affect the relationship between other Frames in this FrameSet, even if they originally depended on the Frame being removed.
  • The number of Frames in a FrameSet cannot be reduced to zero.
  • If a FrameSet's base or current Frame is removed, the Base or Current attribute (respectively) of the FrameSet will have its value cleared, so that another Frame will then assume its role by default.
  • If any other Frame is removed, the base and current Frames will remain the same. To ensure this, the Base and/or Current attributes of the FrameSet will be changed, if necessary, to reflect any change in the indices of these Frames.
Exceptions
std::runtime_errorif you attempt to remove the last frame

Reimplemented in ast::FrameDict.

Definition at line 442 of file FrameSet.h.

442  {
443  astRemoveFrame(getRawPtr(), iframe);
444  assertOK();
445  }

◆ renameVariant()

void ast::FrameSet::renameVariant ( std::string const &  name)
inline

Rename the current Variant of the current Mapping.

The Variant attribute is updated to name.

See the Variant attribute for more details. See also addVariant, getVariant and mirrorVariants.

Parameters
[in]nameThe new name of the current variant Mapping.
Exceptions
std::runtime_errorif:
  • A variant with the supplied name already exists in the current Frame.
  • The current Frame is a mirror for the variant Mappings in another Frame. This is only the case if the astMirrorVariants function has been called to make the current Frame act as a mirror.

Definition at line 463 of file FrameSet.h.

463  {
464  astAddVariant(getRawPtr(), nullptr, name.c_str());
465  assertOK();
466  }

◆ resolve()

ResolvedPoint ast::Frame::resolve ( std::vector< double > const &  point1,
std::vector< double > const &  point2,
std::vector< double > const &  point3 
) const
inherited

Resolve a vector into two orthogonal components.

The vector from point 1 to point 2 is used as the basis vector. The vector from point 1 to point 3 is resolved into components parallel and perpendicular to this basis vector. The lengths of the two components are returned, together with the position of closest aproach of the basis vector to point 3.

Parameters
[in]point1The start of the basis vector, and of the vector to be resolved.
[in]point2The end of the basis vector.
[in]point3The end of the vector to be resolved.
Returns
a ResolvedPoint containing:
  • point The point of closest approach of the basis vector to point 3.
  • d1 The distance from point 1 to the returned point (that is, the length of the component parallel to the basis vector). Positive values are in the same sense as movement from point 1 to point 2.
  • d2 The distance from the returned point to point 3 (that is, the length of the component perpendicular to the basis vector). The value is always positive.

Notes

  • Each vector used in this method is the path of shortest distance between two points, as defined by distance
  • This method will return nan coordinate values if any of the input coordinates are invalid, or if the required output values are undefined.

Definition at line 84 of file Frame.cc.

85  {
86  int const naxes = getNAxes();
87  detail::assertEqual(point1.size(), "a1.size()", static_cast<std::size_t>(naxes), "");
88  detail::assertEqual(point2.size(), "a2.size()", static_cast<std::size_t>(naxes), "");
89  detail::assertEqual(point3.size(), "b1.size()", static_cast<std::size_t>(naxes), "");
90  ResolvedPoint ret(naxes);
91  astResolve(getRawPtr(), point1.data(), point2.data(), point3.data(), ret.point.data(), &ret.d1, &ret.d2);
92  assertOK();
93  detail::astBadToNan(ret.point);
94  return ret;
95 }

◆ same()

bool ast::Object::same ( Object const &  other) const
inlineinherited

Does this contain the same AST object as another?

This is a test of identity, not of equality.

Definition at line 212 of file Object.h.

212 { return astSame(getRawPtr(), other.getRawPtr()); }

◆ set()

void ast::Object::set ( std::string const &  setting)
inlineprotectedinherited

Assign a set of attribute values, over-riding any previous values.

The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form: "attribute_1 = value_1, attribute_2 = value_2, ... " where "attribute_n" specifies an attribute name, and the value to the right of each " =" sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute's data type.

Notes

  • Attribute names are not case sensitive and may be surrounded by white space
  • Attribute names are not case sensitive and may be surrounded by white space.
  • White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned).
  • To include a literal comma or percent sign in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes.
Exceptions
std::runtime_errorif the attribute is read-only

Definition at line 440 of file Object.h.

440  {
441  astSet(getRawPtr(), "%s", setting.c_str());
442  assertOK();
443  }

◆ setActiveUnit()

void ast::Frame::setActiveUnit ( bool  enable)
inlineinherited

Set ActiveUnit: pay attention to units when one Frame is used to match another?

Definition at line 1295 of file Frame.h.

1295  {
1296  astSetActiveUnit(getRawPtr(), enable);
1297  assertOK();
1298  }

◆ setAlignSystem()

void ast::Frame::setAlignSystem ( std::string const &  system)
inlineinherited

Set AlignSystem: the coordinate system used by convert and findFrame to align Frames.

Definition at line 1203 of file Frame.h.

1203 { setC("AlignSystem", system); }
void setC(std::string const &attrib, std::string const &value)
Set the value of an attribute as a string.
Definition: Object.h:464

◆ setB()

void ast::Object::setB ( std::string const &  attrib,
bool  value 
)
inlineprotectedinherited

Set the value of an attribute as a bool.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 452 of file Object.h.

452  {
453  astSetI(getRawPtr(), attrib.c_str(), value);
454  assertOK();
455  }

◆ setBase()

void ast::FrameSet::setBase ( int  ind)
inline

Set Base: index of base Frame.

Definition at line 471 of file FrameSet.h.

471 { setI("Base", ind); }
void setI(std::string const &attrib, int value)
Set the value of an attribute as an int.
Definition: Object.h:500

◆ setBottom()

void ast::Frame::setBottom ( int  axis,
double  bottom 
)
inlineinherited

Set Bottom: the lowest axis value to display.

Definition at line 1208 of file Frame.h.

1208 { setD(detail::formatAxisAttr("Bottom", axis), bottom); }
void setD(std::string const &attrib, double value)
Set the value of an attribute as a double.
Definition: Object.h:476

◆ setC()

void ast::Object::setC ( std::string const &  attrib,
std::string const &  value 
)
inlineprotectedinherited

Set the value of an attribute as a string.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 464 of file Object.h.

464  {
465  astSetC(getRawPtr(), attrib.c_str(), value.c_str());
466  assertOK();
467  }

◆ setCurrent()

void ast::FrameSet::setCurrent ( int  ind)
inline

Set Current: index of current Frame, starting from 1.

Definition at line 476 of file FrameSet.h.

476 { setI("Current", ind); }

◆ setD()

void ast::Object::setD ( std::string const &  attrib,
double  value 
)
inlineprotectedinherited

Set the value of an attribute as a double.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 476 of file Object.h.

476  {
477  astSetD(getRawPtr(), attrib.c_str(), value);
478  assertOK();
479  }

◆ setDigits() [1/2]

void ast::Frame::setDigits ( int  axis,
int  digits 
)
inlineinherited

Set Digits for one axis: number of digits of precision.

Definition at line 1218 of file Frame.h.

1218 { setD(detail::formatAxisAttr("Digits", axis), digits); }

◆ setDigits() [2/2]

void ast::Frame::setDigits ( int  digits)
inlineinherited

Set Digits for all axes: number of digits of precision.

Definition at line 1213 of file Frame.h.

1213 { setI("Digits", digits); }

◆ setDirection()

void ast::Frame::setDirection ( bool  direction,
int  axis 
)
inlineinherited

Set Direction for one axis: display axis in conventional direction?

Definition at line 1223 of file Frame.h.

1223  {
1224  setB(detail::formatAxisAttr("Direction", axis), direction);
1225  }
void setB(std::string const &attrib, bool value)
Set the value of an attribute as a bool.
Definition: Object.h:452

◆ setDomain()

virtual void ast::Frame::setDomain ( std::string const &  domain)
inlinevirtualinherited

Set Domain: coordinate system domain.

Reimplemented in ast::FrameDict.

Definition at line 1230 of file Frame.h.

1230 { setC("Domain", domain); }

◆ setDut1()

void ast::Frame::setDut1 ( double  dut1)
inlineinherited

Set Dut1: difference between the UT1 and UTC timescale (sec)

Definition at line 1235 of file Frame.h.

1235 { setD("Dut1", dut1); }

◆ setEpoch() [1/2]

void ast::Frame::setEpoch ( double  epoch)
inlineinherited

Set Epoch: Epoch of observation as a double (years)

Definition at line 1240 of file Frame.h.

1240 { setD("Epoch", epoch); }

◆ setEpoch() [2/2]

void ast::Frame::setEpoch ( std::string const &  epoch)
inlineinherited

Set Epoch: Epoch of observation as a string.

Definition at line 1245 of file Frame.h.

1245 { setC("Epoch", epoch); }

◆ setF()

void ast::Object::setF ( std::string const &  attrib,
float  value 
)
inlineprotectedinherited

Set the value of an attribute as a float.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 488 of file Object.h.

488  {
489  astSetF(getRawPtr(), attrib.c_str(), value);
490  assertOK();
491  }

◆ setFormat()

void ast::Frame::setFormat ( int  axis,
std::string const &  format 
)
inlineinherited

Set Format for one axis: format specification for axis values.

Definition at line 1250 of file Frame.h.

1250  {
1251  setC(detail::formatAxisAttr("Format", axis), format);
1252  }
std::string format(int axis, double value) const
Return a string containing the formatted (character) version of a coordinate value for a Frame axis.
Definition: Frame.h:782

◆ setI()

void ast::Object::setI ( std::string const &  attrib,
int  value 
)
inlineprotectedinherited

Set the value of an attribute as an int.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 500 of file Object.h.

500  {
501  astSetI(getRawPtr(), attrib.c_str(), value);
502  assertOK();
503  }

◆ setID()

void ast::Object::setID ( std::string const &  id)
inlineinherited

Set ID: object identification string that is not copied.

Definition at line 215 of file Object.h.

215 { setC("ID", id); }

◆ setIdent()

void ast::Object::setIdent ( std::string const &  ident)
inlineinherited

Set Ident: object identification string that is copied.

Definition at line 218 of file Object.h.

218 { setC("Ident", ident); }

◆ setL()

void ast::Object::setL ( std::string const &  attrib,
long int  value 
)
inlineprotectedinherited

Set the value of an attribute as a long int.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 512 of file Object.h.

512  {
513  astSetL(getRawPtr(), attrib.c_str(), value);
514  assertOK();
515  }

◆ setLabel()

void ast::Frame::setLabel ( int  axis,
std::string const &  label 
)
inlineinherited

Set Label(axis) for one axis: axis label.

Definition at line 1257 of file Frame.h.

1257 { setC(detail::formatAxisAttr("Label", axis), label); }

◆ setMatchEnd()

void ast::Frame::setMatchEnd ( bool  match)
inlineinherited

Set MatchEnd: match trailing axes?

Definition at line 1262 of file Frame.h.

1262 { setB("MatchEnd", match); }

◆ setMaxAxes()

void ast::Frame::setMaxAxes ( int  maxAxes)
inlineinherited

Get MaxAxes: the maximum number of axes a frame found by findFrame may have.

Definition at line 1268 of file Frame.h.

1268 { setI("MaxAxes", maxAxes); }

◆ setMinAxes()

void ast::Frame::setMinAxes ( int  minAxes)
inlineinherited

Get MinAxes: the minimum number of axes a frame found by findFrame may have.

Definition at line 1274 of file Frame.h.

1274 { setI("MinAxes", minAxes); }

◆ setObsAlt()

void ast::Frame::setObsAlt ( double  alt)
inlineinherited

Set ObsAlt: Geodetic altitude of observer (m).

Definition at line 1279 of file Frame.h.

1279 { setD("ObsAlt", alt); }

◆ setObsLat()

void ast::Frame::setObsLat ( std::string const &  lat)
inlineinherited

Set ObsLat: frame title.

Definition at line 1284 of file Frame.h.

1284 { setC("ObsLat", lat); }

◆ setObsLon()

void ast::Frame::setObsLon ( std::string const &  lon)
inlineinherited

Set ObsLon: Geodetic longitude of observer.

Definition at line 1289 of file Frame.h.

1289 { setC("ObsLon", lon); }

◆ setPermute()

void ast::Frame::setPermute ( bool  permute)
inlineinherited

Set Permute: allow axis permutation when used as a template?

Definition at line 1303 of file Frame.h.

1303 { setB("Permute", permute); }

◆ setPreserveAxes()

void ast::Frame::setPreserveAxes ( bool  preserve)
inlineinherited

Set PreserveAxes: preserve axes?

Definition at line 1308 of file Frame.h.

1308 { setB("PreserveAxes", preserve); }

◆ setReport()

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

Set Report: report transformed coordinates to stdout?

Definition at line 225 of file Mapping.h.

225 { setB("Report", report); }

◆ setSymbol()

void ast::Frame::setSymbol ( int  axis,
std::string const &  symbol 
)
inlineinherited

Set Symbol(axis) for one axis: axis symbol.

Definition at line 1313 of file Frame.h.

1313  {
1314  setC(detail::formatAxisAttr("Symbol", axis), symbol);
1315  }

◆ setSystem()

void ast::Frame::setSystem ( std::string const &  system)
inlineinherited

Set System: coordinate system used to describe positions within the domain.

Definition at line 1321 of file Frame.h.

1321 { setC("System", system); }

◆ setTitle()

void ast::Frame::setTitle ( std::string const &  title)
inlineinherited

Set Title: frame title.

Definition at line 1326 of file Frame.h.

1326 { setC("Title", title); }

◆ setTop()

void ast::Frame::setTop ( int  axis,
double  top 
)
inlineinherited

Set Top for one axis: the highest axis value to display.

Definition at line 1331 of file Frame.h.

1331 { setD(detail::formatAxisAttr("Top", axis), top); }

◆ setUnit()

void ast::Frame::setUnit ( int  axis,
std::string const &  unit 
)
inlineinherited

Set Unit(axis) for one axis: physical units for formatted axis values.

Definition at line 1336 of file Frame.h.

1336 { setC(detail::formatAxisAttr("Unit", axis), unit); }

◆ setUseDefs()

void ast::Object::setUseDefs ( bool  usedefs)
inlineinherited

Set UseDefs: allow use of default values for Object attributes?

Definition at line 221 of file Object.h.

221 { setB("UseDefs", usedefs); }

◆ show() [1/2]

std::string ast::Object::show ( bool  showComments = true) const
inherited

Return a textual description the object as a string.

Parameters
[in]showCommentsShow comments?

Definition at line 165 of file Object.cc.

165  {
167  show(os, showComments);
168  return os.str();
169 }

◆ show() [2/2]

void ast::Object::show ( std::ostream os,
bool  showComments = true 
) const
inherited

Print a textual description the object to an ostream.

Parameters
[in,out]osThe stream to which to write the string representation.
[in]showCommentsShow comments?

Definition at line 158 of file Object.cc.

158  {
159  Stream stream(nullptr, &os);
160  Channel ch(stream, showComments ? "" : "Comment=0");
161  ch.write(*this);
162  assertOK();
163 }

◆ simplified()

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

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.

Definition at line 248 of file Mapping.h.

248  {
249  AstObject *rawSimpMap = reinterpret_cast<AstObject *>(astSimplify(getRawPtr()));
250  assertOK(rawSimpMap);
251  return Object::fromAstObject<Mapping>(rawSimpMap, true);
252  }

◆ test()

bool ast::Object::test ( std::string const &  attrib) const
inlineinherited

Has this attribute been explicitly set (and not subsequently cleared)?

Warning
Unlike the underlying astTest function, throws an exception if an error results

Notes

  • Attribute names are not case sensitive and may be surrounded by white space.
  • As you might expect, the returned value for a read-only attribute is always false.
Exceptions
std::runtime_errorif an error results.

Definition at line 250 of file Object.h.

250  {
251  bool res = astTest(getRawPtr(), attrib.c_str());
252  assertOK();
253  return res;
254  }

◆ then()

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

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.

Definition at line 37 of file Mapping.cc.

37 { return SeriesMap(*this, next); }

◆ tranGridForward() [1/2]

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

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

Definition at line 358 of file Mapping.h.

359  {
360  _tranGrid(lbnd, ubnd, tol, maxpix, true, to);
361  }

◆ tranGridForward() [2/2]

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

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

Definition at line 369 of file Mapping.h.

369  {
370  Array2D to = ndarray::allocate(nPts, getNOut());
371  _tranGrid(lbnd, ubnd, tol, maxpix, true, to);
372  return to;
373  }

◆ tranGridInverse() [1/2]

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

Transform a grid of points in the inverse direction.

See tranGridForward for the arguments, swapping nIn and nOut

Definition at line 380 of file Mapping.h.

381  {
382  _tranGrid(lbnd, ubnd, tol, maxpix, false, to);
383  }

◆ tranGridInverse() [2/2]

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

Transform a grid of points in the inverse direction.

See tranGridForward for the arguments, swapping nIn and nOut

Definition at line 390 of file Mapping.h.

390  {
391  Array2D to = ndarray::allocate(nPts, getNIn());
392  _tranGrid(lbnd, ubnd, tol, maxpix, false, to);
393  return to;
394  }

◆ under() [1/2]

CmpFrame ast::Frame::under ( Frame const &  next) const
inherited

Combine this frame with another to form a compound frame (CmpFrame), with the axes of this frame followed by the axes of the next frame.

A compound frame allows two component Frames (of any class) to be merged together to form a more complex Frame. The axes of the two component Frames then appear together in the resulting CmpFrame (those of this Frame, followed by those of next).

Since a CmpFrame is itself a Frame, it can be used as a component in forming further CmpFrames. Frames of arbitrary complexity may be built from simple individual Frames in this way.

Also since a Frame is a Mapping, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a UnitMap, but if either of the component Frames within a CmpFrame is a Region (a sub-class of Frame), then the CmpFrame will use the Region as a Mapping when transforming values for axes described by the Region. Thus input axis values corresponding to positions which are outside the Region will result in bad output axis values.

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 next frame in the compound frame (the final next.getNAxes() axes)
Returns
a new CmpFrame
Warning
The contained frames are shallow copies (just like AST); if you want deep copies then make them manually.

Definition at line 66 of file Frame.cc.

66 { return CmpFrame(*this, next); }

◆ under() [2/2]

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

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.

Definition at line 39 of file Mapping.cc.

39 { return ParallelMap(*this, next); }

◆ unformat()

NReadValue ast::Frame::unformat ( int  axis,
std::string const &  str 
) const
inlineinherited

Read a formatted coordinate value (given as a character string) for a Frame axis and return the number of characters read and the value.

The principle use of this function is in decoding user-supplied input which contains formatted coordinate values. Free-format input is supported as far as possible. If input is ambiguous, it is interpreted with reference to the Frame's attributes (in particular, the Format string associated with the Frame's axis).

This function is, in essence, the inverse of astFormat.

Applicability:

Frame This function applies to all Frames. See the "Frame Input Format" section below for details of the input formats accepted by a basic Frame.

SkyFrame The SkyFrame class re-defines the input format to be suitable for representing angles and times, with the resulting coordinate value returned in radians. See the "SkyFrame Input Format" section below for details of the formats accepted.

FrameSet The input formats accepted by a FrameSet are determined by its current Frame (as specified by the Current attribute).

Frame Input Format:

The input format accepted for a basic Frame axis is as follows:

  • An optional sign, followed by:
  • A sequence of one or more digits possibly containing a decimal point, followed by:
  • An optional exponent field.
  • The exponent field, if present, consists of "E" or "e" followed by a possibly signed integer.

Examples of acceptable Frame input formats include:

  • 99
  • 1.25
  • -1.6
  • 1E8
  • -.99e-17
  • <bad>

SkyFrame Input Format:

The input format accepted for a SkyFrame axis is as follows:

  • An optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. "-12 42 03").
  • Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (e.g. decimal degrees might be given as "124.707", while degrees and decimal arc-minutes might be given as "-13 33.8").
  • The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (e.g. "720 45 31" is valid, whereas "11 45 61" is not).
  • Fields may be separated by white space or by ":" (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (e.g. "- 2: 04 : 7.1").
  • The following field identification characters may be used as separators to replace either of those above (or may be appended to the final field), in order to identify the field to which they are appended: "d"—degrees; "h"—hours; "m"—minutes of arc or time; "s"—seconds of arc or time; "'" (single quote)—minutes of arc; """ (double quote)—seconds of arc. Either lower or upper case may be used. Fields must be given in order of decreasing significance (e.g. "-11D 3' 14.4"" or "22h14m11.2s").
  • The presence of any of the field identification characters "d", "'" (single quote) or """ (double quote) indicates that the value is to be interpreted as an angle. Conversely, the presence of "h" indicates that it is to be interpreted as a time (with 24 hours corresponding to 360 degrees). Incompatible angle/time identification characters may not be mixed (e.g. "10h14'3"" is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either.
  • If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by astFormat are correctly interpreted by Frame.unformat.
  • If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by Frame.format are correctly interpreted by Frame.unformat.
  • Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. "-05m13s" is equivalent to "-:05:13"). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters (e.g. "14:25.4s" specifies minutes and seconds, while "14::25.4s" specifies degrees and seconds).
  • If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. "01:02"), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that astFormat would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that astFormat would produce.
  • If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. "01:02"), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that Frame.format would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that Frame.format would produce.

This final convention is intended to ensure that values formatted by Frame.format which contain less than three fields will be correctly interpreted if read back using Frame.unformat, even if they do not contain field identification characters.

Examples of acceptable SkyFrame input formats (with interpretation in parentheses) include:

  • ‘-14d 13m 22.2s (-14d 13’ 22.2")` - `+ 12:34:56.7` (12d 34' 56.7" or 12h 34m 56.7s)
  • 001 : 02 : 03.4 (1d 02' 03.4" or 1h 02m 03.4s)
  • 22h 30 (22h 30m 00s)
  • 136::10"</tt> (136d 00' 10" or 136h 00m 10s)
  • `-14M 27S` (-0d 14' 27" or -0h 14m 27s) - <tt>-:14:</tt> (-0d 14' 00" or -0h 14m 00s)
  • `-::4.1` (-0d 00' 04.1" or -0h 00m 04.1s) - <tt>.9" (0d 00' 00.9") - `d12m` (0d 12' 00")
  • H 12:22.3s (0h 12m 22.3s)
  • <bad> (AST__BAD)

Where alternative interpretations are shown, the choice of angle or time depends on the associated Format(axis) attribute.

Parameters
[in]axisThe number of the Frame axis for which the coordinate value is to be read (axis numbering starts at zero for the first axis).
[in]strString containing the formatted coordinate value.
Returns
an NReadValue containing the number of characters read and the value; if nread is 0 then the value is certainly invalid.

Notes

  • Any white space at the beginning of the string will be skipped, as also will any trailing white space following the coordinate value read. The number of characters read will reflect this.
  • The number of characters will be 0 and the value undefined if the string supplied does not contain a suitably formatted value.
  • The string "<bad>" is recognised as a special case and will generate the value AST__BAD, without error. The test for this string is case-insensitive and permits embedded white space.

Definition at line 1502 of file Frame.h.

1502  {
1503  double value;
1504  int nread = astUnformat(getRawPtr(), axis, str.c_str(), &value);
1505  assertOK();
1506  return NReadValue(nread, detail::safeDouble(value));
1507  }

◆ unlock()

void ast::Object::unlock ( bool  report = false)
inlineinherited

Unlock this object previously locked using lock, so that other threads can use this object.

See lock for further details.

Parameters
[in]reportIf true, an error will be reported if the supplied Object, or any Object contained within the supplied Object, is not currently locked by the running thread. If false, such Objects will be left unchanged, and no error will be reported.

Notes

  • This function attempts to execute even if AST's global error status is set, but no further error report will be made if it subsequently fails under these circumstances.
  • All unlocked Objects are excluded from AST context handling until they are re-locked using astLock.
  • This function returns without action if the Object is not currently locked by any thread. If it is locked by the running thread, it is unlocked. If it is locked by another thread, an error will be reported if "error" is non-zero.
  • This function returns without action if the AST library has been built without POSIX thread support (i.e. the "-with-pthreads" option was not specified when running the "configure" script).

Definition at line 280 of file Object.h.

280  {
281  astUnlock(getRawPtr(), static_cast<int>(report));
282  assertOK();
283  }

Friends And Related Function Documentation

◆ Frame

friend class Frame
friend

Definition at line 100 of file FrameSet.h.

◆ Object

friend class Object
friend

Definition at line 101 of file FrameSet.h.

Member Data Documentation

◆ BASE

constexpr int ast::FrameSet::BASE = AST__BASE
staticconstexpr

index of base frame

Definition at line 104 of file FrameSet.h.

◆ CURRENT

constexpr int ast::FrameSet::CURRENT = AST__CURRENT
staticconstexpr

index of current frame

Definition at line 105 of file FrameSet.h.

◆ NOFRAME

constexpr int ast::FrameSet::NOFRAME = AST__NOFRAME
staticconstexpr

an invalid frame index

Definition at line 106 of file FrameSet.h.


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