org.anchoranalysis.image.core.stack

Class Stack

Object

Stack

All Implemented Interfaces:

Iterable<Channel>

public class Stack
extends Object
implements Iterable<Channel>

One or more single-channel images that all have the same dimensions.

This is one of the fundamental image data structures in Anchor.

The contained channels have a particular voxel-type, but this is deliberately not exposed as a type-parameter to Stack as data-structure, relying on the user to remain aware i.e. it is weakly-typed.

A Channel (or any underlying voxel-buffer} should never exist more than once in a Stack. It is assumed that each Channel has independent buffers, and if this assumption is violated, iteration can not always proceed correctly.

Author:

Owen Feehan

Constructor Summary

Constructors

Constructor and Description
Stack() Creates a new empty Stack that will not become an RGB image after adding channels.
Stack(boolean rgb) Creates a new empty Stack and whether it will become an RGB image or not.
Stack(boolean rgb, Channel... channels) Creates from a varying number of channels, and a flag to indicate if they represent an RGB image or not.
Stack(boolean rgb, java.util.stream.Stream<Channel> stream) Like Stack(Stream) but allows explicitly setting whether it should be interpreted as RGB or not.
Stack(Channel channel) Creates a Stack with a single channel.
Stack(Dimensions dimensions, ChannelFactorySingleType factory, int numberChannels, boolean rgb) Create with a particular number of empty Channels.
Stack(Extent extent) Creates a Stack with a single unsigned-byte channel of size channel.
Stack(java.util.stream.Stream<Channel> stream) Create a Stack from a stream of Channels.

Method Summary

Modifier and Type	Method and Description
void	addBlankChannel() Adds a new empty Channel in the final-most position in the list.
void	addChannel(Channel channel) Appends a channel to the stack, as the new final-most channel position-wise.
void	addChannelsFrom(Stack stack) Add the channels from another instance into this instance.
boolean	allChannelsHaveIdenticalType() Determines if all channels have an identical voxel data-type.
boolean	allChannelsHaveType(VoxelDataType voxelDataType) Determines if all channels have a specific data-type.
List<Channel>	asListChannels() Derives a List of Channels from those in the Stack, preserving order.
void	assignResolution(Resolution resolution) Assigns a new resolution.
Dimensions	dimensions() The dimensions of all channels in the stack.
Stack	duplicateDeep() Performs a deep copy of the stack, so that all channels are duplicated.
Stack	duplicateShallow() Performs a shallow copy of the stack, so that all channels are reused.
boolean	equals(Object other)
boolean	equalsDeep(Stack other, boolean compareResolution) Are the two stack equal using a deep voxel by voxel comparison of each channel?
Extent	extent() The width and height and depth of the image.
Stack	extractSlice(int z) Extract a particular z-slice from the Stack as a new stack.
Stack	extractUpToThreeChannels() Extracts the first three Channels as a new Stack.
Channel	getChannel(int index) Returns the channel at a particular position in the stack.
int	getNumberChannels() The number of channels in the stack.
int	hashCode()
boolean	hasMoreThanOneSlice() Does the stack have more than one slice in the z-dimension?
boolean	isAnyChannel3D() Is at least one channel 3D?
boolean	isRGB() If true, and the stack has exactly three channels, this stack can be interpreted as a RGB image.
Iterator<Channel>	iterator()
Stack	mapChannel(CheckedUnaryOperator<Channel,OperationFailedException> mapping) Produces a new stack with a particular mapping applied to each channel.
Stack	mapChannelWithIndex(CheckedBiFunction<Channel,Integer,Channel,OperationFailedException> mapping) Produces a new stack with a particular mapping applied to each channel (with an index of the channel also available).
Stack	projectMax() Creates a Maximum Intensity Projection of each channel.
Optional<Resolution>	resolution() Resolution of voxels to physical measurements.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface Iterable

forEach, spliterator

Constructor Detail

Stack

public Stack()

