Simbody  3.7
SimTK::Geo::Box_< P > Class Template Reference

A 3d rectangular box aligned with an unspecified frame F and centered at that frame's origin. More...

## Public Member Functions

Box_ ()
Construct an uninitialized Box object; the dimensions will be garbage. More...

Box_ (const Vec3P &halfLengths)
Construct a Box with the given nonnegative half-dimensions. More...

Box_setHalfLengths (const Vec3P &halfLengths)
Change the half-dimensions of this box. More...

Change the half-dimensions of this box by adding the given vector. More...

const Vec3PgetHalfLengths () const
Return the half-lengths of this box as a Vec3 from the center to the first quadrant vertex. More...

RealP getOrderedHalfLength (int i) const
Get lengths in order shortest to longest; 0 is shortest, 2 is longest. More...

CoordinateAxis getOrderedAxis (int i) const
Get axes in order shortest to longest; 0 is shortest, 2 is longest. More...

RealP findVolume () const
Calculate the volume of this box. More...

RealP findArea () const
Calculate the surface area of this box, ignoring degeneracy (meaning that all pairs of sides are counted even if coincident). More...

bool containsPoint (const Vec3P &pt) const
Given a point measured and expressed in the box frame, determine whether it is inside the box (we count touching the surface as inside). More...

Vec3P findClosestPointOfSolidBox (const Vec3P &pt, bool &ptWasInside) const
Given a point location in the box frame, return the closest point of the solid box, and a flag saying whether the given point was inside the box, using the same definition of "inside" as the containsPoint() method. More...

Vec3P findClosestPointOnSurface (const Vec3P &pt, bool &ptWasInside) const
Given a point location in the box frame, return the closest point on the box surface, and a flag saying whether the given point was inside the box, using the same definition of "inside" as the containsPoint() method. More...

RealP findDistanceSqrToPoint (const Vec3P &pt) const
Return the square of the distance from this box to a given point whose location is measured from and expressed in the box frame (at the box center). More...

Vec3P findSupportPoint (const Vec3 &d) const
Find a supporting point on the surface of the box in the given direction, which must be expressed in the box frame. More...

RealP findDistanceSqrToSphere (const Geo::Sphere_< P > &sphere) const
Return the square of the distance from this box to a given sphere whose center location is measured from and expressed in the box frame (at the box center). More...

RealP findDistanceSqrToAlignedBox (const Geo::AlignedBox_< P > &aab) const
Return the square of the distance from this box to an axis-aligned box whose center location is measured from and expressed in this box frame (at the box center). More...

bool intersectsSphere (const Geo::Sphere_< P > &sphere) const
Given a sphere with center measured and expressed in the box frame, return true if the box and sphere intersect. More...

bool intersectsAlignedBox (const Geo::AlignedBox_< P > &aab) const
Given an aligned box with center measured and expressed in the from of this box, return true if the two boxes intersect. More...

bool intersectsOrientedBox (const Geo::OrientedBox_< P > &ob) const
Given an oriented box whose pose is measured and expressed in the frame of this box, return true if the two boxes intersect. More...

bool mayIntersectOrientedBox (const Geo::OrientedBox_< P > &ob) const
Given an oriented box whose pose is measured and expressed in the frame of this box, return true if the two boxes may be intersecting. More...

## Box mesh methods

Methods to use if you want to think of the box as a convex mesh.

Vec3P getVertexPos (int vx) const
Use bits in the vertex number to pick the signs, with 0=negative, 1=positive: More...

int findSupportVertex (const Vec3P &d) const
Find the vertex (0-7) that is furthest in the direction d, which is given in the box frame. More...

UnitVec3P getVertexNormal (int vx) const
Vertex normals point diagonally outwards from the box corners. More...

Vec3P getEdgeCenter (int ex) const
Return the center point of the specified edge, in the box frame. More...

UnitVec3P getEdgeNormal (int ex) const
Edge normals point diagonally outwards from the edge. More...

CoordinateDirection getEdgeCoordinateDirection (int ex) const
Return the direction of an edge, going from its first vertex to its second vertex, as a CoordinateDirection. More...

UnitVec3P getEdgeDirection (int ex) const
Return a unit vector aligned with the selected edge, pointing in the direction from the first vertex towards the second vertex, in the box frame. More...

CoordinateDirection getFaceCoordinateDirection (int fx) const
Return the outward normal for the given face as a CoordinateDirection. More...

Vec3P getFaceCenter (int fx) const
Return the center point position for the given face. More...

