org.geotools.referencing.operation.transform
Class DimensionFilter

java.lang.Object
  org.geotools.referencing.operation.transform.DimensionFilter

public class DimensionFilter

extends java.lang.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 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:

$Id: DimensionFilter.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

To Do:

This class is specific to Geotools implementation; it is better to avoid it if you can. It could be generalized a bit if we perform the same operations on CoordinateOperation interfaces instead of math transforms. We should revisit this issue after grid coverage API has been revisited (since grid coverage is a user of this class)., This class contains a set of static methods that could be factored out in some kind of implementation.

Constructor Summary

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

DimensionFilter(org.opengis.referencing.operation.MathTransformFactory factory)
Constructs a dimension filter with the specified factory.

Method Summary

void	addSourceDimension(int dimension) Add an input dimension to keep.
void	addSourceDimensionRange(int lower, int upper) Add a range of input dimensions to keep.
void	addSourceDimensions(int[] dimensions) Add input dimensions to keep.
void	addTargetDimension(int dimension) Add an output dimension to keep.
void	addTargetDimensionRange(int lower, int upper) Add a range of output dimensions to keep.
void	addTargetDimensions(int[] dimensions) Add output dimensions to keep.
void	clear() Clear any source and target dimension setting.
int[]	getSourceDimensions() Returns the input dimensions.
int[]	getTargetDimensions() Returns the output dimensions.
org.opengis.referencing.operation.MathTransform	separate(org.opengis.referencing.operation.MathTransform transform) Separates the specified math transform.

Methods inherited from class java.lang.Object

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

Constructor Detail

DimensionFilter

public DimensionFilter()

Constructs a dimension filter with the default math transform factory.

DimensionFilter

public DimensionFilter(org.opengis.referencing.operation.MathTransformFactory factory)

Constructs a dimension filter with the specified factory.

Parameters:

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

Method Detail

clear

public void clear()

Clear any source and target dimension setting.

addSourceDimension

public void addSourceDimension(int dimension)
                        throws java.lang.IllegalArgumentException

Add an input dimension to keep. The 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:

java.lang.IllegalArgumentException - if is negative.

addSourceDimensions

public void addSourceDimensions(int[] dimensions)
                         throws java.lang.IllegalArgumentException

Add input dimensions to keep. The 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 values must be in strictly increasing order.

Parameters:

dimensions - The new sequence of dimensions.

Throws:

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

addSourceDimensionRange

public void addSourceDimensionRange(int lower,
                                    int upper)
                             throws java.lang.IllegalArgumentException

Add a range of input dimensions to keep. The and 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:

java.lang.IllegalArgumentException

getSourceDimensions

public int[] getSourceDimensions()
                          throws java.lang.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:

java.lang.IllegalStateException - if input dimensions have not been set.

addTargetDimension

public void addTargetDimension(int dimension)
                        throws java.lang.IllegalArgumentException

Add an output dimension to keep. The 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:

java.lang.IllegalArgumentException - if is negative.

addTargetDimensions

public void addTargetDimensions(int[] dimensions)
                         throws java.lang.IllegalArgumentException

Add output dimensions to keep. The 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 values must be in strictly increasing order.

Parameters:

dimensions - The new sequence of dimensions.

Throws:

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

addTargetDimensionRange

public void addTargetDimensionRange(int lower,
                                    int upper)
                             throws java.lang.IllegalArgumentException

Add a range of output dimensions to keep. The and 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:

java.lang.IllegalArgumentException

getTargetDimensions

public int[] getTargetDimensions()
                          throws java.lang.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 .

Returns:

The output dimension as a sequence of strictly increasing values.

Throws:

java.lang.IllegalStateException - if this information is not available.

separate

public org.opengis.referencing.operation.MathTransform separate(org.opengis.referencing.operation.MathTransform transform)
                                                         throws org.opengis.referencing.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:

org.opengis.referencing.FactoryException - if the transform can't be separated.