Creates a new empty Stack that will not become an RGB image after adding channels.

Stack

public Stack(boolean rgb)

Creates a new empty Stack and whether it will become an RGB image or not.

Parameters:

rgb - whether the stack will represent an RGB image after adding channels.

Stack

public Stack(Channel channel)

Creates a Stack with a single channel.

Parameters:

channel - the channel.

Stack

public Stack(Extent extent)

Creates a Stack with a single unsigned-byte channel of size channel.

Parameters:

extent - the size of the channel to create.

Stack

public Stack(Dimensions dimensions,
             ChannelFactorySingleType factory,
             int numberChannels,
             boolean rgb)
      throws CreateException

Create with a particular number of empty Channels.

Parameters:

dimensions - the dimensions to use for all channels.

factory - a factory to create the empty channels.

numberChannels - how many channels to create.

rgb - whether the channels are RGB (in which case, numberChannels should be 3).

Throws:

CreateException - if rgb==true and there are not three channels.

Stack

public Stack(boolean rgb,
             Channel... channels)
      throws IncorrectImageSizeException,
             CreateException

Creates from a varying number of channels, and a flag to indicate if they represent an RGB image or not.

Parameters:

rgb - true, if the channels represent an RGB image, and are in the corresponding order.

channels - the channels.

Throws:

IncorrectImageSizeException - if the channels are not of uniform size.

CreateException - if rgb==true and there are not three channels.

Stack

public Stack(java.util.stream.Stream<Channel> stream)
      throws IncorrectImageSizeException

Create a Stack from a stream of Channels.

It is assumed these channels will not represent an RGB image.

Parameters:

stream - the stream of channels.

Throws:

IncorrectImageSizeException - if the channels are not of uniform size.

Stack

public Stack(boolean rgb,
             java.util.stream.Stream<Channel> stream)
      throws IncorrectImageSizeException

Like Stack(Stream) but allows explicitly setting whether it should be interpreted as RGB or not.

Parameters:

rgb - whether to interpret the stream as RGB or not, when it is three channels.

stream - the stream of channels.

Throws:

IncorrectImageSizeException - if the channels are not of uniform size.

Method Detail

mapChannel

public Stack mapChannel(CheckedUnaryOperator<Channel,OperationFailedException> mapping)
                 throws OperationFailedException

Produces a new stack with a particular mapping applied to each channel.

The function applied to the channel should ensure it produces uniform sizes.

Parameters:

mapping - performs an operation on a channel and produces a modified channel (or a different one entirely).

Returns:

a new stack (after any modification by mapping) preserving the channel order.

Throws:

OperationFailedException - if the channels produced have non-uniform sizes.

mapChannelWithIndex

public Stack mapChannelWithIndex(CheckedBiFunction<Channel,Integer,Channel,OperationFailedException> mapping)
                          throws OperationFailedException

Produces a new stack with a particular mapping applied to each channel (with an index of the channel also available).

The function applied to the channel should ensure it produces uniform sizes.

Parameters:

mapping - performs an operation on a channel and produces a modified channel (or a different one entirely).

Returns:

a new stack (after any modification by mapping) preserving the channel order.

Throws:

OperationFailedException - if the channels produced have non-uniform sizes.

extractSlice

public Stack extractSlice(int z)

Extract a particular z-slice from the Stack as a new stack.

Parameters:

z - the index in the Z-dimension of the slice to extract.

Returns:

the extracted slice, as a new Stack but reusing the existing voxels.

projectMax

public Stack projectMax()

Creates a Maximum Intensity Projection of each channel.

Note that if the channels do not need projections, the existing Channel is reused in the newly created Stack. But if a projection is needed, it is always freshly created as a new channel.

Returns:

a newly created Stack, with maximum intensity projections of each Channel if 3D. Otherwise if 2D, then this is returned.

addBlankChannel

public void addBlankChannel()
                     throws OperationFailedException

Adds a new empty Channel in the final-most position in the list.

