BALL::TRegularData3D< ValueType > Class Template Reference
[Generic Datastructures for Regularly Spaced Data]

#include <BALL/DATATYPE/regularData3D.h>


Classes
struct	BlockValueType
	The block data type for reading and writing binary data. More...
class	IndexType
	The index type used to refer to a specific element in the grid (x-, y-, and z-index). More...
Public Types
typedef ValueType	value_type
typedef std::vector< ValueType > ::iterator	iterator
typedef std::vector< ValueType > ::const_iterator	const_iterator
typedef std::vector< ValueType > ::reference	reference
typedef std::vector< ValueType > ::const_reference	const_reference
typedef std::vector< ValueType > ::pointer	pointer
typedef std::vector< ValueType > ::difference_type	difference_type
typedef std::vector< ValueType > ::size_type	size_type
Type Definitions
typedef std::vector< ValueType >	VectorType
	The type containing an STL vector of the appropriate type.
typedef TVector3< float >	CoordinateType
	The coordinate type.
typedef std::vector< ValueType > ::iterator	Iterator
	A mutable iterator.
typedef std::vector< ValueType > ::const_iterator	ConstIterator
	A nonmutable iterator.
Public Member Functions
Constructors and Destructors
	TRegularData3D ()
	TRegularData3D (const TRegularData3D< ValueType > &grid) throw (Exception::OutOfMemory)
	TRegularData3D (const CoordinateType &origin, const CoordinateType &dimension, const CoordinateType &spacing) throw (Exception::OutOfMemory)
	TRegularData3D (const CoordinateType &origin, const CoordinateType &x_axis, const CoordinateType &y_axis, const CoordinateType &z_axis, const IndexType &size) throw (Exception::OutOfMemory)
	TRegularData3D (const IndexType &size, const CoordinateType &origin=CoordinateType(0.0), const CoordinateType &dimension=CoordinateType(1.0)) throw (Exception::OutOfMemory)
virtual	~TRegularData3D ()
virtual void	clear ()
Assignment
TRegularData3D &	operator= (const TRegularData3D< ValueType > &data) throw (Exception::OutOfMemory)
Predicates
bool	operator== (const TRegularData3D< ValueType > &grid) const
BALL_INLINE bool	operator!= (const TRegularData3D< ValueType > &grid) const
BALL_INLINE bool	empty () const
	Empty predicate.
bool	isInside (const CoordinateType &r) const
	Test if a given point is inside the grid.
Iterators
BALL_INLINE ConstIterator	begin () const
BALL_INLINE ConstIterator	end () const
BALL_INLINE Iterator	begin ()
BALL_INLINE Iterator	end ()
Accessors
BALL_INLINE size_type	size () const
BALL_INLINE size_type	max_size () const
BALL_INLINE void	swap (TRegularData3D< ValueType > &grid)
const vector< ValueType > &	getData () const
	Get the full data.
