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: Example Coordinate Systems Up: Coordinate System Metadata Previous: Using Metadata to Construct