acquifer.core

Class ImageSeries

Object

acquifer.core.Dataset

acquifer.core.ImageSeries

public class ImageSeries
extends Dataset

An ImageSeries is an ordered n-dimensional collection of ImagePlane belonging to the same well/subposition, and with identical width/height.
The collection of ImagePlane thus forms a multi-dimensional image.
The planes are ordered in a 3D-array in the default c,z,t ordering as in ImageJ. Importantly missing planes (for a z,c,t coordinates) results in null values in this array.

In the image series, every timepoint is expected to have the same number of channels and Z-slices (by default for an IM acquisition).
Similarly for a given timepoint, each channel is expected to have the same number of Z-slices.
If this is not the case (ex: single image files deleted), missing Z-slices and/or channels and/or timepoints are set to null.

There are different ways to access the ImagePlane in an ImageSeries.
Using the public images attribute and the corresponding 0-based positional array indexes.
Using the getImagePlane(int, int, int) and the c,z,t indexes as appearing in the IM filenames.
When the ImageSeries is displayed as a hyperstack, the hyperstack positional index will differ from the IM positional index, but this is taken care of.

Note : the English word "series" is always terminated with a "s", even for a single series, which is the case here.

Field Summary

Fields

Modifier and Type	Field and Description
ImagePlane[][][]	images Multi-dimensional array containing the imagePlanes ordered by t,c,z.

Fields inherited from class acquifer.core.Dataset

listImages

Constructor Summary

Constructors

Constructor and Description
ImageSeries(ImagePlane[] listImages) Create an ImageSerie from a list of ImagePlane.

Method Summary

Modifier and Type	Method and Description
ImagePlane	getFirstNonNullImagePlane() Returns the first non-null ImagePlane in the ImageSeries.
ImagePlane	getImagePlane(int n) Return the ImagePlane at (0-based) index n, if the planes were organised in c,z,t order and "spaced" accordingly (ie for hyperstacks).
ImagePlane	getImagePlane(int t, int c, int z) Return the ImagePlane given the 1-based indexes for C,Z,T as appearing in the image filename.
ImagePlane[]	getListOfImagePlanes() Get the list of ImagePlane in this ImageSeries, ordered using the default c,z,t order.
int	getNumberOfHyperstackPlanes() Return the number of planes if the ImageSeries was visualised as a hyperstack.
String	getSeriesId() Return the SeriesId formed as "well:subposition" ex: "A001:2".
int	getSubPosition() Return the subposition associated to this ImageSeries.
Well	getWell() Return the well associated to this ImageSeries.
String	getWellId() Return the well Id of the associated well, ex : "A001".
boolean	hasMissingHyperstackPlanes() Return true if this ImageSeries is missing some ImagePlane for given c,z or t positions.
int[]	indexIMToPositional(int t, int c, int z) Convert (t,c,z)-indexes as appearing in IM filenames to their actual positional index in the internal lists of timepoints, channels and Z-slices.
int[]	indexToPositional(int n) Convert from a 0-based index (n) to the 0-based (t,c,z) positional indexes in the internal list of dimensions.
String	toString() String representation of an ImageSeries "ImageSeries (n images): directoryName"

Methods inherited from class acquifer.core.Dataset

getDirectory, getDirectoryName, getDirectoryPath, getListOfImagePlanes, getNumberOfChannels, getNumberOfExistingImagePlanes, getNumberOfImageSeries, getNumberOfPlanesPerSeries, getNumberOfSubpositions, getNumberOfTimepoints, getNumberOfWells, getNumberOfZslices, getSetChannels, getSetPlateColumns, getSetPlateRows, getSetSubpositions, getSetTimepoints, getSetWells, getSetZ, getSortOrder, groupByImageSeries

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

images

public final ImagePlane[][][] images

Multi-dimensional array containing the imagePlanes ordered by t,c,z. Contains null when no ImagePlane is available for the given t,c,z.