const ValueType &	getData (const IndexType &index) const throw (Exception::OutOfGrid)
ValueType &	getData (const IndexType &index) throw (Exception::OutOfGrid)
const ValueType &	getData (Position index) const throw (Exception::OutOfGrid)
ValueType &	getData (Position index) throw (Exception::OutOfGrid)
const ValueType &	operator[] (const IndexType &index) const
ValueType &	operator[] (const IndexType &index)
const ValueType &	operator[] (Position index) const
ValueType &	operator[] (Position index)
ValueType	operator() (const CoordinateType &x) const
ValueType	getInterpolatedValue (const CoordinateType &x) const throw (Exception::OutOfGrid)
const ValueType &	getClosestValue (const CoordinateType &x) const throw (Exception::OutOfGrid)
ValueType &	getClosestValue (const CoordinateType &x) throw (Exception::OutOfGrid)
IndexType	getClosestIndex (const CoordinateType &v) const throw (Exception::OutOfGrid)
IndexType	getLowerIndex (const CoordinateType &v) const throw (Exception::OutOfGrid)
const IndexType &	getSize () const
const CoordinateType &	getOrigin () const
const CoordinateType &	getSpacing () const
void	setOrigin (const CoordinateType &origin)
const CoordinateType &	getDimension () const
void	setDimension (const CoordinateType &dimension)
void	resize (const IndexType &size) throw (Exception::OutOfMemory)
void	rescale (const IndexType &new_size) throw (Exception::OutOfMemory)
CoordinateType	getCoordinates (const IndexType &index) const throw (Exception::OutOfGrid)
CoordinateType	getCoordinates (Position index) const throw (Exception::OutOfGrid)
void	getEnclosingIndices (const CoordinateType &r, Position &llf, Position &rlf, Position &luf, Position &ruf, Position &llb, Position &rlb, Position &lub, Position &rub) const throw (Exception::OutOfGrid)
void	getEnclosingValues (const CoordinateType &r, ValueType &llf, ValueType &rlf, ValueType &luf, ValueType &ruf, ValueType &llb, ValueType &rlb, ValueType &lub, ValueType &rub) const throw (Exception::OutOfGrid)
void	binaryWrite (const String &filename) const throw (Exception::FileNotFound)
void	binaryWriteRaw (const String &filename) const throw (Exception::FileNotFound)
void	binaryRead (const String &filename) throw (Exception::FileNotFound)
Protected Member Functions
const CoordinateType	mapToCartesian_ (CoordinateType r) const
	map indices to Cartesian coordinates
const CoordinateType	mapInverse_ (CoordinateType r) const
	map Cartesian coordinates to indices (note: this does not yet convert the double values to Index)
Protected Attributes
VectorType	data_
	The grid data.
CoordinateType	origin_
	Origin of the grid (offset).
CoordinateType	dimension_
	Dimension of the grid.
CoordinateType	spacing_
	Grid spacing.
IndexType	size_
	The dimensions in grid points.
bool	is_orthogonal_
	A flag deciding whether the grid is orthogonal or not.
std::vector< double >	mapping_
	mapping matrix and its inverse
std::vector< double >	inverse_mapping_

Detailed Description

template<typename ValueType>
class BALL::TRegularData3D< ValueType >

Three-dimensional grid class. This class represents a three-dimensional array. An instance of ValueType will be created for each point of the grid upon instantiation of TRegularData3D and initialized with its default value

: This class fulfills the STL Container and Unary Function requirements. Iteration is along the x-axis first, then along the y-axis.

: A TRegularData3D instance can represent a non-orthogonal grid. In this case, a Matrix33 for the conversion to Cartesian coordinates and its inverse must be provided.

Member Typedef Documentation

template<typename ValueType>

typedef std::vector<ValueType>::const_iterator BALL::TRegularData3D< ValueType >::const_iterator

template<typename ValueType>

typedef std::vector<ValueType>::const_reference BALL::TRegularData3D< ValueType >::const_reference

template<typename ValueType>

typedef std::vector<ValueType>::const_iterator BALL::TRegularData3D< ValueType >::ConstIterator

A nonmutable iterator.

template<typename ValueType>

typedef TVector3<float> BALL::TRegularData3D< ValueType >::CoordinateType

The coordinate type.

template<typename ValueType>

typedef std::vector<ValueType>::difference_type BALL::TRegularData3D< ValueType >::difference_type

template<typename ValueType>

typedef std::vector<ValueType>::iterator BALL::TRegularData3D< ValueType >::iterator

template<typename ValueType>

typedef std::vector<ValueType>::iterator BALL::TRegularData3D< ValueType >::Iterator

A mutable iterator.

template<typename ValueType>

typedef std::vector<ValueType>::pointer BALL::TRegularData3D< ValueType >::pointer

template<typename ValueType>

typedef std::vector<ValueType>::reference BALL::TRegularData3D< ValueType >::reference

template<typename ValueType>

typedef std::vector<ValueType>::size_type BALL::TRegularData3D< ValueType >::size_type

template<typename ValueType>

