net.imglib2.algorithm.blocks.downsample

Class Downsample

java.lang.Object

net.imglib2.algorithm.blocks.downsample.Downsample

public class Downsample
extends Object

Downsampling by factor 2 in selected dimensions.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

For T other than DoubleType or FloatType, the input will be converted to float/double for computation and the result converted back to T. To avoid unnecessary conversions, if you want the result as FloatType then you should explicitly convert to FloatType before applying the downsampling operator. This code:

 RandomAccessible< UnsignedByteType > input;
 BlockSupplier< FloatType > downsampled = BlockSupplier.of( input )
         .andThen( Convert.convert( new FloatType() ) )
         .andThen( Downsample.downsample( Offset.HALF_PIXEL ) );
 

avoids loss of precision and is more efficient than

 RandomAccessible< UnsignedByteType > input;
 BlockSupplier< FloatType > downsampled = BlockSupplier.of( input )
         .andThen( Downsample.downsample( Offset.HALF_PIXEL ) )
         .andThen( Convert.convert( new FloatType() ) );
 

The downsample(ComputationType, Offset) methods return factory functions that create UnaryBlockOperator to match the type and dimensionality of a given input BlockSupplier<T>. For example, the following code creates 2D downsampling operator for 2D input, a 3D operator for 3D input, etc.

 RandomAccessible< UnsignedByteType > input;
 BlockSupplier< UnsignedByteType > downsampled = BlockSupplier.of( input )
         .andThen( Downsample.downsample( Offset.HALF_PIXEL ) );
 

An Downsample.Offset specifies whether downsampled pixels are placed on corners or centers of input pixels:

• Downsample.Offset.HALF_PIXEL means that each downsampled pixel is computed as the average of 2 neighboring pixels (respectively 4 pixels for 2D, 8 voxels for 3D, etc.) Downsampled pixels are shifted by half a pixel.
• Downsample.Offset.CENTERED means that each downsampled pixel is computed as the weighted average (with weights {.25, .5, .25}) of 3 neighboring pixels (respectively 9 pixels for 2D, 27 voxels for 3D, etc.). Downsampled pixels are centered on input pixels.

The downsample(ComputationType, int[]) methods support downsampling with arbitrary integer factor by averaging blocks of pixels. (With factors={2,2,2,...}, this is equivalent to downsampling with Downsample.Offset.HALF_PIXEL).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Downsample.Offset Specify where downsampled pixels should be placed.

Constructor Summary

Constructors

Constructor and Description
Downsample()

Method Summary

Modifier and Type	Method and Description
static <T extends NativeType<T>> UnaryBlockOperator<T,T>	createOperator(T type, ComputationType computationType, Downsample.Offset offset, boolean[] downsampleInDim) Create a UnaryBlockOperator to downsample (by factor 2) blocks of the standard ImgLib2 RealType.
static <T extends NativeType<T>> UnaryBlockOperator<T,T>	createOperator(T type, ComputationType computationType, Downsample.Offset offset, int numDimensions) Create a UnaryBlockOperator to downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealType.
static <T extends NativeType<T>> UnaryBlockOperator<T,T>	createOperator(T type, ComputationType computationType, int[] downsamplingFactors) Create a UnaryBlockOperator to downsample (by the given downsamplingFactors) blocks of the standard ImgLib2 RealType.
static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>>	downsample() Downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealTypes.
static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>>	downsample(ComputationType computationType, Downsample.Offset offset) Downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealTypes.
static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>>	downsample(ComputationType computationType, Downsample.Offset offset, boolean[] downsampleInDim) Downsample (by factor 2) blocks of the standard ImgLib2 RealTypes.
static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>>	downsample(ComputationType computationType, int[] downsamplingFactors) Downsample (by the given downsamplingFactors) blocks of the standard ImgLib2 RealTypes.
static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>>	downsample(Downsample.Offset offset) Downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealTypes.
static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>>	downsample(int[] downsamplingFactors) Downsample (by the given downsamplingFactors) blocks of the standard ImgLib2 RealTypes.
static long[]	getDownsampledDimensions(long[] imgDimensions) Returns recommended size of the downsampled image, given an input image of size imgDimensions.
static long[]	getDownsampledDimensions(long[] imgDimensions, boolean[] downsampleInDim) Returns recommended size of the downsampled image, given an input image of size imgDimensions.
static long[]	getDownsampledDimensions(long[] imgDimensions, int[] downsamplingFactors) Returns recommended size of the downsampled image, given an input image of size imgDimensions.

