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

java.lang.Object
  |
  +--ncsa.horizon.coordinates.CoordPos
public class CoordPos
extends java.lang.Object
implements java.lang.Cloneable
support for accessing a representation (string or double) of a position in a coordinate system.

A CoordPos object represents a position in a coordinate space. Such an object is often returned by CoordinateSystem object methods and can be handed back to a Coordinate object for conversion to a data voxel location. One of the most useful features of the CoordPos object is that is knows how to format itself as a string. Code to print out parts of the CoordPos's value might look something like this: 

    CoordPos wcspos;
    ...
    wcspos = wcs.getCoordPos(datapos);
    System.out.println( wcspos.getAxisLabel(0) +   // print position
                        ": " +                     //  along 1st axis
                        wcspos.valueString(0) );     
    System.out.println( wcspos.getAxisLabel(1) +   // print position
                        ": " +                     //  along 2nd axis
                        wcspos.valueString(1) );
which might produce something the following: 
    RA: 12:45:39.11
    Dec: -30:17:20.2
Note that axes are numbered beginning with 0. Position values as doubles can be both retrieved and set.

Coordinate Metadata

A CoordPos can also carry along with it information about the coordinate system within which it exists, stored as a Metadata object. In general, the values within the Metadata list are not actually used by the CoordPos itself (with the exception of two constructors, CoordPos(Metadata) and CoordPos(Metadata, double[])). For this reason, CoordPos allows you to directly manipulate its own copy of its Metadata list. That is, one can make updates to the list directly and have the changes stick with the CoordPos object without a call to setMetadata(); e.g: 

    CoordPos wcspos;
    ...
    wcspos.getMetadata().put("name", "Celestial-Velocity");

See Metadata for more information about accesssing and setting metadata. See also CoordMetadata for information about recognized coordinate metadata names.

Field Summary
static AxisPosFormatter defPosPrinter
           
java.lang.String[] labels
           
int naxes
           
double[] pos
           
AxisPosFormatter[] posPrinter
           
Metadata romdata
           
Metadata wrmdata
           
 
Constructor Summary
CoordPos(int naxes)
          Construct a default coordinate position in a system with a specified number of axes.
CoordPos(CoordPos that, double[] position, boolean selfish)
          Construct a coordinate postion that is a copy of another position apart from the actual position data.
CoordPos(int naxes, Metadata md)
          Construct a default coordinate position in a system with a specified number of axes.
CoordPos(int naxes, double[] position, Metadata md)
          Construct a default coordinate position in a system with a specified number of axes and an initial position.
CoordPos(Metadata md)
          Construct a default coordinate position in a system with a specified number of axes.
CoordPos(Metadata md, double[] position)
          Construct a default coordinate position in a system with a specified number of axes.
CoordPos(int naxes, double[] position, java.lang.String[] labels, AxisPosFormatter[] formatters, Metadata md)
          Construct a CoordPos object, specifying all of its internal data.
CoordPos(int naxes, double[] position, double defpos, java.lang.String[] labels, java.lang.String deflab, AxisPosFormatter[] formatters, AxisPosFormatter deffmtr, Metadata md)
          Construct a CoordPos object, specifying all of its internal data.
 
Method Summary
java.lang.Object clone()
          clone this object.
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.
AxisPosFormatter getFormatter(int i)
          get a copy of the formatter used to display the coordinate position along a given axis
AxisPosFormatter[] getFormatters()
          get copies of the formatters used to display this coordinate position
Metadata getMetadata()
          return a Metadata object that identifies the coordinate system within which this coordinate position exists.
int getNaxes()
          return the number of axes in this coordinate system
double getValue(int axis)
          return a double containing the position's projection along an axis
double[] getValue()
          return an array of doubles representing the position along each axis
void setAxisLabel(java.lang.String[] labs)
          set the axis labels.
void setAxisLabel(int i, java.lang.String lab)
          set an axis label.
void setMetadata(Metadata md)
          set the Metadata object that identifies the coordinate system within which this coordinate position exists.
void setValue(int axis, double newval)
          set the position's projection along an axis to a value
void setValue(double[] newpos)
          set the position along all axes with the values given in the input array, returning the old values;
java.lang.String valueString(int axis)
          return a formatted string containing the position's projection along an axis