typedef ValueType BALL::TRegularData3D< ValueType >::value_type

template<typename ValueType>

typedef std::vector<ValueType> BALL::TRegularData3D< ValueType >::VectorType

The type containing an STL vector of the appropriate type.

Constructor & Destructor Documentation

template<class ValueType >

BALL::TRegularData3D< ValueType >::TRegularData3D ( ) [inline]

Default constructor. Creates a TRegularData3D object without allocating a grid.

template<class ValueType>

BALL::TRegularData3D< ValueType >::TRegularData3D ( const TRegularData3D< ValueType > & grid ) throw (Exception::OutOfMemory) [inline]

Copy constructor.

References BALL::TRegularData3D< ValueType >::data_.

template<typename ValueType>

BALL::TRegularData3D< ValueType >::TRegularData3D	(	const CoordinateType &	origin,
		const CoordinateType &	dimension,
		const CoordinateType &	spacing
	)			throw (Exception::OutOfMemory)

Constructor for an orthogonal TRegularData3D.

template<typename ValueType>

BALL::TRegularData3D< ValueType >::TRegularData3D	(	const CoordinateType &	origin,
		const CoordinateType &	x_axis,
		const CoordinateType &	y_axis,
		const CoordinateType &	z_axis,
		const IndexType &	size
	)			throw (Exception::OutOfMemory)

Constructor for a non-orthogonal TRegularData3D.

template<typename ValueType>

BALL::TRegularData3D< ValueType >::TRegularData3D	(	const IndexType &	size,
		const CoordinateType &	origin = `CoordinateType(0.0)`,
		const CoordinateType &	dimension = `CoordinateType(1.0)`
	)			throw (Exception::OutOfMemory)

Constructor for a standard orthogonal TRegularData3D.

template<class ValueType >

BALL::TRegularData3D< ValueType >::~TRegularData3D ( ) [inline, virtual]

Destructor.

Member Function Documentation

template<typename ValueType>

BALL_INLINE Iterator BALL::TRegularData3D< ValueType >::begin ( ) [inline]

template<typename ValueType>

BALL_INLINE ConstIterator BALL::TRegularData3D< ValueType >::begin ( ) const [inline]

Referenced by BALL::operator>>().

template<typename ValueType >

void BALL::TRegularData3D< ValueType >::binaryRead ( const String & filename ) throw (Exception::FileNotFound) [inline]

Read the grid contents from a file written with binaryWrite

Note: this currently only works correctly for orthogonal grids.

Exceptions:

FileNotFound

thrown if file doesnt exists or could not be read

References BALL::File::close(), BALL::BinaryFileAdaptor< T >::getData(), and BALL::File::isValid().

template<typename ValueType >

void BALL::TRegularData3D< ValueType >::binaryWrite ( const String & filename ) const throw (Exception::FileNotFound) [inline]

Write the grid contents in a (non-portable) binary format.

Note: this currently only works correctly for orthogonal grids.

Exceptions:

FileNotFound

thrown if file could not be written

References BALL::File::close(), BALL::File::isValid(), and BALL::BinaryFileAdaptor< T >::setData().

template<typename ValueType>

void BALL::TRegularData3D< ValueType >::binaryWriteRaw ( const String & filename ) const throw (Exception::FileNotFound)

Writes out raw binary plus text header file. !!!WARNING!!! This method is defined only for float template parameters. If you try it to call it from any other specialization, it will give out compile error that the function has no body.

template<typename ValueType >

void BALL::TRegularData3D< ValueType >::clear ( ) [inline, virtual]

Clear method. Delete the grid contents and resize it to zero.

Reimplemented in BALL::TFFT3D< ComplexTraits >.

References BALL::TRegularData3D< ValueType >::data_, BALL::TRegularData3D< ValueType >::dimension_, BALL::TRegularData3D< ValueType >::is_orthogonal_, BALL::TRegularData3D< ValueType >::origin_, BALL::TVector3< T >::set(), BALL::TRegularData3D< ValueType >::size_, BALL::TRegularData3D< ValueType >::spacing_, BALL::TRegularData3D< ValueType >::IndexType::x, BALL::TRegularData3D< ValueType >::IndexType::y, and BALL::TRegularData3D< ValueType >::IndexType::z.

template<typename ValueType>

BALL_INLINE bool BALL::TRegularData3D< ValueType >::empty ( ) const [inline]

Empty predicate.

template<typename ValueType>

BALL_INLINE Iterator BALL::TRegularData3D< ValueType >::end ( ) [inline]

template<typename ValueType>

BALL_INLINE ConstIterator BALL::TRegularData3D< ValueType >::end ( ) const [inline]

template<typename ValueType>

IndexType BALL::TRegularData3D< ValueType >::getClosestIndex ( const CoordinateType & v ) const throw (Exception::OutOfGrid)

Return the position of the grid point closest to the given vector. If there are multiple grid points with equal distance, the grid point with the lowest indices in x, y direction is returned.

Exceptions:

OutOfGrid

if the point is outside the grid

template<typename ValueType>

ValueType& BALL::TRegularData3D< ValueType >::getClosestValue ( const CoordinateType & x ) throw (Exception::OutOfGrid)

Return a mutable reference to the closest non-interpolated value. This method first performs a range check for the argument x and then returns the value of the closest data point to the left or right of x.

template<typename ValueType>

const ValueType& BALL::TRegularData3D< ValueType >::getClosestValue ( const CoordinateType & x ) const throw (Exception::OutOfGrid)

Return a nonmutable reference to the closest non-interpolated value. This method first performs a range check for the argument x and then returns the value of the closest data point to the left or right of x.

template<class ValueType >

BALL_INLINE TRegularData3D< ValueType >::CoordinateType BALL::TRegularData3D< ValueType >::getCoordinates ( Position index ) const throw (Exception::OutOfGrid) [inline]

Returns the exact coordinates of a grid point.

Returns:: CoordinateType

Exceptions:

OutOfGrid

if the point is outside the grid

template<typename ValueType>

CoordinateType BALL::TRegularData3D< ValueType >::getCoordinates ( const IndexType & index ) const throw (Exception::OutOfGrid)

Returns the exact coordinates of a grid point.

Returns:: CoordinateType

Exceptions:

OutOfGrid

if the point is outside the grid

Referenced by BALL::TContourSurface< T >::Cube::getCoordinates(), and BALL::TContourSurface< T >::Cube::getOrigin().

template<class ValueType >

BALL_INLINE ValueType & BALL::TRegularData3D< ValueType >::getData ( Position index ) throw (Exception::OutOfGrid) [inline]

Return a mutable reference to a specific data element. This is the range checking version of operator [].

template<class ValueType >

BALL_INLINE const ValueType & BALL::TRegularData3D< ValueType >::getData ( Position index ) const throw (Exception::OutOfGrid) [inline]

Return a nonmutable reference to a specific data element. This is the range checking version of operator [].

template<typename ValueType>

ValueType& BALL::TRegularData3D< ValueType >::getData ( const IndexType & index ) throw (Exception::OutOfGrid)

Return a mutable reference to a specific data element. This is the range checking version of operator [].

template<typename ValueType>

const ValueType& BALL::TRegularData3D< ValueType >::getData ( const IndexType & index ) const throw (Exception::OutOfGrid)

Return a nonmutable reference to a specific data element. This is the range checking version of operator [].

template<class ValueType >

BALL_INLINE const vector< ValueType > & BALL::TRegularData3D< ValueType >::getData ( ) const [inline]

Get the full data.

References BALL::TRegularData3D< ValueType >::data_.

Referenced by BALL::VIEW::DemoTutorialDialog::onNotifyDemo_().

template<typename ValueType>

const CoordinateType& BALL::TRegularData3D< ValueType >::getDimension ( ) const [inline]

Return the dimension of the data. The dimension represents the length of the data vector. Hence, the coordinate of the rightmost element, data_[getSize() - 1] is the origin plus the dimension (getOrigin() + getDimension()).

template<typename ValueType>

void BALL::TRegularData3D< ValueType >::getEnclosingIndices	(	const CoordinateType &	r,
		Position &	llf,
		Position &	rlf,
		Position &	luf,
		Position &	ruf,
		Position &	llb,
		Position &	rlb,
		Position &	lub,
		Position &	rub
	)			const throw (Exception::OutOfGrid)

Return the indices of the grid points of the enclosing box. This method calculates the grid box that contains the given vector and returns the indices of the grid points forming this box. The given point lies either in the box or is the lower left front edge of the box.

Exceptions:

OutOfGrid

if the point is outside the grid

Parameters:

	vector	a point inside the grid
	llf	left lower front corner of the box
	rlf	right lower front corner of the box
	luf	left upper front corner of the box
	ruf	right upper front corner of the box
	llb	left lower back corner of the box
	rlb	right lower back corner of the box
	lub	left upper back corner of the box
	rub	right upper back corner of the box

template<typename ValueType>

void BALL::TRegularData3D< ValueType >::getEnclosingValues	(	const CoordinateType &	r,
		ValueType &	llf,
		ValueType &	rlf,
		ValueType &	luf,
		ValueType &	ruf,
		ValueType &	llb,
		ValueType &	rlb,
		ValueType &	lub,
		ValueType &	rub
	)			const throw (Exception::OutOfGrid)

Return the data at the grid points of the enclosing box. getEnclosingIndices

template<typename ValueType>

ValueType BALL::TRegularData3D< ValueType >::getInterpolatedValue ( const CoordinateType & x ) const throw (Exception::OutOfGrid)

Return the linearly interpolated value of the surrounding two grid points. This method first performs a range check for the argument x and then calls operator () (x) to determine an interpolated value at that position.

Reimplemented in BALL::TFFT3D< ComplexTraits >.

template<typename ValueType>

IndexType BALL::TRegularData3D< ValueType >::getLowerIndex ( const CoordinateType & v ) const throw (Exception::OutOfGrid)

Return the position of the next grid point with coordinates smaller than the given vector. This yields the front lower left corner of the cube enclosing the specified position.

Exceptions:

OutOfGrid

if the point is outside the grid

template<typename ValueType>

const CoordinateType& BALL::TRegularData3D< ValueType >::getOrigin ( ) const [inline]

Return the origin of the data. The origin represents the coordinate of the very first (lower left) element, i.e. data_[0].

Referenced by BALL::TContourSurface< T >::operator<<().

template<typename ValueType>

const IndexType& BALL::TRegularData3D< ValueType >::getSize ( ) const [inline]

Return the size of the grid. This method yields the number of grid points in x- and y-direction. Use size to obtain the total number of points in the grid.

Referenced by BALL::TContourSurface< T >::Cube::Cube(), and BALL::TContourSurface< T >::operator<<().

template<typename ValueType>

const CoordinateType& BALL::TRegularData3D< ValueType >::getSpacing ( ) const [inline]

Return the spacing of the data. The spacing corresponds to the distance between two adjacent data elements.

template<typename ValueType>

bool BALL::TRegularData3D< ValueType >::isInside ( const CoordinateType & r ) const

Test if a given point is inside the grid.

template<typename ValueType>

const CoordinateType BALL::TRegularData3D< ValueType >::mapInverse_ ( CoordinateType r ) const [inline, protected]

map Cartesian coordinates to indices (note: this does not yet convert the double values to Index)

template<typename ValueType>

const CoordinateType BALL::TRegularData3D< ValueType >::mapToCartesian_ ( CoordinateType r ) const [inline, protected]

map indices to Cartesian coordinates

template<typename ValueType>

BALL_INLINE size_type BALL::TRegularData3D< ValueType >::max_size ( ) const [inline]

template<typename ValueType>

BALL_INLINE bool BALL::TRegularData3D< ValueType >::operator!= ( const TRegularData3D< ValueType > & grid ) const [inline]

Inequality operator.

template<typename ValueType>

ValueType BALL::TRegularData3D< ValueType >::operator() ( const CoordinateType & x ) const

Function operator. This operator allows the use of a TRegularData1D instance as a unary function. As required by the STL Unary Function concept, the argument x is required to be within the correct range. A more robust (range-checking) version of this operator is implemented as getInterpolatedValue . getInterpolatedValue() . getOrigin() <= x <= getOrigin() + getDimension()

template<typename ValueType>

BALL_INLINE TRegularData3D< ValueType > & BALL::TRegularData3D< ValueType >::operator= ( const TRegularData3D< ValueType > & data ) throw (Exception::OutOfMemory) [inline]

Assignment operator. Copy the data, the origin, and the dimension (spacing is copied implicitly as well).

template<typename ValueType>

bool BALL::TRegularData3D< ValueType >::operator== ( const TRegularData3D< ValueType > & grid ) const [inline]

Equality operator. Two point grids are equal if they have the same number of points in all three dimensions, same origin, spacing and all array members are identical.

References BALL::TRegularData3D< ValueType >::data_, BALL::TRegularData3D< ValueType >::dimension_, BALL::TRegularData3D< ValueType >::is_orthogonal_, BALL::TRegularData3D< ValueType >::origin_, BALL::TRegularData3D< ValueType >::size_, BALL::TRegularData3D< ValueType >::IndexType::x, BALL::TRegularData3D< ValueType >::IndexType::y, and BALL::TRegularData3D< ValueType >::IndexType::z.

Referenced by BALL::TRegularData3D< char >::operator!=().

template<typename ValueType>

ValueType& BALL::TRegularData3D< ValueType >::operator[] ( Position index ) [inline]

Mutable random access operator.

Note:: No range checking is done. For a more robust version, please use getData.

template<typename ValueType>

const ValueType& BALL::TRegularData3D< ValueType >::operator[] ( Position index ) const [inline]

Nonmutable random access operator.

Note:: No range checking is done. For a more robust version, please use getData.

template<typename ValueType>

ValueType& BALL::TRegularData3D< ValueType >::operator[] ( const IndexType & index ) [inline]

Mutable random access operator.

Note:: No range checking is done. For a more robust version, please use getData.

template<typename ValueType>

const ValueType& BALL::TRegularData3D< ValueType >::operator[] ( const IndexType & index ) const [inline]

Nonmutable random access operator.

Note:: No range checking is done. For a more robust version, please use getData.

Referenced by BALL::TFFT3D< ComplexTraits >::operator[]().

template<typename ValueType>

void BALL::TRegularData3D< ValueType >::rescale ( const IndexType & new_size ) throw (Exception::OutOfMemory)

Rescale the data. Keep the current boundaries of the data and reinterpolate the data to reflect the new size. To create a data set of new_size data points, the data is interpolated linearly at the new data points from the closest points in the old data set.

: Note: this function currently only works on orthogonal grids! For non-orthogonal data calls to rescale are ignored.

Parameters:

new_size

the new data set size

template<typename ValueType>

void BALL::TRegularData3D< ValueType >::resize ( const IndexType & size ) throw (Exception::OutOfMemory)

Resize the data. If new_size is larger than the current size, the data vector is extended to the new size and filled with default constructed items of type ValueType. Resizing to a value lesser than the current size truncates the vector.

: The boundaries are adapted and the positions of the retained items fixed, i.e. the dimension is increased or decreased proportionally while the origin remains unchanged.

: Note: this function currently only works on orthogonal grids! For non-orthogonal data calls to resize are ignored.

Parameters:

size

the new size

Referenced by BALL::operator>>().

template<typename ValueType>

void BALL::TRegularData3D< ValueType >::setDimension ( const CoordinateType & dimension ) [inline]

Set the dimension of the data. This will affect neither the origin of the data, nor the number of elements stored (in contrast to resize() ). It will just store the appropriate scaling factor and affect the spacing.