    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.

##

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.
CAN_INTERPOLATE
  this flag indicates that interpolation is desired, if possible, when this volume is applied to a data set; otherwise, use nearest values.
firstAxisIndex
flags
  flags that indicate how this volume can be used; objects operating with this volume, may choose to ignore this value.
loc
naxes
NONE
  null flags value
sample
size

##

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.
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.
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
Volume(Volume)
  create a Volume object that is a copy of another Volume.
Volume(Volume, int)
  create a Volume object that is a copy of another Volume but with the specified index for the first axis.
Volume(Voxel)
  create a Volume object of unit size (and unit sampling) whose origin vertex is located at the given voxel.
Volume(Voxel, int)
  create a Volume object of unit size (and unit sampling) whose origin vertex is located at the given voxel.

##

add(Volume)
  increase the size of this volume just enough to include the projection of another Volume into this space
add(Voxel)
  increase the size of this volume just enough to include the projection of a Voxel into this space
axisPos(int)
  get the location of the Volume's origin vertex along one axis.
clone()
  create a deep copy of this object
equals(Volume)
  return true if another Volume (in principle) samples the same data as this Volume.
getFirstAxisIndex()
  return the index of the first axis (as defined during this object's construction).
getLength(int)
  return the length of a requested side
getLocation()
  return an array of doubles representing the location of the volume's reference vertex.
getLocation(int)
  return an array of doubles representing the location of the volume's reference vertex.
getNaxes()
  return the number of dimensions in the space containing this Volume
getSampling()
  return an array of doubles representing the size of the box along each side.
getSampling(int)
  get the current sampling along each side of the volume
getSize()
  return an array of doubles representing the size of the box along each side.
getSize(int)
  return an array of doubles representing the size of the box along each side.
getStep(int)
  get the sampling for a given side
getTrueLength(int)
  return the true length of a requested side
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.
getTrueSize(int)
  return an array of ints representing the true size of the volume by accounting for the current sampling
getVoxel()
  get the location of volume's reference vertex represented as a Voxel object.
grow(Voxel)
  increase the size of each side by the projected distance of a Voxel from its origin along each corresponding axis.
includes(Volume)
  return true if this volume encloses another volume.
includes(Voxel)
  return true if this volume includes a voxel.
intersection(Volume)
  compute the intersection of this volume with another.
intersects(Volume)
  return true if this volume intersects another volume.
main(String[])
  run this class as an application to test it
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.
setAxisPos(int, double)
  get the location of the Volume's origin vertex along one axis.
setLength(int, double)
  set the length of a side of the volume
setLocation(double[])
  set the location of the volume's vertex closest to the origin.
setLocation(double[], int)
  set the location of the volume's vertex closest to the origin
setLocation(Voxel)
  set the location of the volume's vertex closest to the origin.
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.
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.
setSampling(int, double)
  set the sampling along a side of the volume
setSize(double[])
  set the length of each side of the volume.
setSize(double[], int)
  set the length of each side of the volume
translate(Voxel)
  move this Volume to a relative position
union(Volume)
  compute the union of this volume with another.

##

naxes

      protected int naxes

firstAxisIndex

      protected int firstAxisIndex

loc

      protected double loc[]

size

      protected double size[]

sample

      protected double sample[]

flags

      public int flags

  flags that indicate how this volume can be used; objects operating with this volume, may choose to ignore this value.

NONE

      public final static int NONE

  null flags value

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.

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.

##

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

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

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

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

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

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.

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

##

getNaxes

      public int getNaxes()

  return the number of dimensions in the space containing this Volume

getFirstAxisIndex

      public int getFirstAxisIndex()

  return the index of the first axis (as defined during this object's construction).

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;

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.

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.

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

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

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;

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.

getLength

      public double getLength(int i) throws ArrayIndexOutOfBoundsException

  return the length of a requested side

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;

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.

getTrueLength

      public int getTrueLength(int i) throws ArrayIndexOutOfBoundsException

  return the true length of a requested side

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

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

setLocation

      public void setLocation(Voxel vox)

  set the location of the volume's vertex closest to the origin.

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

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

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

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

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

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

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;

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.

getStep

      public double getStep(int i) throws ArrayIndexOutOfBoundsException

  get the sampling for a given side

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

clone

      public Object clone()

  create a deep copy of this object
  Overrides:
    clone in class Object

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.

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.

intersects

      public boolean intersects(Volume vol)

  return true if this volume intersects another volume. Missing dimensions of over either volume will be considered overlapping

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.

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.

add

      public void add(Voxel vox)

  increase the size of this volume just enough to include the projection of a Voxel into this space

add

      public void add(Volume vol)

  increase the size of this volume just enough to include the projection of another Volume into this space

union

      public Volume union(Volume that)

  compute the union of this volume with another. The dimensionality and sampling will be that of this volume.

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.

equals

      public boolean equals(Volume vol)

  return true if another Volume (in principle) samples the same data as this Volume.

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