Next: Coordinate System Metadata Up: Supporting Metadata and Coordinate Previous: On-Demand Data Loading: The

# The World Coordinate System Classes

The `ncsa.horizon.coordinates` package provides the basic support for world coordinate systems. Central to this package is the `CoordinateSystem` class whose basic purpose is to transform positions in a dataset into positions in world coordinate space and back again. An application usually obtains the `CoordinateSystem` associated with a particular dataset via the `Viewable` method `getCoordSys`. The application can then pass voxels to the `CoordinateSystem` and get out positions in world coordinate space, as illustrated in this example:

    Viewable dataset;
    ...
    CoordinateSystem coordSys = dataset.getCoordSys();

    // position in dataset, one element for each axis in the dataset
    double datapos[] = { 0, 0, 0 };

    // get back position in coordinate system
    CoordPos cpos = coordSys.getCoordPos(datapos);

    // print out positions for the first two axes
    System.out.println( cpos.getAxisLabel(0) + ": " + cpos.getValueString(0) );
    System.out.println( cpos.getAxisLabel(1) + ": " + cpos.getValueString(1) );

This might produce something like the following:

    RA: 12:45:39.11
    Dec: -30:17:20.2

The `CoordPos` stores its coordinate system position internally as an array of doubbles; however, as one can see, the `CoordPos` in this example knows the proper way to turn the position into strings for display.

The Horizon `SelectionViewer` class allows one to request selected voxels which are returned as `Voxel` objects. These `Voxel`s can in turn be passed to the `getCoordPos` method:

    SelectionViewer  viewer;
    ...
    Voxel vox = viewer.getSelectedVoxel();
    CoordPos cpos = coordSys.getCoordPos(vox);

The `getVoxelVal(CoordPos)` and `getVoxel(CoordPos)` do the opposite transform of
[4] `getCoordPos()`, translating a coordinate position into a voxel location in the dataset and returning a `double[]` array and a `Voxel`, respectively.

Converting data positions to coordinate system positions, as in the above example (and perhaps back again) is the extent to which many applications will need to interact with the `CoordinateSystem`. The `Viewable` interface hides the details reading and interpretation of the data and its metadata from the user, returning `CoordinateSystem` with all the information it needs to determine and display coordinate positions. A good example (§4.1) of the use of coordinate systems at this level is the `PosTrackerViewer`, a `Viewer` displays the coordinate positions in an image pointed to by the mouse cursor, tracking the positions as the mouse is moved around the image display. If one plans to implement a `Viewable` interface or otherwise construct `CoordinateSystem` objects, one needs to know a little more about coordinate system metadata and how they are used to instantiate `CoordinateSystem` objects.

- Coordinate System Metadata
  - Using Metadata to Construct CoordinateSystems
  - The Horizon Schema for Coordinate Systems
- Example Coordinate Systems
  - `CoordinateSystem`: the Simplest System
  - `LinearCoordinateSystem`: a System With Linear Axes
  - `LinSphCoordinateSystem`: Combining Spherical and Linear Coordinates
- Converting Between Multiple Coordinate Systems
  - Basic Use
  - Use Outside of a `CoordinateSystem`
  - Implementing New `CoordTransform` Classes
    - `getInAxes(), getOutAxes()`
    - `determineConstraints(Metadata in, boolean forwards)`
    - `init(CoordinateSystem csys, boolean forward, int[] axisIndexList)`
    - `getMetadata(Metadata in, boolean forward, int[] axisIndices)`
- Implementing a New Coordinate System

Next: Coordinate System Metadata Up: Supporting Metadata and Coordinate Previous: On-Demand Data Loading: The