Class ncsa.horizon.util.Volume
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ncsa.horizon.util.Volume

java.lang.Object
   |
   +----ncsa.horizon.util.Volume

public class Volume
extends Object
implements Cloneable
an object that represents a (hyper-) box enclosure of regularly gridded points in a space of an arbitrary number of dimensions. The enclosure is described in terms of the location of one of its vertices (the origin vertex), a length along each side of the box, and the sampling of points along each side.

This object is intended to provide a way of describing a subset of data that exists in a multidimensional space (e.g. a multidimensional data array). The concept of regularly gridded data is supported through an internally stored sampling rate which is equal to one by default. The origin and voxel size need not correspond to how the data it is applied to is stored; more often, they would reflect the units used to measure locations in the space represented by the data. Data retrieval routines would determine how this Volume should be applied to extract or operate on the data.

The axes of the space are referred to through an index which, by default, begins with zero; however, the index that refers to the first axis can be set when the Volume object is created using the appropriate constructor.

It is important to note that the lengths of sides of the volume can be set to negative values. This merely means that the voxel that indicates the volumes position is not the voxel closest to the origin of the space. Note that if "increasing" a negative-valued length by providing a positive value via add() will actually decrease the length. Similarly, the sampling rate can be negative as well, which means that the sampling should start from a vertex other than the one closest to the origin of the space. This confusion can all be straightened out with the makeLengthsPositive() method, which rearranges the description of the volume so that lengths and sampling are both positive, but the same data is sampled.

See also Voxel, Slice, and Segment.


Variable Index

 o CAN_EXTRAPOLATE
this flag indicates that interpolation is desired, if possible, when this volume is applied to a data set; otherwise, use only the intersection of this volume with the dataset domain.
 o CAN_INTERPOLATE
this flag indicates that interpolation is desired, if possible, when this volume is applied to a data set; otherwise, use nearest values.
 o firstAxisIndex
 o flags
flags that indicate how this volume can be used; objects operating with this volume, may choose to ignore this value.
 o loc
 o naxes
 o NONE
null flags value
 o sample
 o size

Constructor Index

 o Volume(int)
create a Volume object in a space of nax dimensions and initialize it to have a unit size with a sampling of 1 along each axis.
 o Volume(int, double[], double[], double[])
create a Volume object in a space of nax dimensions and initialize it to a given location, size, and sampling for each axis.
 o Volume(int, int)
create a Volume object in a space of nax dimensions and initialize it to have a size of 1 with a sampling of 1 along each axis
 o Volume(Volume)
create a Volume object that is a copy of another Volume.
 o Volume(Volume, int)
create a Volume object that is a copy of another Volume but with the specified index for the first axis.
 o Volume(Voxel)
create a Volume object of unit size (and unit sampling) whose origin vertex is located at the given voxel.
 o Volume(Voxel, int)
create a Volume object of unit size (and unit sampling) whose origin vertex is located at the given voxel.

Method Index

 o add(Volume)
increase the size of this volume just enough to include the projection of another Volume into this space
 o add(Voxel)
increase the size of this volume just enough to include the projection of a Voxel into this space
 o axisPos(int)
get the location of the Volume's origin vertex along one axis.
 o clone()
create a deep copy of this object
 o equals(Volume)
return true if another Volume (in principle) samples the same data as this Volume.
 o getFirstAxisIndex()
