#### Description:

A StcsChan is a specialised form of Channel which supports STC-S I/O operations. Writing an Object to an StcsChan (using astWrite) will, if the Object is suitable, generate an STC-S description of that Object, and reading from an StcsChan will create a new Object from its STC-S description.

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.

#### Constructor Function

astStcsChan

#### Inheritance

The StcsChan class inherits from the Channel class.

#### Attributes

In addition to those attributes common to all Channels, every StcsChan also has the following attributes:

- 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?

#### Functions

The StcsChan class does not define any new functions beyond those which are applicable to all Channels.
Copyright (C) 2021 East Asian Observatory