Class ncsa.horizon.coordinates.CoordinateSystem
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ncsa.horizon.coordinates.CoordinateSystem

java.lang.Object
   |
   +----java.util.Observable
           |
           +----ncsa.horizon.coordinates.CoordinateSystem

public class CoordinateSystem
extends Observable
implements Cloneable, Observer
a description of a world coordinate system and the mapping between it and a multidimensional gridded dataset.

General Description

A CoordinateSystem object can be given a data voxel location and return a position in its world coordinate space in the form of a CoordPos object. The code might look something like this:

   CoordinateSystem wcs;
   CoordPos wcspos;
   ...
   double datapos[] = { 0, 0, 0 };     // a position in the dataset
   wcspos = wcs.getCoordPos(datapos);  // the position in coordinate space
   System.out.println( wcspos.getAxisLabel(0) +     // print position
                       ": " +                       //  along 1st axis
                       wcspos.getValueString(0) );     
   System.out.println( wcspos.getAxisLabel(1) +     // print position
                       ": " +                       //  along 2nd axis
                       wcspos.getValueString(1) );     
which might produce something the following:
   RA: 12:45:39.11
   Dec: -30:17:20.2
The getDataLocation() and getVoxel() do the opposite transform of getCoordPos(), translating a coordinate positions into voxel locations in the dataset.

A CoordinateSystem object can automatically convert positions to other coordinate systems by attaching one or more CoordTransform objects to it with attachTransform(); all subsequent calls to getCoordPos will produce positions in the new coordinate system.

Constructing a CoordinateSystem Usually, an application programmer would not need to explicitly construct CoordinateSystem objects; instead, such an object can be obtained by the Viewable method, getCoordinateSystem() which is all set up appropriately for the Viewable dataset.


Variable Index

 o cmdata
 o defPosPrinter
 o gluedTrans
 o labels
 o modlabs
 o modmdata
 o natlabs
 o naxes
 o nnataxes
 o transdirs
 o transforms
 o transmaps
 o usingTransforms

Constructor Index

 o CoordinateSystem()
Construct a CoordinateSystem object with 2 default axes
 o CoordinateSystem(int)
Construct a CoordinateSystem object
 o CoordinateSystem(int, Metadata)
Construct a CoordinateSystem object
 o CoordinateSystem(int, Metadata, CoordTransform, CoordTransformConstraints)
Construct a CoordinateSystem using the specified transforms
 o CoordinateSystem(int, Metadata, Vector, Vector)
Construct a CoordinateSystem using the specified transforms
 o CoordinateSystem(Metadata)
Construct a CoordinateSystem object

Method Index

 o attachTransform(CoordTransform)
attach a coordinate transform to this system
 o attachTransform(CoordTransform, boolean)
attach a coordinate transform to this system
 o attachTransform(CoordTransform, CoordTransformConstraints)
attach a coordinate transform to this system with
 o clone()
clone this object
 o determineConstraints(CoordTransform)
make an educated guess as to the proper way to apply a transform to this coordinate system.
 o determineConstraints(CoordTransform, boolean)
make an educated guess as to the proper way to apply a transform to this coordinate system.
 o getAxisLabel()
return the axis labels as an array of strings.
 o getAxisLabel(int)
return the currently set label for an axis
 o getCoordPos(double[])
return the coordinate position corresponding the specified data voxel
 o getCoordPos(Voxel)
return the coordinate position corresponding the specified data voxel
 o getCoordValue(double[])
return the coordinate position corresponding to the specified data voxel.
 o getDataLocation(double[])
return the location within the dataset corresponding to the specified coordinate position
 o getMetadata()
return a copy of the Metadata object that will describes this this system, accounting for any CoordTransform objects that may be attached and in use.
 o getMetadata(boolean)
return a copy of the Metadata object that will describes this this system
 o getNaxes()
return the number of axes in the space containing this position
 o getNTransforms()
return the number of removeable transforms attached to this CoordinateSystem.
 o getVoxel(CoordPos)
return the location within the dataset corresponding to the specified coordinate position
 o getVoxel(double[])
return the location within the dataset corresponding to the specified coordinate position
 o glueTransforms(boolean)
permanently attach any removable transforms currently attached, making them non-removable.
 o isUsingTransforms()
return true attached CoordTransform objects are being used
 o newCoordinateSystem()
return a CoordinateSystem that is a clone of this one except with the CoordTransform objects permanently attached
 o popAllTransforms()
remove and return all removable CoordTransform objects currently attached to this CoordinateSystem.
 o popTransform()
remove and return the last CoordTransform object attached to this CoordinateSystem, or null if no transforms are currently attached
 o removeAllTransforms()
remove all removable CoordTransform object currently attached to this CoordinateSystem.
 o setAxisLabel(int, String)
set an axis label.
 o setAxisLabel(String[])
set the axis labels.
 o setUsingTransforms(boolean)
turn on or off the use of attached CoordTransform objects.
 o update(Observable, Object)
 o updateModifiedMetadata()
