gov.nasa.worldwind.geom
Class Box

java.lang.Object
  gov.nasa.worldwind.geom.Box

All Implemented Interfaces:

Extent, Renderable

public class Box
extends Object
implements Extent, Renderable

An arbitrarily oriented box, typically used as a oriented bounding volume for a collection of points or shapes. A Box is defined by three orthogonal axes and two positions along each of those axes. Each of the positions specifies the location of a box side along the respective axis. The three axes are named by convention "R", "S" and "T", and are ordered by decreasing length -- R is the longest axis, followed by S and then T.

Field Summary

Vec4	bottomCenter
protected Vec4	center
protected Plane[]	planes
protected static int[][]	ProjectionHullTable ProjectionHullTable defines a table of all possible vertex combinations representing a Box's 2D convex hull in screen coordinates.
protected Vec4	r
protected double	rLength
protected Vec4	ru
protected Vec4	s
protected double	sLength
protected Vec4	su
protected Vec4	t
protected double	tLength
Vec4	topCenter
protected Vec4	tu

Constructor Summary

	Box(Vec4 point) Construct a unit-length cube centered at a specified point.
	Box(Vec4[] axes, double rMin, double rMax, double sMin, double sMax, double tMin, double tMax) Construct a box from three specified unit axes and the locations of the box faces relative to those axes.
protected	Box(Vec4 bottomCenter, Vec4 topCenter, Vec4 center, Vec4 r, Vec4 s, Vec4 t, Vec4 ru, Vec4 su, Vec4 tu, double rlength, double sLength, double tLength, Plane[] planes)

Method Summary

static Box	computeBoundingBox(BufferWrapper coordinates, int stride) Computes a Box that bounds a specified buffer of points.
static Box	computeBoundingBox(Iterable<? extends Vec4> points) Compute a Box that bounds a specified list of points.
protected int	computeProjectionHullCode(View view) Computes an index into the ProjectionHullTable for this Box given the specified view.
protected void	drawBox(DrawContext dc, Vec4 a, Vec4 b, Vec4 c, Vec4 d)
protected void	drawOutline(DrawContext dc, Vec4 a, Vec4 b, Vec4 c, Vec4 d)
boolean	equals(Object o)
Vec4	getBottomCenter() Returns the point corresponding to the center of the box side left-most along the R (first) axis.
Vec4	getCenter() Returns the box's center point.
Vec4[]	getCorners() Returns the eight corners of the box.
double	getDiameter() Returns the effective diameter of the box as if it were a sphere.
double	getEffectiveRadius(Plane plane) Computes the effective radius of the extent relative to a specified plane.
protected double	getEffectiveRadius2(Plane plane) Returns the effective radius of this box relative to a specified plane, using only this box's S and T axes.
Plane[]	getPlanes() Returns the six planes of the box.
double	getProjectedArea(View view) Computes the area in square pixels of this Extent after it is projected into the specified view's viewport.
double	getRadius() Returns the effective radius of the box as if it were a sphere.
Vec4	getRAxis() Returns the R (first) axis.
double	getRLength() Returns the length of the R axis.
Vec4	getSAxis() Returns the S (second) axis.
double	getSLength() Returns the length of the S axis.
Vec4	getTAxis() Returns the T (third) axis.
double	getTLength() Returns the length of the T axis.
Vec4	getTopCenter() Returns the point corresponding to the center of the box side right-most along the R (first) axis.
Vec4	getUnitRAxis() Returns the R (first) axis in unit length.
Vec4	getUnitSAxis() Returns the S (second) axis in unit length.
Vec4	getUnitTAxis() Returns the T (third) axis in unit length.
int	hashCode()
Intersection[]	intersect(Line line) Computes the intersections of this extent with line.
boolean	intersects(Frustum frustum) Determines whether or not this Extent intersects frustum.
boolean	intersects(Line line) Determines whether or not line intersects this Extent.
boolean	intersects(Plane plane) Calculate whether or not this Extent is intersected by plane.
protected double	intersects(Plane plane, double effectiveRadius)
protected double	intersectsAt(Plane plane, double effectiveRadius, Vec4[] endpoints)
void	render(DrawContext dc) Draws a representation of the Box.
Box	translate(Vec4 point)
static Box	union(Iterable<? extends Box> iterable) Computes a Box that represents the union of one or more Boxes.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