UnitVec3P getFaceNormal (int fx) const
Return the outward normal for the given face as a unit vector in the box frame. More...

void getFaceVertices (int fx, int v) const
A face has four vertices ordered counterclockwise about the face normal. More...

void getVertexFaces (int vx, int f, int w) const
Each vertex has three incident faces. More...

void getEdgeVertices (int ex, int v) const
An edge connects two vertices. More...

void getVertexEdges (int vx, int e, int w) const
Each vertex has three incident edges. More...

void getFaceEdges (int fx, int e) const
A face has four edges, ordered by the vertex ordering: v0-v1, v1-v2, v2-v3, v3-v1. More...

void getEdgeFaces (int ex, int f, int w) const
An edge is between two faces. More...

static int getNumVertices ()
Use bits in the vertex number to pick the signs, with 0=negative, 1=positive: More...

static int getNumEdges ()
Use bits in the vertex number to pick the signs, with 0=negative, 1=positive: More...

static int getNumFaces ()
Use bits in the vertex number to pick the signs, with 0=negative, 1=positive: More...

## Detailed Description

### template<class P> class SimTK::Geo::Box_< P >

A 3d rectangular box aligned with an unspecified frame F and centered at that frame's origin.

The box has a local frame B, centered at the box center and oriented along the box edges, and B==F. We keep track of the relative edge lengths to facilitate short-to-long processing.

## ◆ Box_() [1/2]

template<class P >
 SimTK::Geo::Box_< P >::Box_ ( )
inline

Construct an uninitialized Box object; the dimensions will be garbage.

## ◆ Box_() [2/2]

template<class P >
 SimTK::Geo::Box_< P >::Box_ ( const Vec3P & halfLengths )
inline

Construct a Box with the given nonnegative half-dimensions.

Cost is 4 flops to sort the edges.

## ◆ setHalfLengths()

template<class P >
 Box_& SimTK::Geo::Box_< P >::setHalfLengths ( const Vec3P & halfLengths )
inline

Change the half-dimensions of this box.

Dimensions must be nonnegative. Cost is 4 flops to sort the edges.

template<class P >
 Box_& SimTK::Geo::Box_< P >::addToHalfLengths ( const Vec3P & incr )
inline

Change the half-dimensions of this box by adding the given vector.

The result must be nonnegative. Cost is 7 flops, including resorting the edges.

## ◆ getHalfLengths()

template<class P >
 const Vec3P& SimTK::Geo::Box_< P >::getHalfLengths ( ) const
inline

Return the half-lengths of this box as a Vec3 from the center to the first quadrant vertex.

## ◆ getOrderedHalfLength()

template<class P >
 RealP SimTK::Geo::Box_< P >::getOrderedHalfLength ( int i ) const
inline

Get lengths in order shortest to longest; 0 is shortest, 2 is longest.

## ◆ getOrderedAxis()

template<class P >
 CoordinateAxis SimTK::Geo::Box_< P >::getOrderedAxis ( int i ) const
inline

Get axes in order shortest to longest; 0 is shortest, 2 is longest.

## ◆ findVolume()

template<class P >
 RealP SimTK::Geo::Box_< P >::findVolume ( ) const
inline

Calculate the volume of this box.

Cost is 4 flops.

## ◆ findArea()

template<class P >
 RealP SimTK::Geo::Box_< P >::findArea ( ) const
inline

Calculate the surface area of this box, ignoring degeneracy (meaning that all pairs of sides are counted even if coincident).

Cost is 6 flops.

## ◆ containsPoint()

template<class P >
 bool SimTK::Geo::Box_< P >::containsPoint ( const Vec3P & pt ) const
inline

Given a point measured and expressed in the box frame, determine whether it is inside the box (we count touching the surface as inside).

The point must be measured from the box center. Cost is about 5 flops.

## ◆ findClosestPointOfSolidBox()

template<class P >
 Vec3P SimTK::Geo::Box_< P >::findClosestPointOfSolidBox ( const Vec3P & pt, bool & ptWasInside ) const
inline

Given a point location in the box frame, return the closest point of the solid box, and a flag saying whether the given point was inside the box, using the same definition of "inside" as the containsPoint() method.

Here we define the closest point to an inside point to be the point itself. Cost is about 9 flops.

## ◆ findClosestPointOnSurface()

template<class P >
 Vec3P SimTK::Geo::Box_< P >::findClosestPointOnSurface ( const Vec3P & pt, bool & ptWasInside ) const
inline

Given a point location in the box frame, return the closest point on the box surface, and a flag saying whether the given point was inside the box, using the same definition of "inside" as the containsPoint() method.

