Package org.anchoranalysis.image.voxel

Class BoundedVoxels<T>

Object
BoundedVoxels<T>
Type Parameters:
T - buffer-type
public class BoundedVoxels<T> extends Object
Voxels that exist within a particular bounding-box in an image.

The Voxels must always have identical Extent to the bounding-box.

Author:
Owen Feehan

  • Constructor Details

    • BoundedVoxels

      public BoundedVoxels(Voxels<T> voxels)
      Creates voxels bounded to match the entire voxel-data at the origin.
      Parameters:
      voxels - voxel-data.

    • BoundedVoxels

      public BoundedVoxels(BoundedVoxels<T> source)
      Copy constructor.

      It is a deep copy. The voxel memory buffer is duplicated.

      Parameters:
      source - where to copy from.

    • BoundedVoxels

      public BoundedVoxels(BoundingBox boundingBox, Voxels<T> voxels)
      Creates voxels with a corresponding bounding box.
      Parameters:
      boundingBox - bounding-box.
      voxels - voxels which must have the same extent as boundingBox.

  • Method Details

    • equalsDeep

      public boolean equalsDeep(BoundedVoxels<?> other)
      Performs a deep equality check, that includes checking that each voxel has an identical value.
      Parameters:
      other - the voxels to check with.
      Returns:
      true iff the two BoundedVoxels instances have identical values and bounding-boxes.

    • replaceVoxels

      public BoundedVoxels<T> replaceVoxels(Voxels<T> voxelsToAssign)
      Replaces the voxels in the box.

      This is an immutable operation, and a new Voxels are created.

      Parameters:
      voxelsToAssign - voxels to be assigned.
      Returns:
      a newly created replacement voxels but with an identical bounding-box.

    • growToZ

      public BoundedVoxels<T> growToZ(int sizeZ, VoxelsFactoryTypeBound<T> factory) throws OperationFailedException
      Grows a single z-sliced BoundedVoxels 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.
      factory - a factory to use to create the duplicated voxels.
      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).

    • dilate

      public BoundingBox dilate(boolean do3D, Optional<Extent> clipRegion)
      Grow bounding-box by 1 pixel in all directions.
      Parameters:
      do3D - 3-dimensions (true) or 2-dimensions (false).
      clipRegion - a region to clip to, which we can't grow beyond.
      Returns:
      a bounding box: the corner is the relative-position to the current bounding box, the extent is absolute.

    • growBuffer

      public BoundedVoxels<T> growBuffer(Point3i growthNegative, Point3i growthPositive, Optional<Extent> clipRegion, VoxelsFactoryTypeBound<T> factory) throws OperationFailedException
      Grows the voxel buffer 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.
      factory - a factory to create VoxelsFactoryTypeBound.
      Returns:
      a new Voxels with grown buffers.
      Throws:
      OperationFailedException - if the voxels are located outside the clipping region.

    • scale

      public BoundedVoxels<T> scale(ScaleFactor scaleFactor, VoxelsResizer resizer, Optional<Extent> clipTo)
      Creates a scaled-version (in XY dimensions only) of the current bounding-box.

      This is an immutable operation.

      Parameters:
      scaleFactor - what to scale X and Y dimensions by?
      resizer - an interpolator for resizing voxels.
      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 new BoundedVoxels box of specified size containing scaled contents of the existing.

    • projectMax

      public BoundedVoxels<T> projectMax()
      A maximum-intensity projection (flattens in z dimension)

      This is an immutable operation.

      Returns:
      newly-created bounded-voxels flattened in Z dimension.

    • duplicate

      public BoundedVoxels<T> duplicate()
      A deep-copy of the current structure.
      Returns:
      a copy of the current data, including duplication of the memory buffers for the voxels.

    • sliceBufferLocal

      public T sliceBufferLocal(int sliceIndexRelative)
      A slice buffer with local coordinates.
      Parameters:
      sliceIndexRelative - sliceIndex (z) relative to the associated bounding-box minimum corner.
      Returns:
      the buffer.

    • sliceBufferGlobal

      public T sliceBufferGlobal(int sliceIndexGlobal)
      A slice buffer with global coordinates.
      Parameters:
      sliceIndexGlobal - sliceIndex (z) in global coordinates (relative to the image as a whole).
      Returns:
      the buffer.

    • extent

      public Extent extent()
      The size of the voxels across three dimensions, and also the size of the associated bounding-box.
      Returns:
      the size.

    • regionZ

      public BoundedVoxels<T> regionZ(int zMin, int zMax, VoxelsFactoryTypeBound<T> factory) throws CreateException
      Creates an box with a subrange of the slices.

      This will always reuse the existing voxel-buffers.

      Parameters:
      zMin - minimum z-slice index, inclusive.
      zMax - maximum z-slice index, inclusive.
      factory - factory to use to create new voxels.
      Returns:
      a newly created box for the slice-range requested.
      Throws:
      CreateException - if zMin or zMax are outside the permitted range.

    • region

      public BoundedVoxels<T> region(BoundingBox box, boolean reuseIfPossible) throws CreateException
      A (sub-)region of the voxels.

      The region may some smaller portion of the voxels, or the voxels in their entirety.

      It should never be larger than the voxels.

      Parameters:
      box - bounding-box in absolute coordinates.
      reuseIfPossible - if true the existing box will be reused if possible, otherwise a new box is always created.
      Returns:
      bounded0voxels corresponding to the requested region, either newly-created or reused
      Throws:
      CreateException - if the source box does not contain the target box.
      See Also:

    • regionIntersecting

      public BoundedVoxels<T> regionIntersecting(BoundingBox box, int voxelValueForRest) throws CreateException
      Like region(org.anchoranalysis.spatial.box.BoundingBox, boolean) but only expects a bounding-box that intersects at least partially.

      This is a weakened condition compared to region(org.anchoranalysis.spatial.box.BoundingBox, boolean).

      The region outputted will have the same size and coordinates as the bounding-box, but with the correct voxel-values for the part within the voxels. Any other voxels are set to voxelValueForRest.

      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 bounds.
      voxelValueForRest - a voxel-value for the parts of the buffer not covered by the intersection.
      Returns:
      newly created voxels containing partially some parts of the existing voxels and other regions.
      Throws:
      CreateException - if the boxes do not intersect.

    • mapBoundingBoxPreserveExtent

      public BoundedVoxels<T> mapBoundingBoxPreserveExtent(BoundingBox boundingBoxToAssign)
      Applies a function to map the bounding-box to a new-value.

      The Extent of the bounding-box should remain unchanged in value.

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

      Parameters:
      boundingBoxToAssign - the new bounding-box to assign.
      Returns:
      a new object-mask with the updated bounding box.

    • extractSlice

      public BoundedVoxels<T> extractSlice(int sliceIndex)
      Extracts a particular slice.

      This is an immutable operation, but the voxels-buffer for the slice is reused.

      Parameters:
      sliceIndex - which slice to extract (z) in global coordinates.
      Returns:
      the extracted-slice (bounded).

    • 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).

    • replaceSlice

      public void replaceSlice(int sliceIndexToUpdate, VoxelBuffer<T> bufferToAssign)
      Assigns a new buffer for a slice.

      This is a mutable operation.

      Parameters:
      sliceIndexToUpdate - slice-index to update.
      bufferToAssign - buffer to assign.

    • arithmetic

      public VoxelsArithmetic arithmetic()
      Interface that allows manipulation of voxel intensities via arithmetic operations.
      Returns:
      the interface.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • assignValue

      public VoxelsAssigner assignValue(int valueToAssign)
      Assigns a value to a bounded-voxels accepting global coordinates for objects, boxes etc.
      Parameters:
      valueToAssign - value to assign.
      Returns:
      an assigner that expects global coordinates.

    • extract

      public final VoxelsExtracter<T> extract()
      Extracts value from voxels using global coordinates (relative to the image as a whole).
      Returns:
      an extracter instance.

    • boundingBox

      public BoundingBox boundingBox()
      A bounding-box that associates voxels to a particular part of an image.

    • voxels

      public Voxels<T> voxels()
      Voxel-data that fits inside the bounding-box (its extent is invariant with the extent of the bounding-box).