Methods inherited from class java.lang.Object

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

Constructor Detail

Downsample

public Downsample()

Method Detail

getDownsampledDimensions

public static long[] getDownsampledDimensions(long[] imgDimensions)

Returns recommended size of the downsampled image, given an input image of size imgDimensions. In each dimension the recommended size is input size / 2, rounding up (e.g., a 5 pixel input image should be downsampled to a 3 pixel image).

Parameters:

imgDimensions - dimensions of the input image

Returns:

the recommended size of the downsampled image

getDownsampledDimensions

public static long[] getDownsampledDimensions(long[] imgDimensions,
                                              boolean[] downsampleInDim)

Returns recommended size of the downsampled image, given an input image of size imgDimensions. In each dimension (that should be downsampled), the recommended size is input size / 2, rounding up (e.g., a 5 pixel input image should be downsampled to a 3 pixel image).

Parameters:

imgDimensions - dimensions of the input image

downsampleInDim - for each dimension d: if downsampleInDim[d]==true then the input image should be downsampled in dimension d. downsampleInDim is expanded or truncated to the necessary size. For example, if downsampleInDim=={true,true,false} and the operator is applied to a 2D image, downsampleInDim is truncated to {true, true}. If the operator is applied to a 5D image, downsampleInDim is expanded to {true, true, false, false, false}

Returns:

the recommended size of the downsampled image

getDownsampledDimensions

public static long[] getDownsampledDimensions(long[] imgDimensions,
                                              int[] downsamplingFactors)

Returns recommended size of the downsampled image, given an input image of size imgDimensions. In each dimension, the recommended size is input imgDimension / downsamplingFactor, rounding up (e.g., a 5 pixel input image downsampled with factor 2, should yield a 3 pixel image).

Parameters:

imgDimensions - dimensions of the input image

downsamplingFactors - in each dimension d, downsamplingFactors[d] pixels in the input image should be averaged to one output pixel. downsamplingFactors is expanded or truncated to the necessary size. For example, if downsamplingFactors=={2,2,1} and the operator is applied to a 2D image, downsamplingFactors is truncated to {2, 2}. If the operator is applied to a 5D image, downsamplingFactors is expanded to {2, 2, 1, 1, 1}

Returns:

the recommended size of the downsampled image

downsample

public static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>> downsample()

Downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealTypes.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

Precision for intermediate values is chosen as to represent the input/output type without loss of precision. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

Downsampled pixels are computed as the average of 2 neighboring pixels (respectively 4 pixels for 2D, 8 voxels for 3D, etc.) This means downsampled pixels are shifted by half a pixel.

The returned factory function creates an operator matching the type and dimensionality of a given input BlockSupplier<T>.

Type Parameters:

T - the input/output type

Returns:

factory for UnaryBlockOperator to downsample blocks of type T

downsample

public static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>> downsample(Downsample.Offset offset)

Downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealTypes.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

Precision for intermediate values is chosen as to represent the input/output type without loss of precision. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

The returned factory function creates an operator matching the type and dimensionality of a given input BlockSupplier<T>.

Type Parameters:

T - the input/output type

Parameters:

offset - Specifies where downsampled pixels should be placed. HALF_PIXEL means that each downsampled pixel is computed as the average of 2 neighboring pixels (respectively 4 pixels for 2D, 8 voxels for 3D, etc.), and downsampled pixels are shifted by half a pixel. CENTERED means that each downsampled pixel is computed as the weighted average (with weights {.25, .5, .25}) of 3 neighboring pixels (respectively 9 pixels for 2D, 27 voxels for 3D, etc.) Downsampled pixels are centered on input pixels.

