Class LoopBuilder<T>

java.lang.Object

net.imglib2.loops.LoopBuilder<T>

public class LoopBuilder<T>
extends Object

LoopBuilder provides an easy way to write fast loops on RandomAccessibleIntervals. For example, this is a loop that calculates the sum of two images:

RandomAccessibleInterval<DoubleType> imageA = ...
RandomAccessibleInterval<DoubleType> imageB = ...
RandomAccessibleInterval<DoubleType> sum = ...

LoopBuilder.setImages(imageA, imageB, sum).forEachPixel(
    (a, b, s) -> {
         s.setReal(a.getRealDouble() + b.getRealDouble());
    }
);

The RandomAccessibleIntervals imageA, imageB and sum must have equal dimensions, but the bounds of there Intervals can differ.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	LoopBuilder.Chunk<T>
static interface	LoopBuilder.FiveConsumer<A,B,C,D,E>
static interface	LoopBuilder.FourConsumer<A,B,C,D>
static interface	LoopBuilder.SixConsumer<A,B,C,D,E,F>
static interface	LoopBuilder.TriConsumer<A,B,C>

Field Summary

Fields

Modifier and Type	Field	Description
private final Dimensions	dimensions
private final RandomAccessibleInterval<?>[]	images
private TaskExecutor	taskExecutor
private boolean	useFlatIterationOrder

Constructor Summary

Constructors

Modifier	Constructor	Description
private	LoopBuilder(RandomAccessibleInterval<?>... images)

Method Summary

Modifier and Type	Method	Description
private boolean	allCursorsAreFast(List<IterableInterval<?>> iterableIntervals)
private static boolean	allEqual(List<Object> values)
private void	checkDimensions()
private boolean	cursorIsFast(IterableInterval<?> image)
private List<IterableInterval<?>>	equalIterationOrderIterableIntervals()
private List<IterableInterval<?>>	flatIterableIntervals()
LoopBuilder<T>	flatIterationOrder()	LoopBuilder might use any iteration order to execute the loop.
LoopBuilder<T>	flatIterationOrder(boolean value)	If false, LoopBuilder might use any iteration order to execute the loop.
<R> List<R>	forEachChunk(Function<LoopBuilder.Chunk<T>, R> action)	This method is similar to forEachPixel(T) but more flexible when multi threading is used.
void	forEachPixel(T action)
private List<IterableInterval<?>>	imagesAsIterableIntervals()
private static RandomAccess<?>	initRandomAccess(RandomAccessibleInterval<?> image)
private static void	jumpFwd(List<Cursor<?>> cursors, long offset)
LoopBuilder<T>	multiThreaded()	By default LoopBuilder runs the loop without multi-threading.
LoopBuilder<T>	multiThreaded(boolean multiThreaded)
LoopBuilder<T>	multiThreaded(TaskExecutor taskExecutor)	By default LoopBuilder runs the loop without multi-threading.
(package private) static <T,R> R	runOnChunkUsingCursors(List<IterableInterval<?>> iterableIntervals, Function<LoopBuilder.Chunk<T>, R> chunkAction, long offset, long numElements)
(package private) static <T,R> R	runOnChunkUsingRandomAccesses(RandomAccessibleInterval[] images, Function<LoopBuilder.Chunk<T>, R> chunkAction, Interval subInterval)
private <R> List<R>	runUsingCursors(List<IterableInterval<?>> iterableIntervals, Function<LoopBuilder.Chunk<T>, R> chunkAction)
private <R> List<R>	runUsingRandomAccesses(Function<LoopBuilder.Chunk<T>, R> chunkAction)
static <A> LoopBuilder<Consumer<A>>	setImages(RandomAccessibleInterval<A> a)
static <A,B> LoopBuilder<BiConsumer<A,B>>	setImages(RandomAccessibleInterval<A> a, RandomAccessibleInterval<B> b)
static <A,B,C> LoopBuilder<LoopBuilder.TriConsumer<A,B,C>>	setImages(RandomAccessibleInterval<A> a, RandomAccessibleInterval<B> b, RandomAccessibleInterval<C> c)
static <A,B,C,D> LoopBuilder<LoopBuilder.FourConsumer<A,B,C,D>>	setImages(RandomAccessibleInterval<A> a, RandomAccessibleInterval<B> b, RandomAccessibleInterval<C> c, RandomAccessibleInterval<D> d)
static <A,B,C,D,E> LoopBuilder<LoopBuilder.FiveConsumer<A,B,C,D,E>>	setImages(RandomAccessibleInterval<A> a, RandomAccessibleInterval<B> b, RandomAccessibleInterval<C> c, RandomAccessibleInterval<D> d, RandomAccessibleInterval<E> e)
static <A,B,C,D,E,F> LoopBuilder<LoopBuilder.SixConsumer<A,B,C,D,E,F>>	setImages(RandomAccessibleInterval<A> a, RandomAccessibleInterval<B> b, RandomAccessibleInterval<C> c, RandomAccessibleInterval<D> d, RandomAccessibleInterval<E> e, RandomAccessibleInterval<F> f)

