Class Sphere
- java.lang.Object
-
- org.apache.commons.geometry.euclidean.AbstractNSphere<Vector3D>
-
- org.apache.commons.geometry.euclidean.threed.shape.Sphere
-
- All Implemented Interfaces:
Region<Vector3D>
,Sized
,Linecastable3D
public final class Sphere extends AbstractNSphere<Vector3D> implements Linecastable3D
Class representing a 3 dimensional sphere in Euclidean space.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Sphere.SphereMeshApproximationBuilder
Internal class used to construct geodesic mesh sphere approximations.private static class
Sphere.SphereTreeApproximationBuilder
Internal class used to construct hyperplane-bounded approximations of spheres as BSP trees.
-
Field Summary
Fields Modifier and Type Field Description private static double
FOUR_PI
Constant equal to4 * pi
.private static double
FOUR_THIRDS_PI
Constant equal to(4/3) * pi
.private static java.lang.String
INVALID_SUBDIVISION_MESSAGE
Message used when requesting a sphere approximation with an invalid subdivision number.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Vector3D
firstIntersection(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
getBoundarySize()
Get the size of the boundary of the region.private java.util.stream.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.java.util.List<Vector3D>
intersections(Line3D line)
Get the intersections of the given line with this sphere.java.util.List<LinecastPoint3D>
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.LinecastPoint3D
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.Vector3D
project(Vector3D pt)
Project a point onto the boundary of the region.RegionBSPTree3D
toTree(int subdivisions)
Build an approximation of this sphere using aRegionBSPTree3D
.TriangleMesh
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 Detail
-
INVALID_SUBDIVISION_MESSAGE
private static final java.lang.String INVALID_SUBDIVISION_MESSAGE
Message used when requesting a sphere approximation with an invalid subdivision number.- See Also:
- Constant Field Values
-
FOUR_PI
private static final double FOUR_PI
Constant equal to4 * pi
.- See Also:
- Constant Field Values
-
FOUR_THIRDS_PI
private static final double FOUR_THIRDS_PI
Constant equal to(4/3) * pi
.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
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:
java.lang.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 Detail
-
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
-
toTree
public RegionBSPTree3D toTree(int subdivisions)
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:
java.lang.IllegalArgumentException
- ifsubdivisions
is less than zerojava.lang.IllegalStateException
- if tree creation fails for the given subdivision count- See Also:
toTriangleMesh(int)
-
toTriangleMesh
public TriangleMesh toTriangleMesh(int subdivisions)
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:
java.lang.IllegalArgumentException
- ifsubdivisions
is less than zero- See Also:
toTree(int)
-
intersections
public java.util.List<Vector3D> intersections(Line3D line)
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
public Vector3D firstIntersection(Line3D line)
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
public java.util.List<LinecastPoint3D> 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. 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
public LinecastPoint3D 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.- Specified by:
linecastFirst
in interfaceLinecastable3D
- Parameters:
subset
- line subset to intersect- Returns:
- the first intersection found or null if no intersection is found
-
getLinecastStream
private java.util.stream.Stream<LinecastPoint3D> getLinecastStream(LineConvexSubset3D subset)
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:
java.lang.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
-
-