com.bitplane.xt

Class ImarisDataset<T extends NativeType<T> & RealType<T>>

java.lang.Object

com.bitplane.xt.ImarisDataset<T>

Type Parameters:

T - imglib2 pixel type

All Implemented Interfaces:

ChannelSources<T>, EuclideanSpace

public class ImarisDataset<T extends NativeType<T> & RealType<T>>
extends Object
implements EuclideanSpace, ChannelSources<T>

ImarisDataset wraps an Imaris IDataSetPrx into a lazy-loaded ImgLib2 CachedCellImg.

Data is lazy-loaded from Imaris -- image blocks, when they are first accessed, are retrieved through the Imaris XT API and cached. Modified image blocks are persisted back to Imaris before they are evicted from the cache. (Imaris then in turn persists modified blocks to disk when they are evicted from its cache.)

ImarisDataset provides various views on the image data:

• an Img, via the asImg() method,
• an ImgPlus with metadata, via the asImgPlus() method,
• a net.imagej.Dataset with metadata, via the asDataset() method,
• a list of BigDataViewer sources (one for each channel), via the getSources() method. The sources are multi-resolution and have volatile versions for non-blocking display in BDV.

All these are views on the same data, backed by a common cache. Note, that only the last one exposes the Imaris resolution pyramid. The Img, ImgPlus, and net.imagej.Dataset views represent the full-resolution image.

The generic pixel type T is one of UnsignedByteType, UnsignedShortType, FloatType, and matches the type of the Imaris dataset.

Author:

Tobias Pietzsch

Constructor Summary

Constructors

Constructor and Description
ImarisDataset(Context context, Imaris.IDataSetPrx dataset) Wrap an existing IDataSetPrx.
ImarisDataset(Context context, Imaris.IDataSetPrx dataset, ImarisDatasetOptions options) Wrap an existing IDataSetPrx.

Method Summary

Modifier and Type	Method and Description
Dataset	asDataset() Get a IJ2 net.imagej.Dataset wrapping the full resolution image (see asImg(), asImgPlus()).
CachedCellImg<T,?>	asImg() Get the full resolution image.
ImgPlus<T>	asImgPlus() Get an ImgPlus wrapping the full resolution image (see asImg()).
SharedQueue	getCacheControl() Get the SharedQueue used for asynchronous loading of blocks from Imaris.
DatasetCalibration	getCalibration() Get the physical calibration: unit, voxel size, and min in XYZ.
ARGBType	getChannelColor(int channel) Get the base color of a channel.
DatasetDimensions	getDatasetDimensions() Get the size of the underlying 5D Imaris dataset and the mapping to dimensions of the ImgLib2 representation.
String	getFilename() Get the "Image > Filename" parameter of the dataset.
Imaris.IDataSetPrx	getIDataSetPrx() Get the underlying IDataSet ICE proxy.
String	getName() Get the "Image > Name" parameter of the dataset.
List<SourceAndConverter<T>>	getSources() Get a list of BigDataViewer sources, one for each channel of the dataset.
T	getType() Get an instance of the pixel type.
void	invalidatePyramid() Invalidate cache for all levels of the resolution pyramid, except the full resolution.
int	numDimensions()
int	numResolutions() Get the number of levels in the resolution pyramid.
int	numTimepoints() Get the number timepoints.
void	persist() Persist all modifications back to Imaris.
void	setCalibration(DatasetCalibration calibration) Sets unit, voxel size, and min coordinate.
void	setCalibration(String unit, float extendMinX, float extendMaxX, float extendMinY, float extendMaxY, float extendMinZ, float extendMaxZ) Sets unit, voxel size, and min coordinate from Imaris extents.
void	setCalibration(VoxelDimensions voxelDimensions) Set unit and voxel size.
void	setCalibration(VoxelDimensions voxelDimensions, double minX, double minY, double minZ) Sets unit, voxel size, and min coordinate.
void	setModified(boolean modified) Set the modification flag of the Imaris dataset.

Methods inherited from class java.lang.Object

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

Constructor Detail

ImarisDataset

public ImarisDataset(Context context,
                     Imaris.IDataSetPrx dataset)
              throws Imaris.Error

Wrap an existing IDataSetPrx.

Parameters:

context - a SciJava context. This is only required, if used as a net.imagej.Dataset, otherwise can be null.

dataset - the Imaris dataset to wrap

Throws:

Imaris.Error

ImarisDataset

public ImarisDataset(Context context,
                     Imaris.IDataSetPrx dataset,
                     ImarisDatasetOptions options)
              throws Imaris.Error

Wrap an existing IDataSetPrx.

Parameters:

context - a SciJava context. This is only required, if used as a net.imagej.Dataset, otherwise can be null.

dataset - the Imaris dataset to wrap

options - additional options specifying which type of cache to use, etc.

Throws:

Imaris.Error

Method Detail

setCalibration

public void setCalibration(String unit,
                           float extendMinX,
                           float extendMaxX,
                           float extendMinY,
                           float extendMaxY,
                           float extendMinZ,
                           float extendMaxZ)
                    throws Imaris.Error

Sets unit, voxel size, and min coordinate from Imaris extents.