bottomCenter

public Vec4 bottomCenter

center

protected final Vec4 center

planes

protected final Plane[] planes

ProjectionHullTable

protected static final int[][] ProjectionHullTable

ProjectionHullTable defines a table of all possible vertex combinations representing a Box's 2D convex hull in screen coordinates. The index to this table is a 6-bit code, where each bit denotes whether one of the Box's six planes faces the View. This code is organized as follows:

Bit	5	4	3	2	1	0
Code	left	right	back	front	bottom	top

Since at most three of a Box's planes can be visible at one time, there are a total of 26 unique vertex combinations that define a Box's 2D convex hull in the viewport. Index codes that represent a valid combination of planes facing the View result in an array of 4 or 6 integers (depending on whether one, two or three planes face the View), where each element in the array is an index for one of the Box's eight vertices as follows:

Index	0	1	2	3	4	5	6	7
Vertex	bottom-lower-left	bottom-lower-right	bottom-upper-right	bottom-upper-left	top-lower-left	top-lower-right	top-upper-right	top-upper-left

The vertices are organized so that they appear in counter-clockwise order on the screen. Index codes that represent an invalid combination of planes facing the View map to null.

r

protected final Vec4 r

rLength

protected final double rLength

ru

protected final Vec4 ru

s

protected final Vec4 s

sLength

protected final double sLength

su

protected final Vec4 su

t

protected final Vec4 t

tLength

protected final double tLength

topCenter

public Vec4 topCenter

tu

protected final Vec4 tu

Constructor Detail

Box

public Box(Vec4 point)

Construct a unit-length cube centered at a specified point.

Parameters:

point - the center of the cube.

Throws:

IllegalArgumentException - if the point is null.

Box

public Box(Vec4[] axes,
           double rMin,
           double rMax,
           double sMin,
           double sMax,
           double tMin,
           double tMax)

Construct a box from three specified unit axes and the locations of the box faces relative to those axes. The box faces are specified by two scalar locations along each axis, each location indicating a face. The non-unit length of an axis is the distance between its respective two locations. The longest side is specified first, followed by the second longest side and then the shortest side.

The axes are normally principal axes computed from a collection of points in order to form an oriented bounding volume. See WWMath.computePrincipalAxes(Iterable).

Note: No check is made to ensure the order of the face locations.

Parameters:

axes - the unit-length axes.

rMin - the location along the first axis corresponding to the left-most box side relative to the axis.

rMax - the location along the first axis corresponding to the right-most box side relative to the axis.

sMin - the location along the second axis corresponding to the left-most box side relative to the axis.

sMax - the location along the second axis corresponding to the right-most box side relative to the axis.

tMin - the location along the third axis corresponding to the left-most box side relative to the axis.

tMax - the location along the third axis corresponding to the right-most box side relative to the axis.

Throws:

IllegalArgumentException - if the axes array or one of its entries is null.

Box

protected Box(Vec4 bottomCenter,
              Vec4 topCenter,
              Vec4 center,
              Vec4 r,
              Vec4 s,
              Vec4 t,
              Vec4 ru,
              Vec4 su,
              Vec4 tu,
              double rlength,
              double sLength,
              double tLength,
              Plane[] planes)

Method Detail

computeBoundingBox

public static Box computeBoundingBox(BufferWrapper coordinates,
                                     int stride)

Computes a Box that bounds a specified buffer of points. Principal axes are computed for the points and used to form a Box.

The buffer must contain XYZ coordinate tuples which are either tightly packed or offset by the specified stride. The stride specifies the number of buffer elements between the first coordinate of consecutive tuples. For example, a stride of 3 specifies that each tuple is tightly packed as XYZXYZXYZ, whereas a stride of 5 specifies that there are two elements between each tuple as XYZabXYZab (the elements "a" and "b" are ignored). The stride must be at least 3. If the buffer's length is not evenly divisible into stride-sized tuples, this ignores the remaining elements that follow the last complete tuple.

