Package org.anchoranalysis.image.voxel.object

Class ObjectMask

Object
ObjectMask
public class ObjectMask extends Object
A localized-mask in an image, expressed as a BoundingBox, with a corresponding mask sized to match the bounding-box.

This represents the concept of an object residing within the image.

Each voxel in the mask must be one of two states, either on or off. The object is specified by all voxels that are on.

The on voxels need not be contiguous i.e. they need not form a single connected-component.

The interfaces for assigning, extracting voxels etc. all expect global coordinates, expressed relative to the image's coordinates as a whole.

The voxels in the mask are mutable.

A point is informally referred to as belonging on or in in the object-mask, or being contained by the object-mask if it fulfills both the two conditions of:

  • The point exists inside the bounding-box.
  • The corresponding voxel in voxels() has an on state.

  • Constructor Details

  • Method Details

    • duplicate

      public ObjectMask duplicate()
      Creates a deep-copy of the current object-mask.
      Returns:
      a newly created mask that is a duplicate, including duplicating the voxel memory buffers.

    • replaceVoxels

      public ObjectMask replaceVoxels(Voxels<UnsignedByteBuffer> voxelsToAssign)
      Replaces the voxels in the object-mask.

      This is an immutable operation, and a new object-mask is created.

      Parameters:
      voxelsToAssign - voxels to be assigned.
      Returns:
      a new object with the replacement voxels but identical in other respects.

    • growToZ

      public ObjectMask growToZ(int sizeZ) throws OperationFailedException
      Grows a single z-sliced ObjectMask by duplicating the slice across the z-dimension sizeZ number of times.
      Parameters:
      sizeZ - the size in the z-dimension to grow to i.e. the number of duplicated sizes.
      Returns:
      a new BoundedVoxels with an identical corner, but with a 3D bounding-box (and duplicated slices) instead of the previous 2D.
      Throws:
      OperationFailedException - if the existing voxels aren't 2D (a single slice).

    • growBuffer

      public ObjectMask growBuffer(Point3i growthNegative, Point3i growthPositive, Optional<Extent> clipRegion) throws OperationFailedException
      Grows the object-mask's voxel buffers in the positive and negative directions by a certain amount.

      This operation is immutable.

      Parameters:
      growthNegative - how much to grow in the negative direction (i.e. downards direction on an axis).
      growthPositive - how much to grow in the positive direction (i.e. upwards direction on an axis).
      clipRegion - if defined, clips the buffer to this region.
      Returns:
      the grown object-mask with newly-created buffers.
      Throws:
      OperationFailedException - if the voxels are located outside the clipping region.

    • equalsDeep

      public boolean equalsDeep(ObjectMask other)
      A deep equality check with another ObjectMask.

      Each voxel must be identical, as well as identical binary-values and bounding-box.

      Parameters:
      other - the other ObjectMask to compare against.
      Returns:
      true iff the two object-masks are identical.

    • countIntersectingVoxels

      public int countIntersectingVoxels(ObjectMask other)
      Counts the number of intersecting-voxels between two object-masks.

      This is an immutable operation.

      Parameters:
      other - the other object-mask to consider.
      Returns:
      number of on-voxels the two object-masks have in common.

    • hasIntersectingVoxels

      public boolean hasIntersectingVoxels(ObjectMask other)
      Determines whether there are any intersecting voxels on two object-masks.

      This is an immutable operation.

      The algorithm exits as soon as an intersecting voxel is encountered i.e. as early as possible.

      Parameters:
      other - the other object-mask to consider.
      Returns:
      true if at least one voxel exists that is on in both object-masks.

    • scale

      public ObjectMask scale(ScaleFactor factor)
      Produces a scaled-version of an object-mask.

      This is an immutable operation.

      Parameters:
      factor - scale-factor.
      Returns:
      a scaled object-mask.

    • invert

      public ObjectMask invert()
      Produces a new object-mask that uses the same voxel-buffer but switches the off and on mapping.
      Returns:
      a newly created object-mask (reusing the same buffer).

    • scale

      public ObjectMask scale(ScaleFactor factor, Optional<Extent> clipTo)
      Produces a scaled-version of an object-mask.

      This is an immutable operation.

      Parameters:
      factor - scale-factor.
      clipTo - an extent which the object-masks should always fit inside after scaling (to catch any rounding errors that push the bounding box outside the scene-boundary).
      Returns:
      a scaled object-mask.

    • clampTo

      public ObjectMask clampTo(Extent extent)
      Makes sure an object fits inside an extent, removing any parts which do not.

      This is not an immutable operation, returning the current object unchanged if it already fits inside.

      Parameters:
      extent - the extent an object must fit in
      Returns:
      either the current object-mask unchanged (if it already fits inside) or a new object-mask clipped to fit inside

    • centerOfGravity

      public Point3d centerOfGravity()
      Calculates center-of-gravity across all axes.

      This is the mean of the position coordinates in each dimension.

      Returns:
      the center-of-gravity or (NaN, NaN, NaN) if there are no on voxels.

    • centerOfGravity

      public double centerOfGravity(Axis axis)
      Calculates center-of-gravity for one specific axis only.
      Parameters:
      axis - the specific axis.
      Returns:
      a point on the specific axis that is the center-of-gravity, or NaN if there are no on voxels.

    • checkIfConnected

      public boolean checkIfConnected()
      Determines if an object-mask is connected.

      Adjacent is defined with a big neighborhood definition i.e. with 8 or 26 connectivity.

      Returns:
      true if all on voxels in the mask are spatially adjacent to at least one other on voxel with.

    • voxelsOn

      public VoxelsPredicate voxelsOn()
      Provides a VoxelsPredicate that finds or counts all on voxels in the object-mask.
      Returns:
      the predicate.

    • voxelsOff

      public VoxelsPredicate voxelsOff()
      Provides a VoxelsPredicate that finds or counts all off voxels in the object-mask.
      Returns:
      the predicate.

    • numberVoxelsOn

      public int numberVoxelsOn()
      The number of on voxels on the object-mask.
      Returns:
      the number of voxels that are on.

    • intersect

      public Optional<ObjectMask> intersect(ObjectMask other, Extent extent)
      Intersects this object-mask with another

      This is an immutable operation (the existing two masks are not modified).

      Parameters:
      other - the other object-mask to intersect with
      extent - extent to constrain any intersection
      Returns:
      a new object of the intersecting region iff it exists

    • contains

      public boolean contains(Point3i point)
      Whether a particular point exists within the object-mask?

      For this to occur, two condition needs to be fulfilled for the point:

      • It exists inside the bounding-box.
      • The corresponding voxel in #voxels() has an on state.
      Parameters:
      point - the point to query.
      Returns:
      true iff both conditions as true, as per above.

    • flattenZ

      public ObjectMask flattenZ()
      A maximum-intensity projection.

      This flattens across z-dimension, setting a voxel to on if it is on in any one slice.

      This is an immutable operation.

      Returns:
      a new object-mask flattened in Z dimension.

    • boundingBox

      public BoundingBox boundingBox()
      The bounding-box which gives a location for the object-mask on an image.
      Returns:
      the bounding-box.

    • binaryVoxels

      public BinaryVoxels<UnsignedByteBuffer> binaryVoxels()
      The underlying voxel memory buffers for the object-mask, exposed via a BinaryVoxels.
      Returns:
      the voxels.

    • voxels

      public Voxels<UnsignedByteBuffer> voxels()
      The underlying voxel memory buffers for the object-mask, exposed via Voxels.
      Returns:
      the voxels.

    • boundedVoxels

      public BoundedVoxels<UnsignedByteBuffer> boundedVoxels()
      The underlying voxel memory buffers for the object-mask, exposed via BoundedVoxels.
      Returns:
      the voxels.

    • extent

      public Extent extent()
      The size of the object-mask's bounding-box across three dimensions.
      Returns:
      the size.

    • offsetRelative

      public int offsetRelative(int x, int y)
      Calculates an offset for locating a voxel inside the buffer, with local encoding of coordinates.
      Parameters:
      x - the X-dimension value for the voxel, relative to the object-mask's bounding-box.
      y - the Y-dimension value for the voxel, relative to the object-mask's bounding-box.
      Returns:
      the offset to use in the buffer specifying the location of this specific voxel.

    • offsetGlobal

      public int offsetGlobal(int x, int y)
      Calculates an offset for locating a voxel inside the buffer, with global encoding of coordinates.
      Parameters:
      x - the X-dimension value for the voxel, relative to the entire image scene.
      y - the Y-dimension value for the voxel, relative to the entire image scene.
      Returns:
      the offset to use in the buffer specifying the location of this specific voxel.

    • extractSlice

      public ObjectMask extractSlice(int sliceIndex, boolean keepIndex)
      Extracts one particular slice as an object-mask
      Parameters:
      sliceIndex - the z-slice in global coordinates
      keepIndex - iff true the z coordinate is reused for the slice, otherwise 0 is set
      Returns:
      a newly-created object reusing the slice's buffers

    • regionZ

      public ObjectMask regionZ(int zMin, int zMax) throws CreateException
      Creates an object-mask with a subrange of the slices.

      This will always reuse the existing Voxels.

      Parameters:
      zMin - minimum z-slice index, inclusive.
      zMax - maximum z-slice index, inclusive.
      Returns:
      a newly created object-mask for the slice-range requested.
      Throws:
      CreateException

    • region

      public ObjectMask region(BoundingBox box, boolean reuseIfPossible) throws CreateException
      A (sub-)region of the object-mask.

      The region may some smaller portion of the voxels, or the voxels as a whole.

      It should never be larger than the voxels.

      See VoxelsExtracter.region(org.anchoranalysis.spatial.box.BoundingBox, boolean) for more details.

      Parameters:
      box - bounding-box in absolute coordinates.
      reuseIfPossible - if true the existing object will be reused if possible, otherwise a new object is always created.
      Returns:
      an object-mask corresponding to the requested region, either newly-created or reused
      Throws:
      CreateException

    • regionIntersecting

      public ObjectMask regionIntersecting(BoundingBox box) throws CreateException
      Creates an object-mask covering the a bounding-box (that is required to intersect at least partially)

      The region outputted will have the same size and coordinates as the bounding-box not the existing ObjectMask.

      It will contain the correct object-mask values for the intersecting region, and off values for the rest.

      A new voxel-buffer is always created for this operation i.e. the existing box is never reused like sometimes in region(org.anchoranalysis.spatial.box.BoundingBox, boolean).

      Parameters:
      box - bounding-box in absolute coordinates, that must at least partially intersect with the current object-mask bounds.
      Returns:
      a newly created object-mask containing partially some parts of the existing object-mask as well as off voxels for any other region.
      Throws:
      CreateException - if the boxes do not intersect.

    • findArbitraryOnVoxel

      public Optional<Point3i> findArbitraryOnVoxel()
      Finds any arbitrary on voxel on the object.

      First it tries the center-of-gravity voxel, and if that's not on, it iterates through the box until it finds an on voxel.

      This is a DETERMINISTIC operation, so one can rely on the same voxel being found for a given object.

      Returns:
      the location (in absolute coordinates) of an arbitrary on voxel on the object, if it exists.

    • sliceBufferLocal

      public UnsignedByteBuffer sliceBufferLocal(int sliceIndexRelative)
      A slice buffer with local coordinates.

      i.e. with coordinates relative to the bounding-box corner.

      Parameters:
      sliceIndexRelative - sliceIndex (z) relative to the bounding-box of the object-mask.
      Returns:
      the buffer.

    • sliceBufferGlobal

      public UnsignedByteBuffer sliceBufferGlobal(int sliceIndexGlobal)
      A slice buffer with global coordinates.
      Parameters:
      sliceIndexGlobal - sliceIndex (z) in global coordinates.
      Returns:
      the buffer.

    • shiftToOrigin

      public ObjectMask shiftToOrigin()
      Creates a new object-mask with identical voxels but with the bounding-box beginning at the origin (0,0,0).

      This is an immutable operation: but beware the existing voxel-buffers are reused in the new object.

      Returns:
      a new object-mask reusing the existing voxel-buffers.

    • shiftBy

      public ObjectMask shiftBy(ReadableTuple3i shift)
      Shifts the object-mask by moving its bounding-box forwards.

      i.e. by adding shift from its corner.

      This is an immutable operation: but beware the existing voxel-buffers are reused in the new object.

      Parameters:
      shift - what to add from the corner position
      Returns:
      a new object-mask reusing the existing voxel-buffers.

    • shiftBackBy

      public ObjectMask shiftBackBy(ReadableTuple3i shift)
      Shifts the object-mask by moving its bounding-box backwards.

      i.e. by subtracting shift from its corner.

      This is an immutable operation: but beware the existing voxel-buffers are reused in the new object.

      Parameters:
      shift - what to subtract from the corner position.
      Returns:
      a new object-mask reusing the existing voxel-buffers.

    • mapBoundingBoxPreserveExtent

      public ObjectMask mapBoundingBoxPreserveExtent(UnaryOperator<BoundingBox> mapOperation)
      Applies a function to map the bounding-box to a new-value (whose extent should be unchanged in value).

      This is an immutable operation: but beware the existing voxel-buffers are reused in the new object.

      Parameters:
      mapOperation - map function to perform mapping of bounding-box.
      Returns:
      a new object-mask with the updated bounding box (but unchanged voxels).

    • mapBoundingBoxChangeExtent

      public ObjectMask mapBoundingBoxChangeExtent(BoundingBox boxToAssign)
      Applies a function to map the bounding-box to a new-value (whose extent is expected to change in value).

      This is a almost immutable operation, and NEW voxel-buffers are usually created for the new object, but not if the bounding-box or its extent need no change.

      Precondition: the new bounding-box's extent must be greater than or equal to the existing extent in all dimensions.

      Parameters:
      boxToAssign - bounding-box to assign.
      Returns:
      a new object-mask with the updated bounding box (and changed voxels).

    • relativeMaskTo

      public ObjectMask relativeMaskTo(BoundingBox box)
      Creates a new object-mask with coordinates changed to be relative to another box.

      This is an immutable operation.

      Parameters:
      box - box used as a reference point, against which new relative coordinates are calculated.
      Returns:
      a newly created object-mask with updated coordinates.

    • assignOn

      public VoxelsAssigner assignOn()
      Assigns the on value to voxels, expecting global coordinates.
      Returns:
      the assigner.

    • assignOff

      public VoxelsAssigner assignOff()
      Assigns the off value to voxels, expecting global coordinates.
      Returns:
      the assigner.

    • derivePointsLocal

      public List<Point3i> derivePointsLocal()
      Creates a list of all on voxels as points, using local coordinates i.e. relative to the bounding-box corner.
      Returns:
      a newly created list with newly created points.

    • toString

      public String toString()
      A string representation of the object-mask showing:
      1. the center-of-gravity.
      2. the number of on voxels on the object.
      Overrides:
      toString in class Object

    • binaryValues

      public BinaryValuesInt binaryValues()
      What values constitute an on and off state in voxels - as ints.

    • binaryValuesByte

      public BinaryValuesByte binaryValuesByte()
      What values constitute an on and off state in voxels - as bytes.

    • extract

      public VoxelsExtracter<UnsignedByteBuffer> extract()
      Provides methods to read/copy/duplicate regions of voxels.