Package org.anchoranalysis.spatial.box

Class BoundingBox

Object
BoundingBox
All Implemented Interfaces:
Serializable, Comparable<BoundingBox>
public final class BoundingBox extends Object implements Serializable, Comparable<BoundingBox>
A bounding-box in two or three dimensions.

A bounding-box in two dimensions should always set it's z-dimension's extent to 1.

This is an immutable class. No operation modifies the state of the existing object.

See Also:

  • Constructor Details

    • BoundingBox

      public BoundingBox(Extent extent)
      Constructs a bounding-box to cover the entirety of a certain extent.
      Parameters:
      extent - the extent.

  • Method Details

    • createReuse

      public static BoundingBox createReuse(ReadableTuple3i cornerMin, Extent extent)
      Creates a bounding-box from a corner and an extent - reusing cornerMin internally.

      The cornerMin is not duplicated before being stored internally. It should not be subsequently modified externally.

      {code cornerMin} will also never be changed internally, so it is safe to pass a constant using this method.

      See createDuplicate(ReadableTuple3i, Extent) for an alternative that duplicates cornerMin.

      Parameters:
      cornerMin - the corner that is the minimum point in all dimensions for the bounding-box.
      extent - the size of the bounding-box emanating from cornerMin.
      Returns:
      the newly created BoundingBox.

    • createDuplicate

      public static BoundingBox createDuplicate(ReadableTuple3i cornerMin, Extent extent)
      Creates a bounding-box from a corner and an extent - duplicating cornerMin.

      The cornerMin is duplicated before being stored internally. This makes it safe to further modify it externally.

      See createReuse(ReadableTuple3i, Extent) for an alternative that does not duplicate cornerMin.

      Parameters:
      cornerMin - the corner that is the minimum point in all dimensions for the bounding-box.
      extent - the size of the bounding-box emanating from cornerMin.
      Returns:
      the newly created BoundingBox.

    • createReuse

      public static BoundingBox createReuse(ReadableTuple3i cornerMinInclusive, ReadableTuple3i cornerMaxInclusive)
      Creates from two int points (a minimum corner and a maximum corner) - reusing cornerMinInclusive internally.

      The cornerMin is not duplicated before being stored internally. It should not be subsequently modified externally.

      {code cornerMin} will also never be changed internally, so it is safe to pass a constant using this method.

      Parameters:
      cornerMinInclusive - minimum point in each dimension of the bounding-box (that exists inside the box).
      cornerMaxInclusive - maximum point in each dimension of the bounding-box (that exists inside the box).
      Returns:
      the newly created BoundingBox.

    • createDuplicate

      public static BoundingBox createDuplicate(ReadableTuple3i cornerMinInclusive, ReadableTuple3i cornerMaxInclusive)
      Creates from two int points (a minimum corner and a maximum corner) - reusing cornerMinInclusive internally.

      The cornerMin is not duplicated before being stored internally. It should not be subsequently modified externally.

      {code cornerMin} will also never be changed internally, so it is safe to pass a constant using this method.

      Parameters:
      cornerMinInclusive - minimum point in each dimension of the bounding-box (that exists inside the box).
      cornerMaxInclusive - maximum point in each dimension of the bounding-box (that exists inside the box).
      Returns:
      the newly created BoundingBox.

    • createReuse

      public static BoundingBox createReuse(Point3d cornerMinInclusive, Point3d cornerMaxInclusive)
      Creates from two double points (a minimum corner and a maximum corner).

      Neither cornerMinInclusive or cornerMaxInclusive are used internally, and can be modified as necessary after the call.

      Parameters:
      cornerMinInclusive - minimum point in each dimension of the bounding-box (that exists inside the box).
      cornerMaxInclusive - maximum point in each dimension of the bounding-box (that exists inside the box).
      Returns:
      the newly created BoundingBox.

    • midpoint

      public Point3d midpoint()
      A mid-point in the bounding box, corresponding to the exact half-way point between (corner+extent)/2.

      It may not be integral, possibly ending with 0.5

      Returns:
      a newly created point representing the mid-point.

    • centerOfGravity

      public Point3i centerOfGravity()
      A mid-point in the bounding-box, corresponding to the mean of all points inside the box.

      i.e. in each dimension, it is (corner+extent-1)/2

      It is guaranteed to be integral, by flooring.

      This is similar to midpoint() but can be marginally shifted left.

      Returns:
      the center-of-gravity.

    • flattenZ

      public BoundingBox flattenZ()
      Collapses the z-dimension of the box to a single voxel depth, and a corner at 0 voxels.
      Returns:
      a newly created BoundingBox with identical X and Y values, but with the Z dimension flattened.

    • changeExtent

      public BoundingBox changeExtent(Extent extent)
      Creates a copied BoundingBox but with a different extent.
      Parameters:
      extent - the extent to assign.
      Returns:
      a newly-created BoundingBox that has a changed extent, but is otherwise identical.

    • changeExtent

      public BoundingBox changeExtent(UnaryOperator<Extent> extentOperator)
      Creates a copied BoundingBox but with a different extent.
      Parameters:
      extentOperator - an operator that changes the extent.
      Returns:
      a newly-created BoundingBox that has a changed extent, but is otherwise identical.

    • changeZ

      public BoundingBox changeZ(int cornerZ, int extentZ)
      Creates a copied BoundingBox but with a different corner and extent in the Z-dimension.
      Parameters:
      cornerZ - the corner to assign in the z-dimension.
      extentZ - the extent to assign in the z-dimension.
      Returns:
      a newly-created BoundingBox that has a changed extent and corner in the Z-dimension, but is otherwise identical.

    • changeExtentZ

      public BoundingBox changeExtentZ(int extentZ)
      Creates a copied BoundingBox but with a different extent in the Z-dimension.
      Parameters:
      extentZ - the extent to assign in the z-dimension.
      Returns:
      a newly-created BoundingBox that has a changed extent in the Z-dimension, but is otherwise identical.

    • atBorder

      public boolean atBorder(Extent extent)
      Does the bounding-box have an edge at the border of an image of size extent?

      The border of the image is defined as the exterior including all voxels that are a minimum or maximum in any given dimension.

      Parameters:
      extent - the size of the image.
      Returns:
      true iff the bounding box lies at the border.

    • atBorderXY

      public boolean atBorderXY(Extent extent)
      Like atBorder(Extent) but considers only the X- and Y- dimensions.
      Parameters:
      extent - the size of the image.
      Returns:
      true iff the bounding box lies at the border along the X-axis or Y-axis.

    • atBorderZ

      public boolean atBorderZ(Extent extent)
      Like atBorder(Extent) but considers only the Z-dimension.
      Parameters:
      extent - the size of the image.
      Returns:
      true iff the bounding box lies at the border along the Z-axis.

    • growBy

      public BoundingBox growBy(Tuple3i toAdd, Extent containingExtent)
      Grow the bounding-box by toAdd amount in each dimension in both positive and negative directions.

      The box will never be allowed grow larger than containingExtent.

      Unless constrained by the above, the bounding-box's corner and extent will typically both change.

      This is an immutable operation and current state will not be affected.

      Parameters:
      toAdd - the number of voxels to grow by in each direction. Each component should be non-negative.
      containingExtent - an extent the box must never grow beyond, in either the positive or negative directions.
      Returns:
      a newly created grown BoundingBox as per the above.

    • cornerMin

      public ReadableTuple3i cornerMin()
      The minimum corner of the bounding box in each dimension.
      Returns:
      the point used internally as a corner (exposed read-only).

    • calculateCornerMaxInclusive

      public ReadableTuple3i calculateCornerMaxInclusive()
      The maximum (right-most) point inside the box.

      This means that iterators should be <= calculateCornerMax().

      Returns:
      a newly created Point3i, indicating the maximum point inside the box in each dimension.

    • calculateCornerMaxExclusive

      public ReadableTuple3i calculateCornerMaxExclusive()
      The maximum (right-most) point just outside the box.

      It is equivalent to < calculateCornerMax() plus 1 in each dimension.

      This means that iterators should be < calculateCornerMaxExclusive().

      Returns:
      the maximum point inside the box in each dimension

    • clampTo

      public BoundingBox clampTo(Extent extent)
      Ensures that the box fits inside a Extent by reducing any values to their limits in the respective dimension.

      Values that are negative are forced to be 0.

      Values that are larger than the corresponding dimension in Extent are reduced to the maximum permitted in that dimension.

      Parameters:
      extent - the extent the box is made fit inside.
      Returns:
      a newly created bounding-box, if any changes are needed. Otherwise the existing object is reused.

    • relativePositionTo

      public Point3i relativePositionTo(BoundingBox other)
      The relative position of the corner to another bounding box.
      Parameters:
      other - the other box, against whom we consider our coordinates relatively.
      Returns:
      the difference between corners i.e. other bounding-box's corner - this bounding-box's corner.

    • relativePositionToBox

      public BoundingBox relativePositionToBox(BoundingBox other)
      A new bounding-box using relative position coordinates to another box.
      Parameters:
      other - the other box, against whom we consider our coordinates relatively.
      Returns:
      a newly created bounding box with relative coordinates.

    • contains

      public BoundingBoxContains contains()
      For evaluating whether this bounding-box contains other points, boxes etc.?
      Returns:
      a newly-created class to evaluate the contains relationship.

    • intersection

      public BoundingBoxIntersection intersection()
      For evaluating the intersection between this bounding-box and others.
      Returns:
      a newly-created class to evaluate the intersection relationship.

    • union

      public BoundingBoxUnion union()
      For performing a union between this bounding-box and another.
      Returns:
      a newly-created class to evaluate the union relationship.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • shiftToOrigin

      public BoundingBox shiftToOrigin()
      Moves the bounding-box to the origin (0,0,0) but preserves the extent.
      Returns:
      newly-created bounding box with shifted corner position (to the origin) and identical extent.

    • shiftBy

      public BoundingBox shiftBy(ReadableTuple3i shift)
      Shifts the bounding-box forwards.

      i.e. adds a vector to the corner position.

      Parameters:
      shift - what to add to the corner position.
      Returns:
      newly created bounding-box with shifted corner position and identical extent.

    • shiftBackBy

      public BoundingBox shiftBackBy(ReadableTuple3i shift)
      Shifts the bounding-box backwards.

      i.e. subtracts a vector from the corner position.

      Parameters:
      shift - what to subtract from the corner position.
      Returns:
      newly created bounding-box with shifted corner position and identical extent.

    • shiftTo

      public BoundingBox shiftTo(ReadableTuple3i cornerMinToAssign)
      Assigns a new corner-location to the bounding-box.
      Parameters:
      cornerMinToAssign - the new corner, which is used internally in the created BoundingBox. It should therefore not be modified subsequently externally.
      Returns:
      a bounding-box with a new corner and the same extent.

    • shiftToZ

      public BoundingBox shiftToZ(int cornerZToAssign)
      Assigns a new z-slice corner-location to the bounding-box.
      Parameters:
      cornerZToAssign - the new value in Z for the corner.
      Returns:
      a newly-created bounding-box with a new z-slice corner and the same extent.

    • reflectThroughOrigin

      public BoundingBox reflectThroughOrigin()
      Reflects the bounding box through the origin.

      i.e. x, y, z becomes -x, -y, -z.

      Returns:
      a newly-created bounding-box reflected through the origin.

    • scale

      public BoundingBox scale(ScaleFactor scaleFactor)
      Scales the bounding-box, both the corner-point and the extent.
      Parameters:
      scaleFactor - the scaling-factor.
      Returns:
      a new bounding-box with scaled corner-point and extent.

    • scaleClampTo

      public BoundingBox scaleClampTo(ScaleFactor scaleFactor, Extent clampTo)
      Scales the bounding-box, both the corner-point and the extent - ensuring it remains inside a containing-extent.
      Parameters:
      scaleFactor - scaling-factor.
      clampTo - clamps scaled-object's bounding-box to ensure it always fit inside (to catch any rounding errors that push the bounding box outside the scene-boundary).
      Returns:
      a new bounding-box with scaled corner-point and extent.

    • scale

      public BoundingBox scale(ScaleFactor scaleFactor, Extent extentToAssign)
      Scales the bounding-box corner-point, and assigns a new extent.
      Parameters:
      scaleFactor - scaling-factor.
      extentToAssign - extent to assign.
      Returns:
      a new bounding-box with scaled corner-point and the specified extent.

    • compareTo

      public int compareTo(BoundingBox other)
      Specified by:
      compareTo in interface Comparable<BoundingBox>

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • extent

      public Extent extent()
      Dimensions in pixels needed to represent the bounding box.

      This emanates in a positive direction from cornerMin to define the complete box.