G3D::Box Class Reference

An arbitrary (oriented) 3D box, useful as a bounding box. More...

#include <Box.h>

Public Member Functions
	Box ()
	Box (const Any &a)
	Box (const Vector3 &min, const Vector3 &max)
	Box (const Vector3 &osMin, const Vector3 &osMax, const CoordinateFrame &frame)
	Box (class BinaryInput &b)
	Box (const class AABox &b)
	Box (const Point3 &p)
Any	toAny () const
void	serialize (class BinaryOutput &b) const
void	deserialize (class BinaryInput &b)
CoordinateFrame	localFrame () const
void	getLocalFrame (CoordinateFrame &frame) const
Box	operator* (float f) const
Vector3	center () const
Vector3	corner (int i) const
Vector3	axis (int a) const
float	extent (int a) const
Vector3	extent () const
void	getFaceCorners (int f, Vector3 &v0, Vector3 &v1, Vector3 &v2, Vector3 &v3) const
bool	culledBy (const Array< Plane > &plane, int32 &cullingPlaneIndex, const uint32 testMask, uint32 &childMask) const
bool	culledBy (const Array< Plane > &plane, int32 &cullingPlaneIndex=dummy, const uint32 testMask=-1) const
bool	contains (const Vector3 &point) const
float	area () const
float	volume () const
void	getRandomSurfacePoint (Vector3 &P, Vector3 &N=Vector3::ignore()) const
Vector3	randomInteriorPoint () const
void	getBounds (class AABox &) const
bool	isFinite () const

Static Public Member Functions
static Box	inf ()

Private Member Functions
void	init (const Vector3 &min, const Vector3 &max)

Private Attributes
Vector3	_edgeVector [3]
Point3	_center
float	_area
float	_volume

Static Private Attributes
static int32	dummy = 0

Friends
class	CoordinateFrame

Detailed Description

An arbitrary (oriented) 3D box, useful as a bounding box.

To construct a box from a coordinate frame, center and extent, use the idiom: Box box = cframe.toObjectSpace(Box(center - extent/2, center + extent/2));

Constructor & Destructor Documentation

G3D::Box::Box

(

)

 : _area(0), _volume(0) {
}

Here is the caller graph for this function:

G3D::Box::Box ( const Any &  a )

explicit

 {
 if (a.name() == "Box::inf") {
 *this = Box::inf();
 } else {
 a.verifyName("Box", "AABox", "Point3");

 if (a.name() == "Point3") {
 *this = Box(Point3(a));
 } else if (a.size() == 1) {
 // Single point
 *this = Box(Point3(a[0]));
 } else if (a.size() == 2) {
 *this = Box(Point3(a[0]), Point3(a[1]));
 } else {
 // Oriented box
 a.verifySize(2);
 a.verifyName("Box");
 *this = Box(Point3(a[0]), Point3(a[1]), CFrame(a[2]));
 }
 }
}

Here is the call graph for this function:

G3D::Box::Box	(	const Vector3 &	min,
		const Vector3 &	max
	)

Constructs a box from two opposite corners.

 {
 init(min.min(max), min.max(max));
}

Here is the call graph for this function:

G3D::Box::Box	(	const Vector3 &	osMin,
		const Vector3 &	osMax,
		const CoordinateFrame &	frame
	)

G3D::Box::Box

(

class BinaryInput &

b

)

 {
 deserialize(b); 
}

Here is the call graph for this function:

G3D::Box::Box

(

const class AABox &

b

)

G3D::Box::Box ( const Point3 &  p )

explicit

 {
 init(min, min);
}

Here is the call graph for this function:

Member Function Documentation

float G3D::Box::area

(

)

const

 {
 return _area;
}

Vector3 G3D::Box::axis ( int  a ) const

inline

