com.bitplane.xt

Class ImarisDatasetOptions

java.lang.Object

org.scijava.optional.AbstractOptions<ImarisDatasetOptions>

com.bitplane.xt.ImarisDatasetOptions

All Implemented Interfaces:

ImarisAxesOptions<ImarisDatasetOptions>, ImarisCacheOptions<ImarisDatasetOptions>, ReadOnlyOptions<ImarisDatasetOptions>, CacheOptions<ImarisDatasetOptions>, CellDimensionsOptions<ImarisDatasetOptions>, org.scijava.optional.Options<ImarisDatasetOptions>

public class ImarisDatasetOptions
extends org.scijava.optional.AbstractOptions<ImarisDatasetOptions>
implements CellDimensionsOptions<ImarisDatasetOptions>, CacheOptions<ImarisDatasetOptions>, ImarisCacheOptions<ImarisDatasetOptions>, ImarisAxesOptions<ImarisDatasetOptions>, ReadOnlyOptions<ImarisDatasetOptions>

Optional parameters for creating ImarisDataset. This allows to tweak details about the cache, etc.

Author:

Tobias Pietzsch

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	ImarisDatasetOptions.Values

Nested classes/interfaces inherited from class org.scijava.optional.AbstractOptions

org.scijava.optional.AbstractOptions.AbstractValues, org.scijava.optional.AbstractOptions.ValuesToString

Nested classes/interfaces inherited from interface net.imglib2.cache.img.optional.CellDimensionsOptions

CellDimensionsOptions.Val

Nested classes/interfaces inherited from interface net.imglib2.cache.img.optional.CacheOptions

CacheOptions.CacheType, CacheOptions.Val

Nested classes/interfaces inherited from interface com.bitplane.xt.options.ImarisCacheOptions

ImarisCacheOptions.Val

Nested classes/interfaces inherited from interface com.bitplane.xt.options.ImarisAxesOptions

ImarisAxesOptions.Axis, ImarisAxesOptions.Val

Nested classes/interfaces inherited from interface com.bitplane.xt.options.ReadOnlyOptions

ReadOnlyOptions.Val

Field Summary

Fields

Modifier and Type	Field and Description
ImarisDatasetOptions.Values	values

Constructor Summary

Constructors

Constructor and Description
ImarisDatasetOptions()

Method Summary

Modifier and Type	Method and Description
ImarisDatasetOptions	cacheType(CacheOptions.CacheType cacheType) Which in-memory cache type to use.
ImarisDatasetOptions	cellDimensions(int... cellDimensions) Override the dimensions of a cell.
protected ImarisDatasetOptions	copyOrThis()
ImarisDatasetOptions	includeAxes(ImarisAxesOptions.Axis... axes) Specify which axes should be included (at least) when mapping an Imaris dataset to a ImgLib2 image.
ImarisDatasetOptions	maxCacheSize(long maxCacheSize) Set the maximum number of values (cells) to keep in the cache.
ImarisDatasetOptions	maxIoQueueSize(int maxIoQueueSize) Set the maximum size of the disk write queue.
ImarisDatasetOptions	numIoThreads(int numIoThreads) The specified number of threads is started to handle asynchronous writing of values that are evicted from the memory cache.
static ImarisDatasetOptions	options() Create default ImarisDatasetOptions.
ImarisDatasetOptions	readOnly() Open the dataset as read-only (vs modifiable).

Methods inherited from class org.scijava.optional.AbstractOptions

append, setValue, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.bitplane.xt.options.ImarisCacheOptions

initializeCellsAsDirty, persistOnLoad

Methods inherited from interface org.scijava.optional.Options

setValue

Field Detail

values

public final ImarisDatasetOptions.Values values

Constructor Detail

ImarisDatasetOptions

public ImarisDatasetOptions()

Method Detail

cellDimensions

public ImarisDatasetOptions cellDimensions(int... cellDimensions)

Override the dimensions of a cell.

By default, the block dimensions of the Imaris dataset are used.

The argument is extended or truncated as necessary. For example if cellDimensions=[64,32] then for creating a 3D image it will be augmented to [64,32,32]. For creating a 1D image it will be truncated to [64].

Specified by:

cellDimensions in interface CellDimensionsOptions<ImarisDatasetOptions>

Parameters:

cellDimensions - dimensions of a cell.

cacheType

public ImarisDatasetOptions cacheType(CacheOptions.CacheType cacheType)

