Space-Time Coordinate metadata schemata (2)

[Arnold Rots]

The Space-Time Coordinate metadata schemas are finally finished:

	http://hea-www.harvard.edu/~arots/nvometa/stc.xsd
	http://hea-www.harvard.edu/~arots/nvometa/coords.xsd
	http://hea-www.harvard.edu/~arots/nvometa/region.xsd

JD and MJD are now (arbitrary precision) decimals.
Explanation, with two examples, at:

	http://hea-www.harvard.edu/~arots/nvometa/SpaceTime.html

(now complete); some of it attached below.
documentation at:

	http://hea-www.harvard.edu/~arots/nvometa/stc.doc
	http://hea-www.harvard.edu/~arots/nvometa/stc.pdf

Don't try to print it - it's 181 pages; I will try to produce a
shorter version.
This does include the long-awaited region specification.

Enjoy!

  - Arnold

--------------------------------------------------------------------------
Arnold H. Rots                                Chandra X-ray Science Center
Smithsonian Astrophysical Observatory                tel:  +1 617 496 7701
60 Garden Street, MS 67                              fax:  +1 617 495 7356
Cambridge, MA 02138                             arots at head-cfa.harvard.edu
USA                                     http://hea-www.harvard.edu/~arots/
--------------------------------------------------------------------------


Space-Time Coordinate Specification for VO Metadata


1 Scope

The objective is to provide a metadata description of the volume in
space-time parameter space that is occupied by, available in, or
requested by: a data set of any kind, a resource, or a query.  The
"space" part of this parameter space includes spatial coordinates of
any kind: spherical coordinates, 2-D (e.g., detector coordinates) and
3-D Cartesian coordinates, one-dimensional coordinates.  Also included
are the time derivatives: velocities (space velocities and proper
motions) and redshifts/Doppler velocities.  The latter are treated
separately since they are derived quantities based on a formalism,
rather than physical velocities (i.e., the value depends on the
formalism, which is not applicable to true velocities).

What this means for an image, for instance, is that the metadata
describes very precisely and unambiguously what piece of space is
represented or occupied by the image.  However, a separate metadata
object is still needed to specify how that spatial volume is projected
onto a pixel array.  After careful consideration it was decided that
separating the information into two metadata objects (one that
specifies the space-time coordinates associated with the data and
another that specifies the projection onto a pixel array) is the
correct way to model the metadata in this area.

We strongly emphasize that space and time metadata need to be
encapsulated in a single metadata object.  Although it is true that
for the majority of the data that are moved around this is totally
unimportant (very few people besides historians will care when a
particular photograph of M81 was taken), there are a number of cases
where is is crucially important (e.g., high time resolution pulsar
observations).  We feel that the link needs to be enforced from the
outset; it will be very difficult to retrofit it later if it were
initially neglected.  In other words: we need to do this right.

Although the metadata model presented here is only applicable to
space-time coordinates, we would submit that it is also suitable for
application to other coordinates, in particular the
wavelength/frequency/energy coordinate.  This is true for the
coordinate attributes as well as the separation of the location and
projection objects.

The metadata structures are defined in the form of XML schemas:
stc.xsd, coords.xsd, region.xsd.


2 Overall design

There are three toplevel elements:

2.1 CoordSystem

Defines the spatial reference frame, allowing arbitrary,
custom-defined (such as on the surface of an asteroid) coordinate
frame, and includes reference (zero point) positions for space and for
time, as well as redshift/Doppler definitions, if applicable, and
information on the coordinates' "flavor": spherical, Cartesian, etc.

2.2 Coords

Any Coords element needs a reference to a CoordSys element.

2.2.1 Coords provides one or more of the following four coordinates:
2.2.1.1 Time
2.2.1.2 Spatial position
2.2.1.3 Velocity
2.2.1.4 Doppler velocity or redshift

The position and velocity coordinates may be scalar or vector of
length 2 or 3.

2.2.2 Each coordinate holds the following information:
2.2.2.1 Name (this might be a good place for a UCD)
2.2.2.2 Value
2.2.2.3 Error
2.2.2.4 Resolution
2.2.2.5 Size
2.2.2.6 Pixel size

