org.geotoolkit.referencing.operation.transform
Class DimensionFilter

Object
  DimensionFilter

public class DimensionFilter
extends Object

An utility class for the separation of concatenation of pass through transforms. Given an arbitrary math transform, this utility class will returns a new math transform that operates only of a given set of source dimensions. For example if the supplied transform has (x, y, z) inputs and (longitude, latitude, height) outputs, then the following code:

addSourceDimensionRange(0, 2);
MathTransform mt = separate(transform);

will returns a transform with (x, y) inputs and (probably) (longitude, latitude) outputs. The later can be verified with a call to getTargetDimensions().

Since:

2.1

Version:

3.00

Author:

Martin Desruisseaux (IRD), Simone Giannecchini (Geosolutions)

Module:

referencing/geotk-referencing (download)

View source code for this class

TODO:

This class contains a set of static methods that could be factored out in some kind of org.geotoolkit.util.SortedIntegerSet implementation.

Field Summary

static Hints.Key

INSTANCE Hint key for specifying a particular instance of DimensionFilter to use.

Constructor Summary

DimensionFilter()
Constructs a dimension filter with the default math transform factory.

DimensionFilter(Hints hints)
Constructs a dimension filter with a math transform factory built using the provided hints.

DimensionFilter(MathTransformFactory factory)
Constructs a dimension filter with the specified factory.

Method Summary

void	addSourceDimension(int dimension) Adds an input dimension to keep.
void	addSourceDimensionRange(int lower, int upper) Adds a range of input dimensions to keep.
void	addSourceDimensions(int[] dimensions) Adds input dimensions to keep.
void	addTargetDimension(int dimension) Adds an output dimension to keep.
void	addTargetDimensionRange(int lower, int upper) Adds a range of output dimensions to keep.
void	addTargetDimensions(int[] dimensions) Adds output dimensions to keep.
void	clear() Clears any source and target dimension setting.
static DimensionFilter	getInstance(Hints hints) Creates or returns an existing instance from the given set of hints.
int[]	getSourceDimensions() Returns the input dimensions.
int[]	getTargetDimensions() Returns the output dimensions.
MathTransform	separate(MathTransform transform) Separates the specified math transform.

Methods inherited from class Object

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

Field Detail

INSTANCE

public static final Hints.Key INSTANCE

Hint key for specifying a particular instance of DimensionFilter to use.

Since:

2.5

See Also:

getInstance(org.geotoolkit.factory.Hints)

Constructor Detail

DimensionFilter

public DimensionFilter()

Constructs a dimension filter with the default math transform factory.

DimensionFilter

public DimensionFilter(Hints hints)

Constructs a dimension filter with a math transform factory built using the provided hints.

Parameters:

hints - Hints to control the creation of the MathTransformFactory.

DimensionFilter

public DimensionFilter(MathTransformFactory factory)

Constructs a dimension filter with the specified factory.

Parameters:

factory - The factory for the creation of new math transforms.

Method Detail

getInstance

public static DimensionFilter getInstance(Hints hints)

Creates or returns an existing instance from the given set of hints. If the hints contain a value for the INSTANCE key, this value is returned. Otherwise a new instance is created with the given hints.

Parameters:

hints - The hints, or null if none.

Returns:

An existing or a new DimensionFilter instance (never null).

Since:

2.5

See Also:

INSTANCE

clear

public void clear()

Clears any source and target dimension setting.

addSourceDimension

public void addSourceDimension(int dimension)
                        throws IllegalArgumentException

Adds an input dimension to keep. The dimension applies to the source dimensions of the transform to be given to separate(transform). The number must be in the range 0 inclusive to transform.getSourceDimensions() exclusive.

Parameters:

dimension - The dimension to add.

Throws:

IllegalArgumentException - if dimension is negative.

addSourceDimensions

public void addSourceDimensions(int[] dimensions)
                         throws IllegalArgumentException

Adds input dimensions to keep. The dimensions apply to the source dimensions of the transform to be given to separate(transform). All numbers must be in the range 0 inclusive to transform.getSourceDimensions() exclusive. The dimensions values must be in strictly increasing order.

Parameters:

dimensions - The new sequence of dimensions.

Throws:

IllegalArgumentException - if dimensions contains negative values or is not a strictly increasing sequence.

addSourceDimensionRange

public void addSourceDimensionRange(int lower,
                                    int upper)
                             throws IllegalArgumentException

Adds a range of input dimensions to keep. The lower and upper values apply to the source dimensions of the transform to be given to separate(transform).

Parameters:

lower - The lower dimension, inclusive. Must not be smaller than 0.

upper - The upper dimension, exclusive. Must not be greater than transform.getSourceDimensions().

Throws:

IllegalArgumentException - if lower or upper are out of bounds.

getSourceDimensions

public int[] getSourceDimensions()
                          throws IllegalStateException

Returns the input dimensions. This information is available only if at least one setter method has been explicitly invoked for source dimensions.

Returns:

The input dimension as a sequence of strictly increasing values.

Throws:

IllegalStateException - if input dimensions have not been set.

addTargetDimension

public void addTargetDimension(int dimension)
                        throws IllegalArgumentException

Adds an output dimension to keep. The dimension applies to the target dimensions of the transform to be given to separate(transform). The number must be in the range 0 inclusive to transform.getTargetDimensions() exclusive.

Parameters:

dimension - The dimension to add.

Throws:

IllegalArgumentException - if dimension is negative.

addTargetDimensions

public void addTargetDimensions(int[] dimensions)
                         throws IllegalArgumentException

Adds output dimensions to keep. The dimensions apply to the target dimensions of the transform to be given to separate(transform). All numbers must be in the range 0 inclusive to transform.getTargetDimensions() exclusive. The dimensions values must be in strictly increasing order.

Parameters:

dimensions - The new sequence of dimensions.

Throws:

IllegalArgumentException - if dimensions contains negative values or is not a strictly increasing sequence.

addTargetDimensionRange

public void addTargetDimensionRange(int lower,
                                    int upper)
                             throws IllegalArgumentException

Adds a range of output dimensions to keep. The lower and upper values apply to the target dimensions of the transform to be given to separate(transform).

Parameters:

lower - The lower dimension, inclusive. Must not be smaller than 0.

upper - The upper dimension, exclusive. Must not be greater than transform.getTargetDimensions().

Throws:

IllegalArgumentException - if lower or upper are out of bounds.

getTargetDimensions

public int[] getTargetDimensions()
                          throws IllegalStateException

Returns the output dimensions. This information is available only if one of the following conditions is meet:

• Target dimensions has been explicitly set using setter methods.
• No target dimensions were set but separate(transform) has been invoked at least once, in which case the target dimensions are inferred automatically from the source dimensions and the transform.

Returns:

The output dimension as a sequence of strictly increasing values.

Throws:

IllegalStateException - if this information is not available.

separate

public MathTransform separate(MathTransform transform)
                       throws FactoryException

Separates the specified math transform. This method returns a math transform that uses only the specified source dimensions and returns only the specified target dimensions. Special case:

• If source dimensions are unspecified, then the returned transform will expects all source dimensions as input but will produces only the specified target dimensions as output.

• If target dimensions are unspecified, then the returned transform will expects only the specified source dimensions as input, and the target dimensions will be inferred automatically.

Parameters:

transform - The transform to separate.

Returns:

The separated math transform.

Throws:

FactoryException - if the transform can't be separated.