Cost is about 9 flops for outside points, 18 for inside points.

## ◆ findDistanceSqrToPoint()

template<class P >
 RealP SimTK::Geo::Box_< P >::findDistanceSqrToPoint ( const Vec3P & pt ) const
inline

Return the square of the distance from this box to a given point whose location is measured from and expressed in the box frame (at the box center).

If the point is on or inside the box the returned distance is zero. Cost is about 14 flops.

## ◆ findSupportPoint()

template<class P >
 Vec3P SimTK::Geo::Box_< P >::findSupportPoint ( const Vec3 & d ) const
inline

Find a supporting point on the surface of the box in the given direction, which must be expressed in the box frame.

The direction vector does not have to be a unit vector. The returned point will always be one of the eight vertices; we treat zeroes here as positive. Consequently if the input vector is exactly zero, the vertex in the positive orthant is returned as it would be if the input direction were (1,1,1). Cost is about 5 flops.

## ◆ findDistanceSqrToSphere()

template<class P >
 RealP SimTK::Geo::Box_< P >::findDistanceSqrToSphere ( const Geo::Sphere_< P > & sphere ) const
inline

Return the square of the distance from this box to a given sphere whose center location is measured from and expressed in the box frame (at the box center).

If the sphere intersects the box the returned distance is zero. Cost is about 17 flops.

## ◆ findDistanceSqrToAlignedBox()

template<class P >
 RealP SimTK::Geo::Box_< P >::findDistanceSqrToAlignedBox ( const Geo::AlignedBox_< P > & aab ) const
inline

Return the square of the distance from this box to an axis-aligned box whose center location is measured from and expressed in this box frame (at the box center).

If the boxes intersect the returned distance is zero. Cost is about 17 flops.

## ◆ intersectsSphere()

template<class P >
 bool SimTK::Geo::Box_< P >::intersectsSphere ( const Geo::Sphere_< P > & sphere ) const
inline

Given a sphere with center measured and expressed in the box frame, return true if the box and sphere intersect.

We are treating both objects as solids, so we'll say yes even if one object completely contains the other. We also return true if they are just touching. Cost is about 8 flops.

## ◆ intersectsAlignedBox()

template<class P >
 bool SimTK::Geo::Box_< P >::intersectsAlignedBox ( const Geo::AlignedBox_< P > & aab ) const
inline

Given an aligned box with center measured and expressed in the from of this box, return true if the two boxes intersect.

We are treating both objects as solids, so we'll say yes even if one box completely contains the other. We also return true if they are just touching. Cost is about 8 flops.

## ◆ intersectsOrientedBox()

template<class P >
 bool SimTK::Geo::Box_< P >::intersectsOrientedBox ( const Geo::OrientedBox_< P > & ob ) const

Given an oriented box whose pose is measured and expressed in the frame of this box, return true if the two boxes intersect.

We are treating both objects as solids, so we'll say yes even if one box completely contains the other. We also return true if they are just touching. This is an exact but fairly expensive test if the boxes are separated; if you don't mind some false positives, use mayIntersectOrientedBox() instead. Cost is about 200 flops worst case (when boxes are intersecting) although it can return `false` in as few as 16 flops.

## ◆ mayIntersectOrientedBox()

template<class P >
 bool SimTK::Geo::Box_< P >::mayIntersectOrientedBox ( const Geo::OrientedBox_< P > & ob ) const

Given an oriented box whose pose is measured and expressed in the frame of this box, return true if the two boxes may be intersecting.

Only relatively cheap operations are performed at the expense of returning false positives sometimes (allegedly less than 10% of the time). If you need an exact determination, use intersectsOrientedBox(). Cost is about 75 flops worst case (when boxes appear to be intersecting) but can return `false` in as few as 16 flops.

## ◆ getNumVertices()

template<class P >
 static int SimTK::Geo::Box_< P >::getNumVertices ( )
inlinestatic

Use bits in the vertex number to pick the signs, with 0=negative, 1=positive:

```    000  -hx -hy -hz
001  -hx -hy  hz
...
111   hx  hy  hz
```

## ◆ getNumEdges()

template<class P >
 static int SimTK::Geo::Box_< P >::getNumEdges ( )
inlinestatic

Use bits in the vertex number to pick the signs, with 0=negative, 1=positive:

```    000  -hx -hy -hz
001  -hx -hy  hz
...
111   hx  hy  hz
```

## ◆ getNumFaces()

template<class P >
 static int SimTK::Geo::Box_< P >::getNumFaces ( )
