Package 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 Details

    • 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(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, 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 Details

    • 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:
      either the existing Stack (if three channels or less) or 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.