Methods inherited from class Object

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

Field Details

dimensions

private final Dimensions dimensions

images

private final RandomAccessibleInterval<?>[] images

taskExecutor

private TaskExecutor taskExecutor

useFlatIterationOrder

private boolean useFlatIterationOrder

Constructor Details

LoopBuilder

private LoopBuilder(RandomAccessibleInterval<?>... images)

Method Details

setImages

public static <A> LoopBuilder<Consumer<A>> setImages(RandomAccessibleInterval<A> a)

See Also:

• LoopBuilder

setImages

public static <A,B> LoopBuilder<BiConsumer<A,B>> setImages(RandomAccessibleInterval<A> a,
 RandomAccessibleInterval<B> b)

See Also:

• LoopBuilder

setImages

public static <A,B,C>
LoopBuilder<LoopBuilder.TriConsumer<A,B,C>> setImages(RandomAccessibleInterval<A> a,
 RandomAccessibleInterval<B> b,
 RandomAccessibleInterval<C> c)

See Also:

• LoopBuilder

setImages

public static <A,B,C,D>
LoopBuilder<LoopBuilder.FourConsumer<A,B,C,D>> setImages(RandomAccessibleInterval<A> a,
 RandomAccessibleInterval<B> b,
 RandomAccessibleInterval<C> c,
 RandomAccessibleInterval<D> d)

See Also:

• LoopBuilder

setImages

public static <A,B,C,D,E>
LoopBuilder<LoopBuilder.FiveConsumer<A,B,C,D,E>> setImages(RandomAccessibleInterval<A> a,
 RandomAccessibleInterval<B> b,
 RandomAccessibleInterval<C> c,
 RandomAccessibleInterval<D> d,
 RandomAccessibleInterval<E> e)

See Also:

• LoopBuilder

setImages

public static <A,B,C,D,E,F>
LoopBuilder<LoopBuilder.SixConsumer<A,B,C,D,E,F>> setImages(RandomAccessibleInterval<A> a,
 RandomAccessibleInterval<B> b,
 RandomAccessibleInterval<C> c,
 RandomAccessibleInterval<D> d,
 RandomAccessibleInterval<E> e,
 RandomAccessibleInterval<F> f)

See Also:

• LoopBuilder

forEachPixel

public void forEachPixel(T action)

See Also:

• LoopBuilder

forEachChunk

public <R> List<R> forEachChunk(Function<LoopBuilder.Chunk<T>, R> action)

This method is similar to forEachPixel(T) but more flexible when multi threading is used.

The following example calculates the sum of the pixel values of an image. Multi threading is used to improve performance. The image is split into chunks. The chunks are processed in parallel by multiple threads. A variable of IntType is used to calculate the sum, but IntType is not thread safe. It's therefore necessary to have one sum variable per chunk. This can be realized as follows:

List<IntType> listOfSums = LoopBuilder.setImages( image ).multithreaded().forEachChunk(
    chunk -> {
        IntType sum = new IntType();
        chunk.forEach( pixel -> sum.add( pixel ) ):
        return sum;
    }
);

IntType totalSum = new IntType();
listOfSums.forEach( sum -> totalSum.add( sum );
return totalSum;

allCursorsAreFast

private boolean allCursorsAreFast(List<IterableInterval<?>> iterableIntervals)

cursorIsFast

private boolean cursorIsFast(IterableInterval<?> image)

multiThreaded

public LoopBuilder<T> multiThreaded()

By default LoopBuilder runs the loop without multi-threading. Calling this method allows LoopBuilder to use multi-threading for optimal performance.

Usually, if this method is used, LoopBuilder will indeed use multi-threading. But that's not always the case. The Parallelization class can still be used to explicitly run the code single-threaded.

Here is a small example for a copy method with enabled multi-threading.

public void copy( RandomAccessibleInterval<T> source, RandomAccessibleInterval<T> target)
{
    LoopBuilder.setImages( source, target ).multiThreaded().forEachPixel( ( s, t ) -> t.set( s ) );
}

This method usually runs multi-threaded. Which means good performance. But sometimes, a user might want to run the code single-threaded. There's no need to write a second single-threaded version of our copy method. The Parallelization class allows the user to run the code single-threaded:

Parallelization.runSingleThreaded( () -> {
    copy( source, target );
} );

WARNING: You need to make sure that the action passed to forEachPixel(T) is thread safe.

See Also:

• Parallelization

multiThreaded

public LoopBuilder<T> multiThreaded(boolean multiThreaded)

multiThreaded

public LoopBuilder<T> multiThreaded(TaskExecutor taskExecutor)

By default LoopBuilder runs the loop without multi-threading. Calling this method causes LoopBuilder to use the given TaskExecutor for multi-threading.

WARNING: You need to make sure that your operation is thread safe.

flatIterationOrder

public LoopBuilder<T> flatIterationOrder()

LoopBuilder might use any iteration order to execute the loop. Calling this method will cause LoopBuilder to use flat iteration order, when executing the loop.

WARNING: Don't use multi-threading if you want to have flat iteration order.

flatIterationOrder

public LoopBuilder<T> flatIterationOrder(boolean value)

If false, LoopBuilder might use any iteration order to execute the loop.

If true, LoopBuilder will use flat iteration order, and multi threading is disabled.

WARNING: Don't use multi-threading if you want to have flat iteration order.

See Also:

• FlatIterationOrder

checkDimensions

private void checkDimensions()

runUsingRandomAccesses

private <R> List<R> runUsingRandomAccesses(Function<LoopBuilder.Chunk<T>, R> chunkAction)

runOnChunkUsingRandomAccesses

static <T,R> R runOnChunkUsingRandomAccesses(RandomAccessibleInterval[] images,
 Function<LoopBuilder.Chunk<T>, R> chunkAction,
 Interval subInterval)

initRandomAccess

private static RandomAccess<?> initRandomAccess(RandomAccessibleInterval<?> image)

imagesAsIterableIntervals

private List<IterableInterval<?>> imagesAsIterableIntervals()

runUsingCursors

private <R> List<R> runUsingCursors(List<IterableInterval<?>> iterableIntervals,
 Function<LoopBuilder.Chunk<T>, R> chunkAction)

runOnChunkUsingCursors

static <T,R> R runOnChunkUsingCursors(List<IterableInterval<?>> iterableIntervals,
 Function<LoopBuilder.Chunk<T>, R> chunkAction,
 long offset,
 long numElements)

jumpFwd

private static void jumpFwd(List<Cursor<?>> cursors,
 long offset)

equalIterationOrderIterableIntervals

private List<IterableInterval<?>> equalIterationOrderIterableIntervals()

flatIterableIntervals

private List<IterableInterval<?>> flatIterableIntervals()

allEqual

private static boolean allEqual(List<Object> values)