Package org.djutils.draw.bounds

Class Bounds3d

java.lang.Object
org.djutils.draw.bounds.Bounds3d
All Implemented Interfaces:
Iterable<Point3d>, Bounds<Bounds3d,Point3d>, Drawable<Point3d>, Drawable3d
public class Bounds3d extends Object implements Drawable3d, Bounds<Bounds3d,Point3d>
Bounds3d is the generic class for the 3D extent of an object. It is an immutable object.

Copyright (c) 2020-2025 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See DJUTILS License.

Author:
Alexander Verbraeck, Peter Knoppers, Wouter Schakel

  • Constructor Summary

    Constructors
    Constructor
    Description
    Bounds3d(double deltaX, double deltaY, double deltaZ)
    Constructs a new Bounds3d around the origin (0, 0, 0).
    Bounds3d(double minX, double maxX, double minY, double maxY, double minZ, double maxZ)
    Construct a Bounds3d by providing all lower and upper bounds.
    Bounds3d(Collection<Drawable3d> drawableCollection)
    Construct a Bounds3d for a Collection of Drawable2d objects.
    Bounds3d(Iterator<? extends Point3d> points)
    Construct a Bounds3d from some collection of points, finding the lowest and highest x and y coordinates.
    Bounds3d(Drawable3d drawable3d)
    Construct a Bounds3d for a Drawable3d.
    Bounds3d(Drawable3d... drawable3d)
    Construct a Bounds3d for several Drawable2d objects.
    Bounds3d(Point3d[] points)
    Construct a Bounds3d from an array of Point3d, finding the lowest and highest x, y and z coordinates.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    contains(double x, double y, double z)
    Check if this Bounds3d contains a point.
    boolean
    contains(Bounds3d otherBounds)
    Check if this Bounds completely contains another Bounds.
    boolean
    contains(Point3d point)
    Check if a point is contained in this Bounds.
    boolean
    covers(double x, double y, double z)
    Check if this Bounds3d contains a point.
    boolean
    covers(Bounds3d otherBounds)
    Check if no part of a Bounds is outside this Bounds.
    boolean
    covers(Point3d point)
    Check if this Bounds covers or touches a point.
    boolean
    disjoint(Bounds3d otherBounds)
    Return whether a Bounds is disjoint from this Bounds.
    (package private) static Iterator<Drawable3d>
    ensureHasOne(Iterator<Drawable3d> iterator)
    Verify that the iterator has something to return.
    (package private) static Drawable3d[]
    ensureHasOne(Drawable3d[] drawable3dArray)
    Verify that the array contains at least one entry.
    boolean
    equals(Object obj)
     
    Bounds3d
    getAbsoluteBounds()
    Retrieve the bounding box of the object in absolute coordinates.
    double
    getDeltaZ()
    Return the extent of this Bounds3d in the z-direction.
    double
    getMaxX()
    Return the absolute upper bound for x.
    double
    getMaxY()
    Return the absolute upper bound for y.
    double
    getMaxZ()
    Return the upper bound for z.
    double
    getMinX()
    Return the absolute lower bound for x.
    double
    getMinY()
    Return the absolute lower bound for y.
    double
    getMinZ()
    Return the lower bound for z.
    double
    getVolume()
    Return the volume of this Bounds3d.
    int
    hashCode()
     
    Bounds3d
    intersection(Bounds3d otherBounds3d)
    Return the intersecting Bounds of this Bounds and another Bounds.
    boolean
    intersects(Bounds3d otherBounds3d)
    Return whether this Bounds intersects another Bounds.
    Iterator<Point3d>
    iterator()
    After version 2.3.1, the order of the points returned by the iterator of a Bounds object is documented (and changed compared with earlier versions).
    Point3d
    midPoint()
    Return the mid point of this Bounds object.
    static Iterator<Point3d>
    pointsOf(Collection<Drawable3d> drawableCollection)
    Return an iterator that will return all points of one or more Drawable3d objects.
    static Iterator<Point3d>
    pointsOf(Drawable3d... drawable3d)
    Return an iterator that will return all points of one or more Drawable objects.
    Bounds2d
    project()
    Project the object onto the z=0 plane.
    int
    size()
    Retrieve the number of points that make up the object.
    String
    toString()
    Produce a string describing the Drawable using default conversion for the (double) coordinate values.
    String
    toString(String doubleFormat, boolean doNotIncludeClassName)
    Produce a String describing the Drawable.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.djutils.draw.bounds.Bounds

    getDeltaX, getDeltaY

    Methods inherited from interface org.djutils.draw.Drawable

    getPointList, toString, toString

    Methods inherited from interface org.djutils.draw.Drawable3d

    getDimensions

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Constructor Details

    • Bounds3d

      public Bounds3d(double minX, double maxX, double minY, double maxY, double minZ, double maxZ)
      Construct a Bounds3d by providing all lower and upper bounds.
      Parameters:
      minX - the lower bound for x
      maxX - the upper bound for x
      minY - the lower bound for y
      maxY - the upper bound for y
      minZ - the lower bound for z
      maxZ - the upper bound for z
      Throws:
      ArithmeticException - when minX, maxX, minY, maxY,minZ, or maxZ is NaN
      IllegalArgumentException - when minX > maxX, minY > maxY, or minZ > maxZ

    • Bounds3d

      public Bounds3d(double deltaX, double deltaY, double deltaZ)
      Constructs a new Bounds3d around the origin (0, 0, 0).
      Parameters:
      deltaX - the deltaX value around the origin
      deltaY - the deltaY value around the origin
      deltaZ - the deltaZ value around the origin
      Throws:
      ArithmeticException - when deltaX, deltaY, or deltaZ is NaN
      IllegalArgumentException - when deltaX < 0.0, deltaY < 0.0, or deltaZ < 0.0

    • Bounds3d

      public Bounds3d(Iterator<? extends Point3d> points)
      Construct a Bounds3d from some collection of points, finding the lowest and highest x and y coordinates.
      Parameters:
      points - the array of points to construct a Bounds3d from
      Throws:
      NullPointerException - when points is null
      IllegalArgumentException - when the points iterator provides zero points

    • Bounds3d

      public Bounds3d(Point3d[] points)
      Construct a Bounds3d from an array of Point3d, finding the lowest and highest x, y and z coordinates.
      Parameters:
      points - the points to construct a Bounds3d from
      Throws:
      NullPointerException - when points is null
      IllegalArgumentException - when zero points are provided

    • Bounds3d

      public Bounds3d(Drawable3d drawable3d) throws NullPointerException
      Construct a Bounds3d for a Drawable3d.
      Parameters:
      drawable3d - any object that implements the Drawable2d interface
      Throws:
      NullPointerException - when drawable3d is null

    • Bounds3d

      public Bounds3d(Drawable3d... drawable3d)
      Construct a Bounds3d for several Drawable2d objects.
      Parameters:
      drawable3d - the Drawable2d objects
      Throws:
      NullPointerException - when the drawable3d array is null, or contains a null value
      IllegalArgumentException - when the length of the drawable3d array is 0

    • Bounds3d

      public Bounds3d(Collection<Drawable3d> drawableCollection)
      Construct a Bounds3d for a Collection of Drawable2d objects.
      Parameters:
      drawableCollection - the collection
      Throws:
      NullPointerException - when the drawableCollection is null, or contains null values
      IllegalArgumentException - when the drawableCollection is empty

  • Method Details

    • pointsOf

      public static Iterator<Point3d> pointsOf(Drawable3d... drawable3d)
      Return an iterator that will return all points of one or more Drawable objects.
      Parameters:
      drawable3d - the Drawable objects
      Returns:
      iterator that will return all points of the Drawable objects
      Throws:
      NullPointerException - when drawable3darray is null
      IllegalArgumentException - when the drawable3dArray contains 0 elements

    • ensureHasOne

      static Drawable3d[] ensureHasOne(Drawable3d[] drawable3dArray)
      Verify that the array contains at least one entry.
      Parameters:
      drawable3dArray - array of Drawable2d objects
      Returns:
      the array
      Throws:
      NullPointerException - when the drawable3dArray is null
      IllegalArgumentException - when the drawable3dArray contains 0 elements

    • pointsOf

      public static Iterator<Point3d> pointsOf(Collection<Drawable3d> drawableCollection)
      Return an iterator that will return all points of one or more Drawable3d objects.
      Parameters:
      drawableCollection - the collection of Drawable2d objects
      Returns:
      iterator that will return all points of the Drawable objects
      Throws:
      NullPointerException - when the drawableCollection is null, or contains a null value
      IllegalArgumentException - when the drawableCollection is empty

    • ensureHasOne

      static Iterator<Drawable3d> ensureHasOne(Iterator<Drawable3d> iterator)
      Verify that the iterator has something to return.
      Parameters:
      iterator - the iterator
      Returns:
      the iterator
      Throws:
      NullPointerException - when the iterator is null
      IllegalArgumentException - when the hasNext method of the iterator returns false before even one Drawable2d was delivered

    • iterator

      public Iterator<Point3d> iterator()
      Description copied from interface: Bounds
      After version 2.3.1, the order of the points returned by the iterator of a Bounds object is documented (and changed compared with earlier versions). The returned points now form a Hamiltonian circuit through all the vertices of the bounding box, all steps follow an edge (in the 3D case, not all edges are visited).
      Specified by:
      iterator in interface Bounds<Bounds3d,Point3d>
      Specified by:
      iterator in interface Iterable<Point3d>

    • size

      public int size()
      Description copied from interface: Drawable
      Retrieve the number of points that make up the object.
      Specified by:
      size in interface Drawable<Point3d>
      Returns:
      the number of points that make up the object

    • contains

      public boolean contains(double x, double y, double z)
      Check if this Bounds3d contains a point. Contains returns false when the point is on the surface of this Bounds3d.
      Parameters:
      x - the x-coordinate of the point
      y - the y-coordinate of the point
      z - the z-coordinate of the point
      Returns:
      whether this Bounds3d contains the point
      Throws:
      ArithmeticException - when x, or y is NaN

    • contains

      public boolean contains(Point3d point)
      Description copied from interface: Bounds
      Check if a point is contained in this Bounds.
      Specified by:
      contains in interface Bounds<Bounds3d,Point3d>
      Parameters:
      point - the point
      Returns:
      true if the point is within this Bounds; false if the point is not within this Bounds, or on an edge of this Bounds

    • contains

      public boolean contains(Bounds3d otherBounds) throws NullPointerException
      Description copied from interface: Bounds
      Check if this Bounds completely contains another Bounds. If any point of the other Bounds lies on an edge (2d) or surface (3d) of this Bounds, this method returns false.
      Specified by:
      contains in interface Bounds<Bounds3d,Point3d>
      Parameters:
      otherBounds - the Bounds to check for complete containment within this Bounds.
      Returns:
      false if any point of D is on or outside one of the borders of this Bounds; true when all points of D are contained within this Bounds.
      Throws:
      NullPointerException - when otherBounds is null

    • covers

      public boolean covers(double x, double y, double z)
      Check if this Bounds3d contains a point. Covers returns true when the point is on a face of this Bounds3d.
      Parameters:
      x - the x-coordinate of the point
      y - the y-coordinate of the point
      z - the z-coordinate of the point
      Returns:
      whether the bounding box contains the point, including the faces
      Throws:
      ArithmeticException - when x, y, or z is NaN

    • covers

      public boolean covers(Point3d point)
      Description copied from interface: Bounds
      Check if this Bounds covers or touches a point.
      Specified by:
      covers in interface Bounds<Bounds3d,Point3d>
      Parameters:
      point - the Point for which to check if it is covered/touched by this Bounds
      Returns:
      whether this Bounds covers or touches the point

    • covers

      public boolean covers(Bounds3d otherBounds)
      Description copied from interface: Bounds
      Check if no part of a Bounds is outside this Bounds. The edges/surfaces of this Bounds are considered inside.
      Specified by:
      covers in interface Bounds<Bounds3d,Point3d>
      Parameters:
      otherBounds - the Bounds for which to check if it is covered by this Bounds
      Returns:
      whether this Bounds contains the provided Bounds, including overlapping borders

    • disjoint

      public boolean disjoint(Bounds3d otherBounds)
      Description copied from interface: Bounds
      Return whether a Bounds is disjoint from this Bounds. Touching at an edge is not considered disjoint. A Bounds that completely surrounds this Bounds is not disjoint.
      Specified by:
      disjoint in interface Bounds<Bounds3d,Point3d>
      Parameters:
      otherBounds - the other Bounds
      Returns:
      true if the drawable is disjoint from this Bounds, or only touches an edge; false if any point of the other Bounds is inside this Bounds, or the other Bounds surrounds this Bounds

    • intersects

      public boolean intersects(Bounds3d otherBounds3d)
      Description copied from interface: Bounds
      Return whether this Bounds intersects another Bounds. Touching at an edge is considered intersecting.
      Specified by:
      intersects in interface Bounds<Bounds3d,Point3d>
      Parameters:
      otherBounds3d - the other Bounds
      Returns:
      whether this bounding box/rectangle intersects the other Bounds

    • intersection

      public Bounds3d intersection(Bounds3d otherBounds3d)
      Description copied from interface: Bounds
      Return the intersecting Bounds of this Bounds and another Bounds. Touching at an edge is considered intersecting. In case there is no intersection, null is returned.
      Specified by:
      intersection in interface Bounds<Bounds3d,Point3d>
      Parameters:
      otherBounds3d - the other Bounds
      Returns:
      the intersecting Bounds of this Bounds and another Bounds. Touching at the edge is not seen as intersecting. If not intersecting; null is returned

    • project

      public Bounds2d project()
      Description copied from interface: Drawable3d
      Project the object onto the z=0 plane.
      Specified by:
      project in interface Drawable3d
      Returns:
      the projected object

    • getDeltaZ

      public double getDeltaZ()
      Return the extent of this Bounds3d in the z-direction.
      Returns:
      the extent of this Bounds3d in the z-direction

    • getVolume

      public double getVolume()
      Return the volume of this Bounds3d.
      Returns:
      the volume of this Bounds3d

    • getMinX

      public double getMinX()
      Description copied from interface: Bounds
      Return the absolute lower bound for x.
      Specified by:
      getMinX in interface Bounds<Bounds3d,Point3d>
      Returns:
      the absolute lower bound for x

    • getMaxX

      public double getMaxX()
      Description copied from interface: Bounds
      Return the absolute upper bound for x.
      Specified by:
      getMaxX in interface Bounds<Bounds3d,Point3d>
      Returns:
      the absolute upper bound for x

    • getMinY

      public double getMinY()
      Description copied from interface: Bounds
      Return the absolute lower bound for y.
      Specified by:
      getMinY in interface Bounds<Bounds3d,Point3d>
      Returns:
      the absolute lower bound for y

    • getMaxY

      public double getMaxY()
      Description copied from interface: Bounds
      Return the absolute upper bound for y.
      Specified by:
      getMaxY in interface Bounds<Bounds3d,Point3d>
      Returns:
      the absolute upper bound for y

    • getMinZ

      public double getMinZ()
      Return the lower bound for z.
      Returns:
      the lower bound for z

    • getMaxZ

      public double getMaxZ()
      Return the upper bound for z.
      Returns:
      the upper bound for z

    • midPoint

      public Point3d midPoint()
      Description copied from interface: Bounds
      Return the mid point of this Bounds object.
      Specified by:
      midPoint in interface Bounds<Bounds3d,Point3d>
      Returns:
      the mid point of this Bounds object

    • getAbsoluteBounds

      public Bounds3d getAbsoluteBounds()
      Description copied from interface: Drawable3d
      Retrieve the bounding box of the object in absolute coordinates.
      Specified by:
      getAbsoluteBounds in interface Drawable3d
      Returns:
      the bounding box of the object in absolute coordinates

    • toString

      public String toString()
      Description copied from interface: Drawable
      Produce a string describing the Drawable using default conversion for the (double) coordinate values. Regrettably, it is not allowed to provide a default implementation here.
      Specified by:
      toString in interface Drawable<Point3d>
      Overrides:
      toString in class Object
      Returns:
      a string describing the Drawable

    • toString

      public String toString(String doubleFormat, boolean doNotIncludeClassName)
      Description copied from interface: Drawable
      Produce a String describing the Drawable.
      Specified by:
      toString in interface Drawable<Point3d>
      Parameters:
      doubleFormat - a format string (something like "%6.3f") which will be used to render every coordinate value)
      doNotIncludeClassName - if true; the output of toString is not prefixed by the class name. This is useful for concatenating the textual representation of lots of Drawables (e.g. an array, or a List).
      Returns:
      textual representation of the Drawable

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object