Returns:

factory for UnaryBlockOperator to downsample blocks of type T

downsample

public static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>> downsample(ComputationType computationType,
                                                                                                      Downsample.Offset offset)

Downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealTypes.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

The returned factory function creates an operator matching the type and dimensionality of a given input BlockSupplier<T>.

Type Parameters:

T - the input/output type

Parameters:

computationType - specifies in which precision intermediate values should be computed. For AUTO, the type that can represent the input/output type without loss of precision is picked. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

offset - Specifies where downsampled pixels should be placed. HALF_PIXEL means that each downsampled pixel is computed as the average of 2 neighboring pixels (respectively 4 pixels for 2D, 8 voxels for 3D, etc.), and downsampled pixels are shifted by half a pixel. CENTERED means that each downsampled pixel is computed as the weighted average (with weights {.25, .5, .25}) of 3 neighboring pixels (respectively 9 pixels for 2D, 27 voxels for 3D, etc.) Downsampled pixels are centered on input pixels.

Returns:

factory for UnaryBlockOperator to downsample blocks of type T

downsample

public static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>> downsample(ComputationType computationType,
                                                                                                      Downsample.Offset offset,
                                                                                                      boolean[] downsampleInDim)

Downsample (by factor 2) blocks of the standard ImgLib2 RealTypes. The downsampleInDim argument specifies in which dimensions the input should be downsampled.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

The returned factory function creates an operator matching the type and dimensionality of a given input BlockSupplier<T>.

Type Parameters:

T - the input/output type

Parameters:

computationType - specifies in which precision intermediate values should be computed. For AUTO, the type that can represent the input/output type without loss of precision is picked. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

offset - Specifies where downsampled pixels should be placed. HALF_PIXEL means that each downsampled pixel is computed as the average of 2 neighboring pixels (respectively 4 pixels for 2D, 8 voxels for 3D, etc.), and downsampled pixels are shifted by half a pixel. CENTERED means that each downsampled pixel is computed as the weighted average (with weights {.25, .5, .25}) of 3 neighboring pixels (respectively 9 pixels for 2D, 27 voxels for 3D, etc.) Downsampled pixels are centered on input pixels.

downsampleInDim - for each dimension d: if downsampleInDim[d]==true then the input image should be downsampled in dimension d. downsampleInDim is expanded or truncated to the necessary size. For example, if downsampleInDim=={true,true,false} and the operator is applied to a 2D image, downsampleInDim is truncated to {true, true}. If the operator is applied to a 5D image, downsampleInDim is expanded to {true, true, false, false, false}

Returns:

factory for UnaryBlockOperator to downsample blocks of type T

downsample

public static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>> downsample(int[] downsamplingFactors)

Downsample (by the given downsamplingFactors) blocks of the standard ImgLib2 RealTypes.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

Precision for intermediate values is chosen as to represent the input/output type without loss of precision. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

The returned factory function creates an operator matching the type and dimensionality of a given input BlockSupplier<T>.

Type Parameters:

T - the input/output type

Parameters:

downsamplingFactors - in each dimension d, downsamplingFactors[d] pixels in the input image should be averaged to one output pixel. downsamplingFactors is expanded or truncated to the necessary size. For example, if downsamplingFactors=={2,2,1} and the operator is applied to a 2D image, downsamplingFactors is truncated to {2, 2}. If the operator is applied to a 5D image, downsamplingFactors is expanded to {2, 2, 1, 1, 1}

Returns:

factory for UnaryBlockOperator to downsample blocks of type T

downsample

public static <T extends NativeType<T>> Function<BlockSupplier<T>,UnaryBlockOperator<T,T>> downsample(ComputationType computationType,
                                                                                                      int[] downsamplingFactors)

Downsample (by the given downsamplingFactors) blocks of the standard ImgLib2 RealTypes.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

The returned factory function creates an operator matching the type and dimensionality of a given input BlockSupplier<T>.

Type Parameters:

T - the input/output type

Parameters:

computationType - specifies in which precision intermediate values should be computed. For AUTO, the type that can represent the input/output type without loss of precision is picked. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

downsamplingFactors - in each dimension d, downsamplingFactors[d] pixels in the input image should be averaged to one output pixel. downsamplingFactors is expanded or truncated to the necessary size. For example, if downsamplingFactors=={2,2,1} and the operator is applied to a 2D image, downsamplingFactors is truncated to {2, 2}. If the operator is applied to a 5D image, downsamplingFactors is expanded to {2, 2, 1, 1, 1}

Returns:

factory for UnaryBlockOperator to downsample blocks of type T

createOperator

public static <T extends NativeType<T>> UnaryBlockOperator<T,T> createOperator(T type,
                                                                               ComputationType computationType,
                                                                               Downsample.Offset offset,
                                                                               boolean[] downsampleInDim)

Create a UnaryBlockOperator to downsample (by factor 2) blocks of the standard ImgLib2 RealType. The downsampleInDim argument specifies in which dimensions the input should be downsampled.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

Type Parameters:

T - the input/output type

Parameters:

type - instance of the input type

computationType - specifies in which precision intermediate values should be computed. For AUTO, the type that can represent the input/output type without loss of precision is picked. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

offset - Specifies where downsampled pixels should be placed. HALF_PIXEL means that each downsampled pixel is computed as the average of 2 neighboring pixels (respectively 4 pixels for 2D, 8 voxels for 3D, etc.), and downsampled pixels are shifted by half a pixel. CENTERED means that each downsampled pixel is computed as the weighted average (with weights {.25, .5, .25}) of 3 neighboring pixels (respectively 9 pixels for 2D, 27 voxels for 3D, etc.) Downsampled pixels are centered on input pixels.

downsampleInDim - for each dimension d: if downsampleInDim[d]==true then the input image should be downsampled in dimension d.

Returns:

UnaryBlockOperator to downsample blocks of type T

createOperator

public static <T extends NativeType<T>> UnaryBlockOperator<T,T> createOperator(T type,
                                                                               ComputationType computationType,
                                                                               Downsample.Offset offset,
                                                                               int numDimensions)

Create a UnaryBlockOperator to downsample (by factor 2, in all dimensions) blocks of the standard ImgLib2 RealType.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

Type Parameters:

T - the input/output type

Parameters:

type - instance of the input type

computationType - specifies in which precision intermediate values should be computed. For AUTO, the type that can represent the input/output type without loss of precision is picked. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

offset - Specifies where downsampled pixels should be placed. HALF_PIXEL means that each downsampled pixel is computed as the average of 2 neighboring pixels (respectively 4 pixels for 2D, 8 voxels for 3D, etc.), and downsampled pixels are shifted by half a pixel. CENTERED means that each downsampled pixel is computed as the weighted average (with weights {.25, .5, .25}) of 3 neighboring pixels (respectively 9 pixels for 2D, 27 voxels for 3D, etc.) Downsampled pixels are centered on input pixels.

numDimensions - number of dimensions in input/output image.

Returns:

UnaryBlockOperator to downsample blocks of type T

createOperator

public static <T extends NativeType<T>> UnaryBlockOperator<T,T> createOperator(T type,
                                                                               ComputationType computationType,
                                                                               int[] downsamplingFactors)

Create a UnaryBlockOperator to downsample (by the given downsamplingFactors) blocks of the standard ImgLib2 RealType.

Supported types are UnsignedByteType, UnsignedShortType, UnsignedIntType, ByteType, ShortType, IntType, LongType, FloatType, DoubleType).

Type Parameters:

T - the input/output type

Parameters:

type - instance of the input type

computationType - specifies in which precision intermediate values should be computed. For AUTO, the type that can represent the input/output type without loss of precision is picked. That is, FLOAT for u8, i8, u16, i16, i32, f32, and otherwise DOUBLE for u32, i64, f64.

downsamplingFactors - in each dimension d, downsamplingFactors[d] pixels in the input image should be averaged to one output pixel.

Returns:

UnaryBlockOperator to downsample blocks of type T