updates the modified metadata list.

Variables

 o naxes
  protected int naxes
 o nnataxes
  protected int nnataxes
 o usingTransforms
  protected boolean usingTransforms
 o cmdata
  protected Metadata cmdata
 o modmdata
  protected Metadata modmdata
 o labels
  protected String labels[]
 o natlabs
  protected String natlabs[]
 o modlabs
  protected String modlabs[]
 o defPosPrinter
  protected static GenericAxisPosFormatter defPosPrinter
 o transforms
  protected Stack transforms
 o transmaps
  protected Stack transmaps
 o transdirs
  protected Stack transdirs
 o gluedTrans
  protected int gluedTrans

Constructors

 o CoordinateSystem
  public CoordinateSystem(int naxes,
                          Metadata md)
Construct a CoordinateSystem object
Parameters:
naxes - the number of axes in this system
md - the metadata that describes this system; note that no transforms are defined based on values stored in this list
 o CoordinateSystem
  public CoordinateSystem(int naxes)
Construct a CoordinateSystem object
Parameters:
naxes - the number of axes in this system
 o CoordinateSystem
  public CoordinateSystem(Metadata md)
Construct a CoordinateSystem object
Parameters:
md - the metadata that describes this system; note that no transforms are defined based on values stored in this list
 o CoordinateSystem
  public CoordinateSystem()
Construct a CoordinateSystem object with 2 default axes
 o CoordinateSystem
  public CoordinateSystem(int naxes,
                          Metadata md,
                          CoordTransform trans,
                          CoordTransformConstraints constraints) throws IllegalArgumentException
Construct a CoordinateSystem using the specified transforms
Parameters:
naxes - the number of axes
md - the metadata describing this system (after any default transforms are applied)
trans - the CoordTransform objects to apply by default, or null if none should be applied. The transforms should appear in this Vector in the order that they should be applied. The Vector should not contain any empty elements.
constraints - the CoordTransformConstraints with which the trans list should be applied, or null if trans=null. The size of this Vector should be equal to the size of trans and also should not contain any empty elements.
Throws: IllegalArgumentException
thrown if either the trans or constraints Stack has an empty member or member of the wrong type.
 o CoordinateSystem
  public CoordinateSystem(int naxes,
                          Metadata md,
                          Vector trans,
                          Vector constraints) throws IllegalArgumentException
Construct a CoordinateSystem using the specified transforms
Parameters:
naxes - the number of axes
md - the metadata describing this system (after any default transforms are applied)
trans - a CoordTransform object to apply by default, or null if none should be applied.
constraints - the CoordTransformConstraints with which the transform should be applied, or null if trans=null.
Throws: IllegalArgumentException
thrown if either the trans or constraints Stack has an empty member or member of the wrong type.

Methods

 o getNaxes
  public int getNaxes()
return the number of axes in the space containing this position
 o attachTransform
  public synchronized void attachTransform(CoordTransform t,
                                           CoordTransformConstraints c) throws IllegalArgumentException, NullPointerException
attach a coordinate transform to this system with
Parameters:
t - the transform to be atached
c - the constraints by which to attach the transform
 o attachTransform
  public synchronized void attachTransform(CoordTransform t,
                                           boolean attachForwards) throws IllegalTransformException
attach a coordinate transform to this system
Parameters:
t - the transform to be atached
attachForwards - if true, the reverse transform should be attached
Throws: IllegalTransformException
if transform cannot be implicitly attached in the direction requested
 o attachTransform
  public synchronized void attachTransform(CoordTransform t) throws IllegalTransformException
attach a coordinate transform to this system
Parameters:
t - the transform to be atached
Throws: IllegalTransformException
if transform cannot be implicitly attached in the forward direction
 o glueTransforms
  protected void glueTransforms(boolean updateMetadata)
permanently attach any removable transforms currently attached, making them non-removable.
Parameters:
updateMetadata - true if the default metadata should be updated accordingly, or false if the currently set default metadata should remain unchanged.
 o determineConstraints
  public CoordTransformConstraints determineConstraints(CoordTransform in)
make an educated guess as to the proper way to apply a transform to this coordinate system. Note that there may exist a number of ways that this transform might be logically applied to this system.
Parameters:
in - the Metadata describing the system to be transformed
Returns:
CoordTransformConstraints the resulting guess, null if the transform cannot be logically applied
 o determineConstraints
  public CoordTransformConstraints determineConstraints(CoordTransform in,
                                                        boolean forwards)
make an educated guess as to the proper way to apply a transform to this coordinate system. Note that there may exist a number of ways that this transform might be logically applied to this system.
Parameters:
in - the Metadata describing the system to be transformed
forwards - if false, the constraints determined should be for attaching the reverse of the transform
Returns:
CoordTransformConstraints the resulting guess, null if the transform cannot be logically applied
 o getNTransforms
  public int getNTransforms()
return the number of removeable transforms attached to this CoordinateSystem. A non-zero result does not indicate whether they are being used.
 o popTransform
  public synchronized CoordTransform popTransform()