In the case of vectors, the last four items may include position
angles or may be represented by matrices.
Each item includes its own "unit" attribute; this is necessary for
catalog applications.  Units are controlled types, separate for
position and time (hence velocities need both to constitute a velocity
unit).
Items may be specified as actual values (doubles) or as references to
other elements in the document; in particular, this allows referring
to a field (column) in the VOTable.
Alternatively, Coords may point to a FITS file that contains the
information, such as an orbit ephemeris file.

2.3 CoordArea
Specified by intervals in Time, Position, Velocity, and Redshift.
Intervals are specified by an lower and/or upper limit and attributes
indicating whether the limits are to be included.
The Position area has more options and may be specified as:
2.3.1 An interval with lower and/or upper bound
2.3.2 A circle or sphere, with center and radius
2.3.3 A FITS region file
2.3.4 A Region element
  This type of object will be described further below.


3 Application

Precise specification of a volume in space-time parameter space is
required in four contexts:

3.1 Resource
The specification of the spatial and temporal coverage of a
resource, with various associated attributes is achieved through:
3.1.1 CoordSys
3.1.2 CoordArea
  Specifies the coverage of the resource, with or without the use of
the attribute fill_factor.
3.2.3 CoordSpec, an element of type coordsType
  This element does not contain the coordinate values, but one or more
