Package org.djutils.draw.bounds

Class Bounds3d

java.lang.Object

org.djutils.draw.bounds.Bounds3d

All Implemented Interfaces:

Serializable, Bounds<Bounds3d,Point3d,Drawable3d>, Drawable<Point3d>, Drawable3d

public class Bounds3d
extends Object
implements Serializable, Drawable3d, Bounds<Bounds3d,Point3d,Drawable3d>

Bounds3d is the generic class for the 3D extent of an object. It is an immutable object.

Copyright (c) 2020-2023 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

See Also:

Serialized Form

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(Drawable3d drawable)	Check if this Bounds completely contains a Drawable.
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(Drawable3d drawable)	Check if no part of a Drawable is outside this Bounds.
boolean	covers(Point3d point)	Check if this Bounds covers or touches a point.
boolean	disjoint(Drawable3d drawable)	Return whether a Drawable 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	getBounds()	Retrieve the bounding box of the object.
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.
Iterator<Point3d>	getPoints()	Retrieve, or generate all points that make up the object.
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.
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

Constructor Detail

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 - double; the lower bound for x

maxX - double; the upper bound for x

minY - double; the lower bound for y

maxY - double; the upper bound for y

minZ - double; the lower bound for z

maxZ - double; the upper bound for z

Throws:

IllegalArgumentException - when lower bounds are larger than upper boundingBox or any bound is NaN

Bounds3d

public Bounds3d(double deltaX,
                double deltaY,
                double deltaZ)

Constructs a new Bounds3d around the origin (0, 0, 0).

Parameters:

deltaX - double; the deltaX value around the origin

deltaY - double; the deltaY value around the origin

deltaZ - double; the deltaZ value around the origin

Throws:

IllegalArgumentException - when one of the delta values is less than zero

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 - Iterator<? extends Point3d>; the array of points to construct a Bounds3d from

Throws:

NullPointerException - when points is null

IllegalArgumentException - when zero points are provided

Bounds3d

public Bounds3d(Point3d[] points)
         throws NullPointerException,
                IllegalArgumentException

Construct a Bounds3d from an array of Point3d, finding the lowest and highest x, y and z coordinates.

Parameters:

points - Point3d[]; 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 - Drawable3d; any object that implements the Drawable2d interface

Throws:

NullPointerException - when area is null

Bounds3d

public Bounds3d(Drawable3d... drawable3d)
         throws NullPointerException,
                IllegalArgumentException

Construct a Bounds3d for several Drawable2d objects.

Parameters:

drawable3d - Drawable3d...; the Drawable2d objects

Throws:

NullPointerException - when the array is null, or contains a null value

IllegalArgumentException - when the length of the array is 0

Bounds3d

public Bounds3d(Collection<Drawable3d> drawableCollection)
         throws NullPointerException,
                IllegalArgumentException

Construct a Bounds3d for a Collection of Drawable2d objects.

Parameters:

drawableCollection - Collection<Drawable2d>; the collection

Throws:

NullPointerException - when the collection is null, or contains null values

IllegalArgumentException - when the collection is empty

Method Detail

pointsOf

public static Iterator<Point3d> pointsOf(Drawable3d... drawable3d)

Return an iterator that will return all points of one or more Drawable objects.

Parameters:

drawable3d - Drawable3d...; the Drawable objects

Returns:

Iterator<P>; iterator that will return all points of the Drawable objects

Throws:

NullPointerException - when drawable is null, or contains a null value

IllegalArgumentException - when drawable is empty

ensureHasOne

static Drawable3d[] ensureHasOne(Drawable3d[] drawable3dArray)
                          throws NullPointerException,
                                 IllegalArgumentException

Verify that the array contains at least one entry.

Parameters:

drawable3dArray - Drawable3d[]; array of Drawable2d objects

Returns:

Drawable3d[]; the array

Throws:

NullPointerException - when the array is null

IllegalArgumentException - when the array contains 0 elements

pointsOf

public static Iterator<Point3d> pointsOf(Collection<Drawable3d> drawableCollection)
                                  throws NullPointerException,
                                         IllegalArgumentException

Return an iterator that will return all points of one or more Drawable3d objects.

Parameters:

drawableCollection - Collection<Drawable3d>; the collection of Drawable2d objects

Returns:

Iterator<P>; iterator that will return all points of the Drawable objects

Throws:

NullPointerException - when drawableCollection is null, or contains a null value

IllegalArgumentException - when drawableCollection is empty

ensureHasOne

static Iterator<Drawable3d> ensureHasOne(Iterator<Drawable3d> iterator)
                                  throws NullPointerException,
                                         IllegalArgumentException

Verify that the iterator has something to return.

Parameters:

iterator - Iterator<Drawable2d>; the iterator

Returns:

Iterator<Drawable3d>; the iterator

Throws:

NullPointerException - when the iterator is null

IllegalArgumentException - when the hasNext method of the iterator returns false

getPoints

public Iterator<Point3d> getPoints()

Retrieve, or generate all points that make up the object.

Specified by:

getPoints in interface Drawable<Point3d>

Returns:

Iterable<Point2d>; an iterator that generates all points that make up the object

size

public int size()

Retrieve the number of points that make up the object.

Specified by:

size in interface Drawable<Point3d>

Returns:

int; the number of points that make up the object

contains

public boolean contains(double x,
                        double y,
                        double z)
                 throws IllegalArgumentException

Check if this Bounds3d contains a point. Contains returns false when the point is on the surface of this Bounds3d.