java.lang.String valueString(int axis, int prec)
          Deprecated. return a formatted string containing the position's projection along an axis
java.lang.String valueString(int axis, AxisPosFormatter formatter)
          return a formatted string containing the position's projection along an axis using the given formatter.
java.lang.String[] valueStrings()
          return an array of formatted strings containing the position's projection along each axis
java.lang.String[] valueStrings(int prec)
          Deprecated. return an array of formatted strings containing the position's projection along each axis
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notifyAll, notify, toString, wait, wait, wait
 

Field Detail

naxes

protected int naxes

labels

protected java.lang.String[] labels

pos

protected double[] pos

posPrinter

protected AxisPosFormatter[] posPrinter

defPosPrinter

protected static AxisPosFormatter defPosPrinter

romdata

protected Metadata romdata

wrmdata

protected Metadata wrmdata
Constructor Detail

CoordPos

public CoordPos(int naxes)
Construct a default coordinate position in a system with a specified number of axes.
Parameters:
naxes - the number of axes in the coordinate system

CoordPos

public CoordPos(CoordPos that,
                double[] position,
                boolean selfish)
Construct a coordinate postion that is a copy of another position apart from the actual position data. This is usually fastest way to create a CoordPos object.
Parameters:
that - the template coordinate position
position - the new position
selfish - if true, clone the new position array; otherwise, use it as a reference and trust that we will keep control of its values.

CoordPos

public CoordPos(int naxes,
                Metadata md)
Construct a default coordinate position in a system with a specified number of axes. Note that the value of naxes overrides any value that might appear in the Metadata list.
Parameters:
naxes - the number of axes in the coordinate system
md - the Metadata describing the coordinate system within which this position exists. Can be null.

CoordPos

public CoordPos(int naxes,
                double[] position,
                Metadata md)
Construct a default coordinate position in a system with a specified number of axes and an initial position. Note that the value of naxes overrides any value that might appear in the Metadata list.
Parameters:
naxes - the number of axes in the coordinate system
position - a representation of the coordinate position as a double array. Can be null.
md - the Metadata describing the coordinate system within which this position exists. Can be null.

CoordPos

public CoordPos(Metadata md)
         throws CorruptedMetadataException
Construct a default coordinate position in a system with a specified number of axes. The number of axes, the labels, and the formatters are all obtained from the specified Metadata list.
Parameters:
md - the Metadata describing the coordinate system within which this position exists. Can be null.
Throws:
CorruptedMetadataException - if the "naxes" metadatum is not found in md or is of an illegal value

CoordPos

public CoordPos(Metadata md,
                double[] position)
         throws CorruptedMetadataException
Construct a default coordinate position in a system with a specified number of axes. The number of axes, the labels, and the formatters are all obtained from the specified Metadata list.
Parameters:
md - the Metadata describing the coordinate system within which this position exists. Can be null.
position - a representation of the coordinate position as a double array. Can be null.
Throws:
CorruptedMetadataException - if the "naxes" metadatum is not found in md or is of an illegal value

CoordPos

public CoordPos(int naxes,
                double[] position,
                java.lang.String[] labels,
                AxisPosFormatter[] formatters,
                Metadata md)
         throws java.lang.IllegalArgumentException
Construct a CoordPos object, specifying all of its internal data. Any metadata of unexpected types are ignored.
Parameters:
naxes - the number of axes in the coordinate system
position - a representation of the coordinate position as a double array. Can be null.
labels - the labels to use for identifying each of the axes. If a label is missing (or is null), then the value of the "Axis[n].label" metadatum is used; failing that, "Axis[n].name" is used followed by the string "Pixels".
formatters - the formatting objects to use when printing a position along each coordinate axis. If a formatter is missing (or is null), then the value of the "Axis[n].formatter" is used; failing that, a GenericAxisPosFormatter object is used.
md - the Metadata describing the coordinate system within which this position exists. Can be null.
Throws:
java.lang.IllegalArgumentException - if naxes <= 0

CoordPos

public CoordPos(int naxes,
                double[] position,
                double defpos,
                java.lang.String[] labels,
                java.lang.String deflab,
                AxisPosFormatter[] formatters,
                AxisPosFormatter deffmtr,
                Metadata md)
         throws java.lang.IllegalArgumentException
