Package net.algart.math

Class RectangularArea

java.lang.Object
net.algart.math.RectangularArea
public class RectangularArea extends Object

Rectangular real area, i.e. hyperparallelepiped in multidimensional space with real coordinates of vertices. All edges of the hyperparallelepiped are parallel to coordinate axes. In 1-dimensional case it is an equivalent of Range class, in 2-dimensional case it is an analog of the standard java.awt.geom.Rectangle2D class.

More precisely, the region, specified by this class, is defined by two n-dimensional points with real coordinates (Point), named the minimal vertex min and maximal vertex max, and consists of all such points (x0, x1, ..., xn−1), that:

min.coord(0) ≤ x0 ≤ max.coord(0),
min.coord(1) ≤ x1 ≤ max.coord(1),
...,
min.coord(n-1) ≤ xn−1 ≤ max.coord(n-1).

The min and max points are specified while creating an instance of this class and can be retrieved by min() and max() methods.

The coordinates of the minimal vertex min.coord(i) are never greater than the corresponding coordinates of the maximal vertex max.coord(i), and all coordinates of both vertices are never Double.NaN.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:
Daniel Alievsky
See Also:

  • Method Details

    • valueOf

      public static RectangularArea valueOf(Point min, Point max)
      Returns an instance of this class with the given minimal vertex min and maximal vertex max. See the comments to this class for more details.
      Parameters:
      min - the minimal vertex, inclusive.
      max - the maximal vertex, inclusive.
      Returns:
      the new rectangular area "between" these vertices.
      Throws:
      NullPointerException - if one of arguments is null.
      IllegalArgumentException - if the numbers of dimensions in min and max points are different, or if, for some i, min.coord(i) > max.coord(i), or if one of these coordinates is Double.NaN.

    • valueOf

      public static RectangularArea valueOf(Range... coordRanges)
      Returns the Cartesian product of the specified coordinate ranges. More precisely, return an n-dimensional rectangular area with the minimal vertex min and maximal vertex max, where n=coordRanges.length, min.coord(i)=coordRanges[i].min(), max.coord(i)=coordRanges[i].max(). See the comments to this class for more details.
      Parameters:
      coordRanges - the coordinate ranges.
      Returns:
      the Cartesian product of the specified coordinate ranges.
      Throws:
      NullPointerException - if the argument is null or if one of specified coordRanges is null.
      IllegalArgumentException - if the passed array is empty (no ranges are passed).

    • valueOf

      public static RectangularArea valueOf(double minX, double maxX)
      Returns a 1-dimensional rectangular area (range) with the given minimal and maximal vertex. Equivalent to 
       valueOf(
      Point.valueOf(minX),
      Point.valueOf(maxX));
      Parameters:
      minX - the minimal x-coordinate, inclusive.
      maxX - the maximal x-coordinate, inclusive.
      Returns:
      the new 1-dimensional rectangular area.
      Throws:
      IllegalArgumentException - in the same situations as valueOf(Point, Point) method.

    • valueOf

      public static RectangularArea valueOf(double minX, double minY, double maxX, double maxY)
      Returns a 2-dimensional rectangle with the given minimal and maximal vertex. Equivalent to 
       valueOf(
      Point.valueOf(minX, minY),
      Point.valueOf(maxX, maxY));
      Parameters:
      minX - the minimal x-coordinate, inclusive.
      minY - the minimal y-coordinate, inclusive.
      maxX - the maximal x-coordinate, inclusive.
      maxY - the maximal y-coordinate, inclusive.
      Returns:
      the new 2-dimensional rectangle.
      Throws:
      IllegalArgumentException - in the same situations as valueOf(Point, Point) method.

    • valueOf

      public static RectangularArea valueOf(double minX, double minY, double minZ, double maxX, double maxY, double maxZ)
      Returns a 3-dimensional parallelepiped with the given minimal and maximal vertex. Equivalent to 
       valueOf(
      Point.valueOf(minX, minY, minZ),
      Point.valueOf(maxX, maxY, maxZ));
      Parameters:
      minX - the minimal x-coordinate, inclusive.
      minY - the minimal y-coordinate, inclusive.
      minZ - the minimal z-coordinate, inclusive.
      maxX - the maximal x-coordinate, inclusive.
      maxY - the maximal y-coordinate, inclusive.
      maxZ - the maximal z-coordinate, inclusive.
      Returns:
      the new 3-dimensional parallelepiped.
      Throws:
      IllegalArgumentException - in the same situations as valueOf(Point, Point) method.

    • valueOf

      public static RectangularArea valueOf(IRectangularArea iArea)
      Returns a new rectangular area with the same coordinates as the given area. All long coordinates of the passed area are converted to double coordinates of the returned area by standard Java typecast (double)longValue. Equivalent to valueOf(Point.valueOf(iArea.min()), Point.valueOf(iArea.max())).
      Parameters:
      iArea - the integer rectangular area.
      Returns:
      the real rectangular area with same coordinates.
      Throws:
      NullPointerException - if the passed area is null.

    • coordCount

      public int coordCount()
      Returns the number of dimensions of this rectangular area. Equivalent to min().coordCount() or max().coordCount(), but works faster.

      The result of this method is always positive (>0).

      Returns:
      the number of dimensions of this rectangular area.

    • min

      public Point min()
      Returns the minimal vertex of this rectangular area: the point with minimal coordinates, belonging to this area. See the comments to this class for more details.
      Returns:
      the minimal vertex of this rectangular area.

    • max

      public Point max()
      Returns the maximal vertex of this rectangular area: the point with maximal coordinates, belonging to this area. See the comments to this class for more details.
      Returns:
      the maximal vertex of this rectangular area.

    • size

      public Point size()
      Returns all sizes of this rectangular area in a form of Point. Equivalent to Point.valueOf(sizes()). The returned point is equal to max().subtract(min()).
      Returns:
      all sizes of this rectangular area in a form of Point.

    • min

      public double min(int coordIndex)
      Returns min().coord(coordIndex).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      min().coord(coordIndex).
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().

    • max

      public double max(int coordIndex)
      Returns max().coord(coordIndex).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      max().coord(coordIndex).
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().

    • size

      public double size(int coordIndex)
      Returns max(coordIndex) - min(coordIndex).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      max(coordIndex) - min(coordIndex).
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=coordCount().

    • minX

      public double minX()
      Returns min().x().
      Returns:
      min().x().

    • maxX

      public double maxX()
      Returns max().x().
      Returns:
      max().x().

    • sizeX

      public double sizeX()
      Returns maxX() - minX().
      Returns:
      maxX() - minX().

    • minY

      public double minY()
      Returns min().y().
      Returns:
      min().y().
      Throws:
      IllegalStateException - if coordCount()<2.

    • maxY

      public double maxY()
      Returns max().y().
      Returns:
      max().y().
      Throws:
      IllegalStateException - if coordCount()<2.

    • sizeY

      public double sizeY()
      Returns maxY() - minY().
      Returns:
      maxY() - minY().
      Throws:
      IllegalStateException - if coordCount()<2.

    • minZ

      public double minZ()
      Returns min().z().
      Returns:
      min().z().
      Throws:
      IllegalStateException - if coordCount()<3.

    • maxZ

      public double maxZ()
      Returns max().z().
      Returns:
      max().z().
      Throws:
      IllegalStateException - if coordCount()<3.

    • sizeZ

      public double sizeZ()
      Returns maxZ() - minZ().
      Returns:
      maxZ() - minZ().
      Throws:
      IllegalStateException - if coordCount()<3.

    • sizes

      public double[] sizes()
      Returns the sizes of this rectangular area along all dimensions. The returned array consists of coordCount() elements, and the element #k contains size(k).
      Returns:
      the sizes of this rectangular area along all dimensions.

    • volume

      public double volume()
      Returns the volume of this rectangular area: the product of all sizes returned by sizes() method.
      Returns:
      the multidimensional volume of this rectangular area (usual area in 2-dimensional case).

    • range

      public Range range(int coordIndex)
      Returns Range.valueOf(min(coordIndex), max(coordIndex)).
      Parameters:
      coordIndex - the index of the coordinate.
      Returns:
      Range.valueOf(min(coordIndex), max(coordIndex)).

    • ranges

      public Range[] ranges()
      Returns the projections of this rectangular area to all axes. The returned array consists of coordCount() elements, and the element #k contains range(k).
      Returns:
      the projections of this rectangular area to all axes.

    • contains

      public boolean contains(Point point)
      Returns true if and only if min(k)<=point.coord(k)<=max(k) for all k.
      Parameters:
      point - the checked point.
      Returns:
      true if this rectangular area contains the given point.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if point.coordCount() is not equal to the number of dimensions of this instance.

    • contains

      public static boolean contains(Collection<RectangularArea> areas, Point point)
      Returns true if at least one of the specified areas contains the passed point (see contains(Point) method).
      Parameters:
      areas - list of checked rectangular areas.
      point - the checked point.
      Returns:
      true if one of the passed areas contains the given point.
      Throws:
      NullPointerException - if one of the arguments or one of the areas is null.
      IllegalArgumentException - if point.coordCount() is not equal to the number of dimensions of one of areas.

    • contains

      public boolean contains(RectangularArea area)
      Returns true if and only if min(k)<=area.min(k) and area.max(k)<=max(k) for all k.
      Parameters:
      area - the checked rectangular area.
      Returns:
      true if the checked rectangular area is a subset of this area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • contains

      public static boolean contains(Collection<RectangularArea> areas, RectangularArea area)
      Returns true if at least one of the specified areas contains the passed area (see contains(RectangularArea) method).
      Parameters:
      areas - list of checked rectangular areas.
      area - the checked area.
      Returns:
      true if one of the passed areas (1st argument) contains the given area (2nd argument).
      Throws:
      NullPointerException - if one of the arguments or one of the areas is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of one of areas in the 1st argument.

    • intersects

      public boolean intersects(RectangularArea area)
      Returns true if and only if min(k)<=area.max(k) and area.min(k)<=max(k) for all k.
      Parameters:
      area - the checked rectangular area.
      Returns:
      true if the checked rectangular area overlaps with this area, maybe in boundary points only.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • overlaps

      public boolean overlaps(RectangularArea area)
      Returns true if and only if min(k)<area.max(k) and area.min(k)<max(k) for all k.
      Parameters:
      area - the checked rectangular area.
      Returns:
      true if the checked rectangular area overlaps with this area in some internal points.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • intersection

      public RectangularArea intersection(RectangularArea area)
      Returns the set-theoretical intersection A ∩ B of this (A) and the passed rectangular area (B) or null if they do not intersect (A ∩ B = ∅). Equivalent to 
      thisInstance.intersects(area) ? RectangularArea.valueOf(
 thisInstance.min().max(area.min()),
 thisInstance.max().min(area.max())) :
 null
      .
      Parameters:
      area - the second rectangular area.
      Returns:
      intersection of this and the second rectangular area or null if they do not intersect.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • intersection

      public List<RectangularArea> intersection(Collection<RectangularArea> areas)
      Returns a list of set-theoretical intersections A ∩ Bi of this rectangular area (A) and all rectangular areas (Bi), specified by areas argument. If the passed collection doesn't contain areas, intersecting this area, the result will be an empty list.

      Equivalent to the following loop: 

       final List result = ... (some empty list);
 for (RectangularArea area : areas) {
     RectangularArea intersection = intersection(area);
     if (intersection != null) {
         result.add(intersection);
     }
 }
      .
      Parameters:
      areas - collection of areas (we find intersection with each from them).
      Returns:
      intersection of this and the second rectangular area or null if they do not intersect.
      Throws:
      NullPointerException - if the argument is null or one of its elements is null.
      IllegalArgumentException - if this rectangular area or some of elements of the passed collection have different coordCount().

    • difference

      public Collection<RectangularArea> difference(Collection<RectangularArea> results, RectangularArea area)
      Calculates the set-theoretical difference A \ B of this (A) and the passed rectangular area (B) in a form of N rectangular areas R1,R2,...,RN, the set-theoretical union of which is equal to this difference (R1∪R2∪...∪RN = A \ B). The resulting areas R1,R2,...,RN are added into the collection results by Collection.add(...) method. So, the collection results must be not-null and support adding elements (usually it is List or Queue).

      It is possible that the difference is empty (A \ B = ∅), i.e. this area A is a subset of the passed one B. In this case, this method does nothing.

      It is possible that the difference is equal to this area (A \ B = A), i.e. this area A does not intersect the passed one B. In this case, this method is equivalent to results.add(thisInstance) call.

      In other cases, there is more than 1 way to represent the resulting difference in a form of union of several rectangular areas R1,R2,...,RN. The precise way, how this method forms this set of rectangular areas Ri, is not documented, but this method tries to minimize the number N of such areas. In any case, there is a guarantee that N≤2*coordCount().

      Parameters:
      results - the collection to store results (new areas will be added to this collection).
      area - the area B, subtracted from this area A.
      Returns:
      a reference to the results argument.
      Throws:
      NullPointerException - if result or area argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.
      See Also:

    • subtractCollection

      public static Queue<RectangularArea> subtractCollection(Queue<RectangularArea> fromWhatToSubtract, Collection<RectangularArea> whatToSubtract)
      Calculates the set-theoretical difference A \ B of the set-theoretical union A of all elements of the collection fromWhatToSubtract and the set-theoretical union B of all elements of the collection whatToSubtract, in a form of a union of N rectangular areas, and replaces the old content of fromWhatToSubtract with the resulting N areas.

      More precisely, this method is equivalent to the following loop: 

       for (RectangularArea area : whatToSubtract) {
     for (int i = 0, n = fromWhatToSubtract.size(); i < n; i++) {
         RectangularArea minuend = fromWhatToSubtract.poll();
         minuend.difference(fromWhatToSubtract, area);
     }
     if (fromWhatToSubtract.isEmpty()) {
         break;
     }
 }

      Note: if some exception occurs while execution of the listed loop (for example, some elements of the collections are null or have different number of dimensions), the fromWhatToSubtract stays partially modified. In other words, this method is non-atomic regarding failures.

      Parameters:
      fromWhatToSubtract - the minuend A, which will be replaced with A \ B.
      whatToSubtract - the subtrahend B.
      Returns:
      a reference to fromWhatToSubtract argument, which will contain the difference A \ B.
      Throws:
      NullPointerException - if fromWhatToSubtract or whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if some of elements of the passed collections have different coordCount().
      See Also:

    • subtractCollection

      public static Queue<RectangularArea> subtractCollection(Queue<RectangularArea> fromWhatToSubtract, RectangularArea... whatToSubtract)
      Equivalent to subtractCollection(fromWhatToSubtract, java.util.Arrays.asList(whatToSubtract)).
      Parameters:
      fromWhatToSubtract - the minuend A, which will be replaced with A \ B.
      whatToSubtract - the subtrahend B.
      Returns:
      a reference to fromWhatToSubtract argument, which will contain the difference A \ B.
      Throws:
      NullPointerException - if fromWhatToSubtract or whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if some of elements of the passed collection and array have different coordCount().

    • subtract

      public Queue<RectangularArea> subtract(Collection<RectangularArea> whatToSubtract)
      Equivalent to subtractCollection(fromWhatToSubtract, whatToSubtract, where fromWhatToSubtract contains this object as the only element.
      Parameters:
      whatToSubtract - the subtrahend B.
      Returns:
      new collection, containing the difference A \ B (A = this object, B = union of all whatToSubtract).
      Throws:
      NullPointerException - if whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if this rectangular area or some of elements of the passed collection have different coordCount().

    • subtract

      public Queue<RectangularArea> subtract(RectangularArea... whatToSubtract)
      Equivalent to subtract(java.util.Arrays.asList(whatToSubtract)).
      Parameters:
      whatToSubtract - the subtrahend B.
      Returns:
      new collection, containing the difference A \ B (A = this object, B = union of all whatToSubtract).
      Throws:
      NullPointerException - if whatToSubtract argument is null or if one of their elements it null.
      IllegalArgumentException - if this rectangular area or some of elements of the passed array have different coordCount().

    • expand

      public RectangularArea expand(Point point)
      Returns the minimal rectangular area, containing this area and the given point. In the returned area, the minimal vertex is equal to thisInstance.min().min(point) and the maximal vertex is equal to thisInstance.max().max(point).
      Parameters:
      point - some point that should be included to the new rectangular area.
      Returns:
      the expanded rectangular area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if point.coordCount() is not equal to the number of dimensions of this instance, or if the points thisInstance.min().min(point) and thisInstance.max().max(point) do not match requirements of valueOf(Point, Point) method.

    • expand

      public RectangularArea expand(RectangularArea area)
      Returns the minimal rectangular area, containing this and the passed area. Equivalent to 
      RectangularArea.valueOf(
 thisInstance.min().min(area.min()),
 thisInstance.max().max(area.max()))
      .
      Parameters:
      area - the second rectangular area.
      Returns:
      the minimal rectangular area, containing this and the passed area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if area.coordCount() is not equal to the number of dimensions of this instance.

    • minimalContainingArea

      public static RectangularArea minimalContainingArea(Collection<RectangularArea> areas)
      Returns the minimal rectangular area, containing all passed areas. Equivalent to the loop of expand(RectangularArea) methods, called for each element of the passed collection, but works faster.

      If the passed collection is empty, returns null.

      Parameters:
      areas - some collection of rectangular areas.
      Returns:
      the minimal rectangular area, containing all them, or null for empty collection.
      Throws:
      NullPointerException - if the argument or one of the passed areas is null.
      IllegalArgumentException - if coordCount() is not equal for all areas.

    • parallelDistance

      public double parallelDistance(Point point)
      Returns the parallel distance from the given point to this rectangular area. The parallel distance is a usual distance, with plus or minus sign, from the point to some of hyperplanes, containing the hyperfacets of this hyperparallelepiped, chosen so that:
      1. the parallel distance is zero at the hyperfacets, negative inside the rectangular area and positive outside it;
      2. for any constant c, the set of all such points, that the parallel distance from them to this rectangular area ≤c, is also hyperparallelepiped (rectangular area) wich hyperfacets, parallel to the the coordinate hyperplanes, or an empty set if c<c0, where c0 is the (negative) parallel distance from the geometrical center of this hyperparallelepiped.

      Formally, let p is any point with coordinates p0, p1, ..., pn−1, li = min(i), ri = max(i), di = max(li−pi, pi−ri). Note that di is positive if pi<li or pi>ri and negative if pi is inside li..ri range. The parallel distance from the point p to this rectangular area is defined as maximal value from all di: max(d0, d1, ..., dn−1).

      Parameters:
      point - some point.
      Returns:
      the parallel distance from this point to this rectangular area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if point.coordCount() is not equal to the number of dimensions of this instance.

    • parallelDistance

      public double parallelDistance(double... coordinates)
      Equivalent to parallelDistance(Point.valueOf(coordinates)), but works faster because does not require to create an instance of Point class.
      Parameters:
      coordinates - coordinates of some point.
      Returns:
      the parallel distance from this point to this rectangular area.
      Throws:
      NullPointerException - if coordinates argument is null.
      IllegalArgumentException - if coordinates.length is not equal to the number of dimensions of this instance.

    • parallelDistance

      public double parallelDistance(double x, double y)
      Equivalent to parallelDistance(Point.valueOf(x, y)), but works faster because does not require to allocate any objects. Works only for 2-dimensional rectangular areas, in other cases throws IllegalArgumentException.
      Parameters:
      x - the 1st coordinate of some point.
      y - the 2nd coordinate of some point.
      Returns:
      the parallel distance from this point to this rectangular area.
      Throws:
      IllegalArgumentException - if coordinates.length!=2 .

    • parallelDistance

      public double parallelDistance(double x, double y, double z)
      Equivalent to parallelDistance(Point.valueOf(x, y, z)), but works faster because does not require to allocate any objects. Works only for 3-dimensional rectangular areas, in other cases throws IllegalArgumentException.
      Parameters:
      x - the 1st coordinate of some point.
      y - the 2nd coordinate of some point.
      z - the 3rd coordinate of some point.
      Returns:
      the parallel distance from this point to this rectangular area.
      Throws:
      IllegalArgumentException - if coordinates.length!=2 .

    • shift

      public RectangularArea shift(Point vector)
      Shifts this rectangular area by the specified vector and returns the shifted area. Equivalent to 
      valueOf(thisInstance.min().add(vector), thisInstance.max().add(vector))
      Parameters:
      vector - the vector which is added to all vertices of this area.
      Returns:
      the shifted area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if vector.coordCount() is not equal to the number of dimensions of this instance.

    • shiftBack

      public RectangularArea shiftBack(Point vector)
      Shifts this rectangular area by vector.symmetric() and returns the shifted area. Equivalent to 
      valueOf(thisInstance.min().subtract(vector), thisInstance.max().subtract(vector))
      Parameters:
      vector - the vector which is subtracted from all vertices of this area.
      Returns:
      the shifted area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if vector.coordCount() is not equal to the number of dimensions of this instance.

    • dilate

      public RectangularArea dilate(Point expansion)
      Returns this rectangular area, dilated (expanded) according the argument. More precisely, returns 
      RectangularArea.valueOf(
 thisInstance.min().subtract(expansion),
 thisInstance.max().add(expansion))
      (but if expansion.isOrigin(), return this object without changes).
      Parameters:
      expansion - how to dilate this area.
      Returns:
      dilated area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if expansion.coordCount() is not equal to the number of dimensions of this instance, or if the result area will be incorrect (see comments to valueOf(Point, Point) method).

    • dilate

      public RectangularArea dilate(double expansion)
      Equivalent to dilate(Point.valueOfEqualCoordinates(thisObjects.coordCount(), expansion).
      Parameters:
      expansion - how to dilate this area.
      Returns:
      dilated area.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the result area will be incorrect (see comments to valueOf(Point, Point) method).

    • dilateStraightOnly

      public List<RectangularArea> dilateStraightOnly(List<RectangularArea> results, Point expansion)
      Returns this area, dilated according the argument only adouble coordinate axes, without full hypercube areas near vertices (like in dilate(Point) method).

      More precisely, the result is a list, consisting of this area and (usually) 2*coordCount() rectangular areas, lying adouble facets of this area, like in the following picture: 

           aaaaaaaaaaaa
   bbRRRRRRRRRRRRcc
   bbRRRRRRRRRRRRcc
   bbRRRRRRRRRRRRcc
     ddddddddddd
      This figure shows dilation of some 2-dimensional rectangle R by expansion=Point.valueOf(2,1): the results consists of the original rectangle and 4 rectangles a, b (height 1) and c, d (width 2).

      Note: all coordinates of expansion argument must be non-negative (unlike dilate(Point) method).

      If some of coordinates of the point expansion are zero, new areas adouble the corresponding facets are not added (recanglar area cannot be empty). In particular, if expansion.isOrigin(), the result will contain this area as the only element.

      Parameters:
      results - the list to store results (new areas will be added to the end of this list).
      expansion - how to dilate this area.
      Returns:
      a reference to the results argument.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if expansion.coordCount() is not equal to the number of dimensions of this instance, or if one of coordinates of expansion is negative, or if the result area will be incorrect (see comments to valueOf(Point, Point) method).

    • dilateStraightOnly

      public List<RectangularArea> dilateStraightOnly(List<RectangularArea> results, double expansion)
      Equivalent to dilateStraightOnly(results, Point.valueOfEqualCoordinates(thisObjects.coordCount(), expansion).
      Parameters:
      results - the list to store results (new areas will be added to the end of this list).
      expansion - how to dilate this area.
      Returns:
      a reference to the results argument.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if expansion < 0 or if the result area will be incorrect (see comments to valueOf(Point, Point) method).

    • dilate

      public static List<RectangularArea> dilate(Collection<RectangularArea> areas, Point expansion, boolean straightOnly)
      Dilates all areas, specified by the argument, by dilate or dilateStraightOnly method, and returns the list of dilated areas.

      If straightOnly argument is false, this method is equivalent to the following code: 

       final List result = new ArrayList();
 for (RectangularArea area : areas) {
     result.add(area.dilate(expansion));
 }

      If straightOnly argument is true, this method is equivalent to the following code: 

       final List result = new ArrayList();
 for (RectangularArea area : areas) {
     area.dilateStraightOnly(result, expansion);
 }

      Note that in the second case the resulting list will usually contain more elements than the source areas collection.

      Parameters:
      areas - areas to be dilated.
      expansion - how to dilate these areas.
      straightOnly - dilation mode.
      Returns:
      list of dilated areas.
      Throws:
      NullPointerException - if one of the arguments is null or one of areas is null.
      IllegalArgumentException - if expansion.coordCount() is not equal to the number of dimensions of one of areas, or if straightOnly amd one of coordinates of expansion is negative (and collection of areas is not empty), or if one of the result areas will be incorrect (see comments to valueOf(Point, Point) method).

    • toIntegerRectangularArea

      public IRectangularArea toIntegerRectangularArea()
      Equivalent to IRectangularArea.valueOf(thisInstance), with the only difference that IllegalStateException is thrown instead of IllegalArgumentException for unallowed rectangular area.
      Returns:
      the integer rectangular area with same (cast) coordinates.
      Throws:
      IllegalStateException - in the same situation when IRectangularArea.valueOf(RectangularArea) method throws IllegalArgumentException.

    • toRoundedRectangularArea

      public IRectangularArea toRoundedRectangularArea()
      Equivalent to IRectangularArea.roundOf(thisInstance), with the only difference that IllegalStateException is thrown instead of IllegalArgumentException for unallowed rectangular area.
      Returns:
      the integer rectangular area with same (rounded) coordinates.
      Throws:
      IllegalStateException - in the same situation when IRectangularArea.roundOf(RectangularArea) method throws IllegalArgumentException.

    • toString

      public String toString()
      Returns a brief string description of this object.

      The result of this method may depend on implementation and usually contains information about all coordinates ranges between the minimum and maximum vertices of this area.

      Overrides:
      toString in class Object
      Returns:
      a brief string description of this object.

    • hashCode

      public int hashCode()
      Returns the hash code of this rectangular area.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this rectangular area.

    • equals

      public boolean equals(Object obj)
      Indicates whether some other rectangular area is equal to this instance. Returns true if and only if obj instanceof RectangularArea, ((RectangularArea)obj).min().equals(this.min()) and ((RectangularArea)obj).max().equals(this.max()).
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to be compared for equality with this instance.
      Returns:
      true if the specified object is a rectangular area equal to this one.