Parameters:

coordinates - the buffer containing the point coordinates for which to compute a bounding volume.

stride - the number of elements between the first coordinate of consecutive points. If stride is 3, this interprets the buffer has having tightly packed XYZ coordinate tuples.

Returns:

the bounding volume, with axes lengths consistent with the conventions described in the Box class overview.

Throws:

IllegalArgumentException - if the buffer is null or empty, or if the stride is less than three.

computeBoundingBox

public static Box computeBoundingBox(Iterable<? extends Vec4> points)

Compute a Box that bounds a specified list of points. Principal axes are computed for the points and used to form a Box.

Parameters:

points - the points for which to compute a bounding volume.

Returns:

the bounding volume, with axes lengths consistent with the conventions described in the Box class overview.

Throws:

IllegalArgumentException - if the point list is null or empty.

computeProjectionHullCode

protected int computeProjectionHullCode(View view)

Computes an index into the ProjectionHullTable for this Box given the specified view. The returned integer is a 6-bit code, where each bit denotes whether one of this Box's six planes faces the View. See the documentation for ProjectionHullTable for details.

If the view is inside this Box, this returns 0 indicating that none of this Box's planes face the view.

Parameters:

view - the View to compute a lookup index for.

Returns:

an integer who's first 6 bits define an index into the ProjectionHullTable.

drawBox

protected void drawBox(DrawContext dc,
                       Vec4 a,
                       Vec4 b,
                       Vec4 c,
                       Vec4 d)

drawOutline

protected void drawOutline(DrawContext dc,
                           Vec4 a,
                           Vec4 b,
                           Vec4 c,
                           Vec4 d)

equals

public boolean equals(Object o)

Overrides:

equals in class Object

getBottomCenter

public Vec4 getBottomCenter()

Returns the point corresponding to the center of the box side left-most along the R (first) axis.

Returns:

the bottom-center point.

getCenter

public Vec4 getCenter()

Returns the box's center point.

Specified by:

getCenter in interface Extent

Returns:

the box's center point.

getCorners

public Vec4[] getCorners()

Returns the eight corners of the box.

Returns:

the eight box corners in the order bottom-lower-left, bottom-lower-right, bottom-upper-right, bottom-upper-left, top-lower-left, top-lower-right, top-upper-right, top-upper-left.

getDiameter

public double getDiameter()

Returns the effective diameter of the box as if it were a sphere. The length returned is the square root of the sum of the squares of axis lengths.

Specified by:

getDiameter in interface Extent

Returns:

the effective diameter of the box.

getEffectiveRadius

public double getEffectiveRadius(Plane plane)

Computes the effective radius of the extent relative to a specified plane.

Specified by:

getEffectiveRadius in interface Extent

Parameters:

plane - the plane.

Returns:

the effective radius, or 0 if the plane is null.

getEffectiveRadius2

protected double getEffectiveRadius2(Plane plane)

Returns the effective radius of this box relative to a specified plane, using only this box's S and T axes. This is an optimization available when using the effective radius to test the distance from a plane to the line segment along this box's R axis, as is done in this class' intersects(Frustum) method. See Lengyel, 2 Ed, Section 7.2.4.

Parameters:

plane - the plane in question.

Returns:

the effective radius of this box relative to the specified plane, using only this box's S and T axes to determine the effective radius.

getPlanes

public Plane[] getPlanes()

Returns the six planes of the box. The plane normals are directed outwards from the box.

Returns:

the six box planes in the order R-min, R-max, S-min, S-max, T-min, T-max.

getProjectedArea

public double getProjectedArea(View view)

Computes the area in square pixels of this Extent after it is projected into the specified view's viewport. The returned value is the screen area that this Extent covers in the infinite plane defined by the view's viewport. This area is not limited to the size of the view's viewport, and portions of this Extent are not clipped by the view's frustum.

This returns Double.POSITIVE_INFINITY if the view's eye point is inside this Extent, or if any portion of this Extent is behind the eye point. In either case, this Extent has no finite projection on the view.

Specified by:

getProjectedArea in interface Extent

Parameters:

view - the View for which to compute a projected screen area.

