net.imglib2.algorithm.blocks

Interface BlockSupplier<T extends net.imglib2.type.NativeType<T>>

Type Parameters:

T - pixel type

All Superinterfaces:

net.imglib2.EuclideanSpace, net.imglib2.Typed<T>

All Known Implementing Classes:

AbstractBlockSupplier, DisplacementFieldBlockSupplier

public interface BlockSupplier<T extends net.imglib2.type.NativeType<T>>
extends net.imglib2.Typed<T>, net.imglib2.EuclideanSpace

Provides blocks of data from a NativeType<T> source. Use the copy(net.imglib2.Interval, java.lang.Object) method to copy a block out of the source into flat primitive array (of the appropriate type).

Use the static method BlockSupplier.of to create a BlockSupplier accessor from an RandomAccessible source. (This is just a thin wrapper around PrimitiveBlocks).

Currently, only pixel types T are supported that map one-to-one to a primitive type. (For example, ComplexDoubleType or Unsigned4BitType are not supported.)

If a source RandomAccessible view construction cannot be understood, BlockSupplier.of will return a fall-back implementation. Fallback can be configured with the optional OnFallback argument to BlockSupplier.of.

Use andThen(net.imglib2.algorithm.blocks.UnaryBlockOperator<T, U>) to decorate a BlockSupplier with a sequence of UnaryBlockOperators.

Use toCellImg(long[], int...) to create CachedCellImg which copies cells from a BlockSupplier.

Implementations are not thread-safe in general. Use threadSafe() to obtain a thread-safe instance (implemented using ThreadLocal copies). E.g.,

 		BlockSupplier<FloatType> blocks = BlockSupplier.of(view).threadSafe();
 

Method Summary

Modifier and Type	Method and Description
default <U extends net.imglib2.type.NativeType<U>> BlockSupplier<U>	andThen(Function<BlockSupplier<T>,UnaryBlockOperator<T,U>> function)
default <U extends net.imglib2.type.NativeType<U>> BlockSupplier<U>	andThen(UnaryBlockOperator<T,U> operator) Returns a BlockSupplier that provide blocks using the given operator with this BlockSupplier as input.
void	copy(net.imglib2.Interval interval, Object dest) Copy a block from the (T-typed) source into primitive arrays (of the appropriate type).
BlockSupplier<T>	independentCopy() Returns an instance of this BlockSupplier that can be used independently, e.g., in another thread or in another place in the same pipeline.
static <T extends net.imglib2.type.NativeType<T>> BlockSupplier<T>	of(net.imglib2.RandomAccessible<T> ra) Create a BlockSupplier accessor for an arbitrary RandomAccessible source.
static <T extends net.imglib2.type.NativeType<T>> BlockSupplier<T>	of(net.imglib2.RandomAccessible<T> ra, net.imglib2.blocks.PrimitiveBlocks.OnFallback onFallback) Create a BlockSupplier accessor for an arbitrary RandomAccessible source.
BlockSupplier<T>	threadSafe() Get a thread-safe version of this BlockSupplier.
default BlockSupplier<T>	tile(int... tileSize) Returns a new BlockSupplier that handles copy(net.imglib2.Interval, java.lang.Object) requests by splitting into tileSize portions that are each handled by this BlockSupplier and assembled into the final result.
default net.imglib2.cache.img.CachedCellImg<T,?>	toCellImg(long[] dimensions, int... cellDimensions) Return a CachedCellImg which copies cells from this BlockSupplier.

Methods inherited from interface net.imglib2.Typed

getType

Methods inherited from interface net.imglib2.EuclideanSpace

numDimensions

Method Detail

copy

void copy(net.imglib2.Interval interval,
          Object dest)

Copy a block from the (T-typed) source into primitive arrays (of the appropriate type).

Parameters:

interval - the block to copy

dest - primitive array to copy into. Must correspond to T, for example, if T is UnsignedByteType then dest must be byte[].

threadSafe

BlockSupplier<T> threadSafe()

Get a thread-safe version of this BlockSupplier.

independentCopy

BlockSupplier<T> independentCopy()

Returns an instance of this BlockSupplier that can be used independently, e.g., in another thread or in another place in the same pipeline.

andThen

default <U extends net.imglib2.type.NativeType<U>> BlockSupplier<U> andThen(UnaryBlockOperator<T,U> operator)

Returns a BlockSupplier that provide blocks using the given operator with this BlockSupplier as input.

andThen

default <U extends net.imglib2.type.NativeType<U>> BlockSupplier<U> andThen(Function<BlockSupplier<T>,UnaryBlockOperator<T,U>> function)

of

static <T extends net.imglib2.type.NativeType<T>> BlockSupplier<T> of(net.imglib2.RandomAccessible<T> ra)

Create a BlockSupplier accessor for an arbitrary RandomAccessible source. Many View constructions (that ultimately end in CellImg, ArrayImg, etc.) are understood and will be handled by an optimized copier.

If the source RandomAccessible cannot be understood, a warning is printed, and a fall-back implementation (based on LoopBuilder) is returned.

The returned BlockSupplier is not thread-safe in general. Use threadSafe() to obtain a thread-safe instance, e.g., BlockSupplier.of(view).threadSafe().

Type Parameters:

T - pixel type

Parameters:

ra - the source

Returns:

a BlockSupplier accessor for ra.

of

static <T extends net.imglib2.type.NativeType<T>> BlockSupplier<T> of(net.imglib2.RandomAccessible<T> ra,
                                                                      net.imglib2.blocks.PrimitiveBlocks.OnFallback onFallback)

Create a BlockSupplier accessor for an arbitrary RandomAccessible source. Many View constructions (that ultimately end in CellImg, ArrayImg, etc.) are understood and will be handled by an optimized copier.

If the source RandomAccessible cannot be understood, a fall-back implementation (based on LoopBuilder) has to be used. The onFallback argument specifies how to handle this case:

• ACCEPT: silently accept fall-back
• WARN: accept fall-back, but print a warning explaining why the input ra requires fall-back
• FAIL: throw IllegalArgumentException explaining why the input ra requires fall-back

The returned BlockSupplier is not thread-safe in general. Use threadSafe() to obtain a thread-safe instance, e.g., BlockSupplier.of(view).threadSafe().

Type Parameters:

T - pixel type

Parameters:

ra - the source

Returns:

a BlockSupplier accessor for ra.

toCellImg

default net.imglib2.cache.img.CachedCellImg<T,?> toCellImg(long[] dimensions,
                                                           int... cellDimensions)

Return a CachedCellImg which copies cells from this BlockSupplier.

Parameters:

dimensions - dimensions of the CachedCellImg to create

cellDimensions - block size of the CachedCellImg to create. This 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}.

Returns:

a CachedCellImg which copies cells from this BlockSupplier.

tile

default BlockSupplier<T> tile(int... tileSize)

Returns a new BlockSupplier that handles copy(net.imglib2.Interval, java.lang.Object) requests by splitting into tileSize portions that are each handled by this BlockSupplier and assembled into the final result.

Example use cases:

• Compute large outputs (e.g. for writing to N5 or wrapping as ArrayImg) with operators that have better performance with small block sizes.
• Avoid excessively large blocks when chaining downsampling operators.

Parameters:

tileSize - (maximum) dimensions of a request to the srcSupplier. tileSize is expanded or truncated to the necessary size. For example, if tileSize=={64} and this BlockSupplier is 3D, then tileSize is expanded to {64, 64, 64}.