next up previous 264
Next: XmlLength - Controls output buffer length
Up: AST Attribute Descriptions
Previous: Width(element) - Line width for a Plot element


XmlFormat - System for formatting Objects as XML

Description:
This attribute specifies the formatting system to use when AST Objects are written out as XML through an XmlChan. It affects the behaviour of the astWrite function when they are used to transfer any AST Object to or from an external XML representation.

The XmlChan class allows AST objects to be represented in the form of XML in several ways (conventions) and the XmlFormat attribute is used to specify which of these should be used. The formatting options available are outlined in the "Formats Available" section below.

By default, an XmlChan will attempt to determine which format system is already in use, and will set the default XmlFormat value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical items which only occur in particular formats. For details of how this works, see the "Choice of Default Format" section below. If you wish to ensure that a particular format system is used, independently of any XML already read, you should set an explicit XmlFormat value yourself.

Type:
String.
Class Applicability:
XmlChan
All XmlChans have this attribute.
Formats Available
The XmlFormat attribute can take any of the following (case insensitive) string values to select the corresponding formatting system:

  • "NATIVE": This is a direct conversion to XML of the heirarchical format used by a standard XML channel (and also by the NATIVE encoding of a FitsChan).

  • "QUOTED": This is the same as NATIVE format except that extra information is included which allows client code to convert the XML into a form which can be read by a standard AST Channel. This extra information indicates which AST attribute values should be enclosed in quotes before being passed to a Channel.

  • "IVOA": This is a format that uses an early draft of the STC-X schema developed by the International Virtual Observatory Alliance (IVOA - see "http://www.ivoa.net/") to describe coordinate systems, regions, mappings, etc. Support is limited to V1.20 described at "http://www.ivoa.net/Documents/WD/STC/STC-20050225.html". Since the version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, this format is now mainly of historical interest. Note, the alternative "STC-S" format (a simpler non-XML encoding of the STC metadata) is supported by the StcsChan class.
Choice of Default Format;
If the XmlFormat attribute of an XmlChan is not set, the default value it takes is determined by the presence of certain critical items within the document most recently read using astRead. The sequence of decision used to arrive at the default value is as follows:

  • If the previous document read contained any elements in any of the STC namespaces ("urn:nvo-stc", "urn:nvo-coords" or "urn:nvo-region"), then the default value is IVOA.

  • If the previous document read contained any elements in the AST namespace which had an associated XML attribute called "quoted", then the default value is QUOTED.

  • Otherwise, if none of these conditions is met (as would be the case if no document had yet been read), then NATIVE format is used.

Setting an explicit value for the XmlFormat attribute always over-rides this default behaviour.
The IVOA Format
The IVOA support caters only for certain parts of V1.20 of the draft Space-Time Coordinate (STC) schema (see http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this draft has now been superceded by an officially adopted version that differs in several significant respects from V1.20. Consequently, the "IVOA" XmlChan format is of historical interest only.

The following points should be noted when using an XmlChan to read or write STC information (note, this list is currently incomplete):

  • Objects can currently only be read using this format, not written.

  • The AST object generated by reading an $<$STCMetadata$>$ element will be an instance of one of the AST "Stc" classes: StcResourceProfile, StcSearchLocation, StcCatalogEntryLocation, StcObsDataLocation.

  • When reading an $<$STCMetadata$>$ element, the axes in the returned AST Object will be in the order space, time, spectral, redshift, irrespective of the order in which the axes occur in the $<$STCMetadata$>$ element. If the supplied $<$STCMetadata$>$ element does not contain all of these axes, the returned AST Object will also omit them, but the ordering of those axes which are present will be as stated above. If the spatial frame represents a celestial coordinate system the spatial axes will be in the order (longitude, latitude).

  • Until such time as the AST TimeFrame is complete, a simple 1-dimensional Frame (with Domain set to TIME) will be used to represent the STC $<$TimeFrame$>$ element. Consequently, most of the information within a $<$TimeFrame$>$ element is currently ignored.

  • $<$SpaceFrame$>$ elements can only be read if they describe a celestial longitude and latitude axes supported by the AST SkyFrame class. The space axes will be returned in the order (longitude, latitude).

  • Velocities associated with SpaceFrames cannot be read.

  • Any $<$GenericCoordFrame$>$ elements within an $<$AstroCoordSystem$>$ element are currently ignored.

  • Any second or subsequent $<$AstroCoordSystem$>$ found within an STCMetaData element is ignored.

  • Any second or subsequent $<$AstroCoordArea$>$ found within an STCMetaData element is ignored.

  • Any $<$OffsetCenter$>$ found within a $<$SpaceFrame$>$ is ignored.

  • Any CoordFlavor element found within a $<$SpaceFrame$>$ is ignored.

  • $<$SpaceFrame$>$ elements can only be read if they refer to one of the following space reference frames: ICRS, GALACTIC_II, SUPER_GALACTIC, HEE, FK4, FK5, ECLIPTIC.

  • $<$SpaceFrame$>$ elements can only be read if the reference position is TOPOCENTER. Also, any planetary ephemeris is ignored.

  • Regions: there is currently no support for STC regions of type Sector, ConvexHull or SkyIndex.

  • The AST Region read from a CoordInterval element is considered to be open if either the lo_include or the hi_include attribute is set to false.

  • $<$RegionFile$>$ elements are not supported.

  • Vertices within $<$Polygon$>$ elements are always considered to be joined using great circles (that is, $<$SmallCircle$>$ elements are ignored).


next up previous 264
Next: XmlLength - Controls output buffer length
Up: AST Attribute Descriptions
Previous: Width(element) - Line width for a Plot element

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council