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