I/O Channel using STC-S to represent Objects StcsChan
When an STC-S description is read using astRead, 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 astRead.
When an STC-S description is created from an AST Object using astWrite, 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 astWrite 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 astRead and astWrite functions work together so that any Object returned by astRead can immediately be re-written using astWrite.
Normally, when you use an StcsChan, you should provide "
source"
and "
sink"
functions which connect it to an external data store by reading and writing the
resulting text. These functions should perform any conversions needed between
external character encodings and the internal ASCII encoding. If no such functions
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?