return the index of the first axis (as defined during this object's construction).
 o getLength(int)
return the length of a requested side
 o getLocation()
return an array of doubles representing the location of the volume's reference vertex.
 o getLocation(int)
return an array of doubles representing the location of the volume's reference vertex.
 o getNaxes()
return the number of dimensions in the space containing this Volume
 o getSampling()
return an array of doubles representing the size of the box along each side.
 o getSampling(int)
get the current sampling along each side of the volume
 o getSize()
return an array of doubles representing the size of the box along each side.
 o getSize(int)
return an array of doubles representing the size of the box along each side.
 o getStep(int)
get the sampling for a given side
 o getTrueLength(int)
return the true length of a requested side
 o getTrueSize()
return an array of ints representing the true size of the volume by accounting for the current sampling The first value will appear at the first axis index used when this object was constructed, unless that index is < 0, in which case the first value will appear at index 0.
 o getTrueSize(int)
return an array of ints representing the true size of the volume by accounting for the current sampling
 o getVoxel()
get the location of volume's reference vertex represented as a Voxel object.
 o grow(Voxel)
increase the size of each side by the projected distance of a Voxel from its origin along each corresponding axis.
 o includes(Volume)
return true if this volume encloses another volume.
 o includes(Voxel)
return true if this volume includes a voxel.
 o intersection(Volume)
compute the intersection of this volume with another.
 o intersects(Volume)
return true if this volume intersects another volume.
 o main(String[])
run this class as an application to test it
 o makeLengthsPositive()
adjust the description of this volume so that the lengths and sampling of each side are positive but without changing the actual enclosed volume.
 o setAxisPos(int, double)
get the location of the Volume's origin vertex along one axis.
 o setLength(int, double)
set the length of a side of the volume
 o setLocation(double[])
set the location of the volume's vertex closest to the origin.
 o setLocation(double[], int)
set the location of the volume's vertex closest to the origin
 o setLocation(Voxel)
set the location of the volume's vertex closest to the origin.
 o setSampling(double[])
set the volume sampling: each value in the input array represents the sampling of the volume along each axis; thus, the volume includes the first voxel and every value-th voxel along each axis.
 o setSampling(double[], int)
set the volume sampling: each value in the input array represents the sampling of the volume along each axis; thus, the volume includes the first voxel and every value-th voxel along each axis.
 o setSampling(int, double)
set the sampling along a side of the volume
 o setSize(double[])
set the length of each side of the volume.
 o setSize(double[], int)
set the length of each side of the volume
 o translate(Voxel)
move this Volume to a relative position
 o union(Volume)
compute the union of this volume with another.

Variables

 o naxes
  protected int naxes
 o firstAxisIndex
  protected int firstAxisIndex
 o loc
  protected double loc[]
 o size
  protected double size[]
 o sample
  protected double sample[]
 o flags
  public int flags
flags that indicate how this volume can be used; objects operating with this volume, may choose to ignore this value.
 o NONE
  public final static int NONE
null flags value
 o CAN_INTERPOLATE
  public final static int CAN_INTERPOLATE
this flag indicates that interpolation is desired, if possible, when this volume is applied to a data set; otherwise, use nearest values.
 o CAN_EXTRAPOLATE
  public final static int CAN_EXTRAPOLATE
this flag indicates that interpolation is desired, if possible, when this volume is applied to a data set; otherwise, use only the intersection of this volume with the dataset domain.

Constructors

 o Volume
  public Volume(int nax) throws ArrayIndexOutOfBoundsException
create a Volume object in a space of nax dimensions and initialize it to have a unit size with a sampling of 1 along each axis. The index of the first axis will be zero.
Parameters:
nax - number of axes or dimensions in the space
Throws: ArrayIndexOutOfBoundsException
thrown if nax < 0
 o Volume
  public Volume(int nax,
                int firstAxisIndex) throws ArrayIndexOutOfBoundsException
create a Volume object in a space of nax dimensions and initialize it to have a size of 1 with a sampling of 1 along each axis
Parameters:
nax - number of axes or dimensions in the space
firstAxisIndex - index of the first axis (can be <, =, or > 0)
Throws: ArrayIndexOutOfBoundsException
thrown if nax < 0
 o Volume
  public Volume(int nax,
                double loc[],
                double sz[],
                double sam[]) throws ArrayIndexOutOfBoundsException
create a Volume object in a space of nax dimensions and initialize it to a given location, size, and sampling for each axis. The index of the first axis will be zero. Input arrays can be null to get default.
Parameters:
nax - number of axes or dimensions in the space
loc - location of volume vertex (default: origin)
sz - length of each side (default: one)
sam - sampling along each side (default: one)
Throws: ArrayIndexOutOfBoundsException
thrown if nax < 0
 o Volume
  public Volume(Volume in)
create a Volume object that is a copy of another Volume. The index of the new Volume will be that of the input Volume
 o Volume
  public Volume(Volume in,
                int firstAxisIndex)
create a Volume object that is a copy of another Volume but with the specified index for the first axis.
Parameters:
in - the input Volume
firstAxisIndex - the index to be given to the first Axis in the new Volume
 o Volume
  public Volume(Voxel in)
create a Volume object of unit size (and unit sampling) whose origin vertex is located at the given voxel. The index of the new Volume will be that of the input Volume.
 o Volume
  public Volume(Voxel in,
                int firstAxisIndex)
create a Volume object of unit size (and unit sampling) whose origin vertex is located at the given voxel.
Parameters:
in - the input Voxel
firstAxisIndex - the index to be given to the first Axis in the new Volume

Methods

 o getNaxes
  public int getNaxes()
return the number of dimensions in the space containing this Volume
 o getFirstAxisIndex
  public int getFirstAxisIndex()
return the index of the first axis (as defined during this object's construction).
 o getLocation
  public double[] getLocation(int firstaxis) throws ArrayIndexOutOfBoundsException
return an array of doubles representing the location of the volume's reference vertex.
Parameters:
firstaxis - the desired index of the first axis in the output array
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0;
 o getLocation
  public double[] getLocation()
return an array of doubles representing the location of the volume's reference vertex. The first value will appear at the first axis index used when this object was constructed, unless that index is < 0, in which case the first value will appear at index 0.
 o getVoxel
  public Voxel getVoxel()
get the location of volume's reference vertex represented as a Voxel object. The output voxel will have the same index for the first axis as this object.
 o axisPos
  public double axisPos(int i) throws ArrayIndexOutOfBoundsException
get the location of the Volume's origin vertex along one axis.
Parameters:
int - axis index of desired axis (using the numbering convention established when object was constructed.)
 o setAxisPos
  public void setAxisPos(int i,
                         double pos) throws ArrayIndexOutOfBoundsException
get the location of the Volume's origin vertex along one axis.
Parameters:
i - axis index of desired axis (using the numbering convention established when object was constructed.)
pos - position along the desired axis
 o getSize
  public double[] getSize(int firstaxis) throws ArrayIndexOutOfBoundsException
return an array of doubles representing the size of the box along each side.
Parameters:
firstaxis - the desired index of the first axis in the output array
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0;
 o getSize
  public double[] getSize()
return an array of doubles representing the size of the box along each side. The first value will appear at the first axis index used when this object was constructed, unless that index is < 0, in which case the first value will appear at index 0.
 o getLength
  public double getLength(int i) throws ArrayIndexOutOfBoundsException
return the length of a requested side
 o getTrueSize
  public int[] getTrueSize(int firstaxis) throws ArrayIndexOutOfBoundsException
return an array of ints representing the true size of the volume by accounting for the current sampling
Parameters:
firstaxis - the desired index of the first axis in the output array
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0;
 o getTrueSize
  public int[] getTrueSize()
return an array of ints representing the true size of the volume by accounting for the current sampling The first value will appear at the first axis index used when this object was constructed, unless that index is < 0, in which case the first value will appear at index 0.
 o getTrueLength
  public int getTrueLength(int i) throws ArrayIndexOutOfBoundsException
return the true length of a requested side
 o setLocation
  public void setLocation(double newpos[],
                          int firstaxis) throws ArrayIndexOutOfBoundsException
set the location of the volume's vertex closest to the origin
Parameters:
newpos - array of doubles containing position values
firstaxis - index at which first value appears in newpos
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0
 o setLocation
  public void setLocation(double newpos[])
set the location of the volume's vertex closest to the origin. The first value will be assumed to be at the first index axis defined when this object was constructed, unless that index is < 0, in which case, the first value will be assumed to be at 0.
Parameters:
newpos - array of doubles containing position values
 o setLocation
  public void setLocation(Voxel vox)
set the location of the volume's vertex closest to the origin.
 o setSize
  public void setSize(double newsz[],
                      int firstaxis) throws ArrayIndexOutOfBoundsException
set the length of each side of the volume
Parameters:
newsz - array of doubles containing position values
firstaxis - index at which first value appears in newpos
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0
 o setSize
  public void setSize(double newsz[])
set the length of each side of the volume. The first value will be assumed to be at the first index axis defined when this object was constructed, unless that index is < 0, in which case, the first value will be assumed to be at 0.
Parameters:
newsz - array of doubles containing position values
 o setLength
  public void setLength(int i,
                        double sz) throws ArrayIndexOutOfBoundsException
set the length of a side of the volume
Parameters:
i - the index of the axis to be set
sz - the length to set the side to
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0
 o setSampling
  public void setSampling(double newsam[],
                          int firstaxis) throws ArrayIndexOutOfBoundsException
set the volume sampling: each value in the input array represents the sampling of the volume along each axis; thus, the volume includes the first voxel and every value-th voxel along each axis.
Parameters:
newsam - array of doubles containing the sampling values
firstaxis - index at which first value appears in newpos
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0
 o setSampling
  public void setSampling(double newsz[])
set the volume sampling: each value in the input array represents the sampling of the volume along each axis; thus, the volume includes the first voxel and every value-th voxel along each axis. The first value will be assumed to be at the first index axis defined when this object was constructed, unless that index is < 0, in which case, the first value will be assumed to be at 0.
Parameters:
newsz - array of doubles containing position values
 o setSampling
  public void setSampling(int i,
                          double sam) throws ArrayIndexOutOfBoundsException
set the sampling along a side of the volume
Parameters:
i - the index of the axis to be set
sam - the sampling to set the side to
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0
 o getSampling
  public double[] getSampling(int firstaxis) throws ArrayIndexOutOfBoundsException
get the current sampling along each side of the volume
Parameters:
firstaxis - the desired index of the first axis in the output array
Throws: ArrayIndexOutOfBoundsException
if firstaxis < 0;
 o getSampling
  public double[] getSampling()
return an array of doubles representing the size of the box along each side. The first value will appear at the first axis index used when this object was constructed, unless that index is < 0, in which case the first value will appear at index 0.
 o getStep
  public double getStep(int i) throws ArrayIndexOutOfBoundsException
get the sampling for a given side
 o makeLengthsPositive
  public boolean makeLengthsPositive()
adjust the description of this volume so that the lengths and sampling of each side are positive but without changing the actual enclosed volume. The location voxel will be moved to the vertex that is closest to the origin of the space containing this volume.
Returns:
boolean true if a transformation was applied
 o clone
  public Object clone()
create a deep copy of this object
Overrides:
clone in class Object
 o includes
  public boolean includes(Voxel vox)
return true if this volume includes a voxel. The voxel will not be considered included if the number of dimensions in its space is greater than that of this volume.
 o includes
  public boolean includes(Volume vol)
return true if this volume encloses another volume. The given voxel will not be considered included if the number of dimensions in its space is greater than that of this volume.
 o intersects
  public boolean intersects(Volume vol)
return true if this volume intersects another volume. Missing dimensions of over either volume will be considered overlapping
 o translate
  public void translate(Voxel vox)
move this Volume to a relative position
Parameters:
vox - the relative position to add to this volume's position; only dimensions that overlap this space will be added.
 o grow
  public void grow(Voxel vox)
increase the size of each side by the projected distance of a Voxel from its origin along each corresponding axis.
 o add
  public void add(Voxel vox)
increase the size of this volume just enough to include the projection of a Voxel into this space
 o add
  public void add(Volume vol)
increase the size of this volume just enough to include the projection of another Volume into this space
 o union
  public Volume union(Volume that)
compute the union of this volume with another. The dimensionality and sampling will be that of this volume.
 o intersection
  public Volume intersection(Volume vol)
compute the intersection of this volume with another. The dimensionality, the sampling, and the sign of the size will be that of this volume. If the two volumes do not actually overlap the result will be the smallest volume that connects the two vertices that are closest.
 o equals
  public boolean equals(Volume vol)
return true if another Volume (in principle) samples the same data as this Volume.
 o main
  public static void main(String args[])
run this class as an application to test it
Parameters:
args - components of a vector

All Packages  Class Hierarchy  This Package  Previous  Next  Index