Construct a CoordPos object, specifying all of its internal data. Note that appropriate values for the formatters and labels found in the Metadata object overrides the default given in this constructor. Any metadata of unexpected types are ignored.
Parameters:
naxes - the number of axes in the coordinate system
position - a representation of the coordinate position as a double array. Can be null.
defpos - a default value to use for elements that are missing from position (i.e. elements with indices < naxes but >= position.length).
labels - the labels to use for identifying each of the axes. If a label is missing (or is null), then the value of the "Axis[n].label" metadatum is used; failing that, "Axis[n].name" is used followed by the value of deflab.
deflab - the default label to use if nothing better can be found. If null, "Pixels" is used
formatters - the formatting objects to use when printing a position along each coordinate axis. If a formatter is missing (or is null), then the value of the "Axis[n].formatter" is used; failing that, deffmtr is used.
deffmtr - the default label to use if nothing better can be found. If null, a GenericAxisPosFormatter object is used.
md - the Metadata describing the coordinate system within which this position exists. Can be null.
Throws:
java.lang.IllegalArgumentException - if naxes <= 0
Method Detail

getNaxes

public int getNaxes()
return the number of axes in this coordinate system

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.

getFormatters

public AxisPosFormatter[] getFormatters()
get copies of the formatters used to display this coordinate position

getFormatter

public AxisPosFormatter getFormatter(int i)
get a copy of the formatter used to display the coordinate position along a given axis

getMetadata

public Metadata getMetadata()
return a Metadata object that identifies the coordinate system within which this coordinate position exists.
Returns:
Metadata an editable Metadata object (not a copy), or null if one is not available. Updates made to the returned Metadata's contents will be carried along with this CoordPos object even without calls to setMetadata().

setMetadata

public void setMetadata(Metadata md)
set the Metadata object that identifies the coordinate system within which this coordinate position exists.

getValue

public double getValue(int axis)
               throws java.lang.ArrayIndexOutOfBoundsException
return a double containing the position's projection along an axis
Parameters:
axis - the axis of interest; axes are numbered beginning with 0.

setValue

public void setValue(int axis,
                     double newval)
             throws java.lang.ArrayIndexOutOfBoundsException
set the position's projection along an axis to a value
Parameters:
axis - the axis of interest; axes are numbered beginning with 0.
newval - the new value
Returns:
the old value

getValue

public double[] getValue()
return an array of doubles representing the position along each axis

setValue

public void setValue(double[] newpos)
set the position along all axes with the values given in the input array, returning the old values;

valueString

public java.lang.String valueString(int axis)
                            throws java.lang.ArrayIndexOutOfBoundsException
return a formatted string containing the position's projection along an axis
Parameters:
axis - the axis of interest; axes are numbered beginning with 0.

valueString

public java.lang.String valueString(int axis,
                          int prec)
                            throws java.lang.ArrayIndexOutOfBoundsException
Deprecated. Note that this method is deprecated in favor of valueString(int, AxisPosFormatter). This implimentation may cause the default precision to be updated.
return a formatted string containing the position's projection along an axis
Parameters:
axis - the axis of interest; axes are numbered beginning with 0.
prec - the precision of the string; the interpretation of the as depends on the AxisPosFormatter object in use for the requested axis.

valueString

public java.lang.String valueString(int axis,
                          AxisPosFormatter formatter)
                            throws java.lang.ArrayIndexOutOfBoundsException
return a formatted string containing the position's projection along an axis using the given formatter. (Note: Unlike the deprecated valueString(int, int) method, this method will not update this position's internal state.
Parameters:
axis - the axis of interest; axes are numbered beginning with 0.
formatter - the formatting object to use

valueStrings

public java.lang.String[] valueStrings()
                               throws java.lang.ArrayIndexOutOfBoundsException
return an array of formatted strings containing the position's projection along each axis

valueStrings

public java.lang.String[] valueStrings(int prec)
                               throws java.lang.ArrayIndexOutOfBoundsException
Deprecated. Note that this method is deprecated in favor of valueString(int, AxisPosFormatter). This implimentation may cause the default precision to be updated.
return an array of formatted strings containing the position's projection along each axis
Parameters:
prec - the precision of the string; the interpretation of the as depends on the AxisPosFormatter object in use for the requested axis.

clone

public java.lang.Object clone()
clone this object.
Overrides:
clone in class java.lang.Object
Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS FRAMES  | NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD