dlr::numeric::AmanatidesWoo3D< ARRAY3D > Class Template Reference

This class implements the Fast Voxel Traversal Algorithm of Amanatides and Woo [Ref] for 3D arrays. More...

#include <amanatidesWoo3D.h>

List of all members.

Public Types

typedef
AmanatidesWoo3DIterator
< ARRAY3D > iterator

This typedef specifies the type which will be returned by member functions begin() and end().

Public Member Functions

AmanatidesWoo3D (ARRAY3D &data, const Transform3D &voxelTworld, const Vector3D &rayOrigin, const Vector3D &rayDirection, bool downstreamOnly=true)

This constructor specifies all of the internal state of the AmanatidesWoo3D class.

AmanatidesWoo3D (const AmanatidesWoo3D &source)

This is the copy constructor.

~AmanatidesWoo3D ()

This is the destructor.

iterator begin ()

This member function returns an iterator which references the first voxel along the traced ray.

iterator end ()

This member function returns an iterator which references an invalid voxel, and which will be equal (==) to the iterator returned by member function begin() when that iterator has fully traversed the line of voxels.

ARRAY3D & getData ()

This member function returns a reference to the array object over which iteration is performed.

bool validIntersection ()

This member function returns true if the iterator returned by member function begin() will point to a valid voxel.

AmanatidesWoo3D & operator= (const AmanatidesWoo3D &source)

The assignment operator copies its argument.

Detailed Description

template<class ARRAY3D>
class dlr::numeric::AmanatidesWoo3D< ARRAY3D >

This class implements the Fast Voxel Traversal Algorithm of Amanatides and Woo [Ref] for 3D arrays.

The algorithm is for efficient ray tracing through regular grids. For convenience, there are two coordinate systems associated with this class:

The voxel coordinate system is an integer-based coordinate system associated with the array.

The world coordinate system, which can differ from the voxel coordinate system only by translation, rotation, and non-isotropic scaling, but is in other respects arbitrary.