Constructor Detail

ImageSeries

public ImageSeries(ImagePlane[] listImages)

Create an ImageSerie from a list of ImagePlane.
The list of image planes MUST represent images belonging to the same well and subposition (ie image serie) and must reside in the same directory.
If the list of image planes contains more than 1 well/subposition an error is thrown. This constructor computes the dimensions available from the list of images, and sort the list of images if sortOrder is not null.

Method Detail

getWell

public Well getWell()

Return the well associated to this ImageSeries.

getWellId

public String getWellId()

Return the well Id of the associated well, ex : "A001".

getSeriesId

public String getSeriesId()

Return the SeriesId formed as "well:subposition" ex: "A001:2".

getSubPosition

public int getSubPosition()

Return the subposition associated to this ImageSeries.

indexIMToPositional

public int[] indexIMToPositional(int t,
                                 int c,
                                 int z)

Convert (t,c,z)-indexes as appearing in IM filenames to their actual positional index in the internal lists of timepoints, channels and Z-slices.
These indexes are specific to an ImageSeries since they depend on the content of the lists.

indexToPositional

public int[] indexToPositional(int n)

Convert from a 0-based index (n) to the 0-based (t,c,z) positional indexes in the internal list of dimensions.
This is mostly used when working with ImageJ functions (for instance in VirtualImageSeries ie using an ImageSeries as data-storage for a VirtualStack).

Parameters:

n - theoretical 0-based positional index, if the planes were sorted in the default CZT order (ie channel varying faster, then Z then T)

Returns:

the 0-based (t,c,z) indexes.

Throws:

IllegalArgumentException - if n is not in range (0, nHyperstackPlanes-1).

getImagePlane

public ImagePlane getImagePlane(int t,
                                int c,
                                int z)

Return the ImagePlane given the 1-based indexes for C,Z,T as appearing in the image filename.
Note : C,Z,T indexes in IM filenames are 1-based.
To get the ImagePlane using 0-based positional index, directly use the public n-dimensional array images.

Returns:

the 0-based (t,c,z) indexes to use with the internal imagePlane[][][].

getImagePlane

public ImagePlane getImagePlane(int n)

Return the ImagePlane at (0-based) index n, if the planes were organised in c,z,t order and "spaced" accordingly (ie for hyperstacks).
This can thus return null if there is no plane available for a given set of (c,z,t) coordinates.

Overrides:

getImagePlane in class Dataset

Throws:

IllegalArgumentException - if n is not in range (0, nHyperstackPlanes-1).

getFirstNonNullImagePlane

public ImagePlane getFirstNonNullImagePlane()

Returns the first non-null ImagePlane in the ImageSeries.

Throws:

Error - if all ImagePlane are null, this is theoretically impossible, as instantiating an empty ImageSeries readily throws an error.

getNumberOfHyperstackPlanes

public int getNumberOfHyperstackPlanes()

Return the number of planes if the ImageSeries was visualised as a hyperstack.
This plane count would include empty planes i.e for which no corresponding image file is available.
It is computed as nT x nC x nZ.

hasMissingHyperstackPlanes

public boolean hasMissingHyperstackPlanes()

Return true if this ImageSeries is missing some ImagePlane for given c,z or t positions.
This can happen if some image files were deleted from disk.
When such an ImageSeries is visualised as a hyperstack, the missing ImagePlanes are replaced by black image planes.

getListOfImagePlanes

public ImagePlane[] getListOfImagePlanes()

Get the list of ImagePlane in this ImageSeries, ordered using the default c,z,t order.
Reminder : ctz order means c changing fastest then z then t. This list may contain null planes where ImagePlane are missing for a given c,z,t. TODO add version with custom ordering (overwriting the dataset one which had no null).

Overrides:

getListOfImagePlanes in class Dataset

toString

public String toString()

String representation of an ImageSeries "ImageSeries (n images): directoryName"

Overrides:

toString in class Dataset