Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class ncsa.horizon.coordinates.CoordinateSystem

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

Subclasses:

LinearCoordinateSystem, SphLinCoordinateSystem

public class CoordinateSystem

extends java.util.Observable

implements java.lang.Cloneable, java.util.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.

Field Summary

Metadata	cmdata
static GenericAxisPosFormatter	defPosPrinter
int	gluedTrans
java.lang.String[]	labels
java.lang.String[]	modlabs
Metadata	modmdata
static MessageCenter	msgs A bus for routing user messages.
java.lang.String[]	natlabs
int	naxes
int	nnataxes
java.util.Stack	transdirs
java.util.Stack	transforms
java.util.Stack	transmaps
boolean	usingTransforms

Constructor Summary

CoordinateSystem(int naxes, Metadata md)
Construct a CoordinateSystem object

CoordinateSystem(int naxes)
Construct a CoordinateSystem object

CoordinateSystem(Metadata md)
Construct a CoordinateSystem object

CoordinateSystem()
Construct a CoordinateSystem object with 2 default axes

CoordinateSystem(int naxes, Metadata md, CoordTransform trans, CoordTransformConstraints constraints)
Construct a CoordinateSystem using the specified transforms

CoordinateSystem(int naxes, Metadata md, java.util.Vector trans, java.util.Vector constraints)
Construct a CoordinateSystem using the specified transforms

Method Summary

void	attachTransform(CoordTransform t, CoordTransformConstraints c) attach a coordinate transform to this system with
void	attachTransform(CoordTransform t, boolean attachForwards) attach a coordinate transform to this system
void	attachTransform(CoordTransform t) attach a coordinate transform to this system
java.lang.Object	clone() clone this object
static CoordinateSystem	createSystem(Metadata cmd) return a best-guess coordinate system given a set of metadata
CoordTransformConstraints	determineConstraints(CoordTransform in) make an educated guess as to the proper way to apply a transform to this coordinate system.
CoordTransformConstraints	determineConstraints(CoordTransform in, boolean forwards) make an educated guess as to the proper way to apply a transform to this coordinate system.
java.lang.String	getAxisLabel(int axis) return the currently set label for an axis
java.lang.String[]	getAxisLabel() return the axis labels as an array of strings.
CoordPos	getCoordPos(Voxel vox) return the coordinate position corresponding the specified data voxel
CoordPos	getCoordPos(double[] vox) return the coordinate position corresponding the specified data voxel
double[]	getCoordValue(double[] vox) return the coordinate position corresponding to the specified data voxel.
double[]	getDataLocation(double[] pos) return the location within the dataset corresponding to the specified coordinate position
static int	getErrSlot() return the slot number where error messages from this package are sent.
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.
Metadata	getMetadata(boolean withTransforms) return a copy of the Metadata object that will describes this this system
int	getNaxes() return the number of axes in the space containing this position
int	getNTransforms() return the number of removeable transforms attached to this CoordinateSystem.
Voxel	getVoxel(CoordPos pos) return the location within the dataset corresponding to the specified coordinate position
Voxel	getVoxel(double[] pos) return the location within the dataset corresponding to the specified coordinate position
void	glueTransforms(boolean updateMetadata) permanently attach any removable transforms currently attached, making them non-removable.
boolean	isUsingTransforms() return true attached CoordTransform objects are being used
CoordinateSystem	newCoordinateSystem() return a CoordinateSystem that is a clone of this one except with the CoordTransform objects permanently attached
java.util.Stack	popAllTransforms() remove and return all removable CoordTransform objects currently attached to this CoordinateSystem.
CoordTransform	popTransform() remove and return the last CoordTransform object attached to this CoordinateSystem, or null if no transforms are currently attached
void	removeAllTransforms() remove all removable CoordTransform object currently attached to this CoordinateSystem.
void	setAxisLabel(java.lang.String[] labs) set the axis labels.
void	setAxisLabel(int i, java.lang.String lab) set an axis label.
static void	setErrSlot(int slot) set the slot number were error messages from this package should be sent.
void	setUsingTransforms(boolean yes) turn on or off the use of attached CoordTransform objects.
static void	suppressErrorMessages() prevent error messages from this package from reaching the console
void	update(java.util.Observable o, java.lang.Object arg)
void	updateModifiedMetadata() updates the modified metadata list.
static void	warn(java.lang.String msg) print a warning message.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notifyAll, notify, toString, wait, wait, wait

Field Detail

naxes

protected int naxes

nnataxes

protected int nnataxes

usingTransforms

protected boolean usingTransforms

cmdata

protected Metadata cmdata

modmdata

protected Metadata modmdata

labels

protected java.lang.String[] labels

natlabs

protected java.lang.String[] natlabs

modlabs

protected java.lang.String[] modlabs

defPosPrinter

protected static GenericAxisPosFormatter defPosPrinter

transforms

protected java.util.Stack transforms

transmaps

protected java.util.Stack transmaps

transdirs

protected java.util.Stack transdirs

gluedTrans

protected int gluedTrans

msgs

public static MessageCenter msgs

A bus for routing user messages. By default, error and output messages will be routed to the console. This can be altered either through MessageCenter methods on this bus or by setting the field to a new MessageCenter or null.

This bus is used by classes in this package (and its subpackages) to send error and warning messages to the user. The slot used by this package is returned by the getErrSlot() method.

See Also:

MessageCenter, Horizon

Constructor Detail

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 java.lang.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:

java.lang.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,
                        java.util.Vector trans,
                        java.util.Vector constraints)
                 throws java.lang.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:

java.lang.IllegalArgumentException - thrown if either the trans or constraints Stack has an empty member or member of the wrong type.

Method Detail

getNaxes

public int getNaxes()

return the number of axes in the space containing this position

attachTransform

public void attachTransform(CoordTransform t,
                            CoordTransformConstraints c)
                    throws java.lang.IllegalArgumentException,
                           java.lang.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 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 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 CoordTransform popTransform()

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

popAllTransforms

public java.util.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 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 void updateModifiedMetadata()

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

setUsingTransforms

public 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 java.lang.String getAxisLabel(int axis)
                             throws java.lang.ArrayIndexOutOfBoundsException

return the currently set label for an axis

Parameters:

axis - the axis of interest; axes are numbered beginning with 0.

getAxisLabel

public java.lang.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(java.lang.String[] labs)

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

setAxisLabel

public void setAxisLabel(int i,
                         java.lang.String lab)
                 throws java.lang.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 java.lang.Object clone()

clone this object

Overrides:

clone in class java.lang.Object

update

public void update(java.util.Observable o,
                   java.lang.Object arg)

Description copied from interface:

Specified by:

update(java.util.Observable, java.lang.Object) in interface java.util.Observer

createSystem

public static CoordinateSystem createSystem(Metadata cmd)
                                                             throws IllegalTransformException

return a best-guess coordinate system given a set of metadata

Parameters:

cmd - the metadata describing the system

getErrSlot

public static int getErrSlot()

return the slot number where error messages from this package are sent.

setErrSlot

public static void setErrSlot(int slot)

set the slot number were error messages from this package should be sent. Error messages will no longer be sent to the console unless that slot is already configured to do so.

suppressErrorMessages

public static void suppressErrorMessages()

prevent error messages from this package from reaching the console

warn

public static void warn(java.lang.String msg)

print a warning message. By default, this message appears on the console via the static MessageCenter, msgs. No message is printed if msgs is null or if suppressErrorMessages() has been called.