inlinestatic

Use bits in the vertex number to pick the signs, with 0=negative, 1=positive:

```    000  -hx -hy -hz
001  -hx -hy  hz
...
111   hx  hy  hz
```

## ◆ getVertexPos()

template<class P >
 Vec3P SimTK::Geo::Box_< P >::getVertexPos ( int vx ) const
inline

Use bits in the vertex number to pick the signs, with 0=negative, 1=positive:

```    000  -hx -hy -hz
001  -hx -hy  hz
...
111   hx  hy  hz
```

## ◆ findSupportVertex()

template<class P >
 int SimTK::Geo::Box_< P >::findSupportVertex ( const Vec3P & d ) const
inline

Find the vertex (0-7) that is furthest in the direction d, which is given in the box frame.

Zero coordinates in d are treated as though positive.

## ◆ getVertexNormal()

template<class P >
 UnitVec3P SimTK::Geo::Box_< P >::getVertexNormal ( int vx ) const
inline

Vertex normals point diagonally outwards from the box corners.

These are unit vectors with each coordinate +/- 1/sqrt(3).

## ◆ getEdgeCenter()

template<class P >
 Vec3P SimTK::Geo::Box_< P >::getEdgeCenter ( int ex ) const
inline

Return the center point of the specified edge, in the box frame.

## ◆ getEdgeNormal()

template<class P >
 UnitVec3P SimTK::Geo::Box_< P >::getEdgeNormal ( int ex ) const
inline

Edge normals point diagonally outwards from the edge.

These are unit vectors with one coordinate zero and the others +/- 1/sqrt(2).

## ◆ getEdgeCoordinateDirection()

template<class P >
 CoordinateDirection SimTK::Geo::Box_< P >::getEdgeCoordinateDirection ( int ex ) const
inline

Return the direction of an edge, going from its first vertex to its second vertex, as a CoordinateDirection.

## ◆ getEdgeDirection()

template<class P >
 UnitVec3P SimTK::Geo::Box_< P >::getEdgeDirection ( int ex ) const
inline

Return a unit vector aligned with the selected edge, pointing in the direction from the first vertex towards the second vertex, in the box frame.

For a box, all edges are aligned with the coordinate system axes so the returned vector will have only one non-zero component which will be 1 or -1.

## ◆ getFaceCoordinateDirection()

template<class P >
 CoordinateDirection SimTK::Geo::Box_< P >::getFaceCoordinateDirection ( int fx ) const
inline

Return the outward normal for the given face as a CoordinateDirection.

## ◆ getFaceCenter()

template<class P >
 Vec3P SimTK::Geo::Box_< P >::getFaceCenter ( int fx ) const
inline

Return the center point position for the given face.

This will be a vector with one non-zero component of magnitude equal to one of the box half-dimensions, with the appropriate sign.

## ◆ getFaceNormal()

template<class P >
 UnitVec3P SimTK::Geo::Box_< P >::getFaceNormal ( int fx ) const
inline

Return the outward normal for the given face as a unit vector in the box frame.

This will have only one non-zero component which will be 1 or -1.

## ◆ getFaceVertices()

template<class P >
 void SimTK::Geo::Box_< P >::getFaceVertices ( int fx, int v ) const
inline

A face has four vertices ordered counterclockwise about the face normal.

## ◆ getVertexFaces()

template<class P >
 void SimTK::Geo::Box_< P >::getVertexFaces ( int vx, int f, int w ) const
inline

Each vertex has three incident faces.

Return the face numbers (0-5) and which of the four face vertices is this one (0-3).

## ◆ getEdgeVertices()

template<class P >
 void SimTK::Geo::Box_< P >::getEdgeVertices ( int ex, int v ) const
inline

An edge connects two vertices.

## ◆ getVertexEdges()

template<class P >
 void SimTK::Geo::Box_< P >::getVertexEdges ( int vx, int e, int w ) const
inline

Each vertex has three incident edges.

Return the edge numbers (0-11) and which of the two edge vertices is this one (0-1).

## ◆ getFaceEdges()

template<class P >
 void SimTK::Geo::Box_< P >::getFaceEdges ( int fx, int e ) const
inline

A face has four edges, ordered by the vertex ordering: v0-v1, v1-v2, v2-v3, v3-v1.

## ◆ getEdgeFaces()

template<class P >
 void SimTK::Geo::Box_< P >::getEdgeFaces ( int ex, int f, int w ) const
inline

An edge is between two faces.

Return the face numbers (0-5) and which one of the four edges on each face is this edge (0-3).

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