next up previous contents
Next: Example Coordinate Systems Up: Coordinate System Metadata Previous: Using Metadata to Construct

The Horizon Schema for Coordinate Systems

 

The Horizon package provides several special implementations of the CoordinateSystem class to support some common coordinate systems encountered in scientific data. These systems can be parameterized using metadata defined by the Horizon schema. While the Horizon schema is fully described in Appendix A.2, this section describes the basic concepts behind the schema and gives some examples of its use.

The most commonly used coordinate system metadatum is ``naxes'', an Integer used to indicate the number of axes in the space described by the coordinate system. Each axis then will require a set of metadata to describe the parameters for that axis. To do this, one uses the ``Axes'' metadatum, which is of type Metavector whose elements are of type Metadata, containing the parameters for each axis. The Horizon schema defines a set of metadata that can be used to set these parameters.

As of this writing, all of the specialized versions of the CoordinateSystem class use a scheme of describing coordinate systems based on reference voxels (indicated by the axis metadatum ``axisSchema'' equal to ``referenced''). In this scheme, one specifies the coordinate position of one specific reference voxel; all other coordinate positions are referenced to this voxel via some assumed function. The function for a specific axis need not be linear nor independent of other axes. Table 3.1.2 lists the metadata used to describe a referenced axis definition.

  
Table 2: Axis Metadata Defined by the Horizon Schema

One axis metadatum that deserves more explanation is ``formatter''. The type of this metadatum, AxisPosFormatter, is a Horizon-defined interface that can convert a double value representing a position along a coordinate system axis to a specially formatted String
[0] (and back again, if necessary). Table 3.1.2 lists some of the formatters currently supported by Horizon. Normally, one does not need to explicitly call any methods of an AxisPosFormatter implementation; this is usually done transparently by the CoordPos class via its getValueString method.

  
Table 3: Sample Axis Formatting Classes

To aid in the management of coordinate system metadata, the Horizon package provides a subclass of Metadata called ncsa.horizon.coordinates.CoordMetadata. This class provides special methods for loading ``referenced'' coordinate system metadata. Not only does it make loading the data easier, it helps ensure that the data is loaded with the proper types. First consider a simple example in which we want to set the value of ``naxes'', the number of axes in our system, with the value of 2. Here's one way we could do it:

    Metadata cmdata = new Metadata();
    cmdata.put("naxes", new Integer(2));
The CoordMetadata class offers a safer alternative:
    CoordMetadata cmdata = new CoordMetadata();
    cmdata.setNaxes(2);
The setNaxes() method guarantees at compile-time that the ``naxes'' metadatum is save with type Integer.

Now consider a more complex example in which our data reader has produced the following parameters for a simple linear, referenced coordinate system:

    // Number of axes
    int naxes = 3;

    // Names for the axes
    String[] names = { "East-West", "North-South", "Altitude" };

    // Reference position in degrees
    double[] refval = { 0.0, 0.0, 0.0 };

    // Reference voxel: the voxel whose position is the reference position.  
    double[] refpos = { 115.0, 289.0, 0.0 };

    // Voxel size in absolute degrees
    double[] voxelsize = { -0.25, 0.25, 10.0 };
One can load this data into a Metadata object via the following:
    CoordMetadata cmdata = new CoordMetadata(naxes);

    for(int i=0, i < 3; i++) {
        cmdata.setAxisType(i, "linear");
        cmdata.setAxisName(i, names[i]);
        cmdata.setAxisRefposition(i, refpos[i]);
        cmdata.setAxisRefvalue(i, refval[i]);
        cmdata.setAxisStepsize(i, voxelsize[i]);
    }
This procedure loads all the data with the proper names and types in accordance with the ``horizon'' schema and the ``referenced'' axis schema. And the constructor actually does more than set ``naxes'' to 3; it also automatically sets ``schema'' to ``horizon'' and ``axisSchema'' to ``referenced'' for each of the axes. The subsequent set methods set the values as sub-metadata of the ``Axes'' metadatum. To illustrate this, consider how we might recall these values from the CoordMetadata object:
    Integer nax = (Integer) cmdata.getMetadatum("naxes");  // equals 3
    String class0 = (String) 
        cmdata.getMetadatum("Axes[0].axisSchema");   // equals "referenced"
    Double refp1 = (Double)
        cmdata.getMetadatum("Axes[1].refposition");  // equals 289.0


next up previous contents
Next: Example Coordinate Systems Up: Coordinate System Metadata Previous: Using Metadata to Construct

Ray Plante
Mon Aug 25 15:16:12 CDT 1997