Which in-memory cache type to use. The options are

• SOFTREF: The cache keeps SoftReferences to values (cells), basically relying on GC for removal. The advantage of this is that many caches can be created without needing to put a limit on the size of any of them. GC will take care of balancing that. The downside is that OutOfMemoryError may occur because SoftReferences are cleared too slow. SoftReferences are not collected for a certain time after they have been used. If there is heavy thrashing with cells being constantly swapped in and out from disk then OutOfMemory may happen because of this. This sounds worse than it is in practice and should only happen in pathological situations. Tuning the -XX:SoftRefLRUPolicyMSPerMB JVM flag does often help.
• BOUNDED: The cache keeps strong references to a limited number of values (cells). The advantage is that there is never OutOfMemory because of the issues described above (fingers crossed). The downside is that the number of cells that should be cached needs to be specified beforehand. So OutOfMemoryError may occur if many caches are opened and consume too much memory in total.

Specified by:

cacheType in interface CacheOptions<ImarisDatasetOptions>

Parameters:

cacheType - which cache type to use (default is SOFTREF).

maxCacheSize

public ImarisDatasetOptions maxCacheSize(long maxCacheSize)

Set the maximum number of values (cells) to keep in the cache. This is only used if CacheOptions.cacheType(CacheType) is CacheType#BOUNDED.

Specified by:

maxCacheSize in interface CacheOptions<ImarisDatasetOptions>

Parameters:

maxCacheSize - maximum number of values in the cache (default is 1000).

numIoThreads

public ImarisDatasetOptions numIoThreads(int numIoThreads)

The specified number of threads is started to handle asynchronous writing of values that are evicted from the memory cache.

Specified by:

numIoThreads in interface ImarisCacheOptions<ImarisDatasetOptions>

Parameters:

numIoThreads - how many writer threads to start (default is 1).

maxIoQueueSize

public ImarisDatasetOptions maxIoQueueSize(int maxIoQueueSize)

Set the maximum size of the disk write queue. When the queue is full, removing entries from the cache will block until earlier values have been written.

Because processing of removed entries is done whenever the cache is accessed, this may also block accesses to the cache. (This is a good thing, because it avoids running out of memory because entries cannot be cleared fast enough...)

Specified by:

maxIoQueueSize in interface ImarisCacheOptions<ImarisDatasetOptions>

Parameters:

maxIoQueueSize - the maximum size of the write queue (default is 10).

includeAxes

public ImarisDatasetOptions includeAxes(ImarisAxesOptions.Axis... axes)

Specify which axes should be included (at least) when mapping an Imaris dataset to a ImgLib2 image.

In Imaris, datasets are always 5D: for example, a 2D dataset (without channel or time) is represented as 5D with size=1 along Z, C, T axes. In ImgLib2, there is a distinction between a 2D image and a 5D image with size=1 along the 3rd, 4th, and 5th dimension. Therefore, there are several ways to represent such a dataset in ImgLib2.

By default, axes Z, C, and T are not represented in ImgLib2 if the dataset size along those axes is s=1. By specifying these axes as includeAxes() arguments, this can be overridden. For example, an Imaris dataset with size {100, 100, 1, 1, 1} would be represented as a 2D ImgLib2 image with size {100, 100}. Specifying includeAxes(Z, T), would result in a 4D ImgLib2 image with size {100,100,1,1}.

Specified by:

includeAxes in interface ImarisAxesOptions<ImarisDatasetOptions>

Parameters:

axes - the axes that should be included (at least) when mapping the Imaris dataset to ImgLib2 image.

readOnly

public ImarisDatasetOptions readOnly()

Open the dataset as read-only (vs modifiable).

Modifying methods like ImarisDataset.setCalibration(java.lang.String, float, float, float, float, float, float) will throw UnsupportedOperationException. Changes to pixel values are possible but will not be written back to Imaris and are forgotten when the respective pixel is evicted from cache.

By default, all datasets are modifiable.

Specified by:

readOnly in interface ReadOnlyOptions<ImarisDatasetOptions>

options

public static ImarisDatasetOptions options()

Create default ImarisDatasetOptions.

Returns:

default ImarisDatasetOptions.

copyOrThis

protected ImarisDatasetOptions copyOrThis()

Overrides:

copyOrThis in class org.scijava.optional.AbstractOptions<ImarisDatasetOptions>