LSST Applications g063fba187b+fee0456c91,g0f08755f38+ea96e5a5a3,g1653933729+a8ce1bb630,g168dd56ebc+a8ce1bb630,g1a2382251a+90257ff92a,g20f6ffc8e0+ea96e5a5a3,g217e2c1bcf+937a289c59,g28da252d5a+daa7da44eb,g2bbee38e9b+253935c60e,g2bc492864f+253935c60e,g3156d2b45e+6e55a43351,g32e5bea42b+31359a2a7a,g347aa1857d+253935c60e,g35bb328faa+a8ce1bb630,g3a166c0a6a+253935c60e,g3b1af351f3+a8ce1bb630,g3e281a1b8c+c5dd892a6c,g414038480c+416496e02f,g41af890bb2+afe91b1188,g599934f4f4+0db33f7991,g7af13505b9+e36de7bce6,g80478fca09+da231ba887,g82479be7b0+a4516e59e3,g858d7b2824+ea96e5a5a3,g89c8672015+f4add4ffd5,g9125e01d80+a8ce1bb630,ga5288a1d22+bc6ab8dfbd,gb58c049af0+d64f4d3760,gc28159a63d+253935c60e,gcab2d0539d+3f2b72788c,gcf0d15dbbd+4ea9c45075,gda6a2b7d83+4ea9c45075,gdaeeff99f8+1711a396fd,ge79ae78c31+253935c60e,gef2f8181fd+3031e3cf99,gf0baf85859+c1f95f4921,gfa517265be+ea96e5a5a3,gfa999e8aa5+17cd334064,w.2024.50
LSST Data Management Base Package
|
SkyFrame is a specialised form of Frame which describes celestial longitude/latitude coordinate systems. More...
#include <SkyFrame.h>
Public Types | |
using | ObjectPtr = std::unique_ptr<AstObject, Deleter> |
unique pointer holding an AST raw pointer | |
Public Member Functions | |
SkyFrame (std::string const &options="") | |
Construct a SkyFrame. | |
virtual | ~SkyFrame () |
SkyFrame (SkyFrame const &)=default | |
Copy constructor: make a deep copy. | |
SkyFrame (SkyFrame &&)=default | |
SkyFrame & | operator= (SkyFrame const &)=delete |
SkyFrame & | operator= (SkyFrame &&)=default |
std::shared_ptr< SkyFrame > | copy () const |
Return a deep copy of this object. | |
bool | getAlignOffset () const |
Get AlignOffset: align SkyFrames using the offset coordinate system? | |
bool | getAsTime (int axis) const |
Get AsTime(axis) for one axis: format celestial coordinates as times? | |
double | getEquinox () const |
Get Equinox: epoch of the mean equinox. | |
bool | getIsLatAxis (int axis) const |
Get IsLatAxis(axis) for one axis: is the specified axis the latitude axis? | |
bool | getIsLonAxis (int axis) const |
Get IsLonAxis(axis) for one axis: is the specified axis the longitude axis? | |
int | getLatAxis () const |
Get LatAxis: index of the latitude axis. | |
int | getLonAxis () const |
Get LonAxis: index of the longitude axis. | |
bool | getNegLon () const |
Get NegLon: display longitude values in the range [-pi,pi]? | |
std::string | getProjection () const |
Get Projection: sky projection description. | |
std::vector< double > | getSkyRef () const |
Get SkyRef for both axes: position defining location of the offset coordinate system. | |
std::string | getSkyRefIs () const |
Get SkyRefIs: selects the nature of the offset coordinate system. | |
std::vector< double > | getSkyRefP () const |
Get SkyRefP for both axes: position defining orientation of the offset coordinate system. | |
double | getSkyTol () const |
Get SkyTol: smallest significant shift in sky coordinates. | |
void | setAlignOffset (bool alignOffset) |
Set AlignOffset: align SkyFrames using the offset coordinate system? | |
void | setAsTime (int axis, bool asTime) |
Set AsTime(axis) for one axis: format celestial coordinates as times? | |
void | setEquinox (double equinox) |
Set Equinox: epoch of the mean equinox. | |
void | setNegLon (bool negLon) |
Set NegLon: display longitude values in the range [-pi,pi]? | |
void | setProjection (std::string const &projection) |
Set Projection: sky projection description. | |
void | setSkyRef (std::vector< double > const &skyRef) |
Set SkyRef: position defining location of the offset coordinate system. | |
void | setSkyRefIs (std::string const &skyRefIs) |
Set SkyRefIs: selects the nature of the offset coordinate system. | |
void | setSkyRefP (std::vector< double > const &skyRefP) |
Set SkyRefP: position defining orientation of the offset coordinate system. | |
void | setSkyTol (double skyTol) |
Set SkyTol: smallest significant shift in sky coordinates. | |
std::shared_ptr< Mapping > | skyOffsetMap () |
Get a sky offset map. | |
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. | |
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. | |
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. | |
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. | |
std::shared_ptr< FrameSet > | convert (Frame const &to, std::string const &domainlist="") |
Compute a frameset that describes the conversion between this frame and another frame. | |
double | distance (PointD const &point1, PointD const &point2) const |
Find the distance between two points whose Frame coordinates are given. | |
std::shared_ptr< FrameSet > | findFrame (Frame const &tmplt, std::string const &domainlist="") |
Find a coordinate system with specified characteristics. | |
std::string | format (int axis, double value) const |
Return a string containing the formatted (character) version of a coordinate value for a Frame axis. | |
bool | getActiveUnit () const |
Get ActiveUnit: pay attention to units when one Frame is used to match another? | |
std::string | getAlignSystem () const |
Get AlignSystem: the coordinate system used by convert and findFrame to align Frames. | |
double | getBottom (int axis) const |
Get Bottom for one axis: the lowest axis value to display. | |
int | getDigits () const |
Get Digits: the default used if no specific value specified for an axis. | |
int | getDigits (int axis) const |
Get Digits for one axis. | |
bool | getDirection (int axis) const |
Get Direction for one axis: display axis in conventional direction? | |
std::string | getDomain () const |
Get Domain: coordinate system domain. | |
double | getDut1 () const |
Get Dut1: difference between the UT1 and UTC timescale (sec) | |
double | getEpoch () const |
Get Epoch: Epoch of observation. | |
std::string | getFormat (int axis) const |
Get Format for one axis: format specification for axis values. | |
std::string | getInternalUnit (int axis) const |
Get InternalUnit(axis) read-only attribute for one axis: physical units for unformated axis values. | |
std::string | getLabel (int axis) const |
Get Label(axis) for one axis: axis label. | |
bool | getMatchEnd () const |
Get MatchEnd: match trailing axes? | |
int | getMaxAxes () const |
Get MaxAxes: the maximum axes a frame found by findFrame may have. | |
int | getMinAxes () const |
Get MinAxes: the maximum axes a frame found by findFrame may have. | |
int | getNAxes () const |
Get NAxes: the number of axes in the frame (i.e. | |
std::string | getNormUnit (int axis) const |
Get NormUnit(axis) read-only attribute for one frame: normalised physical units for formatted axis values. | |
double | getObsAlt () const |
Get ObsAlt: Geodetic altitude of observer (m). | |
std::string | getObsLat () const |
Get ObsLat: Geodetic latitude of observer. | |
std::string | getObsLon () const |
Get ObsLon: Geodetic longitude of observer. | |
bool | getPermute () const |
Get Permute: allow axis permutation when used as a template? | |
bool | getPreserveAxes () const |
Get PreserveAxes: preserve axes? | |
std::string | getSymbol (int axis) const |
Get Symbol(axis) for one axis: axis symbol. | |
std::string | getSystem () const |
Get System: coordinate system used to describe positions within the domain. | |
std::string | getTitle () const |
Get Title: frame title. | |
double | getTop (int axis) const |
Get Top: the highest axis value to display. | |
std::string | getUnit (int axis) const |
Get Unit(axis) for one axis: physical units for formatted axis values. | |
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. | |
std::vector< int > | matchAxes (Frame const &other) const |
Look for corresponding axes between this frame and another. | |
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. | |
ParallelMap | under (Mapping const &next) const |
Return a parallel compound mapping containing shallow copies of the original. | |
PointD | norm (PointD value) const |
Normalise a set of Frame coordinate values which might be unsuitable for display (e.g. | |
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. | |
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. | |
void | permAxes (std::vector< int > perm) |
Permute the order in which a Frame's axes occur. | |
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. | |
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. | |
void | setAlignSystem (std::string const &system) |
Set AlignSystem: the coordinate system used by convert and findFrame to align Frames. | |
void | setBottom (int axis, double bottom) |
Set Bottom: the lowest axis value to display. | |
void | setDigits (int digits) |
Set Digits for all axes: number of digits of precision. | |
void | setDigits (int axis, int digits) |
Set Digits for one axis: number of digits of precision. | |
void | setDirection (bool direction, int axis) |
Set Direction for one axis: display axis in conventional direction? | |
virtual void | setDomain (std::string const &domain) |
Set Domain: coordinate system domain. | |
void | setDut1 (double dut1) |
Set Dut1: difference between the UT1 and UTC timescale (sec) | |
void | setEpoch (double epoch) |
Set Epoch: Epoch of observation as a double (years) | |
void | setEpoch (std::string const &epoch) |
Set Epoch: Epoch of observation as a string. | |
void | setFormat (int axis, std::string const &format) |
Set Format for one axis: format specification for axis values. | |
void | setLabel (int axis, std::string const &label) |
Set Label(axis) for one axis: axis label. | |
void | setMatchEnd (bool match) |
Set MatchEnd: match trailing axes? | |
void | setMaxAxes (int maxAxes) |
Get MaxAxes: the maximum number of axes a frame found by findFrame may have. | |
void | setMinAxes (int minAxes) |
Get MinAxes: the minimum number of axes a frame found by findFrame may have. | |
void | setObsAlt (double alt) |
Set ObsAlt: Geodetic altitude of observer (m). | |
void | setObsLat (std::string const &lat) |
Set ObsLat: frame title. | |
void | setObsLon (std::string const &lon) |
Set ObsLon: Geodetic longitude of observer. | |
void | setActiveUnit (bool enable) |
Set ActiveUnit: pay attention to units when one Frame is used to match another? | |
void | setPermute (bool permute) |
Set Permute: allow axis permutation when used as a template? | |
void | setPreserveAxes (bool preserve) |
Set PreserveAxes: preserve axes? | |
void | setSymbol (int axis, std::string const &symbol) |
Set Symbol(axis) for one axis: axis symbol. | |
void | setSystem (std::string const &system) |
Set System: coordinate system used to describe positions within the domain. | |
void | setTitle (std::string const &title) |
Set Title: frame title. | |
void | setTop (int axis, double top) |
Set Top for one axis: the highest axis value to display. | |
void | setUnit (int axis, std::string const &unit) |
Set Unit(axis) for one axis: physical units for formatted axis values. | |
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. | |
int | getNIn () const |
Get NIn: the number of input axes. | |
int | getNOut () const |
Get NOut: the number of output axes. | |
bool | getIsSimple () const |
Get IsSimple: has the mapping been simplified? | |
bool | isInverted () const |
Is this an inverted mapping? | |
bool | getIsLinear () const |
Get IsLinear: is the Mapping linear? | |
bool | getReport () const |
Get Report: report transformed coordinates to stdout? | |
bool | hasForward () const |
Is the forward transform available? | |
bool | hasInverse () const |
Is the inverse transform available? | |
std::shared_ptr< Mapping > | inverted () const |
Get an inverse mapping. | |
Array2D | linearApprox (PointD const &lbnd, PointD const &ubnd, double tol) const |
Compute a linear approximation to the forward transformation. | |
SeriesMap | then (Mapping const &next) const |
Return a series compound mapping this(first(input)) containing shallow copies of the original. | |
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. | |
void | setReport (bool report) |
Set Report: report transformed coordinates to stdout? | |
std::shared_ptr< Mapping > | simplified () const |
Return a simplied version of the mapping (which may be a compound Mapping such as a CmpMap). | |
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. | |
Array2D | applyForward (ConstArray2D const &from) const |
Perform a forward transformation on a 2-D array, returning the results as a new array. | |
std::vector< double > | applyForward (std::vector< double > const &from) const |
Perform a forward transformation on a vector, returning the results as a new vector. | |
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. | |
Array2D | applyInverse (ConstArray2D const &from) const |
Perform an inverse transformation on a 2-D array, returning the results as a new 2-D array. | |
std::vector< double > | applyInverse (std::vector< double > const &from) const |
Perform an inverse transformation on a vector, returning the results as a new vector. | |
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. | |
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. | |
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. | |
Array2D | tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const |
Transform a grid of points in the inverse direction. | |
bool | operator== (Object const &rhs) const |
Return True if this and rhs are the equal. | |
bool | operator!= (Object const &rhs) const |
Return True if this and rhs are not equal. | |
void | clear (std::string const &attrib) |
Clear the values of a specified set of attributes for an Object. | |
bool | hasAttribute (std::string const &attrib) const |
Does this object have an attribute with the specified name? | |
std::string | getClassName () const |
Get Class: the name of the class (e.g. | |
std::string | getID () const |
Get ID: object identification string that is not copied. | |
std::string | getIdent () const |
Get Ident: object identification string that is copied. | |
int | getNObject () const |
Get NObject: number of AST objects in existence of the same type as the underlying AST class. | |
int | getObjSize () const |
Get ObjSize: the in-memory size of the AST object in bytes. | |
int | getRefCount () const |
Get RefCount: number of active pointers to the underlying AST object. | |
bool | getUseDefs () const |
Get UseDefs: allow use of default values for Object attributes? | |
void | lock (bool wait) |
Lock this object for exclusive use by the calling thread. | |
bool | same (Object const &other) const |
Does this contain the same AST object as another? | |
void | setID (std::string const &id) |
Set ID: object identification string that is not copied. | |
void | setIdent (std::string const &ident) |
Set Ident: object identification string that is copied. | |
void | setUseDefs (bool usedefs) |
Set UseDefs: allow use of default values for Object attributes? | |
void | show (std::ostream &os, bool showComments=true) const |
Print a textual description the object to an ostream. | |
std::string | show (bool showComments=true) const |
Return a textual description the object as a string. | |
bool | test (std::string const &attrib) const |
Has this attribute been explicitly set (and not subsequently cleared)? | |
void | unlock (bool report=false) |
Unlock this object previously locked using lock, so that other threads can use this object. | |
AstObject const * | getRawPtr () const |
Get the raw AST pointer. | |
AstObject * | getRawPtr () |
Get the raw AST pointer. | |
Static Public Member Functions | |
static std::shared_ptr< Object > | fromString (std::string const &str) |
Construct an Object from a string, using astFromString. | |
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. | |
Protected Member Functions | |
virtual std::shared_ptr< Object > | copyPolymorphic () const override |
Return a deep copy of this object. | |
SkyFrame (AstSkyFrame *rawptr) | |
Construct a SkyFrame from a raw AST pointer. | |
template<typename Class > | |
std::shared_ptr< Class > | decompose (int i, bool copy) const |
Return a deep copy of one of the two component mappings. | |
template<typename T , typename AstT > | |
std::shared_ptr< T > | copyImpl () const |
Implementation of deep copy. | |
bool | getB (std::string const &attrib) const |
Get the value of an attribute as a bool. | |
std::string const | getC (std::string const &attrib) const |
Get the value of an attribute as a string. | |
double | getD (std::string const &attrib) const |
Get the value of an attribute as a double. | |
float | getF (std::string const &attrib) const |
Get the value of an attribute as a float. | |
int | getI (std::string const &attrib) const |
Get the value of an attribute as an int. | |
long int | getL (std::string const &attrib) const |
Get the value of an attribute as a long int. | |
void | set (std::string const &setting) |
Assign a set of attribute values, over-riding any previous values. | |
void | setB (std::string const &attrib, bool value) |
Set the value of an attribute as a bool. | |
void | setC (std::string const &attrib, std::string const &value) |
Set the value of an attribute as a string. | |
void | setD (std::string const &attrib, double value) |
Set the value of an attribute as a double. | |
void | setF (std::string const &attrib, float value) |
Set the value of an attribute as a float. | |
void | setI (std::string const &attrib, int value) |
Set the value of an attribute as an int. | |
void | setL (std::string const &attrib, long int value) |
Set the value of an attribute as a long int. | |
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. | |
Friends | |
class | Object |
SkyFrame is a specialised form of Frame which describes celestial longitude/latitude coordinate systems.
The particular celestial coordinate system to be represented is specified by setting the SkyFrame's System
attribute (currently, the default is ICRS
) qualified, as necessary, by a mean Equinox
value and/or an Epoch
.
For each of the supported celestial coordinate systems, a SkyFrame can apply an optional shift of origin to create a coordinate system representing offsets within the celestial coordinate system from some specified point. This offset coordinate system can also be rotated to define new longitude and latitude axes. See attributes SkyRef
, SkyRefIs
and SkyRefP
.
All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using format.
SkyFrame provides the following attributes, in addition to those provided by Frame, Mapping and Object
Definition at line 66 of file SkyFrame.h.
|
inherited |
|
inlineexplicit |
Construct a SkyFrame.
[in] | options | String containing an optional comma-separated list of attribute assignments to be used for initialising the new SkyFrame. The syntax used is identical to that for set. |
auto auto = astSkyFrame("")
Creates a SkyFrame to describe the default ICRS celestial coordinate system.
auto auto = astSkyFrame("System = FK5, Equinox = J2005, Digits = 10")
Creates a SkyFrame to describe the FK5 celestial coordinate system, with a mean Equinox oc Because especially accurate coordinates will be used, additional precision (10 digits) has been requested. This will be used when coordinate values are formatted for display.
auto auto = astSkyFrame("System = FK4, Equinox = 1955-sep-2")
Creates a SkyFrame to describe the old FK4 celestial coordinate system. A default Epoch value (B1950.0) is used, but the mean Equinox value is given explicitly as "1955-sep-2".
auto auto = astSkyFrame("System = GAPPT, Epoch = J2000")
Creates a SkyFrame to describe the Geocentric Apparent celestial coordinate system.
ICRS
. However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in behaviour with future versions of this function). If you intend to use the ICRS
system indefinitely then you should specify it explicitly using an options
value of System=ICRS
.Definition at line 124 of file SkyFrame.h.
|
inlinevirtual |
Definition at line 129 of file SkyFrame.h.
|
default |
Copy constructor: make a deep copy.
|
default |
|
inlineexplicitprotected |
Construct a SkyFrame from a raw AST pointer.
Definition at line 250 of file SkyFrame.h.
|
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.
[in] | a | the coordinates of the first point |
[in] | b | the coordinates of the first second |
[in] | c | the coordinates of the first third |
std::invalid_argument | if a , b or c have the wrong length |
Definition at line 201 of file Frame.h.
|
inlineinherited |
Perform a forward transformation on a 2-D array, returning the results as a new array.
[in] | from | input coordinates, with dimensions (nPts, nIn) |
Definition at line 268 of file Mapping.h.
|
inlineinherited |
|
inlineinherited |
Perform a forward transformation on a vector, returning the results as a new vector.
[in] | from | input coordinates as a vector, with axes adjacent, e.g. x0, y0, x1, y1...xn, yn |
Definition at line 280 of file Mapping.h.
|
inlineinherited |
Perform an inverse transformation on a 2-D array, returning the results as a new 2-D array.
[in] | from | output coordinates, with dimensions (nPts, nOut) |
|
inlineinherited |
Perform an inverse transformation on a 2-D array, putting the results into a pre-allocated 2-D array.
[in] | from | input coordinates, with dimensions (nPts, nOut) |
[out] | to | transformed coordinates, with dimensions (nPts, nIn) |
Definition at line 294 of file Mapping.h.
|
inlineinherited |
Perform an inverse transformation on a vector, returning the results as a new vector.
[in] | from | input coordinates as a vector, with axes adjacent, e.g. x0, y0, x1, y1...xn, yn |
Definition at line 314 of file Mapping.h.
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.
[in] | a | the coordinates of the first point |
[in] | b | the coordinates of the second point |
[in] | axis | the index of the axis from which the angle is to be measured, where 1 is the first axis |
std::invalid_argument | if a or b have the wrong length |
distance
method. Definition at line 229 of file Frame.h.
|
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.
[in] | axis | The index of the axis to which the supplied values refer. The first axis has index 1. |
[in] | v1 | The first axis value. |
[in] | v2 | The second axis value. |
|
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.
[in] | axis | The index of the axis to which the supplied values refer. The first axis has index 1. |
[in] | v1 | The original axis value. |
[in] | dist | The axis increment to add to the original axis value. |
|
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.
|
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.
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).
This function applies to all Frames. Alignment occurs within the coordinate system given by attribute AlignSystem.
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:
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.
Alignment occurs within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest
.
Alignment occurs within the time system and time scale given by attributes AlignSystem and AlignTimeScale
.
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.
[in,out] | to | A 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] | domainlist | A 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. |
Definition at line 31 of file Frame.cc.
|
inline |
Return a deep copy of this object.
Definition at line 138 of file SkyFrame.h.
|
inlineprotectedinherited |
|
inlineoverrideprotectedvirtual |
Return a deep copy of this object.
This is called by copy.
Each subclass must override this method. The standard implementation is:
for example Frame implements this as:
Reimplemented from ast::Frame.
Definition at line 245 of file SkyFrame.h.
|
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[]
.
[in] | i | Index: 0 for the first mapping, 1 for the second |
[in] | copy | If true make a deep copy, else a shallow copy |
std::invalid_argument | if i is not 0 or 1. |
std::runtime_error | if this mapping is not a compound mapping. |
Definition at line 64 of file Mapping.cc.
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.
[in] | point1 | The coordinates of the first point. |
[in] | point2 | The coordinates of the second point. |
Definition at line 474 of file Frame.h.
|
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:
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.
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:
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.
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).
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,out] | tmplt | Template 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] | domainlist | String 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. |
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.
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.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.
|
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.
[in] | axis | The number of the Frame axis for which formatting is to be performed (axis numbering starts at 1 for the first axis). |
[in] | value | The coordinate value to be formatted. |
|
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.
Class | The class of the returned shared pointer. (The actual class will be the correct class of rawPtr.) |
[in] | rawObj | A bare AST object pointer |
[in] | copy | If True then make a deep copy of the pointer (and free the original) |
Definition at line 138 of file Object.cc.
|
inlinestaticinherited |
|
inlineinherited |
|
inline |
Get AlignOffset: align SkyFrames using the offset coordinate system?
Definition at line 141 of file SkyFrame.h.
|
inlineinherited |
Get AlignSystem: the coordinate system used by convert and findFrame to align Frames.
Definition at line 802 of file Frame.h.
|
inline |
Get AsTime(axis) for one axis: format celestial coordinates as times?
Definition at line 144 of file SkyFrame.h.
|
inlineprotectedinherited |
Get the value of an attribute as a bool.
If possible, the attribute value is converted to the type you request.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
Get Bottom for one axis: the lowest axis value to display.
Definition at line 807 of file Frame.h.
|
inlineprotectedinherited |
Get the value of an attribute as a string.
If possible, the attribute value is converted to the type you request.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
Get Class: the name of the class (e.g.
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.
|
inlineprotectedinherited |
Get the value of an attribute as a double.
If possible, the attribute value is converted to the type you request.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
Get Digits: the default used if no specific value specified for an axis.
Definition at line 812 of file Frame.h.
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inline |
|
inlineprotectedinherited |
Get the value of an attribute as a float.
If possible, the attribute value is converted to the type you request.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
|
protectedinherited |
Get the value of an attribute as an int.
If possible, the attribute value is converted to the type you request.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
Get InternalUnit(axis) read-only attribute for one axis: physical units for unformated axis values.
Definition at line 848 of file Frame.h.
|
inline |
Get IsLatAxis(axis) for one axis: is the specified axis the latitude axis?
Definition at line 150 of file SkyFrame.h.
|
inlineinherited |
|
inline |
Get IsLonAxis(axis) for one axis: is the specified axis the longitude axis?
Definition at line 153 of file SkyFrame.h.
|
inlineinherited |
|
inlineprotectedinherited |
Get the value of an attribute as a long int.
If possible, the attribute value is converted to the type you request.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
|
inline |
|
inline |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inline |
Get NegLon: display longitude values in the range [-pi,pi]?
Definition at line 162 of file SkyFrame.h.
|
inlineinherited |
|
inlineinherited |
|
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.
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inline |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inline |
Get SkyRef for both axes: position defining location of the offset coordinate system.
Definition at line 169 of file SkyFrame.h.
|
inline |
Get SkyRefIs: selects the nature of the offset coordinate system.
Definition at line 178 of file SkyFrame.h.
|
inline |
Get SkyRefP for both axes: position defining orientation of the offset coordinate system.
Definition at line 182 of file SkyFrame.h.
|
inline |
Get SkyTol: smallest significant shift in sky coordinates.
Definition at line 191 of file SkyFrame.h.
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
Get Unit(axis) for one axis: physical units for formatted axis values.
Definition at line 933 of file Frame.h.
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
Is the forward transform available?
hasForward
instead of getTranForward
for clarity, since it does not return a transform. Definition at line 114 of file Mapping.h.
|
inlineinherited |
Is the inverse transform available?
hasInverse
instead of getTranInverse
for clarity, since it does not return a transform. Definition at line 123 of file Mapping.h.
|
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.
[in] | a1 | Coordinates of the first point on the first geodesic curve. |
[in] | a2 | Coordinates of the second point on the first geodesic curve. |
[in] | b1 | Coordinates of the first point on the second geodesic curve. |
[in] | b2 | Coordinates of the second point on the second geodesic curve. |
std::runtime_error | if the frame is not 2-dimensional |
a1
.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.Definition at line 51 of file Frame.cc.
|
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.
|
inlineinherited |
|
inherited |
Compute a linear approximation to the forward transformation.
[in] | lbnd | Input point defining the lower bounds of the box over which the linear approximation is computed. |
[in] | ubnd | Input point defining the upper bounds of the box over which the linear approximation is computed. |
[in] | tol | The 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. |
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
std::runtime_error | if the forward transformation cannot be modeled to within the specified tol . |
Definition at line 49 of file Mapping.cc.
|
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.
[in] | wait | If 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. |
|
inlinestaticprotectedinherited |
Functor to make an astshim instance from a raw AST pointer of the corresponding type.
ShimT | Output astshim class |
AstT | Output AST class |
|
inlineinherited |
Look for corresponding axes between this frame and another.
[in] | other | The other frame |
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
.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.
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.
[in] | value | A point in the space which the Frame describes. |
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.norm
function of a specified Frame.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.
[in] | point1 | The point marking the start of the geodesic curve. |
[in] | point2 | The point marking the end of the geodesic curve. |
[in] | offset | The 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. |
distance
function.std::invalid_argument | if:
|
Definition at line 1075 of file Frame.h.
|
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.
[in] | point1 | The point marking the start of the geodesic curve. |
[in] | angle | The 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] | offset | The 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. |
std::invalid_argument | if
|
Definition at line 1117 of file Frame.h.
|
inlineinherited |
|
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.
|
inlineinherited |
Permute the order in which a Frame's axes occur.
[in] | perm | A 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.
|
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.
[in] | axes | the 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. |
Definition at line 68 of file Frame.cc.
|
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.
[in] | at | The input position at which the rate of change is to be evaluated. |
[in] | ax1 | The index of the output for which the rate of change is to be found (1 for first output). |
[in] | ax2 | The index of the input which is to be varied in order to find the rate of change (1 for the first input). |
ax1
with respect to input ax2
, evaluated at at
, or nan
if the value cannot be calculated.
|
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.
[in] | point1 | The start of the basis vector, and of the vector to be resolved. |
[in] | point2 | The end of the basis vector. |
[in] | point3 | The end of the vector to be resolved. |
nan
coordinate values if any of the input coordinates are invalid, or if the required output values are undefined.
|
inlineinherited |
|
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.
std::runtime_error | if the attribute is read-only |
|
inlineinherited |
|
inline |
Set AlignOffset: align SkyFrames using the offset coordinate system?
Definition at line 194 of file SkyFrame.h.
|
inlineinherited |
Set AlignSystem: the coordinate system used by convert and findFrame to align Frames.
Definition at line 1203 of file Frame.h.
|
inline |
Set AsTime(axis) for one axis: format celestial coordinates as times?
Definition at line 197 of file SkyFrame.h.
|
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.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
Set Bottom: the lowest axis value to display.
Definition at line 1208 of file Frame.h.
|
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.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
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.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
|
inlineinherited |
Set Digits for all axes: number of digits of precision.
Definition at line 1213 of file Frame.h.
|
inlineinherited |
Set Direction for one axis: display axis in conventional direction?
|
inlinevirtualinherited |
Set Domain: coordinate system domain.
Reimplemented in ast::FrameDict.
Definition at line 1230 of file Frame.h.
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inline |
|
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.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
Set Format for one axis: format specification for axis values.
Definition at line 1250 of file Frame.h.
|
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.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
|
inlineinherited |
|
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.
std::runtime_error | if the attribute does not exist or the value cannot be converted |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inline |
Set NegLon: display longitude values in the range [-pi,pi]?
Definition at line 203 of file SkyFrame.h.
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inline |
|
inlineinherited |
|
inline |
Set SkyRef: position defining location of the offset coordinate system.
Definition at line 209 of file SkyFrame.h.
|
inline |
Set SkyRefIs: selects the nature of the offset coordinate system.
Definition at line 217 of file SkyFrame.h.
|
inline |
Set SkyRefP: position defining orientation of the offset coordinate system.
Definition at line 220 of file SkyFrame.h.
|
inline |
Set SkyTol: smallest significant shift in sky coordinates.
Definition at line 228 of file SkyFrame.h.
|
inlineinherited |
Set Symbol(axis) for one axis: axis symbol.
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
|
inlineinherited |
Set Unit(axis) for one axis: physical units for formatted axis values.
Definition at line 1336 of file Frame.h.
|
inlineinherited |
|
inherited |
Return a textual description the object as a string.
[in] | showComments | Show comments? |
|
inherited |
Print a textual description the object to an ostream.
[in,out] | os | The stream to which to write the string representation. |
[in] | showComments | Show comments? |
Definition at line 158 of file Object.cc.
|
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.
|
inline |
Get a sky offset map.
Get a Mapping in which the forward transformation transforms a position in the coordinate system given by the System attribute of the supplied SkyFrame, into the offset coordinate system specified by the SkyRef
, SkyRefP
and SkyRefIs
attributes of the sky frame. A UnitMap is returned if the sky frame does not define an offset coordinate system.
Definition at line 238 of file SkyFrame.h.
|
inlineinherited |
Has this attribute been explicitly set (and not subsequently cleared)?
false
.std::runtime_error | if an error results. |
Return a series compound mapping this(first(input)) containing shallow copies of the original.
[in] | next | the mapping whose input is the output of this mapping |
std::invalid_argument | if the number of input axes of next does not match the number of output axes of this mapping. |
Definition at line 37 of file Mapping.cc.
|
inlineinherited |
Transform a grid of points in the forward direction.
[in] | lbnd | The coordinates of the centre of the first pixel in the input grid along each dimension, size = nIn |
[in] | ubnd | The coordinates of the centre of the last pixel in the input grid along each dimension, size = nIn |
[in] | tol | The 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.
[in] | maxpix | A 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] | to | Computed points, with dimensions (nPts, nOut), where nPts the desired number of points |
Definition at line 358 of file Mapping.h.
|
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
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.
[in] | next | The next frame in the compound frame (the final next.getNAxes() axes) |
Definition at line 66 of file Frame.cc.
|
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.
[in] | next | the mapping that processes the final next.getNin() axes of input to produce the final next.getNout() axes of output. |
Definition at line 39 of file Mapping.cc.
|
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:
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:
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:
001 : 02 : 03.4
(1d 02' 03.4" or 1h 02m 03.4s)
- <tt>22h 30</tt> (22h 30m 00s)
- <tt>136::10" (136d 00' 10" or 136h 00m 10s)
- `-14M 27S` (-0d 14' 27" or -0h 14m 27s)-:14:
(-0d 14' 00" or -0h 14m 00s)
- `-::4.1` (-0d 00' 04.1" or -0h 00m 04.1s).9"</tt> (0d 00' 00.9")
`d12m` (0d 12' 00")
- <tt>H 12:22.3s</tt> (0h 12m 22.3s)
- <tt>\<bad\></tt> (<tt>AST__BAD</tt>)
Where alternative interpretations are shown, the choice of angle or
time depends on the associated Format(axis) attribute.
@param [in] axis The number of the Frame axis for which the coordinate value
is to be read (axis numbering starts at zero for the first axis).
@param [in] str String containing the formatted coordinate value.
@return an NReadValue containing the number of characters read and the value;
if nread is 0 then the value is certainly invalid.
<h3>Notes</h3>
- 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.
|
inlineinherited |
Unlock this object previously locked using lock, so that other threads can use this object.
See lock for further details.
[in] | report | If 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. |
|
friend |
Definition at line 67 of file SkyFrame.h.