Note, that the given min/max extents are in Imaris conventions: extendMinX refers to the min corner of the min voxel of the dataset, extendMaxX refers to the max corner of the max voxel of the dataset.

This is in contrast to the ImgLib2 convention, where coordinates always refer to the voxel center.

Throws:

Imaris.Error

setCalibration

public void setCalibration(VoxelDimensions voxelDimensions)
                    throws Imaris.Error

Set unit and voxel size. (The min coordinate is not modified).

Throws:

Imaris.Error

setCalibration

public void setCalibration(VoxelDimensions voxelDimensions,
                           double minX,
                           double minY,
                           double minZ)
                    throws Imaris.Error

Sets unit, voxel size, and min coordinate.

Note, that the min coordinate is in ImgLib2 convention: It refers to the voxel center. This is in contrast to Imaris conventions, where ExtendMinX, ExtendMinY, ExtendMinZ indicate the min corner of the min voxel.

This method translates the given min coordinate (etc) to Imaris extendMin/Max extents.

Throws:

Imaris.Error

setCalibration

public void setCalibration(DatasetCalibration calibration)
                    throws Imaris.Error

Sets unit, voxel size, and min coordinate.

Note, that the min coordinate is in ImgLib2 convention: It refers to the voxel center. This is in contrast to Imaris conventions, where ExtendMinX, ExtendMinY, ExtendMinZ indicate the min corner of the min voxel.

This method translates the given min coordinate (etc) to Imaris extendMin/Max extents.

Throws:

Imaris.Error

setModified

public void setModified(boolean modified)
                 throws Imaris.Error

Set the modification flag of the Imaris dataset.

Imaris asks whether to save a modified dataset, if modified=true. Set modified=false, if you want Imaris to terminate without prompting.

Throws:

Imaris.Error

asImg

public CachedCellImg<T,?> asImg()

Get the full resolution image. The image is a CachedCellImg which loads blocks from Imaris, and writes modified blocks back to Imaris.

asImgPlus

public ImgPlus<T> asImgPlus()

Get an ImgPlus wrapping the full resolution image (see asImg()). Metadata and color tables are set up according to Imaris (at the time of construction of this ImarisDataset).

asDataset

public Dataset asDataset()

Get a IJ2 net.imagej.Dataset wrapping the full resolution image (see asImg(), asImgPlus()). Metadata and color tables are set up according to Imaris (at the time of construction of this ImarisDataset).

getSources

public List<SourceAndConverter<T>> getSources()

Get a list of BigDataViewer sources, one for each channel of the dataset. The sources provide nested volatile versions. The sources are multi-resolution, reflecting the resolution pyramid of the Imaris dataset.

Specified by:

getSources in interface ChannelSources<T extends NativeType<T> & RealType<T>>

getCacheControl

public SharedQueue getCacheControl()

Get the SharedQueue used for asynchronous loading of blocks from Imaris.

Specified by:

getCacheControl in interface ChannelSources<T extends NativeType<T> & RealType<T>>

numDimensions

public int numDimensions()

Specified by:

numDimensions in interface EuclideanSpace

numResolutions

public int numResolutions()

Get the number of levels in the resolution pyramid.

numTimepoints

public int numTimepoints()

Get the number timepoints.

Specified by:

numTimepoints in interface ChannelSources<T extends NativeType<T> & RealType<T>>

getType

public T getType()

Get an instance of the pixel type.

Specified by:

getType in interface ChannelSources<T extends NativeType<T> & RealType<T>>

getDatasetDimensions

public DatasetDimensions getDatasetDimensions()

Get the size of the underlying 5D Imaris dataset and the mapping to dimensions of the ImgLib2 representation.

getCalibration

public DatasetCalibration getCalibration()

Get the physical calibration: unit, voxel size, and min in XYZ.

getChannelColor

public ARGBType getChannelColor(int channel)
                         throws Imaris.Error

Get the base color of a channel.

Parameters:

channel - index of the channel

Returns:

channel color

Throws:

Imaris.Error

getFilename

public String getFilename()
                   throws Imaris.Error

Get the "Image > Filename" parameter of the dataset.

Throws:

Imaris.Error

getName

public String getName()
               throws Imaris.Error

Get the "Image > Name" parameter of the dataset.

Throws:

Imaris.Error

getIDataSetPrx

public Imaris.IDataSetPrx getIDataSetPrx()

Get the underlying IDataSet ICE proxy.

persist

public void persist()

Persist all modifications back to Imaris.

invalidatePyramid

public void invalidatePyramid()

Invalidate cache for all levels of the resolution pyramid, except the full resolution. This is necessary when modifying a dataset and at the same time visualizing it in BigDataViewer. (This scenario is not very likely in practice, but still...)

While actual modifications to the full-resolution image are immediately visible, updating the resolution pyramid needs to go through Imaris. That is, after making modifications, first persist() should be called to ensure all changes have been transferred to Imaris. Second, the dataset should be visible in Imaris, so that Imaris recomputes the resolution pyramid. Finally, the lower-resolution images on the ImgLib2 side should be invalidated (using this method), so the recomputed pyramid data is fetched from Imaris.