Returns:

the projected screen area of this Extent in square pixels, or Double.POSITIVE_INFINITY if the view's eye point is inside this Extent or part of this Extent is behind the view's eye point.

getRadius

public double getRadius()

Returns the effective radius of the box as if it were a sphere. The length returned is half the square root of the sum of the squares of axis lengths.

Specified by:

getRadius in interface Extent

Returns:

the effective radius of the box.

getRAxis

public Vec4 getRAxis()

Returns the R (first) axis. The axis length is the distance between the box sides perpendicular to the axis.

Returns:

the R axis.

getRLength

public double getRLength()

Returns the length of the R axis.

Returns:

the length of the R axis.

getSAxis

public Vec4 getSAxis()

Returns the S (second) axis. The axis length is the distance between the box sides perpendicular to the axis.

Returns:

the S axis.

getSLength

public double getSLength()

Returns the length of the S axis.

Returns:

the length of the S axis.

getTAxis

public Vec4 getTAxis()

Returns the T (third) axis. The axis length is the distance between the box sides perpendicular to the axis.

Returns:

the T axis.

getTLength

public double getTLength()

Returns the length of the T axis.

Returns:

the length of the T axis.

getTopCenter

public Vec4 getTopCenter()

Returns the point corresponding to the center of the box side right-most along the R (first) axis.

Returns:

the top-center point.

getUnitRAxis

public Vec4 getUnitRAxis()

Returns the R (first) axis in unit length.

Returns:

the unit R axis.

getUnitSAxis

public Vec4 getUnitSAxis()

Returns the S (second) axis in unit length.

Returns:

the unit S axis.

getUnitTAxis

public Vec4 getUnitTAxis()

Returns the T (third) axis in unit length.

Returns:

the unit T axis.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

intersect

public Intersection[] intersect(Line line)

Computes the intersections of this extent with line. The returned array may be either null or of zero length if no intersections are discovered. It does not contain null elements. Tangential intersections are marked as such. line is considered to have infinite length in both directions.

Specified by:

intersect in interface Extent

Parameters:

line - the Line with which to intersect this Extent.

Returns:

an array of intersections representing all the points where line enters or leave this Extent.

intersects

public boolean intersects(Frustum frustum)

Determines whether or not this Extent intersects frustum. Returns true if any part of these two objects intersect, including the case where either object wholly contains the other, false otherwise.

Specified by:

intersects in interface Extent

Parameters:

frustum - the Frustum with which to test for intersection.

Returns:

true if there is an intersection, false otherwise.

intersects

public boolean intersects(Line line)

Determines whether or not line intersects this Extent. This method may be faster than checking the size of the array returned by intersect(Line). Implementing methods must ensure that this method returns true if and only if intersect(Line) returns a non-null array containing at least one element.

Specified by:

intersects in interface Extent

Parameters:

line - the Line with which to test for intersection.

Returns:

true if an intersection is found, false otherwise.

intersects

public boolean intersects(Plane plane)

Calculate whether or not this Extent is intersected by plane.

Specified by:

intersects in interface Extent

Parameters:

plane - the Plane with which to test for intersection.

Returns:

true if plane is found to intersect this Extent.

intersects

protected double intersects(Plane plane,
                            double effectiveRadius)

intersectsAt

protected double intersectsAt(Plane plane,
                              double effectiveRadius,
                              Vec4[] endpoints)

render

public void render(DrawContext dc)

Draws a representation of the Box.

Specified by:

render in interface Renderable

Parameters:

dc - the DrawContext to be used.

See Also:

DrawContext

translate

public Box translate(Vec4 point)

union

public static Box union(Iterable<? extends Box> iterable)

Computes a Box that represents the union of one or more Boxes. If the iterable has two or more non-null Boxes, the returned encloses the Boxes. In this case axes and center point of the returned Box may differ from the Boxes. If the iterable has only one non-null Box, this returns that sole Box. This returns null if the iterable is empty or contains only null references.

Parameters:

iterable - an iterable of Boxes to enclose.

Returns:

a new Box that encloses the specified iterable of Boxes.

Throws:

IllegalArgumentException - if the iterable is null.