public class ObjectMask extends Object
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:
voxels()
has an on state.
Modifier and Type | Method and Description |
---|---|
VoxelsAssigner |
assignOff()
Assigns the off value to voxels, expecting global coordinates.
|
VoxelsAssigner |
assignOn()
Assigns the on value to voxels, expecting global coordinates.
|
BinaryValuesInt |
binaryValues()
What values constitute an on and off state in
voxels - as ints. |
BinaryValuesByte |
binaryValuesByte()
What values constitute an on and off state in
voxels - as bytes. |
BinaryVoxels<UnsignedByteBuffer> |
binaryVoxels()
The underlying voxel memory buffers for the object-mask, exposed via a
BinaryVoxels . |
BoundedVoxels<UnsignedByteBuffer> |
boundedVoxels()
The underlying voxel memory buffers for the object-mask, exposed via
BoundedVoxels . |
BoundingBox |
boundingBox()
The bounding-box which gives a location for the object-mask on an image.
|
Point3d |
centerOfGravity()
Calculates center-of-gravity across all axes.
|
double |
centerOfGravity(Axis axis)
Calculates center-of-gravity for one specific axis only.
|
boolean |
checkIfConnected()
Determines if an object-mask is connected.
|
ObjectMask |
clampTo(Extent extent)
Makes sure an object fits inside an extent, removing any parts which do not.
|
boolean |
contains(Point3i point)
Whether a particular point exists within the object-mask?
|
int |
countIntersectingVoxels(ObjectMask other)
Counts the number of intersecting-voxels between two object-masks.
|
List<Point3i> |
derivePointsLocal()
Creates a list of all on voxels as points, using local coordinates i.e.
|
ObjectMask |
duplicate()
Creates a deep-copy of the current object-mask.
|
boolean |
equalsDeep(ObjectMask other)
A deep equality check with another
ObjectMask . |
Extent |
extent()
The size of the object-mask's bounding-box across three dimensions.
|
VoxelsExtracter<UnsignedByteBuffer> |
extract()
Provides methods to read/copy/duplicate regions of voxels.
|
ObjectMask |
extractSlice(int sliceIndex,
boolean keepIndex)
Extracts one particular slice as an object-mask
|
Optional<Point3i> |
findArbitraryOnVoxel()
Finds any arbitrary on voxel on the object.
|
ObjectMask |
flattenZ()
A maximum-intensity projection.
|
ObjectMask |
growBuffer(Point3i growthNegative,
Point3i growthPositive,
Optional<Extent> clipRegion)
Grows the object-mask's voxel buffers in the positive and negative directions by a certain
amount.
|
ObjectMask |
growToZ(int sizeZ)
Grows a single z-sliced
ObjectMask by duplicating the slice across the z-dimension
sizeZ number of times. |
boolean |
hasIntersectingVoxels(ObjectMask other)
Determines whether there are any intersecting voxels on two object-masks.
|
Optional<ObjectMask> |
intersect(ObjectMask other,
Extent extent)
Intersects this object-mask with another
|
ObjectMask |
invert()
Produces a new object-mask that uses the same voxel-buffer but switches the off and
on mapping.
|
ObjectMask |
mapBoundingBoxChangeExtent(BoundingBox boxToAssign)
Applies a function to map the bounding-box to a new-value (whose extent is expected to change
in value).
|
ObjectMask |
mapBoundingBoxPreserveExtent(java.util.function.UnaryOperator<BoundingBox> mapOperation)
Applies a function to map the bounding-box to a new-value (whose extent should be unchanged
in value).
|
int |
numberVoxelsOn()
The number of on voxels on the object-mask.
|
int |
offsetGlobal(int x,
int y)
Calculates an offset for locating a voxel inside the buffer, with global encoding of
coordinates.
|
int |
offsetRelative(int x,
int y)
Calculates an offset for locating a voxel inside the buffer, with local encoding of
coordinates.
|
ObjectMask |
region(BoundingBox box,
boolean reuseIfPossible)
A (sub-)region of the object-mask.
|
ObjectMask |
regionIntersecting(BoundingBox box)
Creates an object-mask covering the a bounding-box (that is required to intersect at least
partially)
|
ObjectMask |
regionZ(int zMin,
int zMax)
Creates an object-mask with a subrange of the slices.
|
ObjectMask |
relativeMaskTo(BoundingBox box)
Creates a new object-mask with coordinates changed to be relative to another box.
|
ObjectMask |
replaceVoxels(Voxels<UnsignedByteBuffer> voxelsToAssign)
Replaces the voxels in the object-mask.
|
ObjectMask |
scale(ScaleFactor factor)
Produces a scaled-version of an object-mask.
|
ObjectMask |
scale(ScaleFactor factor,
Optional<Extent> clipTo)
Produces a scaled-version of an object-mask.
|
ObjectMask |
shiftBackBy(ReadableTuple3i shift)
Shifts the object-mask by moving its bounding-box backwards.
|
ObjectMask |
shiftBy(ReadableTuple3i shift)
Shifts the object-mask by moving its bounding-box forwards.
|
ObjectMask |
shiftToOrigin()
Creates a new object-mask with identical voxels but with the bounding-box beginning at the
origin (0,0,0).
|
UnsignedByteBuffer |
sliceBufferGlobal(int sliceIndexGlobal)
A slice buffer with global coordinates.
|
UnsignedByteBuffer |
sliceBufferLocal(int sliceIndexRelative)
A slice buffer with local coordinates.
|
String |
toString()
A string representation of the object-mask showing:
the center-of-gravity.
|
Voxels<UnsignedByteBuffer> |
voxels()
The underlying voxel memory buffers for the object-mask, exposed via
Voxels . |
VoxelsPredicate |
voxelsOff()
Provides a
VoxelsPredicate that finds or counts all off voxels in the
object-mask. |
VoxelsPredicate |
voxelsOn()
Provides a
VoxelsPredicate that finds or counts all on voxels in the
object-mask. |
public ObjectMask(Voxels<UnsignedByteBuffer> voxels)
Voxels
mask that is cornered at the origin.
i.e. the bounding box corner is set as 0,0,0
.
Default BinaryValuesInt
of (off=0
, on=255
) are used to interpret
Voxels
as a mask.
The Voxels
are reused internally in memory without duplication.
voxels
- voxels to be used in the object-mask.public ObjectMask(BoundingBox box)
Default BinaryValuesInt
of (off=0, on=255) are used for the mask.
box
- bounding-box.public ObjectMask(BoundedVoxels<UnsignedByteBuffer> voxels)
BoundedVoxels
with UnsignedByteBuffer
.
The voxels are reused without duplication.
Default BinaryValuesInt
of (off=0, on=255) are assumed, and voxels
should
only contain these values.
voxels
- voxels to be used in the object-mask.public ObjectMask(BinaryVoxels<UnsignedByteBuffer> voxels)
BinaryVoxels
to be located at the origin.
The voxels are reused without duplication.
voxels
- the voxels.public ObjectMask(BoundingBox box, Voxels<UnsignedByteBuffer> voxels)
Voxels
and a BoundingBox
with default BinaryValuesInt
.
The voxels are reused without duplication.
Default BinaryValuesInt
of (off=0, on=255) are assumed, and voxels
should
only contain these values.
box
- the bounding-box.voxels
- the voxels, which must be the same size as box
.public ObjectMask(BoundingBox box, Voxels<UnsignedByteBuffer> voxels, BinaryValuesInt binaryValues)
Voxels
and a corresponding BoundingBox
and BinaryValuesInt
.
The voxels are reused without duplication.
box
- the bounding-box.voxels
- the voxels, which must be the same size as box
, and should only contain
values in binaryValues
.binaryValues
- the binary-values to use (as int
s).public ObjectMask(BoundingBox box, BinaryVoxels<UnsignedByteBuffer> voxels)
BinaryVoxels
and a corresponding bounding-box.
The voxels are reused without duplication.
box
- the bounding-box.voxels
- the voxels, which must be the same size as box
.public ObjectMask(BoundedVoxels<UnsignedByteBuffer> voxels, BinaryValuesInt binaryValues)
BoundedVoxels
and corresponding BinaryValuesInt
.
The voxels are reused without duplication.
voxels
- the voxels.binaryValues
- the binary-values to use.public ObjectMask(BoundingBox box, Voxels<UnsignedByteBuffer> voxels, BinaryValuesByte binaryValues)
ObjectMask(BoundingBox, Voxels, BinaryValuesInt)
but specifies the
binary-values as bytes.box
- the bounding-box.voxels
- the voxels, which must be the same size as box
, and should only contain
values in binaryValues
.binaryValues
- the binary-values to use (as byte
s).public ObjectMask duplicate()
public ObjectMask replaceVoxels(Voxels<UnsignedByteBuffer> voxelsToAssign)
This is an immutable operation, and a new object-mask is created.
voxelsToAssign
- voxels to be assigned.public ObjectMask growToZ(int sizeZ) throws OperationFailedException
ObjectMask
by duplicating the slice across the z-dimension
sizeZ
number of times.sizeZ
- the size in the z-dimension to grow to i.e. the number of duplicated sizes.BoundedVoxels
with an identical corner, but with a 3D bounding-box (and
duplicated slices) instead of the previous 2D.OperationFailedException
- if the existing voxels aren't 2D (a single slice).public ObjectMask growBuffer(Point3i growthNegative, Point3i growthPositive, Optional<Extent> clipRegion) throws OperationFailedException
This operation is immutable.
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.OperationFailedException
- if the voxels are located outside the clipping region.public boolean equalsDeep(ObjectMask other)
ObjectMask
.
Each voxel must be identical, as well as identical binary-values and bounding-box.
other
- the other ObjectMask
to compare against.public int countIntersectingVoxels(ObjectMask other)
This is an immutable operation.
other
- the other object-mask to consider.public boolean hasIntersectingVoxels(ObjectMask other)
This is an immutable operation.
The algorithm exits as soon as an intersecting voxel is encountered i.e. as early as possible.
other
- the other object-mask to consider.public ObjectMask scale(ScaleFactor factor)
This is an immutable operation.
factor
- scale-factor.public ObjectMask invert()
public ObjectMask scale(ScaleFactor factor, Optional<Extent> clipTo)
This is an immutable operation.
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).public ObjectMask clampTo(Extent extent)
This is not an immutable operation, returning the current object unchanged if it already fits inside.
extent
- the extent an object must fit inpublic Point3d centerOfGravity()
This is the mean of the position coordinates in each dimension.
(NaN, NaN, NaN)
if there are no on voxels.public double centerOfGravity(Axis axis)
axis
- the specific axis.NaN
if there
are no on voxels.public boolean checkIfConnected()
Adjacent is defined with a big neighborhood definition i.e. with 8 or 26 connectivity.
public VoxelsPredicate voxelsOn()
VoxelsPredicate
that finds or counts all on voxels in the
object-mask.public VoxelsPredicate voxelsOff()
VoxelsPredicate
that finds or counts all off voxels in the
object-mask.public int numberVoxelsOn()
public Optional<ObjectMask> intersect(ObjectMask other, Extent extent)
This is an immutable operation (the existing two masks are not modified).
other
- the other object-mask to intersect withextent
- extent to constrain any intersectionpublic boolean contains(Point3i point)
For this to occur, two condition needs to be fulfilled for the point
:
#voxels()
has an on state.
point
- the point to query.public ObjectMask flattenZ()
This flattens across z-dimension, setting a voxel to on if it is on in any one slice.
This is an immutable operation.
public BoundingBox boundingBox()
public BinaryVoxels<UnsignedByteBuffer> binaryVoxels()
BinaryVoxels
.public Voxels<UnsignedByteBuffer> voxels()
Voxels
.public BoundedVoxels<UnsignedByteBuffer> boundedVoxels()
BoundedVoxels
.public Extent extent()
public int offsetRelative(int x, int y)
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.public int offsetGlobal(int x, int y)
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.public ObjectMask extractSlice(int sliceIndex, boolean keepIndex)
sliceIndex
- the z-slice in global coordinateskeepIndex
- iff true the z coordinate is reused for the slice, otherwise 0 is setpublic ObjectMask regionZ(int zMin, int zMax) throws CreateException
This will always reuse the existing Voxels
.
zMin
- minimum z-slice index, inclusive.zMax
- maximum z-slice index, inclusive.CreateException
public ObjectMask region(BoundingBox box, boolean reuseIfPossible) throws CreateException
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.
box
- bounding-box in absolute coordinates.reuseIfPossible
- if true the existing object will be reused if possible, otherwise a
new object is always created.CreateException
public ObjectMask regionIntersecting(BoundingBox box) throws CreateException
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)
.
box
- bounding-box in absolute coordinates, that must at least partially intersect with
the current object-mask bounds.CreateException
- if the boxes do not intersect.public Optional<Point3i> findArbitraryOnVoxel()
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.
public UnsignedByteBuffer sliceBufferLocal(int sliceIndexRelative)
i.e. with coordinates relative to the bounding-box corner.
sliceIndexRelative
- sliceIndex (z) relative to the bounding-box of the object-mask.public UnsignedByteBuffer sliceBufferGlobal(int sliceIndexGlobal)
sliceIndexGlobal
- sliceIndex (z) in global coordinates.public ObjectMask shiftToOrigin()
This is an immutable operation: but beware the existing voxel-buffers are reused in the new object.
public ObjectMask shiftBy(ReadableTuple3i shift)
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.
shift
- what to add from the corner positionpublic ObjectMask shiftBackBy(ReadableTuple3i shift)
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.
shift
- what to subtract from the corner position.public ObjectMask mapBoundingBoxPreserveExtent(java.util.function.UnaryOperator<BoundingBox> mapOperation)
This is an immutable operation: but beware the existing voxel-buffers are reused in the new object.
mapOperation
- map function to perform mapping of bounding-box.public ObjectMask mapBoundingBoxChangeExtent(BoundingBox boxToAssign)
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.
boxToAssign
- bounding-box to assign.public ObjectMask relativeMaskTo(BoundingBox box)
This is an immutable operation.
box
- box used as a reference point, against which new relative coordinates are
calculated.public VoxelsAssigner assignOn()
public VoxelsAssigner assignOff()
public List<Point3i> derivePointsLocal()
public String toString()
public BinaryValuesInt binaryValues()
voxels
- as ints.public BinaryValuesByte binaryValuesByte()
voxels
- as bytes.public VoxelsExtracter<UnsignedByteBuffer> extract()
Copyright © 2010–2023 Owen Feehan, ETH Zurich, University of Zurich, Hoffmann-La Roche. All rights reserved.