Class Sphere
- All Implemented Interfaces:
Region<Vector3D>
,Sized
,Linecastable3D
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
Internal class used to construct geodesic mesh sphere approximations.private static final class
Internal class used to construct hyperplane-bounded approximations of spheres as BSP trees. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final double
Constant equal to4 * pi
.private static final double
Constant equal to(4/3) * pi
.private static final String
Message used when requesting a sphere approximation with an invalid subdivision number. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfirstIntersection
(Line3D line) Get the first intersection point between the given line and this sphere, or null if no such point exists.static Sphere
from
(Vector3D center, double radius, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a sphere from a center point and radius.double
Get the size of the boundary of the region.private Stream
<LinecastPoint3D> getLinecastStream
(LineConvexSubset3D subset) Get a stream containing the linecast intersection points of the given line subset with this instance.double
getSize()
Get the size of the instance.intersections
(Line3D line) Get the intersections of the given line with this sphere.linecast
(LineConvexSubset3D subset) Intersect the given line convex subset against the boundaries in this instance, returning a list of all intersections in order of increasing distance along the line.linecastFirst
(LineConvexSubset3D subset) Intersect the given line convex subset against the boundaries in this instance, returning the first intersection found when traveling in the direction of the line subset from its start point.Project a point onto the boundary of the region.toTree
(int subdivisions) Build an approximation of this sphere using aRegionBSPTree3D
.toTriangleMesh
(int subdivisions) Build an approximation of this sphere using aTriangleMesh
.Methods inherited from class org.apache.commons.geometry.euclidean.AbstractNSphere
classify, equals, firstIntersection, getCenter, getCentroid, getPrecision, getRadius, hashCode, intersections, isEmpty, isFull, project, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.commons.geometry.euclidean.threed.line.Linecastable3D
linecast, linecastFirst
Methods inherited from interface org.apache.commons.geometry.core.Sized
isFinite, isInfinite
-
Field Details
-
INVALID_SUBDIVISION_MESSAGE
Message used when requesting a sphere approximation with an invalid subdivision number.- See Also:
-
FOUR_PI
private static final double FOUR_PIConstant equal to4 * pi
.- See Also:
-
FOUR_THIRDS_PI
private static final double FOUR_THIRDS_PIConstant equal to(4/3) * pi
.- See Also:
-
-
Constructor Details
-
Sphere
private Sphere(Vector3D center, double radius, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a new sphere from its component parts.- Parameters:
center
- the center of the sphereradius
- the sphere radiusprecision
- precision context used to compare floating point numbers- Throws:
IllegalArgumentException
- if center is not finite or radius is not finite or is less than or equal to zero as evaluated by the given precision context
-
-
Method Details
-
getSize
public double getSize()Get the size of the instance. -
getBoundarySize
public double getBoundarySize()Get the size of the boundary of the region. The size is a value in thed-1
dimension space. For example, in Euclidean space, this will be a length in 2D and an area in 3D.- Specified by:
getBoundarySize
in interfaceRegion<Vector3D>
- Returns:
- the size of the boundary of the region
-
project
-
toTree
Build an approximation of this sphere using aRegionBSPTree3D
. The approximation is constructed by taking an octahedron (8-sided polyhedron with triangular faces) inscribed in the sphere and subdividing each triangular facesubdivisions
number of times, each time projecting the newly created vertices onto the sphere surface. Each triangle subdivision produces 4 triangles, meaning that the total number of triangles inserted into tree is equal to \(8 \times 4^s\), where \(s\) is the number of subdivisions. For example, calling this method withsubdivisions
equal to3
will produce a tree having \(8 \times 4^3 = 512\) triangular facets inserted. See the table below for other examples. The returned BSP tree also contains structural cuts to reduce the overall height of the tree.Subdivisions to Triangle Counts Subdivisions Triangles 0 8 1 32 2 128 3 512 4 2048 5 8192 Care must be taken when using this method with large subdivision numbers so that floating point errors do not interfere with the creation of the planes and triangles in the tree. For example, if the number of subdivisions is too high, the subdivided triangle points may become equivalent according to the sphere's
precision context
and plane creation may fail. Or plane creation may succeed but insertion of the plane into the tree may fail for similar reasons. In general, it is best to use the lowest subdivision number practical for the intended purpose.- Parameters:
subdivisions
- the number of triangle subdivisions to use when creating the tree; the total number of triangular facets inserted into the returned tree is equal to \(8 \times 4^s\), where \(s\) is the number of subdivisions- Returns:
- a BSP tree containing an approximation of the sphere
- Throws:
IllegalArgumentException
- ifsubdivisions
is less than zeroIllegalStateException
- if tree creation fails for the given subdivision count- See Also:
-
toTriangleMesh
Build an approximation of this sphere using aTriangleMesh
. The approximation is constructed by taking an octahedron (8-sided polyhedron with triangular faces) inscribed in the sphere and subdividing each triangular facesubdivisions
number of times, each time projecting the newly created vertices onto the sphere surface. Each triangle subdivision produces 4 triangles, meaning that the total number of triangles in the returned mesh is equal to \(8 \times 4^s\), where \(s\) is the number of subdivisions. For example, calling this method withsubdivisions
equal to3
will produce a mesh having \(8 \times 4^3 = 512\) triangular facets inserted. See the table below for other examples.Subdivisions to Triangle Counts Subdivisions Triangles 0 8 1 32 2 128 3 512 4 2048 5 8192 BSP Tree Conversion
Inserting the boundaries of a sphere mesh approximation directly into a BSP tree will invariably result in poor performance: since the region is convex the constructed BSP tree degenerates into a simple linked list of nodes. If a BSP tree is needed, users should prefer the
toTree(int)
method, which creates balanced tree approximations directly, or theRegionBSPTree3D.PartitionedRegionBuilder3D
class, which can be used to insert the mesh faces into a pre-partitioned tree.- Parameters:
subdivisions
- the number of triangle subdivisions to use when creating the mesh; the total number of triangular faces in the returned mesh is equal to \(8 \times 4^s\), where \(s\) is the number of subdivisions- Returns:
- a triangle mesh approximation of the sphere
- Throws:
IllegalArgumentException
- ifsubdivisions
is less than zero- See Also:
-
intersections
Get the intersections of the given line with this sphere. The returned list will contain either 0, 1, or 2 points.- 2 points - The line is a secant line and intersects the sphere at two distinct points. The points are ordered such that the first point in the list is the first point encountered when traveling in the direction of the line. (In other words, the points are ordered by increasing abscissa value.)
- 1 point - The line is a tangent line and only intersects the sphere at a single point (as evaluated by the sphere's precision context).
- 0 points - The line does not intersect the sphere.
- Parameters:
line
- line to intersect with the sphere- Returns:
- a list of intersection points between the given line and this sphere
-
firstIntersection
Get the first intersection point between the given line and this sphere, or null if no such point exists. The "first" intersection point is the first such point encountered when traveling in the direction of the line from infinity.- Parameters:
line
- line to intersect with the sphere- Returns:
- the first intersection point between the given line and this instance or null if no such point exists
-
linecast
Intersect the given line convex subset against the boundaries in this instance, returning a list of all intersections in order of increasing distance along the line. An empty list is returned if no intersections are discovered.- Specified by:
linecast
in interfaceLinecastable3D
- Parameters:
subset
- line subset to intersect- Returns:
- a list of computed intersections in order of increasing distance along the line
-
linecastFirst
Intersect the given line convex subset against the boundaries in this instance, returning the first intersection found when traveling in the direction of the line subset from its start point.- Specified by:
linecastFirst
in interfaceLinecastable3D
- Parameters:
subset
- line subset to intersect- Returns:
- the first intersection found or null if no intersection is found
-
getLinecastStream
Get a stream containing the linecast intersection points of the given line subset with this instance.- Parameters:
subset
- line subset to intersect against this instance- Returns:
- a stream containing linecast intersection points
-
from
public static Sphere from(Vector3D center, double radius, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a sphere from a center point and radius.- Parameters:
center
- the center of the sphereradius
- the sphere radiusprecision
- precision context used to compare floating point numbers- Returns:
- a sphere constructed from the given center point and radius
- Throws:
IllegalArgumentException
- if center is not finite or radius is not finite or is less than or equal to zero as evaluated by the given precision context
-