ast Namespace Reference
AST wrapper classes and functions. More...
Namespaces | |
| namespace | detail |
Classes | |
| class | Channel |
| Channel provides input/output of AST objects. More... | |
| class | ChebyDomain |
| The domain over which a Chebyshev polynomial is defined; returned by ChebyMap.getDomain. More... | |
| class | ChebyMap |
| A ChebyMap is a form of Mapping which performs a Chebyshev polynomial transformation. More... | |
| class | CmpFrame |
| A CmpFrame is a compound Frame which allows two component Frames (of any class) to be merged together to form a more complex Frame. More... | |
| class | CmpMap |
| Abstract base class for SeriesMap and ParallelMap. More... | |
| class | DirectionPoint |
| Struct returned by Frame.offset2 containing a direction and a point. More... | |
| class | FileStream |
| File-based source or sink (not both) for channels. More... | |
| class | FitsChan |
| A specialized form of Channel which reads and writes FITS header cards. More... | |
| class | FitsTable |
| class | FoundValue |
| A value and associated validity flag. More... | |
| class | FrameDict |
| A FrameSet whose frames can be referenced by domain name. More... | |
| class | FrameMapping |
| Struct returned by Frame.pickAxes containing a frame and a mapping. More... | |
| class | FrameSet |
| 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... | |
| class | KeyMap |
| KeyMap is used to store a set of values with associated keys which identify the values. More... | |
| class | LutMap |
| LutMap is a specialised form of Mapping which transforms 1-dimensional coordinates by using linear interpolation in a lookup table. More... | |
| class | MapBox |
| Object to compute the bounding box which just encloses another box after it has been transformed by a mapping. More... | |
| class | Mapping |
| An abstract base class for objects which transform one set of coordinates to another. More... | |
| class | MapSplit |
| A Mapping split off as a subset of another Mapping. More... | |
| class | MathMap |
| A MathMap is a Mapping which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C. More... | |
| class | MatrixMap |
| MatrixMap is a form of Mapping which performs a general linear transformation. More... | |
| class | NormMap |
| A Mapping which normalises coordinate values using the norm method of the supplied Frame. More... | |
| class | NReadValue |
| Struct returned by Frame.unformat containing the number of characters read and corresponding value. More... | |
| class | Object |
| Abstract base class for all AST objects. More... | |
| class | ParallelMap |
| A parallel compound mapping where the first Mapping is used to transform the lower numbered coordinates of each point and the second Mapping is used to transform the remaining coordinates. More... | |
| class | PcdMap |
| A PcdMap is a non-linear Mapping which transforms 2-dimensional positions to correct for the radial distortion introduced by some cameras and telescopes. More... | |
| class | PermMap |
| A Mapping which permutes the order of coordinates, and possibly also changes the number of coordinates, between its input and output. More... | |
| class | PolyMap |
| PolyMap is a Mapping which performs a general polynomial transformation. More... | |
| class | QuadApprox |
| A quadratic approximation to a 2D Mapping. More... | |
| class | RateMap |
| RateMap is a Mapping which represents a single element of the Jacobian matrix of another Mapping. More... | |
| class | ResolvedPoint |
| Struct returned by Frame.resolve containing a point and the resolved vector components. More... | |
| class | SeriesMap |
| A series compound mapping where the first Mapping is used to transform the coordinates of each point and the second Mapping is then applied to the result. More... | |
| class | ShiftMap |
| ShiftMap is a linear Mapping which shifts each axis by a specified constant value. More... | |
| class | SkyFrame |
| SkyFrame is a specialised form of Frame which describes celestial longitude/latitude coordinate systems. More... | |
| class | SlaMap |
| SlaMap is a specialised form of Mapping which can be used to represent a sequence of conversions between standard celestial (longitude, latitude) coordinate systems. More... | |
| class | SpecFrame |
| A specialised form of one-dimensional Frame which represents various coordinate systems used to describe positions within an electro-magnetic spectrum. More... | |
| class | SphMap |
| A SphMap is a Mapping which transforms points from a 3-dimensional Cartesian coordinate system into a 2-dimensional spherical coordinate system (longitude and latitude on a unit sphere centred at the origin). More... | |
| class | SplineMap |
| SplineMap is a Mapping which performs a 2-in, 2-out Mapping defined by a pair of two- dimensional B-spline surfaces. More... | |
| class | Stream |
| A stream for ast::Channel. More... | |
| class | StringStream |
| String-based source and sink for channels. More... | |
| class | Table |
| class | TimeFrame |
| A TimeFrame is a specialised form of one-dimensional Frame which represents various coordinate systems used to describe positions in time. More... | |
| class | TimeMap |
| A TimeMap is a specialised form of 1-dimensional Mapping which can be used to represent a sequence of conversions between standard time coordinate systems. More... | |
| class | TranMap |
| TranMap is a Mapping which combines the forward transformation of a supplied Mapping with the inverse transformation of another supplied Mapping, ignoring the un-used transformation in each Mapping (indeed the un-used transformation need not exist). More... | |
| class | UnitMap |
| A UnitMap is a unit (null) Mapping that has no effect on the coordinates supplied to it. More... | |
| class | UnitNormMap |
| The forward transformation of a UnitNormMap subtracts the specified centre and then transforms the resulting vector to a unit vector and the vector norm. More... | |
| class | WcsMap |
| Map from a spherical system to a cartesian system using standard FITS sky coordinate projections. More... | |
| class | WinMap |
| A WinMap is a linear Mapping which transforms a rectangular window in one coordinate system into a similar window in another coordinate system by scaling and shifting each axis (the window edges being parallel to the coordinate axes). More... | |
| class | XmlChan |
| XmlChan provides input/output of AST objects. More... | |
| class | ZoomMap |
| A Mapping which "zooms" a set of points about the origin by multiplying all coordinate values by the same scale factor. More... | |
Typedefs | |
| using | Array2D = ndarray::Array<double, 2, 2> |
| 2D array of const double; typically used for lists of const points | |
| using | ConstArray2D = ndarray::Array<const double, 2, 2> |
| 2D array of const double; typically used for lists of const points | |
| using | PointI = std::vector<int> |
| Vector of ints; typically used for the bounds of Mapping.tranGridForward and inverse. | |
| using | PointD = std::vector<double> |
| Vector of double; used for bounds, points. | |
Enumerations | |
| enum class | DataType { IntType = AST__INTTYPE , ShortIntType = AST__SINTTYPE , ByteType = AST__BYTETYPE , DoubleType = AST__DOUBLETYPE , FloatType = AST__FLOATTYPE , StringType = AST__STRINGTYPE , ObjectType = AST__OBJECTTYPE , PointerType = AST__POINTERTYPE , UndefinedType = AST__UNDEFTYPE , BadType = AST__BADTYPE } |
| Data types held by a KeyMap. More... | |
| enum class | FitsKeyState { ABSENT = 0 , NOVALUE , PRESENT } |
| Enums describing the presence or absence of a FITS keyword. More... | |
| enum class | CardType { NOTYPE = AST__NOTYPE , COMMENT = AST__COMMENT , INT = AST__INT , FLOAT = AST__FLOAT , STRING = AST__STRING , COMPLEXF = AST__COMPLEXF , COMPLEXI = AST__COMPLEXI , LOGICAL = AST__LOGICAL , CONTINUE = AST__CONTINUE , UNDEF = AST__UNDEF } |
| Enums describing the FITS card type. More... | |
| enum class | WcsType { AZP = AST__AZP , SZP = AST__SZP , TAN = AST__TAN , STG = AST__STG , SIN = AST__SIN , ARC = AST__ARC , ZPN = AST__ZPN , ZEA = AST__ZEA , AIR = AST__AIR , CYP = AST__CYP , CEA = AST__CEA , CAR = AST__CAR , MER = AST__MER , SFL = AST__SFL , PAR = AST__PAR , MOL = AST__MOL , AIT = AST__AIT , COP = AST__COP , COE = AST__COE , COD = AST__COD , COO = AST__COO , BON = AST__BON , PCO = AST__PCO , TSC = AST__TSC , CSC = AST__CSC , QSC = AST__QSC , NCP = AST__NCP , GLS = AST__GLS , TPN = AST__TPN , HPX = AST__HPX , XPH = AST__XPH , WCSBAD = AST__WCSBAD } |
| WCS types that give the projection type code (in upper case) as used in the FITS-WCS "CTYPEi" keyword. More... | |
Functions | |
| void | assertOK (AstObject *rawPtr1=nullptr, AstObject *rawPtr2=nullptr) |
| Throw std::runtime_error if AST's state is bad. | |
| bool | escapes (int include=-1) |
| Control whether graphical escape sequences are included in strings. | |
| int | ast_version (void) |
| Frame (int naxes, std::string const &options="") | |
| Frame is used to represent a coordinate system. | |
| virtual | ~Frame () |
| Frame (Frame &&)=default | |
| Frame & | operator= (Frame const &)=delete |
| Frame & | operator= (Frame &&)=default |
| *Return a deep copy of this object std::shared_ptr< Frame > | copy () const |
| 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. | |
| double | distance (PointD const &point1, PointD const &point2) const |
| Compute a frameset that describes the conversion between this frame and another frame. | |
| 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. | |
| 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. | |
| Frame (AstFrame *rawPtr) | |
| Construct a Frame from a pointer to a raw AstFrame. | |
| virtual std::shared_ptr< Object > | copyPolymorphic () const override |
| std::shared_ptr< FrameSet > | append (FrameSet const &first, FrameSet const &second) |
| Construct a FrameSet that performs two transformations in series. | |
| std::shared_ptr< Mapping > | makeRadialMapping (std::vector< double > const ¢er, Mapping const &mapping1d) |
| Construct a radially symmetric mapping from a 1-dimensional mapping. | |
| ConstArray2D | arrayFromVector (std::vector< double > const &vec, int nAxes) |
| Reshape a vector as a 2-dimensional array that shares the same memory. | |
| Array2D | arrayFromVector (std::vector< double > &vec, int nAxes) |
| Reshape a vector as a 2-dimensional array that shares the same memory. | |
Variables | |
| *Copy | constructor |
Detailed Description
AST wrapper classes and functions.
Typedef Documentation
◆ Array2D
| using ast::Array2D = ndarray::Array<double, 2, 2> |
◆ ConstArray2D
| using ast::ConstArray2D = ndarray::Array<const double, 2, 2> |
◆ PointD
| using ast::PointD = std::vector<double> |
Vector of double; used for bounds, points.
Also used to store a list of points as sequential data, as an alternative to Array2D and ConstArray2D
◆ PointI
| using ast::PointI = std::vector<int> |
Vector of ints; typically used for the bounds of Mapping.tranGridForward and inverse.
Enumeration Type Documentation
◆ CardType
|
strong |
Enums describing the FITS card type.
Definition at line 49 of file FitsChan.h.
◆ DataType
|
strong |
◆ FitsKeyState
|
strong |
Enums describing the presence or absence of a FITS keyword.
| Enumerator | |
|---|---|
| ABSENT | keyword is not present |
| NOVALUE | keyword is present, but has no value |
| PRESENT | keyword is present and has a value |
Definition at line 40 of file FitsChan.h.
◆ WcsType
|
strong |
WCS types that give the projection type code (in upper case) as used in the FITS-WCS "CTYPEi" keyword.
You should consult the FITS-WCS paper for a list of the available projections. The additional code of WcsType::TPN can be supplied which represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper.
These have the same value as the corresponding AST__ constant, e.g. WcsType::TAN = AST__TAN.
I am not sure what AST__WCSBAD is used for, but I included it anyway.
| Enumerator | |
|---|---|
| AZP | |
| SZP | |
| TAN | |
| STG | |
| SIN | |
| ARC | |
| ZPN | |
| ZEA | |
| AIR | |
| CYP | |
| CEA | |
| CAR | |
| MER | |
| SFL | |
| PAR | |
| MOL | |
| AIT | |
| COP | |
| COE | |
| COD | |
| COO | |
| BON | |
| PCO | |
| TSC | |
| CSC | |
| QSC | |
| NCP | |
| GLS | |
| TPN | |
| HPX | |
| XPH | |
| WCSBAD | |
Function Documentation
◆ ~Frame()
◆ angle()
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] a the coordinates of the first point [in] b the coordinates of the first second [in] c the 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_argument if a, b or c have the wrong length
◆ append()
| std::shared_ptr< FrameSet > ast::append | ( | FrameSet const & | first, |
| FrameSet const & | second ) |
Construct a FrameSet that performs two transformations in series.
When used as a Mapping, the FrameSet shall apply first, followed by second. Its inverse shall apply the inverse of second, followed by the inverse of first. The concatenation is only valid if first.getCurrent() and second.getBase() have the same number of axes.
The new FrameSet shall contain all Frames and Mappings from first, followed by all Frames and Mappings from second, preserving their original order. The current frame of first shall be connected to the base frame of second by a UnitMap. The new set's base frame shall be the base frame of first, and its current frame shall be the current frame of second.
The FrameSet shall be independent of the input arguments, so changes to the original FrameSets (in particular, reassignments of their base or current frames) shall not affect it.
- Parameters
-
first,second the FrameSets to concatenate.
- Returns
- a pointer to a combined FrameSet as described above
Example: if first has 3 frames and second has 4, then the result shall contain 7 frames, of which frames 1-3 are the same as frames 1-3 of first, in order, and frames 4-7 are the same as frames 1-4 of second, in order.
Definition at line 33 of file functional.cc.
◆ arrayFromVector() [1/2]
| Array2D ast::arrayFromVector | ( | std::vector< double > & | vec, |
| int | nAxes ) |
Reshape a vector as a 2-dimensional array that shares the same memory.
To convert a vector of coefficients to an array of coefficients for PolyMap or ChebyMap, call this with nAxes = nPoints / width, where width is the number of elements in each coefficient: width = nOut + 2 for forward coefficients, nIn + 2 for inverse coefficients.
- Parameters
-
[in] vec Vector of points, with all values for one axis first, then the next axes, and so on, e.g. x1, x2, ...xnPt, y1, y2, ...ynNpt [in] nAxes Number of axes per point
- Returns
- 2-dimensional array with dimensions (nPts, nAxes)
- Exceptions
-
std::runtime_error if vec length is not a multiple of nAxes
- Warning
- You must hold onto the original vector until you are done with the returned array, else the array will be corrupted. (However, the Python version returns a copy, to avoid memory issues.)
◆ arrayFromVector() [2/2]
| ConstArray2D ast::arrayFromVector | ( | std::vector< double > const & | vec, |
| int | nAxes ) |
Reshape a vector as a 2-dimensional array that shares the same memory.
To convert a vector of coefficients to an array of coefficients for PolyMap or ChebyMap, call this with nAxes = nPoints / width, where width is the number of elements in each coefficient: width = nOut + 2 for forward coefficients, nIn + 2 for inverse coefficients.
- Parameters
-
[in] vec Vector of points, with all values for one axis first, then the next axes, and so on, e.g. x1, x2, ...xnPt, y1, y2, ...ynNpt [in] nAxes Number of axes per point
- Returns
- 2-dimensional array with dimensions (nPts, nAxes)
- Exceptions
-
std::runtime_error if vec length is not a multiple of nAxes
- Warning
- You must hold onto the original vector until you are done with the returned array, else the array will be corrupted. (However, the Python version returns a copy, to avoid memory issues.)
◆ assertOK()
| void ast::assertOK | ( | AstObject * | rawPtr1 = nullptr, |
| AstObject * | rawPtr2 = nullptr ) |
Throw std::runtime_error if AST's state is bad.
- Parameters
-
rawPtr1 An AST object to free if status is bad rawPtr2 An AST object to free if status is bad
- Note
- on the first call an error handler is registered that saves error messages to a buffer.
◆ ast_version()
◆ axAngle()
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] 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
- 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_argument if 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.
◆ axDistance()
| double ast::axDistance | ( | int | axis, |
| double | v1, | ||
| double | v2 ) const |
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] 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.
- Returns
- The distance from the first to the second axis value.
◆ axOffset()
| double ast::axOffset | ( | int | axis, |
| double | v1, | ||
| double | dist ) const |
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] 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.
- Returns
- The incremented axis value
◆ copy()
| *Return a deep copy of this object std::shared_ptr< Frame > ast::copy | ( | ) | const |
◆ copyPolymorphic()
|
overrideprotectedvirtual |
◆ distance()
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
-
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.
-
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.
-
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.
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] 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.
- 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). */ std::shared_ptr<FrameSet> convert(Frame const &to, std::string const &domainlist = "");
/** 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] point1 The coordinates of the first point. [in] point2 The coordinates of the second point.
- Returns
- The distance between the two points.
◆ escapes()
|
inline |
Control whether graphical escape sequences are included in strings.
The Plot class defines a set of escape sequences which can be included within a text string in order to control the appearance of sub-strings within the text. (See the Escape attribute for a description of these escape sequences). It is usually inappropriate for AST to return strings containing such escape sequences when called by application code. For instance, an application which displays the value of the Title attribute of a Frame usually does not want the displayed string to include potentially long escape sequences which a human read would have difficuly interpreting. Therefore the default behaviour is for AST to strip out such escape sequences when called by application code. This default behaviour can be changed using this function.
- Parameters
-
[in] include Possible values are: - -1 (or any negative value) to return the current value without changing it.
- 0 to not include escape sequences,
- 1 (or any positive value) to include escape sequences,
- Returns
- the previous value (or current value if include is negative).
Notes:
- This function also controls whether the AST function astStripEscapes removes escape sequences from the supplied string, or returns the supplied string without change.
- Unlike the AST function astEscapes, this function will not attempt to execute if an error has already occurred.
◆ findFrame()
| std::shared_ptr< FrameSet > Frame::findFrame | ( | Frame const & | tmplt, |
| std::string const & | domainlist = "" ) |
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
-
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] 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.
- 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.
◆ format()
| std::string ast::format | ( | int | axis, |
| double | value ) const |
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] 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.
◆ Frame() [1/3]
|
explicitprotected |
◆ Frame() [2/3]
|
default |
◆ Frame() [3/3]
|
explicit |
Frame is used to represent a coordinate system.
It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a Title (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two.
Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame.
Frames may also contain knowledge of how to transform to and from related coordinate systems.
Attributes
In addition to those provided by Mapping and Object, Frame provides the following attributes, where axis is an axis number, starting from 1 and (axis) may be omitted if the Frame has only one axis:
- ActiveUnit: pay attention to units when one Frame is used to match another? (Note: not a true attribute, but close).
- AlignSystem: Coordinate system used to align Frames
- Bottom(axis): Lowest axis value to display
- Digits/Digits(axis)`: Number of digits of precision- @ref Frame_Direction Direction(axis)": Display axis in conventional direction? - @ref Frame_Domain "Domain": Coordinate system domain - @ref Frame_Dut1 "Dut1": Difference between the UT1 and UTC timescale (sec) - @ref Frame_Epoch "Epoch": Epoch of observation - @ref Frame_Format "Format(axis)": Format specification for axis values - @ref Frame_InternalUnit "InternalUnit(axis)": Physical units for unformated axis values - @ref Frame_Label "Label(axis)": Axis label - @ref Frame_MatchEnd "MatchEnd": Match trailing axes? - @ref Frame_MaxAxes "MaxAxes": Maximum number of axes a frame found by @ref findFrame may have. - @ref Frame_MinAxes "MinAxes": Minimum number of axes a frame found by @ref findFrame may have. - @ref Frame_NAxes "NAxes": Number of Frame axes - @ref Frame_NormUnit "NormUnit(axis)": Normalised physical units for formatted axis values - @ref Frame_ObsAlt "ObsAlt": Geodetic altitude of observer (m) - @ref Frame_ObsLat "ObsLat": Geodetic latitude of observer - @ref Frame_ObsLon "ObsLon": Geodetic longitude of observer - @ref Frame_Permute "Permute": Allow axis permutation when used as a template? - @ref Frame_PreserveAxes "PreserveAxes": Preserve axes? - @ref Frame_Symbol "Symbol(axis)": Axis symbol - @ref Frame_System "System": Coordinate system used to describe positions within the domain - @ref Frame_Title "Title: Frame title
- Top(axis): Highest axis value to display
- Unit(axis): Physical units for formatted axis values */ class Frame : public Mapping { friend class Object;
public: /** Construct a Frame
- Parameters
-
[in] naxes The number of Frame axes (i.e. the number of dimensions of the coordinate space which the Frame describes). [in] options Comma-separated list of attribute assignments.
◆ getActiveUnit()
| bool ast::getActiveUnit | ( | ) | const |
Get ActiveUnit: pay attention to units when one Frame is used to match another?
◆ getAlignSystem()
| std::string ast::getAlignSystem | ( | ) | const |
Get AlignSystem: the coordinate system used by convert and findFrame to align Frames.
◆ getBottom()
| double ast::getBottom | ( | int | axis | ) | const |
◆ getDigits() [1/2]
| int ast::getDigits | ( | ) | const |
◆ getDigits() [2/2]
| int ast::getDigits | ( | int | axis | ) | const |
◆ getDirection()
| bool ast::getDirection | ( | int | axis | ) | const |
◆ getDomain()
| std::string ast::getDomain | ( | ) | const |
◆ getDut1()
| double ast::getDut1 | ( | ) | const |
◆ getEpoch()
| double ast::getEpoch | ( | ) | const |
◆ getFormat()
| std::string ast::getFormat | ( | int | axis | ) | const |
◆ getInternalUnit()
| std::string ast::getInternalUnit | ( | int | axis | ) | const |
Get InternalUnit(axis) read-only attribute for one axis: physical units for unformated axis values.
◆ getLabel()
| std::string ast::getLabel | ( | int | axis | ) | const |
Get Label(axis) for one axis: axis label.
◆ getMatchEnd()
| bool ast::getMatchEnd | ( | ) | const |
◆ getMaxAxes()
| int ast::getMaxAxes | ( | ) | const |
◆ getMinAxes()
| int ast::getMinAxes | ( | ) | const |
◆ getNAxes()
| int ast::getNAxes | ( | ) | const |
◆ getNormUnit()
| std::string ast::getNormUnit | ( | int | axis | ) | const |
Get NormUnit(axis) read-only attribute for one frame: normalised physical units for formatted axis values.
◆ getObsAlt()
| double ast::getObsAlt | ( | ) | const |
◆ getObsLat()
| std::string ast::getObsLat | ( | ) | const |
◆ getObsLon()
| std::string ast::getObsLon | ( | ) | const |
◆ getPermute()
| bool ast::getPermute | ( | ) | const |
◆ getPreserveAxes()
| bool ast::getPreserveAxes | ( | ) | const |
Get PreserveAxes: preserve axes?
◆ getSymbol()
| std::string ast::getSymbol | ( | int | axis | ) | const |
Get Symbol(axis) for one axis: axis symbol.
◆ getSystem()
| std::string ast::getSystem | ( | ) | const |
◆ getTitle()
| std::string ast::getTitle | ( | ) | const |
◆ getTop()
| double ast::getTop | ( | int | axis | ) | const |
◆ getUnit()
| std::string ast::getUnit | ( | int | axis | ) | const |
Get Unit(axis) for one axis: physical units for formatted axis values.
◆ intersect()
| std::vector< double > Frame::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.
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] 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.
- Returns
- the point of intersection between the two geodesic curves.
- Exceptions
-
std::runtime_error if 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
◆ makeRadialMapping()
| std::shared_ptr< Mapping > ast::makeRadialMapping | ( | std::vector< double > const & | center, |
| Mapping const & | mapping1d ) |
Construct a radially symmetric mapping from a 1-dimensional mapping.
The transform will be symmetrical about the specified center. The forward transform is as follows: input -> unitNormMap -> input norm -> mapping1d -> output norm -> unitNormMap inverse -> output -> unit vector ----------------------------> where unitNormMap is UnitNormMap(center)
The returned mapping will support forward and/or inverse transformation as mapping1d does.
- Parameters
-
[in] center Center of radial symmetry [in] mapping1d 1-dimensional mapping
- Returns
- a mapping that is radially symmetric about the center and has nIn = nOut = center.size()
- Exceptions
-
std::invalid_argument if mapping1d has nIn or nOut != 1 std::runtime_error if center is empty
Definition at line 48 of file functional.cc.
◆ matchAxes()
| std::vector< int > ast::matchAxes | ( | Frame const & | other | ) | const |
Look for corresponding axes between this frame and another.
- Parameters
-
[in] other The 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
◆ norm()
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] value A 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).
◆ offset()
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] 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.
- 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_argument if: - point1 or point2 is the wrong length
◆ offset2()
| DirectionPoint ast::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.
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] 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.
- 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_argument if - 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
◆ operator=() [1/2]
◆ operator=() [2/2]
◆ permAxes()
| void ast::permAxes | ( | std::vector< int > | perm | ) |
Permute the order in which a Frame's axes occur.
- Parameters
-
[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).
◆ pickAxes()
| FrameMapping Frame::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.
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] 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.
- Returns
- a FrameMapping containing:
◆ resolve()
| ResolvedPoint Frame::resolve | ( | std::vector< double > const & | point1, |
| std::vector< double > const & | point2, | ||
| std::vector< double > const & | point3 ) const |
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] 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.
- 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.
◆ setActiveUnit()
| void ast::setActiveUnit | ( | bool | enable | ) |
Set ActiveUnit: pay attention to units when one Frame is used to match another?
◆ setAlignSystem()
| void ast::setAlignSystem | ( | std::string const & | system | ) |
Set AlignSystem: the coordinate system used by convert and findFrame to align Frames.
◆ setBottom()
| void ast::setBottom | ( | int | axis, |
| double | bottom ) |
◆ setDigits() [1/2]
| void ast::setDigits | ( | int | axis, |
| int | digits ) |
◆ setDigits() [2/2]
| void ast::setDigits | ( | int | digits | ) |
◆ setDirection()
| void ast::setDirection | ( | bool | direction, |
| int | axis ) |
◆ setDomain()
|
virtual |
◆ setDut1()
| void ast::setDut1 | ( | double | dut1 | ) |
◆ setEpoch() [1/2]
| void ast::setEpoch | ( | double | epoch | ) |
◆ setEpoch() [2/2]
| void ast::setEpoch | ( | std::string const & | epoch | ) |
◆ setFormat()
| void ast::setFormat | ( | int | axis, |
| std::string const & | format ) |
◆ setLabel()
| void ast::setLabel | ( | int | axis, |
| std::string const & | label ) |
Set Label(axis) for one axis: axis label.
◆ setMatchEnd()
| void ast::setMatchEnd | ( | bool | match | ) |
◆ setMaxAxes()
| void ast::setMaxAxes | ( | int | maxAxes | ) |
◆ setMinAxes()
| void ast::setMinAxes | ( | int | minAxes | ) |
◆ setObsAlt()
| void ast::setObsAlt | ( | double | alt | ) |
◆ setObsLat()
| void ast::setObsLat | ( | std::string const & | lat | ) |
◆ setObsLon()
| void ast::setObsLon | ( | std::string const & | lon | ) |
◆ setPermute()
| void ast::setPermute | ( | bool | permute | ) |
◆ setPreserveAxes()
| void ast::setPreserveAxes | ( | bool | preserve | ) |
Set PreserveAxes: preserve axes?
◆ setSymbol()
| void ast::setSymbol | ( | int | axis, |
| std::string const & | symbol ) |
Set Symbol(axis) for one axis: axis symbol.
◆ setSystem()
| void ast::setSystem | ( | std::string const & | system | ) |
◆ setTitle()
| void ast::setTitle | ( | std::string const & | title | ) |
◆ setTop()
| void ast::setTop | ( | int | axis, |
| double | top ) |
◆ setUnit()
| void ast::setUnit | ( | int | axis, |
| std::string const & | unit ) |
Set Unit(axis) for one axis: physical units for formatted axis values.
◆ under()
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] next The 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.
◆ unformat()
| NReadValue ast::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.
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" (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" (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] 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). [in] str String 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.
Variable Documentation
◆ constructor
Generated on for lsst.astshim by
1.17.0