I/O Channel using STC-S to represent Objects StcsChan
When an STC-S description is read using AST_READ, the returned AST Object may be 1) a PointList describing the STC AstroCoords (i.e. a single point of interest within the coordinate frame described by the STC-S description), or 2) a Region describing the STC AstrCoordsArea (i.e. an area or volume of interest within the coordinate frame described by the STC-S description), or 3) a KeyMap containing the uninterpreted property values read form the STC-S description, or 4) a KeyMap containing any combination of the first 3 options. The attributes StcsArea, StcsCoords and StcsProps control which of the above is returned by AST_READ.
When an STC-S description is created from an AST Object using AST_WRITE, the AST Object must be
either a Region or a KeyMap. If it is a Region, it is assumed to define the AstroCoordsArea or (if the
Region is a single point) the AstroCoords to write to the STC-S description. If the Object is a KeyMap,
it may contain an entry with the key "
AREA"
, holding a Region to be used to define the
AstroCoordsArea. It may also contain an entry with the key "
COORDS"
, holding a Region (a
PointList) to be used to create the AstroCoords. It may also contain an entry with key "
PROPS"
,
holding a KeyMap that contains uninterpreted property values to be used as defaults for any
STC-S properties that are not determined by the other supplied Regions. In addition, a
KeyMap supplied to AST_WRITE may itself hold the default STC-S properties (rather than
defaults being held in a secondary KeyMap, stored as the "
PROPS"
entry in the supplied
KeyMap).
The AST_READ and AST_WRITE functions work together so that any Object returned by AST_READ can immediately be re-written using AST_WRITE.
Normally, when you use an StcsChan, you should provide "
source"
and "
sink"
routines which
connect it to an external data store by reading and writing the resulting text. These routines should
perform any conversions needed between external character encodings and the internal ASCII
encoding. If no such routines are supplied, a Channel will read from standard input and write to
standard output.
Alternatively, an XmlChan can be told to read or write from specific text files using the SinkFile and SourceFile attributes, in which case no sink or source function need be supplied.
Support for STC-S is currently based on the IVOA document "
STC-S: Space-Time Coordinate (STC)
Metadata Linear String Implementation"
, version 1.30 (dated 5th December 2007), available at
http://www.ivoa.net/Documents/latest/STC-S.html. Note, this document is a recommednation only
and does not constitute an accepted IVOA standard.
The full text of version 1.30 is supported by the StcsChan class, with the following exceptions and provisos:
When reading an STC-S phrase, case is ignored except when reading units strings.
There is no support for multiple intervals specified within a TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval.
If the ET timescale is specified, TT is used instead.
If the TEB timescale is specified, TDB is used instead.
The LOCAL timescale is not supported.
The AST TimeFrame and SkyFrame classes do not currently allow a reference position to be specified. Consequently, any refpos specified within the Time or Space sub-phrase of an STC-S document is ignored.
The Convex identifier for the space sub-phrase is not supported.
The GEO_C and GEO_D space frames are not supported.
The UNITSPHERE and SPHER3 space flavours are not supported.
If any Error values are supplied in a space sub-phrase, then the number of values supplied should equal the number of spatial axes, and the values are assumed to specify an error box (i.e. error circles, ellipses, etc, are not supported).
The spectral and redshift sub-phrases do not support the following refpos values: LOCAL_GROUP_CENTER, UNKNOWNRefPos, EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO.
Error values are supported but error ranges are not.
Resolution, PixSize and Size values are ignored.
Space velocity sub-phrases are ignored.
StcsArea: Return the CoordinateArea component after reading an STC-S?
StcsCoords: Return the Coordinates component after reading an STC-S?
StcsLength: Controls output buffer length
StcsProps: Return the STC-S properties after reading an STC-S?