remove and return the last CoordTransform object attached to this CoordinateSystem, or null if no transforms are currently attached
 o popAllTransforms
  public synchronized Stack popAllTransforms()
remove and return all removable CoordTransform objects currently attached to this CoordinateSystem.
Returns:
Stack a list of the CoordTransform object, beginning with the first one that was attached and ending with the last one.
 o removeAllTransforms
  public synchronized void removeAllTransforms()
remove all removable CoordTransform object currently attached to this CoordinateSystem. (If no other objects have references to the transform objects, the Garbage collector will recover their memory.)
 o isUsingTransforms
  public boolean isUsingTransforms()
return true attached CoordTransform objects are being used
 o updateModifiedMetadata
  protected synchronized void updateModifiedMetadata()
updates the modified metadata list. This should be called anytime a transform is added or removed
 o setUsingTransforms
  public synchronized void setUsingTransforms(boolean yes)
turn on or off the use of attached CoordTransform objects. By default, the value is of this property is true.
Parameters:
yes - true if the transforms should be used
 o newCoordinateSystem
  public CoordinateSystem newCoordinateSystem()
return a CoordinateSystem that is a clone of this one except with the CoordTransform objects permanently attached
 o getMetadata
  public Metadata getMetadata()
return a copy of the Metadata object that will describes this this system, accounting for any CoordTransform objects that may be attached and in use.
 o getMetadata
  public Metadata getMetadata(boolean withTransforms)
return a copy of the Metadata object that will describes this this system
Parameters:
withTransforms - true the Metadata returned should account for any CoordTransform objects that may be attached and in use; false, if they should be ignored
 o getAxisLabel
  public String getAxisLabel(int axis) throws ArrayIndexOutOfBoundsException
return the currently set label for an axis
Parameters:
axis - the axis of interest; axes are numbered beginning with 0.
 o getAxisLabel
  public String[] getAxisLabel()
return the axis labels as an array of strings. The index of the label for the first axis is zero.
 o setAxisLabel
  public void setAxisLabel(String labs[])
set the axis labels. Extra labels in the input array are ignored.
 o setAxisLabel
  public void setAxisLabel(int i,
                           String lab) throws ArrayIndexOutOfBoundsException
set an axis label. This method will not affect the contents of the Metadata object returned by the getMetadata() method.
 o getCoordPos
  public CoordPos getCoordPos(Voxel vox) throws PositionBeyondDomainException, TransformUndefinedException
return the coordinate position corresponding the specified data voxel
Parameters:
vox - the location in the dataset expressed as a Voxel. The position along missing axes are taken to be zero; extra axes are ignored.
Returns:
CoordPos the position in world coordinates
 o getCoordPos
  public CoordPos getCoordPos(double vox[]) throws PositionBeyondDomainException, TransformUndefinedException
return the coordinate position corresponding the specified data voxel
Parameters:
vox - the location in the dataset expressed as an array of doubles, with each element being the location along each axis. Missing elements are taken to be zero; extra elements are ignored.
Returns:
CoordPos the position in world coordinates
 o getCoordValue
  public double[] getCoordValue(double vox[]) throws PositionBeyondDomainException, TransformUndefinedException
return the coordinate position corresponding to the specified data voxel.
Parameters:
vox - the location in the dataset expressed as a Voxel. The position along missing axes are taken to be zero; extra axes are ignored.
double[] - the position in world coordinates, where each element in the array is a representation of the location along an axis as a double
 o getVoxel
  public Voxel getVoxel(CoordPos pos) throws PositionBeyondDomainException, TransformUndefinedException
return the location within the dataset corresponding to the specified coordinate position
Parameters:
pos - the position in world coordinates. No checking is done to ensure that this position can exist within this coordinate system (say, via a check of its metadata). Values for missing axes are taken to be zero; extra axes are ignored.
Returns:
Voxel the location in the dataset.
 o getVoxel
  public Voxel getVoxel(double pos[]) throws PositionBeyondDomainException, TransformUndefinedException
return the location within the dataset corresponding to the specified coordinate position
Parameters:
pos - the position in world coordinates, expressed as an array of doubles where each element is a representation of the location along an axis Missing axes are taken to be zero; extra axes are ignored.
Returns:
Voxel the location in the dataset.
 o getDataLocation
  public double[] getDataLocation(double pos[]) throws PositionBeyondDomainException, TransformUndefinedException
return the location within the dataset corresponding to the specified coordinate position
Parameters:
pos - the position in world coordinates, expressed as an array of doubles where each element is a representation of the location along an axis Missing axes are taken to be zero; extra axes are ignored.
Returns:
double[] the location in the dataset, where each element is a location in the dataset along each axis.
 o clone
  public synchronized Object clone()
clone this object
Overrides:
clone in class Object
 o update
  public void update(Observable o,
                     Object arg)

All Packages  Class Hierarchy  This Package  Previous  Next  Index