org.geotoolkit.image.io
Class SampleConverter

Object
  SampleConverter

@Immutable
public abstract class SampleConverter
extends Object

Converts samples from the values stored in the image file to the values stored in the raster. Some typical conversions are:

• Replace "nodata" values (typically a fixed value like 9999 or 32767) by NaN if the target type is float or double, or 0 if the target type is an integer.
• Replace signed integers by unsigned integers, by applying an offset to the values.

Note that pad values are replaced by 0 in the integer case, not by an arbitrary number, because 0 is the result of (int) NaN cast. While not mandatory, this property make some mathematics faster during conversions between geophysics and display views in the coverage module.

There is no scaling because this class is not for samples to geophysics values conversions (except the replacement of pad values by NaN). This class is about the minimal changes needed in order to comply to the constraints of a target color model, for example in order to workaround the fact that IndexColorModel does not accept negative numbers.

SampleConverters are typically created and used by the SpatialImageReader class and subclasses. They are created (directly or indirectly) by the getImageType method and used by the read method.

Since:

2.4

Version:

3.07

Author:

Martin Desruisseaux (Geomatys)

See Also:

SampleConversionType

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

static SampleConverter

IDENTITY A sample converter that do not performs any conversion.

Constructor Summary

protected

SampleConverter() Constructs a sample converter.

Method Summary

abstract double	convert(double value) Converts a double-precision value before to store it in the raster.
void	convert(double[] values, int offset, int length) Converts in-place an array of double-precision values.
abstract float	convert(float value) Converts a float-precision value before to store it in the raster.
void	convert(float[] values, int offset, int length) Converts in-place an array of single-precision values.
abstract int	convert(int value) Converts a float-precision value before to store it in the raster.
void	convert(int[] values, int offset, int length) Converts in-place an array of integer values.
void	convert(short[] values, int offset, int length) Converts in-place an array of short values.
void	convertUnsigned(byte[] values, int offset, int length) Converts in-place an array of unsigned byte values.
void	convertUnsigned(short[] values, int offset, int length) Converts in-place an array of unsigned short values.
static SampleConverter	createOffset(double offset, double padValue) Creates a sample converter that replaces a pad value by NaN or 0, and applies an offset on all other values.
static SampleConverter	createOffset(double offset, double[] padValues) Creates a sample converter that replaces an arbitrary amount of pad values by NaN or 0, and applies an offset on all other values.
static SampleConverter	createPadValueMask(double padValue) Creates a sample converter that replaces a single pad value by NaN for floating point numbers, or 0 for integers.
static SampleConverter	createPadValuesMask(double[] padValues) Creates a sample converter that replaces an arbitrary amount of pad values by NaN for floating point numbers, or 0 for integers.
double	getOffset() If this converter applies an offset, returns the offset.
String	toString() Returns a string representation of this sample converter.

Methods inherited from class Object

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

Field Detail

IDENTITY

public static final SampleConverter IDENTITY

A sample converter that do not performs any conversion.

Constructor Detail

SampleConverter

protected SampleConverter()

Constructs a sample converter.

Method Detail

createPadValueMask

public static SampleConverter createPadValueMask(double padValue)

Creates a sample converter that replaces a single pad value by NaN for floating point numbers, or 0 for integers.

Parameters:

padValue - The pad values to replace by NaN or 0.

Returns:

The sample converter.

createPadValuesMask

public static SampleConverter createPadValuesMask(double[] padValues)

Creates a sample converter that replaces an arbitrary amount of pad values by NaN for floating point numbers, or 0 for integers.

Parameters:

padValues - The pad values to replace by NaN or 0, or null if none.

Returns:

The sample converter.

createOffset

public static SampleConverter createOffset(double offset,
                                           double padValue)

Creates a sample converter that replaces a pad value by NaN or 0, and applies an offset on all other values. This is typically used in order to shift a range of arbitrary (including negative) integer values to a range of strictly positive values. The later is more manageable by index color model.

Parameters:

offset - An offset to add to the values to be read, before to store them in the raster. This is used primarily for transforming signed short into unsigned short.

padValue - The pad value to replace. This the value before the offset is applied.

Returns:

The sample converter.

createOffset

public static SampleConverter createOffset(double offset,
                                           double[] padValues)

Creates a sample converter that replaces an arbitrary amount of pad values by NaN or 0, and applies an offset on all other values.

Parameters:

offset - An offset to add to the values to be read, before to store them in the raster.

padValues - The pad values to replace. They the values before the offset is applied.

Returns:

The sample converter.

convert

public abstract double convert(double value)

Converts a double-precision value before to store it in the raster. Subclasses should override this method if some fixed values need to be converted into Double.NaN value.

Parameters:

value - The value read from the image file.

Returns:

The value to store in the raster.

convert

public abstract float convert(float value)

Converts a float-precision value before to store it in the raster. Subclasses should override this method if some fixed values need to be converted into Float.NaN value.

Parameters:

value - The value read from the image file.

Returns:

The value to store in the raster.

convert

public abstract int convert(int value)

Converts a float-precision value before to store it in the raster.

Parameters:

value - The value read from the image file.

Returns:

The value to store in the raster.

convert

public void convert(double[] values,
                    int offset,
                    int length)

Converts in-place an array of double-precision values.

Parameters:

values - The values to convert.

offset - Index of the first sample to convert.

length - Number of samples to convert.

Since:

3.07

convert

public void convert(float[] values,
                    int offset,
                    int length)

Converts in-place an array of single-precision values.

Parameters:

values - The values to convert.

offset - Index of the first sample to convert.

length - Number of samples to convert.

Since:

3.07

convert

public void convert(int[] values,
                    int offset,
                    int length)

Converts in-place an array of integer values.

Parameters:

values - The values to convert.

offset - Index of the first sample to convert.

length - Number of samples to convert.

Since:

3.07

convert

public void convert(short[] values,
                    int offset,
                    int length)

Converts in-place an array of short values.

Parameters:

values - The values to convert.

offset - Index of the first sample to convert.

length - Number of samples to convert.

Since:

3.07

convertUnsigned

public void convertUnsigned(short[] values,
                            int offset,
                            int length)

Converts in-place an array of unsigned short values.

Parameters:

values - The values to convert.

offset - Index of the first sample to convert.

length - Number of samples to convert.

Since:

3.07

convertUnsigned

public void convertUnsigned(byte[] values,
                            int offset,
                            int length)

Converts in-place an array of unsigned byte values.

Parameters:

values - The values to convert.

offset - Index of the first sample to convert.

length - Number of samples to convert.

Since:

3.07

getOffset

public double getOffset()

If this converter applies an offset, returns the offset. Otherwise returns 0.

Returns:

The offset applied when converting sample values.

toString

public String toString()

Returns a string representation of this sample converter. This is mostly for debugging purpose and may change in any future version.

Overrides:

toString in class Object