Unit length.

 {
 debugAssert(a < 3);
 return _edgeVector[a].direction();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

Vector3 G3D::Box::center ( ) const

inline

Returns the centroid of the box.

 {
 return _center;
 }

Here is the caller graph for this function:

bool G3D::Box::contains

(

const Vector3 &

point

)

const

 {

 // Form axes from three edges, transform the point into that
 // space, and perform 3 interval tests
 // TODO: Write in a more intuitive way. I left it as it was before after figuring it out, but
 // this should make no sense to someone who is just starting to read this code.
 const Vector3& u = _edgeVector[2];
 const Vector3& v = _edgeVector[1];
 const Vector3& w = _edgeVector[0];

 Matrix3 M = Matrix3(u.x, v.x, w.x,
 u.y, v.y, w.y,
 u.z, v.z, w.z);

 // M^-1 * (point - _corner[0]) = point in unit cube's object space
 // compute the inverse of M
 Vector3 osPoint = M.inverse() * (point - corner(0));

 return
 (osPoint.x >= 0) && 
 (osPoint.y >= 0) &&
 (osPoint.z >= 0) &&
 (osPoint.x <= 1) &&
 (osPoint.y <= 1) &&
 (osPoint.z <= 1);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Vector3 G3D::Box::corner

(

int

i

)

const

    

    2--------3
   / :      /|
  /  :     / |
 6--------7  |
 |   :    |  |
 |   0....|..1
 | /      | /
 |/       |/
 4--------5

  y  
  ^ 
  |
  |-->x
z/


    

 {
 debugAssert(i < 8);
 // The corner forms a bit mask (xyz), where a one indicates we should
 // add half of the corresponding edge vector from center, and a zero indicates 
 // we should subtract it. Note:
 // 1 = 001
 // 2 = 010
 // 4 = 100
 // 
 // The following bit-hacky code shows this directly:
 // return _center + ((_edgeVector[0] * ((i&1) - 0.5) +
 // _edgeVector[1] * (((i>>1)&1) - 0.5) +
 // _edgeVector[2] * (((i>>2)&1) - 0.5)));
 // This method is implemented as a swtich statement due to being marginally faster than the bit-hack method
 // Also, the _center + 0.5f * (...) is repeated every time for similarly speed-based reasons.
 switch(i) {
 case 0: return _center + (0.5f * (-_edgeVector[0] - _edgeVector[1] - _edgeVector[2]));
 case 1: return _center + (0.5f * ( _edgeVector[0] - _edgeVector[1] - _edgeVector[2]));
 case 2: return _center + (0.5f * (-_edgeVector[0] + _edgeVector[1] - _edgeVector[2]));
 case 3: return _center + (0.5f * ( _edgeVector[0] + _edgeVector[1] - _edgeVector[2]));
 case 4: return _center + (0.5f * (-_edgeVector[0] - _edgeVector[1] + _edgeVector[2]));
 case 5: return _center + (0.5f * ( _edgeVector[0] - _edgeVector[1] + _edgeVector[2]));
 case 6: return _center + (0.5f * (-_edgeVector[0] + _edgeVector[1] + _edgeVector[2]));
 default: return _center + (0.5f * ( _edgeVector[0] + _edgeVector[1] + _edgeVector[2]));//case 7
 }
 
}

Here is the caller graph for this function:

bool G3D::Box::culledBy	(	const Array< Plane > &	plane,
		int32 &	cullingPlaneIndex,
		const uint32	testMask,
		uint32 &	childMask
	)		const

See AABox::culledBy

bool G3D::Box::culledBy	(	const Array< Plane > &	plane,
		int32 &	cullingPlaneIndex = dummy,
		const uint32	testMask = -1
	)		const

Conservative culling test that does not produce a mask for children.

void G3D::Box::deserialize

(

class BinaryInput &

b

)

 {
 int i;
 for (i = 0; i < 3; ++i) {
 _edgeVector[i].deserialize(b);
 }
 _center.deserialize(b);

 float extent0 = extent(0);
 float extent1 = extent(1);
 float extent2 = extent(2);
 _volume = extent0 * extent1 * extent2;

 _area = 2 * 
 (extent0 * extent1 +
 extent1 * extent2 +
 extent2 * extent0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

float G3D::Box::extent ( int  a ) const

inline

Distance from corner(0) to the next corner along the box's local axis a.

 {
 debugAssert(a < 3);
 return _edgeVector[a].length();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

Vector3 G3D::Box::extent ( ) const

inline

 {
 return Vector3(_edgeVector[0].length(), _edgeVector[1].length(), _edgeVector[2].length());
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Box::getBounds

(

class AABox &

aabb

)

const

 {
 debugAssert(! _edgeVector[0].isNaN());
 debugAssert(! _center.isNaN());
 aabb = AABox::empty();
 for (int i = 0; i < 8; ++i) {
 aabb.merge(corner(i));
 }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Box::getFaceCorners	(	int	f,
		Vector3 &	v0,
		Vector3 &	v1,
		Vector3 &	v2,
		Vector3 &	v3
	)		const

Returns the four corners of a face (0 <= f < 6). The corners are returned to form a clockwise quad facing outwards.

  +--------+
 / :      /|
/  :     / |

+-----—+ | | : | | | +....|..+ | / | / |/ |/ +-----—+

y ^ | |–>x z/ Faces are in the following order: 0: -Z 1: X 2: Z 3: Y 4: -X 5: -Y

 {
 switch (f) {
 case 0:
 v0 = corner(0); v1 = corner(2); v2 = corner(3); v3 = corner(1);
 break;

 case 1:
 v0 = corner(1); v1 = corner(3); v2 = corner(7); v3 = corner(5);
 break;

 case 2:
 v0 = corner(6); v1 = corner(4); v2 = corner(5); v3 = corner(7);
 break;

 case 3:
 v0 = corner(3); v1 = corner(2); v2 = corner(6); v3 = corner(7);
 break;

 case 4:
 v0 = corner(2); v1 = corner(0); v2 = corner(4); v3 = corner(6);
 break;

 case 5:
 v0 = corner(1); v1 = corner(5); v2 = corner(4); v3 = corner(0);
 break;

 default:
 debugAssert((f >= 0) && (f < 6));
 }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Box::getLocalFrame

(

CoordinateFrame &

frame

)

const

See also

localFrame

 {
 const Vector3& axis0 = axis(0);
 const Vector3& axis1 = axis(1);
 const Vector3& axis2 = axis(2);

 frame.rotation = Matrix3(
 axis0[0], axis1[0], axis2[0],
 axis0[1], axis1[1], axis2[1],
 axis0[2], axis1[2], axis2[2]);

 frame.translation = _center;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Box::getRandomSurfacePoint	(	Vector3 &	P,
		Vector3 &	N = Vector3::ignore()
	)		const

 {
 float aXY = extent(0) * extent(1);
 float aYZ = extent(1) * extent(2);
 float aZX = extent(2) * extent(0);

 float r = (float)uniformRandom(0, aXY + aYZ + aZX);

 // Choose evenly between positive and negative face planes
 float d = (uniformRandom(0, 1) < 0.5f) ? -1.0f : 1.0f;

 // The probability of choosing a given face is proportional to
 // its area.
 if (r < aXY) {
 P = _edgeVector[0] * (float)uniformRandom(-0.5, 0.5) +
 _edgeVector[1] * (float)uniformRandom(-0.5, 0.5) +
 _center + _edgeVector[2] * d * 0.5f;
 N = axis(2) * d;
 } else if (r < aYZ) {
 P = _edgeVector[1] * (float)uniformRandom(-0.5, 0.5) +
 _edgeVector[2] * (float)uniformRandom(-0.5, 0.5) +
 _center + _edgeVector[0] * d * 0.5f;
 N = axis(0) * d;
 } else {
 P = _edgeVector[2] * (float)uniformRandom(-0.5, 0.5) +
 _edgeVector[0] *(float) uniformRandom(-0.5, 0.5) +
 _center + _edgeVector[1] * d * 0.5f;
 N = axis(1) * d;
 }
}

Here is the call graph for this function:

Box G3D::Box::inf ( )

static

 {
 return Box(-Vector3::inf(), Vector3::inf());
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Box::init ( const Vector3 &  min, const Vector3 &  max  )

private

 {

 debugAssert(
 (min.x <= max.x) &&
 (min.y <= max.y) &&
 (min.z <= max.z));

 _center = (max + min) * 0.5f;

 Vector3 bounds = Vector3(max.x - min.x, max.y - min.y, max.z - min.z);
 _edgeVector[0] = Vector3(bounds.x, 0, 0);
 _edgeVector[1] = Vector3(0, bounds.y, 0);
 _edgeVector[2] = Vector3(0, 0, bounds.z);
 bool finiteExtent = true;
 
 for (int i = 0; i < 3; ++i) {
 if (! G3D::isFinite(extent(i))) {
 finiteExtent = false;
 // If the extent is infinite along an axis, make the center zero to avoid NaNs
 _center[i] = 0.0f;
 }
 }


 if (finiteExtent) {
 _volume = bounds.x * bounds.y * bounds.z;
 } else {
 _volume = G3D::finf();
 }

 debugAssert(! _edgeVector[0].isNaN());

 _area = 2 * 
 (bounds.x * bounds.y +
 bounds.y * bounds.z +
 bounds.z * bounds.x);
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::Box::isFinite ( ) const

inline

 {
 return G3D::isFinite(_volume);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

CoordinateFrame G3D::Box::localFrame

(

)

const

Returns the object to world transformation for this box, where the origin is the center of the box. localFrame().worldToObject(...) takes objects into the space where the box axes are (1,0,0), (0,1,0), (0,0,1). Note that there is no scaling in this transformation.

 {
 CoordinateFrame out;
 getLocalFrame(out);
 return out;
}

Here is the call graph for this function:

Box G3D::Box::operator*

(

float

f

)

const

 {
 Box b;

 for (int i = 0; i < 3; ++i) {
 b._edgeVector[i] = _edgeVector[i] * f;
 b._center = _center * f;
 b._area = _area * square(f * f);
 b._volume = _area * (f * f * f);
 }

 return b;
}

Here is the call graph for this function:

Vector3 G3D::Box::randomInteriorPoint

(

)

const

Uniformly distributed on the interior (includes surface)

 {
 Vector3 sum = _center;

 for (int a = 0; a < 3; ++a) {
 sum += _edgeVector[a] * (float)uniformRandom(-0.5, 0.5);
 }

 return sum;
}

Here is the call graph for this function:

void G3D::Box::serialize

(

class BinaryOutput &

b

)

const

 {
 int i;
 for (i = 0; i < 3; ++i) {
 _edgeVector[i].serialize(b);
 }
 _center.serialize(b);

 // Other state can be reconstructed
}

Here is the call graph for this function:

Any G3D::Box::toAny

(

)

const

 {
 if (! isFinite()) {
 return Any(Any::ARRAY, "Box::inf");
 } else {
 CFrame c;
 getLocalFrame(c);
 if (c.rotation == Matrix3::identity()) {
 // Aligned box
 AABox b;
 getBounds(b);
 return b.toAny();
 } else {
 // Oriented box
 Any a(Any::ARRAY, "Box");

 AABox b;
 c.toObjectSpace(*this).getBounds(b);
 a.append(b.low(), b.high(), c);
 return a;
 }
 }
}

Here is the call graph for this function:

float G3D::Box::volume

(

)

const

 {
 return _volume;
}

Friends And Related Function Documentation

friend class CoordinateFrame

friend

Member Data Documentation

float G3D::Box::_area

private

Point3 G3D::Box::_center

private

Vector3 G3D::Box::_edgeVector[3]

private

Axes with length equal to the 4 edges that run along each of them

float G3D::Box::_volume

private

int G3D::Box::dummy = 0

staticprivate

---

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

• dep/g3dlite/include/G3D/Box.h
• dep/g3dlite/source/Box.cpp