Package org.djutils.draw.bounds

Class Bounds2d

java.lang.Object
org.djutils.draw.bounds.Bounds2d
All Implemented Interfaces:
Serializable, Bounds<Bounds2d,Point2d,Drawable2d>, Drawable<Point2d>, Drawable2d
public class Bounds2d extends Object implements Drawable2d, Bounds<Bounds2d,Point2d,Drawable2d>
A Bounds2d stores the rectangular 2D bounds of a 2d object, or a collection of 2d objects. The Bounds2d is an immutable object.

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

  • Constructor Details

    • Bounds2d

      public Bounds2d(double minX, double maxX, double minY, double maxY) throws IllegalArgumentException
      Construct a Bounds2d by providing its lower and upper bounds in both dimensions.
      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
      Throws:
      IllegalArgumentException - when a lower bound is larger than the corresponding upper bound, or any of the bounds is NaN

    • Bounds2d

      public Bounds2d(double deltaX, double deltaY)
      Constructs a new Bounds2d around the origin (0, 0).
      Parameters:
      deltaX - double; the deltaX value around the origin
      deltaY - double; the deltaY value around the origin
      Throws:
      IllegalArgumentException - when one of the delta values is less than zero

    • Bounds2d

      public Bounds2d(Iterator<? extends Point2d> points)
      Construct a Bounds2d from some collection of points, finding the lowest and highest x and y coordinates.
      Parameters:
      points - Iterator<? extends Point2d>; Iterator that will generate all the points for which to construct a Bounds2d
      Throws:
      NullPointerException - when points is null
      IllegalArgumentException - when the iterator provides zero points

    • Bounds2d

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

    • Bounds2d

      public Bounds2d(Drawable2d drawable2d) throws NullPointerException
      Construct a Bounds2d for a Drawable2d.
      Parameters:
      drawable2d - Drawable2d; any object that implements the Drawable2d interface
      Throws:
      NullPointerException - when drawable2d is null

    • Bounds2d

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

    • Bounds2d

      public Bounds2d(Collection<Drawable2d> drawableCollection) throws NullPointerException, IllegalArgumentException
      Construct a Bounds2d 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 Details

    • ensureHasOne

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

    • pointsOf

      public static Iterator<Point2d> pointsOf(Drawable2d... drawable2d)
      Return an iterator that will return all points of one or more Drawable objects.
      Parameters:
      drawable2d - Drawable2d...; 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

    • pointsOf

      public static Iterator<Point2d> pointsOf(Collection<Drawable2d> drawableCollection) throws NullPointerException, IllegalArgumentException
      Return an iterator that will return all points of one or more Drawable2d objects.
      Parameters:
      drawableCollection - Collection<Drawable2d>; 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

      public static Iterator<Drawable2d> ensureHasOne(Iterator<Drawable2d> iterator) throws NullPointerException, IllegalArgumentException
      Verify that the iterator has something to return.
      Parameters:
      iterator - Iterator<Drawable2d>; the iterator
      Returns:
      Iterator<Drawable2d>; the iterator
      Throws:
      NullPointerException - when the iterator is null
      IllegalArgumentException - when the hasNext method of the iterator returns false

    • getPoints

      public Iterator<Point2d> getPoints()
      Retrieve, or generate all points that make up the object.
      Specified by:
      getPoints in interface Drawable<Point2d>
      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<Point2d>
      Returns:
      int; the number of points that make up the object

    • contains

      public boolean contains(double x, double y) throws IllegalArgumentException
      Check if this Bounds2d contains a point. Contains considers a point on the border of this Bounds2d to be outside.
      Parameters:
      x - double; the x-coordinate of the point
      y - double; the y-coordinate of the point
      Returns:
      boolean; whether this Bounds2d contains the point
      Throws:
      IllegalArgumentException - when any of the coordinates is NaN

    • contains

      public boolean contains(Point2d point)
      Check if a point is contained in this Bounds.
      Specified by:
      contains in interface Bounds<Bounds2d,Point2d,Drawable2d>
      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(Drawable2d 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<Bounds2d,Point2d,Drawable2d>
      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)
      Check if this Bounds2d covers a point. Covers returns true when the point is on, or inside this Bounds2d.
      Parameters:
      x - double; the x-coordinate of the point
      y - double; the y-coordinate of the point
      Returns:
      boolean; whether this Bounds2d, including its borders, contains the point

    • covers

      public boolean covers(Point2d point)
      Check if this Bounds covers or touches a point.
      Specified by:
      covers in interface Bounds<Bounds2d,Point2d,Drawable2d>
      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(Drawable2d drawable) throws NullPointerException
      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<Bounds2d,Point2d,Drawable2d>
      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
      Throws:
      NullPointerException - when otherBounds is null

    • disjoint

      public boolean disjoint(Drawable2d drawable) throws NullPointerException
      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<Bounds2d,Point2d,Drawable2d>
      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
      Throws:
      NullPointerException - when bounds is null

    • intersects

      public boolean intersects(Bounds2d otherBounds2d) throws NullPointerException
      Return whether this Bounds intersects another Bounds. Touching at an edge is considered intersecting.
      Specified by:
      intersects in interface Bounds<Bounds2d,Point2d,Drawable2d>
      Parameters:
      otherBounds2d - B; the other Bounds
      Returns:
      boolean; whether this bounding box/rectangle intersects the other Bounds
      Throws:
      NullPointerException - when otherBounds is null

    • intersection

      public Bounds2d intersection(Bounds2d otherBounds2d)
      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<Bounds2d,Point2d,Drawable2d>
      Parameters:
      otherBounds2d - 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

    • toRectangle2D

      public Rectangle2D toRectangle2D()
      Return an AWT Rectangle2D that covers the same area as this Bounds2d.
      Returns:
      Rectangle2D; the rectangle that covers the same area as this Bounds2d

    • getMinX

      public double getMinX()
      Return the absolute lower bound for x.
      Specified by:
      getMinX in interface Bounds<Bounds2d,Point2d,Drawable2d>
      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<Bounds2d,Point2d,Drawable2d>
      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<Bounds2d,Point2d,Drawable2d>
      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<Bounds2d,Point2d,Drawable2d>
      Returns:
      double; the absolute upper bound for y

    • midPoint

      public Point2d midPoint()
      Return the mid point of this Bounds object.
      Specified by:
      midPoint in interface Bounds<Bounds2d,Point2d,Drawable2d>
      Returns:
      P; the mid point of this Bounds object

    • getArea

      public double getArea()
      Return the area of this Bounds2d.
      Returns:
      double; the area of this Bounds2d

    • getBounds

      public Bounds2d getBounds()
      Retrieve the bounding rectangle of the object.
      Specified by:
      getBounds in interface Drawable2d
      Returns:
      Bounds2d; 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<Point2d>
      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<Point2d>
      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