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.
  • Field Details

    • INVALID_SUBDIVISION_MESSAGE

      private static final String INVALID_SUBDIVISION_MESSAGE
      Message used when requesting a sphere approximation with an invalid subdivision number.
      See Also:
    • FOUR_PI

      private static final double FOUR_PI
      Constant equal to 4 * pi.
      See Also:
    • FOUR_THIRDS_PI

      private static final double FOUR_THIRDS_PI
      Constant 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 sphere
      radius - the sphere radius
      precision - 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.
      Specified by:
      getSize in interface Sized
      Returns:
      the size of the instance
    • getBoundarySize

      public double getBoundarySize()
      Get the size of the boundary of the region. The size is a value in the d-1 dimension space. For example, in Euclidean space, this will be a length in 2D and an area in 3D.
      Specified by:
      getBoundarySize in interface Region<Vector3D>
      Returns:
      the size of the boundary of the region
    • project

      public Vector3D project(Vector3D pt)
      Project a point onto the boundary of the region. Null is returned if the region contains no boundaries (ie, is either full or empty).
      Specified by:
      project in interface Region<Vector3D>
      Parameters:
      pt - pt to project
      Returns:
      projection of the point on the boundary of the region or null if the region does not contain any boundaries
    • toTree

      public RegionBSPTree3D toTree(int subdivisions)
      Build an approximation of this sphere using a RegionBSPTree3D. The approximation is constructed by taking an octahedron (8-sided polyhedron with triangular faces) inscribed in the sphere and subdividing each triangular face subdivisions 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 with subdivisions equal to 3 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
      08
      132
      2128
      3512
      42048
      58192

      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 - if subdivisions is less than zero
      IllegalStateException - if tree creation fails for the given subdivision count
      See Also:
    • toTriangleMesh

      public TriangleMesh toTriangleMesh(int subdivisions)
      Build an approximation of this sphere using a TriangleMesh. The approximation is constructed by taking an octahedron (8-sided polyhedron with triangular faces) inscribed in the sphere and subdividing each triangular face subdivisions 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 with subdivisions equal to 3 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
      08
      132
      2128
      3512
      42048
      58192

      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 the RegionBSPTree3D.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 - if subdivisions is less than zero
      See Also:
    • intersections

      public 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 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 interface Linecastable3D
      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 interface Linecastable3D
      Parameters:
      subset - line subset to intersect
      Returns:
      the first intersection found or null if no intersection is found
    • getLinecastStream

      private 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 sphere
      radius - the sphere radius
      precision - 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