The voxel coordinate system has its origin at the corner of the 3D array, has its first coordinate (which we'll call U) parallel to the rows of the array, has its second coordinate (which we'll call V) parallel to the columns of the array, and has its third coordinate (which we'll call W) parallel to the direction of increasing slice number. As you move along any row of any slice in the 3D array, the transition from the first column to the second occurs at U == 1.0, the transition from the second column to the third occurs at U == 2.0, and so on. Similarly as you move along any column of any slice of the array, the transition from the first row to the second occurs at V == 1.0, and the transition from the second row to the third occurs at V == 2.0. At any row, column coordinate, as you move through subsequent slices of the array, the transition from the first slice to the second occurs at W == 1.0, and the transition from the second slice to the third occurs at W == 2.0, and so on.

Once constructed, you can use the AmanatidesWoo3D class to access voxels along a straight line through the 3D array using STL-style iteration. That is, the member functions AmanatidesWoo3D::begin() returns an iterator which references subsequent voxels along the line, and will become equal (==) to the iterator returned by AmanatidesWoo3D::end() when the line passes out of the 3D array. Here's an example usage, which will probably format terribly in the Doxygen-generated doc:

typedef AmanatidesWoo3D< Array3D<int> >iterator awIterator;

AmanatidesWoo3D< Array3D<int> > rayTracer( myArray3D, rayOrigin, rayDirection, false);

awIterator iterator0 = rayTracer.begin();

awIterator iterator1 = rayTracer.end();

for(; iterator0 != iterator1; ++iterator0) {

*iterator0 = 0;

}

Definition at line 84 of file amanatidesWoo3D.h.

Member Typedef Documentation

template<class ARRAY3D >

typedef AmanatidesWoo3DIterator<ARRAY3D> dlr::numeric::AmanatidesWoo3D< ARRAY3D >::iterator

This typedef specifies the type which will be returned by member functions begin() and end().

AmanatidesWoo3DIterator is a forward iterator, and has unusual semantics for operator==(). Be sure to understand them before using this class.

Definition at line 95 of file amanatidesWoo3D.h.

Constructor & Destructor Documentation

template<class ARRAY3D >

dlr::numeric::AmanatidesWoo3D< ARRAY3D >::AmanatidesWoo3D	(	ARRAY3D &	data,
		const Transform3D &	voxelTworld,
		const Vector3D &	rayOrigin,
		const Vector3D &	rayDirection,
		bool	downstreamOnly = `true`
	)			`[inline]`

This constructor specifies all of the internal state of the AmanatidesWoo3D class.

After construction, the AmanatidesWoo3D instance is ready to be used.

Parameters:

	data	This argument specifies the 3D array over which to iterate.
	voxelTworld	This parameter specifies a coordinate transformation which takes world coordinates and converts them into voxel coordinates.
	rayOrigin	This parameter specifies the starting point of the ray to be traced, expressed in world coordinates. If you'd rather express rayOrigin and rayDirection in voxel coordinates, simply set argument voxelTworld to the identity transform. Note that rayOrigin does not have to lie inside the voxel array.
	rayDirection	This parameter specifies the direction of the ray to be traced, expressed in world coordinates. In other words, any point on the line of interest can be written as (rayOrigin + t * rayDirection) for some value of t. If you'd rather express rayOrigin and rayDirection in voxel coordinates, simply set argument voxelTworld to the identity transform.
	downstreamOnly	This boolean argument specifies whether voxels "upstream" of rayOrigin are to be included in the voxel traversal. If downstreamOnly is set to false, voxels which intersect the line (rayOrigin + t * rayDirection) will be included in the iteration even if they intersect the line at negative values of t.

Definition at line 366 of file amanatidesWoo3D.h.

References dlr::numeric::Vector3D::x(), dlr::numeric::Vector3D::y(), and dlr::numeric::Vector3D::z().

template<class ARRAY3D >

dlr::numeric::AmanatidesWoo3D< ARRAY3D >::AmanatidesWoo3D ( const AmanatidesWoo3D< ARRAY3D > & source ) [inline]

This is the copy constructor.

After copying, the new AmanatidesWoo3D instance and the copied instance both reference the same voxel array.

Parameters:

source

The AmanatidesWoo3D instance to be copied.

Definition at line 523 of file amanatidesWoo3D.h.

template<class ARRAY3D >

dlr::numeric::AmanatidesWoo3D< ARRAY3D >::~AmanatidesWoo3D ( ) [inline]

This is the destructor.

It destroys the AmanatidesWoo3D instance and cleans up any allocated memory.

Definition at line 545 of file amanatidesWoo3D.h.

Member Function Documentation

template<class ARRAY3D >

AmanatidesWoo3D< ARRAY3D >::iterator dlr::numeric::AmanatidesWoo3D< ARRAY3D >::begin ( ) [inline]

This member function returns an iterator which references the first voxel along the traced ray.

If constructor argument downstreamOnly was set to false, this iterator will either point to a voxel on the very edge of the array, or (in the case that the ray does not intersect the voxel array) be equal to this->end(). If constructor argument downstreamOnly was set to true, then this iterator will point to an edge voxel, or point to an interior voxel (in the case that rayOrigin lies within the boundaries of the voxel array), or be equal to this->end() (in the case that the ray does not intersect the voxel array, and in the case that rayOrigin lies outside the voxel array and rayDirection points away from the voxel array).

Returns:: The return value is an iterator pointing to the first voxel in the array, or else an iterator for which (iter == this->end()) is true.

Definition at line 550 of file amanatidesWoo3D.h.

template<class ARRAY3D >

AmanatidesWoo3D< ARRAY3D >::iterator dlr::numeric::AmanatidesWoo3D< ARRAY3D >::end ( ) [inline]

This member function returns an iterator which references an invalid voxel, and which will be equal (==) to the iterator returned by member function begin() when that iterator has fully traversed the line of voxels.

Returns:: The return value is an iterator pointing to an invalid voxel, for use as the end iterator in the comparison clause of a loop: "while(rayIterator != endIterator) {++rayIterator; ...;}".

Definition at line 560 of file amanatidesWoo3D.h.

template<class ARRAY3D >

ARRAY3D& dlr::numeric::AmanatidesWoo3D< ARRAY3D >::getData ( ) [inline]

This member function returns a reference to the array object over which iteration is performed.

Returns:: The return value is a reference to the data array.

Definition at line 200 of file amanatidesWoo3D.h.

template<class ARRAY3D >

AmanatidesWoo3D< ARRAY3D > & dlr::numeric::AmanatidesWoo3D< ARRAY3D >::operator= ( const AmanatidesWoo3D< ARRAY3D > & source ) [inline]

The assignment operator copies its argument.

After copying, *this and the copied instance both reference the same voxel array.

Parameters:

source

The AmanatidesWoo3D instance to be copied.

Returns:: The return value is a reference to *this.

Definition at line 582 of file amanatidesWoo3D.h.

template<class ARRAY3D >

bool dlr::numeric::AmanatidesWoo3D< ARRAY3D >::validIntersection ( ) [inline]

This member function returns true if the iterator returned by member function begin() will point to a valid voxel.

In other words, if constructor argument downstreamOnly was set to false, the return value of validIntersection() indicates whether the ray specified in the constructor actually intersects the voxel array. If constructor argument downstreamOnly was set to true, the return value of validIntersection whether the "downstream" half of the ray actually intersects the voxel array.

Returns:: A boolean indicating whether or not (this->begin() == this->end()) will be true.

Definition at line 574 of file amanatidesWoo3D.h.

The documentation for this class was generated from the following file:

amanatidesWoo3D.h


Public Types
typedef AmanatidesWoo3DIterator < ARRAY3D >	iterator
	This typedef specifies the type which will be returned by member functions begin() and end().
Public Member Functions
	AmanatidesWoo3D (ARRAY3D &data, const Transform3D &voxelTworld, const Vector3D &rayOrigin, const Vector3D &rayDirection, bool downstreamOnly=true)
	This constructor specifies all of the internal state of the AmanatidesWoo3D class.
	AmanatidesWoo3D (const AmanatidesWoo3D &source)
	This is the copy constructor.
	~AmanatidesWoo3D ()
	This is the destructor.
iterator	begin ()
	This member function returns an iterator which references the first voxel along the traced ray.
iterator	end ()
	This member function returns an iterator which references an invalid voxel, and which will be equal (==) to the iterator returned by member function begin() when that iterator has fully traversed the line of voxels.
ARRAY3D &	getData ()
	This member function returns a reference to the array object over which iteration is performed.
bool	validIntersection ()
	This member function returns true if the iterator returned by member function begin() will point to a valid voxel.
AmanatidesWoo3D &	operator= (const AmanatidesWoo3D &source)
	The assignment operator copies its argument.

dlr::numeric::AmanatidesWoo3D< ARRAY3D > Class Template Reference

Public Types

Public Member Functions

Detailed Description

template<class ARRAY3D> class dlr::numeric::AmanatidesWoo3D< ARRAY3D >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<class ARRAY3D>
class dlr::numeric::AmanatidesWoo3D< ARRAY3D >