Parameters:

x - double; the x-coordinate of the point

y - double; the y-coordinate of the point

z - double; the z-coordinate of the point

Returns:

boolean; whether this Bounds3d contains the point

Throws:

IllegalArgumentException - when any of the coordinates is NaN

contains

public boolean contains(Point3d point)

Check if a point is contained in this Bounds.

Specified by:

contains in interface Bounds<Bounds3d,Point3d,Drawable3d>

Parameters:

point - P; the point

Returns:

boolean; 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(Drawable3d drawable)
                 throws NullPointerException

Check if this Bounds completely contains a Drawable. If any point of the Drawable lies on an edge (2d) or surface (3d) of this Bounds, this method returns false.

Specified by:

contains in interface Bounds<Bounds3d,Point3d,Drawable3d>

Parameters:

drawable - D; the object for which to check if it is completely contained within this Bounds.

Returns:

boolean; 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 drawable2d is null

covers

public boolean covers(double x,
                      double y,
                      double z)
               throws IllegalArgumentException

Check if this Bounds3d contains a point. Covers returns true when the point is on a face of this Bounds3d.

Parameters:

x - double; the x-coordinate of the point

y - double; the y-coordinate of the point

z - double; the z-coordinate of the point

Returns:

boolean; whether the bounding box contains the point, including the faces

Throws:

IllegalArgumentException - when any of the coordinates is NaN

covers

public boolean covers(Point3d point)

Check if this Bounds covers or touches a point.

Specified by:

covers in interface Bounds<Bounds3d,Point3d,Drawable3d>

Parameters:

point - P; the Point for which to check if it is covered/touched by this Bounds

Returns:

boolean; whether this Bounds covers or touches the point

covers

public boolean covers(Drawable3d drawable)

Check if no part of a Drawable is outside this Bounds. The edges/surfaces of this Bounds are considered inside.

Specified by:

covers in interface Bounds<Bounds3d,Point3d,Drawable3d>

Parameters:

drawable - D; the Drawable for which to check if it is contained within this Bounds

Returns:

boolean; whether this Bounds contains the provided Bounds, including overlapping borders

disjoint

public boolean disjoint(Drawable3d drawable)

Return whether a Drawable is disjoint from this Bounds. Touching at an edge is not considered disjoint. A Drawable that completely surrounds this Drawable is not disjoint.

Specified by:

disjoint in interface Bounds<Bounds3d,Point3d,Drawable3d>

Parameters:

drawable - D; the drawable

Returns:

boolean; true if the drawable is disjoint from this Bounds, or only touches an edge; false if any point of the drawable is inside this Bounds, or the drawable surrounds this Bounds

intersects

public boolean intersects(Bounds3d otherBounds3d)

Return whether this Bounds intersects another Bounds. Touching at an edge is considered intersecting.

Specified by:

intersects in interface Bounds<Bounds3d,Point3d,Drawable3d>

Parameters:

otherBounds3d - B; the other Bounds

Returns:

boolean; whether this bounding box/rectangle intersects the other Bounds

intersection

public Bounds3d intersection(Bounds3d otherBounds3d)

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,Drawable3d>

Parameters:

otherBounds3d - B; the other Bounds

Returns:

Bounds; 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()

Project the object onto the z=0 plane.

Specified by:

project in interface Drawable3d

Returns:

Drawable2d; the projected object

getDeltaZ

public double getDeltaZ()

Return the extent of this Bounds3d in the z-direction.

Returns:

double; the extent of this Bounds3d in the z-direction

getVolume

public double getVolume()

Return the volume of this Bounds3d.

Returns:

double; the volume of this Bounds3d

getMinX

public double getMinX()

Return the absolute lower bound for x.

Specified by:

getMinX in interface Bounds<Bounds3d,Point3d,Drawable3d>

Returns:

double; the absolute lower bound for x

getMaxX

public double getMaxX()

Return the absolute upper bound for x.

Specified by:

getMaxX in interface Bounds<Bounds3d,Point3d,Drawable3d>

Returns:

double; the absolute upper bound for x

getMinY

public double getMinY()

Return the absolute lower bound for y.

Specified by:

getMinY in interface Bounds<Bounds3d,Point3d,Drawable3d>

Returns:

double; the absolute lower bound for y

getMaxY

public double getMaxY()

Return the absolute upper bound for y.

Specified by:

getMaxY in interface Bounds<Bounds3d,Point3d,Drawable3d>

Returns:

double; the absolute upper bound for y

getMinZ

public double getMinZ()

Return the lower bound for z.

Returns:

double; the lower bound for z

getMaxZ

public double getMaxZ()

Return the upper bound for z.

Returns:

double; the upper bound for z

midPoint

public Point3d midPoint()

Return the mid point of this Bounds object.

Specified by:

midPoint in interface Bounds<Bounds3d,Point3d,Drawable3d>

Returns:

P; the mid point of this Bounds object

getBounds

public Bounds3d getBounds()

Retrieve the bounding box of the object.

Specified by:

getBounds in interface Drawable3d

Returns:

Bounds3d; the bounding box of the object

toString

public String toString()

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:

String; a string describing the Drawable

toString

public String toString(String doubleFormat,
                       boolean doNotIncludeClassName)

Produce a String describing the Drawable.

Specified by:

toString in interface Drawable<Point3d>

Parameters:

doubleFormat - String; a format string (something like "%6.3f") which will be used to render every coordinate value)

doNotIncludeClassName - boolean; 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:

String; 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