of the other coordinate items to indicate typical values for the data
in the resource, such as errors, resolution, and size ("Region of
Regard").

3.2 Query
The specification of a region of interest in a query, as well as
the space-time coordinate attributes desired for the requested data:
3.2.1 CoordSys
3.2.2 CoordArea
  Specifies the region of interest
3.2.3 CoordSpec, an element of type coordsType
  This element does not contain the coordinate values, but one or more
of the other coordinate items to indicate desired data parameters,
such as errors, resolution, and size ("Region of Regard").

3.3 Catalog data
The space-time coordinate information in returned catalog entry data:
3.3.1 CoordSys
3.3.2 Coords
  If a table is returned, these will typically be references to table
columns that comtain the actual values.
3.3.3 CoordArea (optional)
  The area covered by the catalog entries; important for completeness
considerations.

3.4 Observational data sets
The space-time metadata associated with data sets (observed or
theoretical, images or event lists, ...)
3.4.1 ObservatoryPosition
  This needs to be known, for instance for high-precision timing and
near-field (solar system) observations.
3.4.1.1 CoordSys
3.4.1.2 Coords
  Position of the observatory; may be an orbit ephemeris file.

3.4.2 ObservationPosition
3.4.2.1 CoordSys
3.4.2.2 Coords
3.4.2.3 CoordArea
  The Field or View.

3.5 Other applications

In addition, the space-time coordinate metadata objects are available
for use in related contexts:
- astronTimeType is an XML type that gives a proper description of any
astronomical time instance (though we would warn against careless use
of it without an associated coordinate system definition); allowed
formats are JD, MJD, ISO-8601 (but only the
yyyy-mm-ddThh:mm:ss.sss... part), and elapsed time (relative to a
specific time instance in JD, MJD, or ISO 8691)
- coordsType is an XML type that allows one to specify any space-time
coordinate position
- regionType is a very general definition of regions and allows
specifying spatial regions in a variety of context: sky coverage, bad
detector areas, source regions, background regions, etc.


4 Region

In keeping with the space-time coordinate metadata model, all regions
are defined in world coordinates, not in projected coordinates.
Simply put, a region consists of a shape or the result of an operation
performed on one or more regions.  There is a limited list of
enumerated shapes and operations.  A region may have a fill_factor
element (with a value between 0.0 and 1.0) indicating what proportion
of the region is actually filled (the meaning of which depends on the
context); the default is 1.0.

4.1 Shapes
Boundaries of shapes are considered to be part of the shapes.

4.1.1 Polygon
Specified by a list of vertices.  A vertex is specified by a
coordsType element and an optional small-circle element which has
meaning only for spherical coordinate systems.  The presence of the
smallCircle element indicates that the polygon side between this
vertex and its predecessor is to be a smallcircle, rather than the
default greatcircle.  Optionally, the pole of the smallcircle system
may be specified; if absent, the pole of the referenced CoordSys is
assumed.  Obviously, one has to take care that the two vertices
actually lie on the same smallcircle.  The last vertex in the list is
the predecessor of the first vertex.  The inside of the polygon is
circled counter-clockwise.  Polygons may be concave, but should not be
self-intersecting.

4.1.2 Circle
Specified by a center and a radius.

4.1.3 Ellipse
Although strictly speaking the circle is a special case of an ellipse,
we derive the ellipse from the circle by adding a semi minor axis and
a position angle element.

4.1.4 Sector
A sector between two half-lines, extending from a particular point, is
selected.  Specified by a position and two position angles.

4.1.5 Constraint (spherical coordinates only)
A plane is defined by a unit vector that is its normal and by the
distance (offset) between the origin and the intersection of the
normal and the plane (if negative: in the opposite direction of the
normal vector).  All points on the surface of the unit sphere that lie
beyond the intersection of that plane with the unit sphere in the
direction of the normal vector are selected. This means:
	offset > 1.0:	no intersection, resulting in an empty shape
	offset = 1.0:	tangent plane, resulting in a single point
	1.0 > offset > 0.0:	intersection a smallcircle, resulting
in less than a hemisphere
	offset = 0.0:	intersection a greatcircle, resulting
in a hemisphere
	0.0 > offset > -1.0:	intersection a smallcircle, resulting
in more than a hemisphere
	offset = -1.0:	tangent plane, resulting in the entire sphere
	offset < -1.0:	no intersection, resulting in the entire sphere

4.1.6 Convex
A convex polygon, or set of convex polygons, resulting from two or
more constraints.
Note that convexes and polygons can easily be converted into each
other, with the proviso that a set of constraints resulting in
multiple disconnected regions needs to be translated into a union of
multiple polygons, while a concave polygon needs to be translated into
a union of convexes.

4.1.7 Convex hull
Specified by a set of points, this is the smallest convex that will
include all those points.


4.2 Operations

This is, on purpose, a minimum but sufficient set of operations.
Additional operations (such as XOR or difference) may be constructed by combining any of these
three.

4.2.1 Negation
Unary operator.  All of space is selected, except the region that is
the operand.  The boundary is probably also excluded.  Logical NOT
operation.

4.2.2 Union
Operand: two or more regions.  All points that lie in one or more of
the operands are selected; logical OR operation.

4.2.3 Intersection
Operand: two or more regions.  Only points that lie in all of the
operands are selected; logical AND operation.  Here one has to be
careful about boundaries: two regions that only share a boundary
should probably have an empty intersection.


4.3 Desirable functions
Applications dealing with regions need tools to perform the following
operations on regions:

4.3.1 Logical operations:
  - is a point inside a region?
  - is a point outside a region?
  - is a region wholly contained in another region?
  - are two regions disjoint?
4.3.2 Information on a single region:
  - exterior extent: smallest (unrotated) rectangle/circle containing
    a region
  - interior extent: largest (unrotated) rectangle/circle fitting
    inside a region
  - the area of a region
4.3.3 Interface operations:
  - convert region to pixel mask
  - generate pixel list


5 Projection Object

As a placeholder, we can define the following projection element
type.  I think it contains the basic information but will undoubtedly
need to be extended.

        <xs:simpleType name="projectionType">
          <xs:restriction base="xs:string">
            <xs:enumeration value="TAN"/>
            <xs:enumeration value="SIN"/>
            <xs:enumeration value="STG"/>
            <xs:enumeration value="CAR"/>
          </xs:restriction>
        </xs:simpleType>
	<complexType name="coordProjectionType">
	  <sequence>
	    <element name="Projection" type="projectionType"/>
	    <element name="RefPos" type="IDREF"/>
	    <element name="RefPix" type="crd:doubleArrayType"/>
	    <choice>
	      <xs:element name="CoordPixsize" type="crd:coordValueType"/>
	      <xs:element name="CoordPixsize" type="crd:coord2SizeType"/>
	      <xs:element name="CoordPixsize" type="crd:coord3SizeType"/>
	    </choice>
	  </sequence>
	</complexType>