Package org.anchoranalysis.spatial.box

Class Extent

Object
Extent
All Implemented Interfaces:
Serializable, Comparable<Extent>
public final class Extent extends Object implements Serializable, Comparable<Extent>
The sizes: width, height, depth etc. of an entity in 2 or 3 dimensions.

When describing a 2D entity, the depth (Z-axis value) is always 1.

Each size corresponds to the perpendicular Cartesian axes i.e. X, Y and Z axes.

This class is immutable. No operation will modify existing state.

The area (width by height) is pre-calculated to make certain operations like calculating offsets (which may need to be called frequently) efficient. However, for sizes producing very large areas that exceed the bounds of an int these need to be handled separately and carefully. These cases can be checked for by calling areaXY().

See Also:

  • Constructor Details

    • Extent

      public Extent(int x, int y)
      Creates with with only X and Y dimensions.

      The z-dimension is assigned a value of 1.

      Parameters:
      x - size along the X-axis dimension.
      y - size along the Y-axis dimension.

    • Extent

      public Extent(int x, int y, int z)
      Creates with X and Y and Z dimensions.
      Parameters:
      x - size along the X-axis dimension.
      y - size along the Y-axis dimension.
      z - size along the Z-axis dimension.

  • Method Details

    • createFromTupleDuplicate

      public static Extent createFromTupleDuplicate(ReadableTuple3i tuple)
      Creates from a ReadableTuple3i representing the sizes in each dimension, where the tuple is not used internally.

      The tuple is not used internally, with its values being copied in the constructor.

      Parameters:
      tuple - a tuple with the extent size's for each dimension.
      Returns:
      a newly created extent - that doesn't reuse tuple internally.

    • createFromTupleReuse

      public static Extent createFromTupleReuse(ReadableTuple3i tuple)
      Creates from a ReadableTuple3i representing the sizes in each dimension, where the tuple is used internally.
      Parameters:
      tuple - a tuple with the extent size's for each dimension.
      Returns:
      a newly created extent - that reuses tuple internally.

    • areaXY

      public int areaXY()
      Size in X multiplied by size in Y.

      This may be convenient for calculating offsets and for iterations.

      Note that for very large sizes (e.g. the sizes of whole-slide images) an int may be insufficiently large to capture the area. Consider instead using calculateAreaXYAsDouble() in these cases.

      Returns:
      the X-size multiplied by the Y-size.
      Throws:
      AnchorFriendlyRuntimeException - if the area is too large to be expressed as an int.

    • calculateAreaXYAsDouble

      public double calculateAreaXYAsDouble()
      Calculates the area freshly by multiplying the x-size with y-size, as doubles.

      This is useful if the area would otherwise be too large to be represented as an int.

      Any previously calculated area is ignored.

      Returns:
      the area calculated as a double.

    • calculateVolume

      public long calculateVolume()
      Calculates the volume of the Extent when considered as a box.

      This is is the size in the X, Y and Z dimensions multiplied together.

      Returns:
      the volume in voxels.

    • calculateVolumeAsInt

      public int calculateVolumeAsInt()
      Like calculateVolume() but uses an int to calculate the volume.

      A AnchorFriendlyRuntimeException is thrown if an overflow occurs.

      Returns:
      the volume in voxels.

    • isEmpty

      public boolean isEmpty()
      Does the extent contain zero voxels?
      Returns:
      true if any dimension has size 0.

    • x

      public int x()
      The size in the X dimension.
      Returns:
      the size.

    • y

      public int y()
      The size in the Y dimension.
      Returns:
      the size.

    • z

      public int z()
      The size in the Z dimension.
      Returns:
      the size.

    • valueByDimension

      public int valueByDimension(int dimensionIndex)
      The size in the dimension identified by dimensionIndex.
      Parameters:
      dimensionIndex - the dimension to return a size for, as per ReadableTuple3i#valueByDimension(int).
      Returns:
      the size.

    • valueByDimension

      public int valueByDimension(Axis axis)
      The size in the dimension identified by axis.
      Parameters:
      axis - the dimension to return a size for, as per ReadableTuple3i#valueByDimension(Axis).
      Returns:
      the size.

    • asTuple

      public ReadableTuple3i asTuple()
      Exposes the extent as a tuple.

      Importantly, this class is designed to be immutable, so this tuple should be treated as read-only, and never modified.

      Returns:
      the extent's width, height, depth as a tuple.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

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

    • equalsIgnoreZ

      public boolean equalsIgnoreZ(Extent other)
      Checks for equality with another extent ignoring any differences in the Z dimension.
      Parameters:
      other - the extent to check for equality with.
      Returns:
      true if the current extent is identical to obj ignoring the Z dimension.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • offset

      public final int offset(int x, int y)
      Calculates a XY-offset of a point in a buffer whose dimensions are this extent.
      Parameters:
      x - the value in the X-dimension for the point.
      y - the value in the Y-dimension for the point.
      Returns:
      the offset, pertaining only to all dimensions.

    • offset

      public final int offset(int x, int y, int z)
      Calculates a XYZ-offset of a point in a buffer whose dimensions are this extent.

      To be computationally efficient, this does not actively check that areaXY is non-negative. It is the responsibility of the caller of this function to otherwise check this, or infer it from context.

      Parameters:
      x - the value in the X-dimension for the point.
      y - the value in the Y-dimension for the point.
      z - the value in the Z-dimension for the point.
      Returns:
      the offset, pertaining only to all dimensions.

    • offset

      public final int offset(ReadableTuple3i point)
      Calculates a XYZ-offset of a point in a buffer whose dimensions are this extent.

      To be computationally efficient, this does not actively check that areaXY is non-negative. It is the responsibility of the caller of this function to otherwise check this, or infer it from context.

      Parameters:
      point - the point to calculate an offset for.
      Returns:
      the offset, pertaining only to all dimensions.

    • offset

      public final int offset(Point2i point)
      Calculates a XY-offset of a point in a buffer whose dimensions are this extent.

      To be computationally efficient, this does not actively check that areaXY is non-negative. It is the responsibility of the caller of this function to otherwise check this, or infer it from context.

      Parameters:
      point - the point to calculate an offset for.
      Returns:
      the offset, pertaining only to the X and Y dimensions.

    • offsetSlice

      public final int offsetSlice(ReadableTuple3i point)
      Calculates a XY-offset of a point in a buffer whose dimensions are this extent.

      To be computationally efficient, this does not actively check that areaXY is non-negative. It is the responsibility of the caller of this function to otherwise check this, or infer it from context.

      Parameters:
      point - the point to calculate an offset for.
      Returns:
      the offset, pertaining only to the X and Y dimensions.

    • duplicateChangeX

      public Extent duplicateChangeX(int xToAssign)
      Creates a copy of the current Extent with the value for the X-dimension changed.
      Parameters:
      xToAssign - the value to assign for the x-dimension.
      Returns:
      the copy, with a changed x-value.

    • duplicateChangeY

      public Extent duplicateChangeY(int yToAssign)
      Creates a copy of the current Extent with the value for the Y-dimension changed.
      Parameters:
      yToAssign - the value to assign for the y-dimension.
      Returns:
      the copy, with a changed y-value.

    • duplicateChangeZ

      public Extent duplicateChangeZ(int zToAssign)
      Creates a copy of the current Extent with the value for the Z-dimension changed.
      Parameters:
      zToAssign - the value to assign for the z-dimension.
      Returns:
      the copy, with a changed z-value.

    • containsX

      public boolean containsX(double value)
      Is a value contained within the extent on the X-axis?
      Parameters:
      value - the value to check.
      Returns:
      true iff the value is non-negative and less than the size of the extent in the X-axis.

    • containsY

      public boolean containsY(double value)
      Is a value contained within the extent on the Y-axis?
      Parameters:
      value - the value to check.
      Returns:
      true iff the value is non-negative and less than the size of the extent in the Y-axis.

    • containsZ

      public boolean containsZ(double value)
      Is a value contained within the extent on the Z-axis?
      Parameters:
      value - the value to check.
      Returns:
      true iff the value is non-negative and less than the size of the extent in the Z-axis.

    • containsX

      public boolean containsX(int value)
      Is a value contained within the extent on the X-axis?
      Parameters:
      value - the value to check.
      Returns:
      true iff the value is non-negative and less than the size of the extent in the X-axis.

    • containsY

      public boolean containsY(int value)
      Is a value contained within the extent on the Y-axis?
      Parameters:
      value - the value to check.
      Returns:
      true iff the value is non-negative and less than the size of the extent in the Y-axis.

    • containsZ

      public boolean containsZ(int value)
      Is a value contained within the extent on the Z-axis?
      Parameters:
      value - the value to check.
      Returns:
      true iff the value is non-negative and less than the size of the extent in the Z-axis.

    • contains

      public boolean contains(Point2i point)
      Is a point of type Point2i contained within the extent in the XY plane?

      The z-dimension is ignored.

      Parameters:
      point - the point to check.
      Returns:
      true iff the point exists within the plane.

    • contains

      public boolean contains(Point3d point)
      Is a point of type Point3d contained within the extent?
      Parameters:
      point - the point to check.
      Returns:
      true iff the point exists within the extent, considering all axes.

    • contains

      public boolean contains(ReadableTuple3i point)
      Is a point of type ReadableTuple3i contained within the extent?
      Parameters:
      point - the point to check.
      Returns:
      true iff the point exists within the extent, considering all axes.

    • contains

      public boolean contains(int x, int y, int z)
      Is a point contained within the extent?
      Parameters:
      x - the value of the point on the x-axis.
      y - the value of the point on the y-axis.
      z - the value of the point on the z-axis.
      Returns:
      true iff the point exists within the extent, considering all axes.

    • contains

      public boolean contains(BoundingBox box)
      Is box entirely contained within the extent?
      Parameters:
      box - the bounding-box to check.
      Returns:
      true iff only describes space contained in the current extent.

    • scaleXYBy

      public Extent scaleXYBy(ScaleFactor scaleFactor, boolean round)
      Scales the X- and Y- dimensions by a scaling-factor.
      Parameters:
      scaleFactor - the scaling-factor to multiply the respective X and Y dimension values by.
      round - if true, each dimension is rounded to the nearest whole number. If false, it is ceiled upwards to the nearest number.
      Returns:
      a new Extent whose X and Y values are scaled versions of the current values, and Z value is unchanged.

    • scaleXYBy

      public Extent scaleXYBy(double scaleFactor, boolean round)
      Scales all dimensions by a scaling-factor.
      Parameters:
      scaleFactor - the scaling-factor to multiply the respective dimension values by.
      round - if true, each dimension is rounded to the nearest whole number. If false, it is ceiled upwards to the nearest number.
      Returns:
      a new Extent whose dimension values are scaled versions of the current values, with a minimum of 1.

    • createMinusOne

      public Point3i createMinusOne()
      Creates a new Extent with each dimension decreased by one.
      Returns:
      the new extent.

    • growBy

      public Extent growBy(int toAdd)
      Creates a new Extent with toAdd size added to each dimension.
      Parameters:
      toAdd - the number of voxels to add to all dimensions.
      Returns:
      a newly created Extent grown as per above.

    • growBy

      public Extent growBy(ReadableTuple3i toAdd)
      Creates a new Extent with toAdd size added to each respective dimension.
      Parameters:
      toAdd - the number of voxels to add to each dimension.
      Returns:
      a newly created Extent grown as per above.

    • shrinkBy

      public Extent shrinkBy(ReadableTuple3i toSubtract)
      Creates a new Extent with toSubtract size subtracted from each respective dimension.
      Parameters:
      toSubtract - the number of voxels to subtract from each dimension.
      Returns:
      a newly created Extent shrunk as per above.

    • intersectWith

      public Extent intersectWith(Extent other)
      Intersects this extent with another (i.e. takes the smaller value in each dimension).
      Parameters:
      other - the other.
      Returns:
      a newly-created extent that is the intersection of this and another.

    • flattenZ

      public Extent flattenZ()
      Collapses the Z dimension.
      Returns:
      a new otherwise identical extent bit with size of of 1 in Z-dimension.

    • anyDimensionIsLargerThan

      public boolean anyDimensionIsLargerThan(Extent other)
      Returns true if any dimension in this extent is larger than the corresponding dimension in other extent.
      Parameters:
      other - extent to compare to.
      Returns:
      true or false (if all dimensions or less than or equal to their corresponding dimension in other).

    • iterateOverXY

      public <E extends Exception> void iterateOverXY(OffsettedScalarTwoDimensionalConsumer<E> pointConsumer) throws E
      Calls processor once for each x and y-values in the range.

      This occurs in ascending order (x-dimension increments first, y-dimension increments second).

      Type Parameters:
      E - a checked-exception that indexConsumer may throw.
      Parameters:
      pointConsumer - called for each point.
      Throws:
      E - if indexConsumer throws this exception.

    • iterateOverXY

      public void iterateOverXY(PointTwoDimensionalConsumer pointConsumer)
      Calls processor once for each x and y-values in the range.

      This occurs in ascending order (x-dimension increments first, y-dimension increments second).

      Parameters:
      pointConsumer - called for each point.

    • iterateOverXYWithShift

      public void iterateOverXYWithShift(Point2i shift, PointTwoDimensionalConsumer pointConsumer)
      Calls processor once for each x and y-values in the range, with a shift added.

      This occurs in ascending order (x-dimension increments first, y-dimension increments second).

      Parameters:
      shift - a shift added to each point, so the effective iteration occurs over @ extent + shift.
      pointConsumer - called for each point.

    • iterateOverXYOffset

      public <E extends Exception> void iterateOverXYOffset(CheckedIntConsumer<E> offsetConsumer) throws E
      Calls processor once for each x and y-values but only passing an offset.

      This occurs in ascending order (x-dimension increments first, y-dimension increments second).

      Type Parameters:
      E - a checked-exception that offsetConsumer may throw.
      Parameters:
      offsetConsumer - called for each point with the offset.
      Throws:
      E - if indexConsumer throws this exception.
      AnchorFriendlyRuntimeException - if the area is too large to be expressed as an int.

    • iterateOverXYOffset

      public void iterateOverXYOffset(OffsettedPointTwoDimensionalConsumer pointConsumer)
      Calls processor once for each x and y-values in the range.

      This occurs in ascending order (x-dimension increments first, y-dimension increments second).

      Parameters:
      pointConsumer - called for each point.

    • iterateOverYXOffset

      public void iterateOverYXOffset(OffsettedPointTwoDimensionalConsumer pointConsumer)
      Calls processor once for each x and y-values in the range.

      This occurs in ascending order (x-dimension increments first, y-dimension increments second).

      Parameters:
      pointConsumer - called for each point.

    • iterateOverZ

      public <E extends Exception> void iterateOverZ(CheckedIntConsumer<E> indexConsumer) throws E
      Calls processor once for each z-value in the range.

      This occurs sequentially from 0 (inclusive) to z() (exclusive).

      Type Parameters:
      E - a checked-exception that indexConsumer may throw
      Parameters:
      indexConsumer - called for each index (z-value)
      Throws:
      E - if indexConsumer throws this exception

    • iterateOverZUntil

      public boolean iterateOverZUntil(IntPredicate indexPredicate)
      Calls processor once for each z-value in the range unless indexPredicate returns false.

      This occurs sequentially from 0 (inclusive) to z() (exclusive).

      As soon as the indexPredicate returns false, the iteration stops.

      Parameters:
      indexPredicate - called for each index (z-value)
      Returns:
      true if indexPredicate always returned true for every slice, false otherwise.

    • streamOverZ

      public IntStream streamOverZ()
      Streams over the range of z values.

      The values range from 0 (inclusive) to z() (exclusive).

      Returns:
      the stream.

    • toArray

      public int[] toArray()
      Derives an three-element array with each dimension in the extent.
      Returns:
      a newly created three-element array with respectively extents for the x, y and z dimensions.

    • minimum

      public Extent minimum(Extent extent)
      An extent that contains the minimum of two extents for each dimension respectively.

      This is an immutable operation.

      Parameters:
      extent - the other extent to find a minimum with.
      Returns:
      a newly created extent.

    • aspectRatioXY

      public double aspectRatioXY()
      Derives an aspect-ratio, by dividing the X-dimension by the Y-dimension value.

      Note that the Z-dimension is irrelevant to this calculation.

      Returns:
      The X-dimension divided by the Y-dimension.

    • compareTo

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