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:
AST A Library for Handling World Coordinate Systems in Astronomy