The dimensions and type of the new channel are inferred from existing channels.

Throws:

OperationFailedException - if no existing channel exists, or the existing channels lack uniform size or type.

addChannel

public final void addChannel(Channel channel)
                      throws IncorrectImageSizeException

Appends a channel to the stack, as the new final-most channel position-wise.

Parameters:

channel - the channel.

Throws:

IncorrectImageSizeException - if channel has a mismatching size.

addChannelsFrom

public final void addChannelsFrom(Stack stack)
                           throws IncorrectImageSizeException

Add the channels from another instance into this instance.

Parameters:

stack - the stack whose Channels will be added to this instance.

Throws:

IncorrectImageSizeException - if any channel to be added has a mismatching size.

getChannel

public final Channel getChannel(int index)

Returns the channel at a particular position in the stack.

Parameters:

index - the index (zero-indexed).

Returns:

the respective channel.

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())

getNumberChannels

public final int getNumberChannels()

The number of channels in the stack.

Returns:

the number of channels.

dimensions

public Dimensions dimensions()

The dimensions of all channels in the stack.

Returns:

the dimensions.

resolution

public Optional<Resolution> resolution()

Resolution of voxels to physical measurements.

e.g. physical size of each voxel in a particular dimension.

Returns:

the resolution.

extent

public Extent extent()

The width and height and depth of the image.

i.e. the size of each of the three possible dimensions.

Returns:

the extent.

duplicateDeep

public Stack duplicateDeep()

Performs a deep copy of the stack, so that all channels are duplicated.

Returns:

a new stack with deep-copied channels.

isAnyChannel3D

public boolean isAnyChannel3D()

Is at least one channel 3D?

Returns:

true if at least one channel exists with a z-size that is more than one. false otherwise (including if no channels exist).

duplicateShallow

public Stack duplicateShallow()

Performs a shallow copy of the stack, so that all channels are reused.

Returns:

a new stack with reused channels.

extractUpToThreeChannels

public Stack extractUpToThreeChannels()

Extracts the first three Channels as a new Stack.

If fewer Channels exist, only these are included, without throwing an exception.

Returns:

a newly created Stack reusing the existing Channels in this instance.

hasMoreThanOneSlice

public boolean hasMoreThanOneSlice()

Does the stack have more than one slice in the z-dimension?

Returns:

true if there is more than one z slice, false if there is 1

iterator

public Iterator<Channel> iterator()

Specified by:

iterator in interface Iterable<Channel>

asListChannels

public List<Channel> asListChannels()

Derives a List of Channels from those in the Stack, preserving order.

Returns:

a newly created List, reusing the existing Channels.

allChannelsHaveIdenticalType

public boolean allChannelsHaveIdenticalType()

Determines if all channels have an identical voxel data-type.

Returns:

true iff all channels have an identical voxel data-type.

allChannelsHaveType

public boolean allChannelsHaveType(VoxelDataType voxelDataType)

Determines if all channels have a specific data-type.

Parameters:

voxelDataType - the specific data-type.

Returns:

true iff all channels have voxelDataType as their voxel data-type.

equals

public boolean equals(Object other)

Overrides:

equals in class Object

equalsDeep

public boolean equalsDeep(Stack other,
                          boolean compareResolution)

Are the two stack equal using a deep voxel by voxel comparison of each channel?

Parameters:

other - the stack to compare with.

compareResolution - if true, the image-resolution is also compared for each channel.

Returns:

true if they are deemed equals, false otherwise.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

assignResolution

public void assignResolution(Resolution resolution)

Assigns a new resolution.

This is a mutable operation that replaces existing state.

Parameters:

resolution - the resolution to assign.

isRGB

public boolean isRGB()

If true, and the stack has exactly three channels, this stack can be interpreted as a RGB image.

This is an important flag for determining how a stack is displayed visually, determining whether a stack is portrayed as a color image or composite grayscale channels.

Returns:

whether the stack can be interpreted as an RGB image when it has three channels.