    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.

##

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

##

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

##

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

##

naxes

      protected int naxes

nnataxes

      protected int nnataxes

usingTransforms

      protected boolean usingTransforms

cmdata

      protected Metadata cmdata

modmdata

      protected Metadata modmdata

labels

      protected String labels[]

natlabs

      protected String natlabs[]

modlabs

      protected String modlabs[]

defPosPrinter

      protected static GenericAxisPosFormatter defPosPrinter

transforms

      protected Stack transforms

transmaps

      protected Stack transmaps

transdirs

      protected Stack transdirs

gluedTrans

      protected int gluedTrans

##

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

CoordinateSystem

      public CoordinateSystem(int naxes)

  Construct a CoordinateSystem object
  Parameters:
    naxes - the number of axes in this system

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

CoordinateSystem

      public CoordinateSystem()

  Construct a CoordinateSystem object with 2 default axes

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.

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.

##

getNaxes

      public int getNaxes()

  return the number of axes in the space containing this position

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

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

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

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.

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

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

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.

popTransform

      public synchronized CoordTransform popTransform()

  remove and return the last CoordTransform object attached to this CoordinateSystem, or null if no transforms are currently attached

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.

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.)

isUsingTransforms

      public boolean isUsingTransforms()

  return true attached CoordTransform objects are being used

updateModifiedMetadata

      protected synchronized void updateModifiedMetadata()

  updates the modified metadata list. This should be called anytime a transform is added or removed

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

newCoordinateSystem

      public CoordinateSystem newCoordinateSystem()

  return a CoordinateSystem that is a clone of this one except with the CoordTransform objects permanently attached

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.

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

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.

getAxisLabel

      public String[] getAxisLabel()

  return the axis labels as an array of strings. The index of the label for the first axis is zero.

setAxisLabel

      public void setAxisLabel(String labs[])

  set the axis labels. Extra labels in the input array are ignored.

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.

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

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

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

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.

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.

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.

clone

      public synchronized Object clone()

  clone this object
  Overrides:
    clone in class Object

update

      public void update(Observable o,
                         Object arg)

    All Packages  Class Hierarchy  This Package  Previous  Next  Index