Class TransformSeparator
 Object

 TransformSeparator

public class TransformSeparator extends Object
Extracts a subtransform from a givenMathTransform
and source or target dimension indices. Given an arbitraryMathTransform
, this class tries to return a new math transform that operates only on a given set of source or target dimensions.Example: if the suppliedtransform
has (x,y,z) inputs and (λ,φ,h) outputs, then the following code:
will return a transform with (x,y) inputs and (probably) (λ,φ) outputs. The output dimensions can be verified with a call toTransformSeparator s = new TransformSeparator(theTransform); s.addSourceDimensionRange(0, 2); MathTransform mt = s.separate();
getTargetDimensions()
. Since:
 0.7
Defined in the
sisreferencing
module


Field Summary
Fields Modifier and Type Field Description protected int[]
sourceDimensions
Indices of transform input dimensions to keep, ornull
if not yet defined.protected int[]
targetDimensions
Indices of transform output dimensions to keep, ornull
if not yet defined.protected MathTransform
transform
The transform to separate.

Constructor Summary
Constructors Constructor Description TransformSeparator(MathTransform transform)
Constructs a separator for the given transform.TransformSeparator(MathTransform transform, MathTransformFactory factory)
Constructs a separator for the given transform and using the given factory.

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addSourceDimensionRange(int lower, int upper)
Adds a range of input dimensions to keep in the separated transform.void
addSourceDimensions(int... dimensions)
Adds input dimensions to keep in the separated transform.void
addTargetDimensionRange(int lower, int upper)
Adds a range of output dimensions to keep in the separated transform.void
addTargetDimensions(int... dimensions)
Adds output dimensions to keep in the separated transform.void
clear()
Resets this transform separator in the same state than after construction.protected MathTransform
filterSourceDimensions(MathTransform step, int[] dimensions)
Creates a transform for the same mathematic than the givenstep
but expecting only the given dimensions as inputs.protected MathTransform
filterTargetDimensions(MathTransform step, int[] dimensions)
Creates a transform for the same mathematic than the givenstep
but producing only the given dimensions as outputs.int[]
getSourceDimensions()
Returns the input dimensions to keep or kept in the separated transform.int[]
getTargetDimensions()
Returns the output dimensions to keep or kept in the separated transform.MathTransform
separate()
Separates the math transform specified at construction time for given dimension indices.



Field Detail

transform
protected final MathTransform transform
The transform to separate.

sourceDimensions
protected int[] sourceDimensions
Indices of transform input dimensions to keep, ornull
if not yet defined. If nonnull, the indices in the array must be sorted in strictly increasing order. This sequence can contain any integers in the range 0 inclusive toMathTransform.getSourceDimensions()
exclusive.Values in this array should never be modified. For adding, removing or editing indices, new arrays should be created and assigned to this field. This approach makes easier to keep snapshots of indices arrays at various stages during the process of separating a
MathTransform
.

targetDimensions
protected int[] targetDimensions
Indices of transform output dimensions to keep, ornull
if not yet defined. If nonnull, the indices in the array must be sorted in strictly increasing order. This sequence can contain any integers in the range 0 inclusive toMathTransform.getTargetDimensions()
exclusive.Values in this array should never be modified. For adding, removing or editing indices, new arrays should be created and assigned to this field. This approach makes easier to keep snapshots of indices arrays at various stages during the process of separating a
MathTransform
.


Constructor Detail

TransformSeparator
public TransformSeparator(MathTransform transform)
Constructs a separator for the given transform. Parameters:
transform
 the transform to separate.

TransformSeparator
public TransformSeparator(MathTransform transform, MathTransformFactory factory)
Constructs a separator for the given transform and using the given factory. Parameters:
transform
 the transform to separate.factory
 the factory to use for creating new math transforms, ornull
if none.


Method Detail

clear
public void clear()
Resets this transform separator in the same state than after construction. This method clears any source dimensions and target dimensions settings. This method can be invoked when the sameMathTransform
needs to be separated in more than one part, for example an horizontal and a vertical component.

addSourceDimensions
public void addSourceDimensions(int... dimensions) throws IllegalArgumentException
Adds input dimensions to keep in the separated transform. The given values are source dimension indices of the transform given to the constructor.Constraints:
 All numbers shall be in the range 0 inclusive to
MathTransform.getSourceDimensions()
exclusive.  The
dimensions
values shall be in strictly increasing order.  The
dimensions
values shall be greater than all values specified by all previous calls of this method since construction or since the last call toclear()
.
 Parameters:
dimensions
 a sequence of source dimensions to keep, in strictly increasing order. Throws:
IllegalArgumentException
 ifdimensions
contains negative values or if values are not in a strictly increasing order.
 All numbers shall be in the range 0 inclusive to

addSourceDimensionRange
public void addSourceDimensionRange(int lower, int upper) throws IllegalArgumentException
Adds a range of input dimensions to keep in the separated transform. Thelower
andupper
values define a range of source dimension indices of the transform given to the constructor. Parameters:
lower
 the lower dimension, inclusive. Shall not be smaller than 0.upper
 the upper dimension, exclusive. Shall be smaller thanMathTransform.getSourceDimensions()
. Throws:
IllegalArgumentException
 iflower
orupper
are out of bounds.

getSourceDimensions
public int[] getSourceDimensions() throws IllegalStateException
Returns the input dimensions to keep or kept in the separated transform. This method performs the first applicable action in the following list: Source dimensions have been explicitly set by at least one call to
addSourceDimensions(int...)
oraddSourceDimensionRange(int, int)
since construction or since last call toclear()
. In such case, this method returns all specified source dimensions.  No source dimensions were set but
separate()
has been invoked. In such case, this method returns the sequence of source dimensions thatseparate()
chooses to retain. It may be all source dimensions of the transform given at construction time, but not necessarily.  Otherwise an exception is thrown.
TransformSeparator
tries to reduce the set of source dimensions to the smallest set required for computing the target dimensions. Returns:
 the input dimension as a sequence of strictly increasing values.
 Throws:
IllegalStateException
 if input dimensions have not been set andseparate()
has not yet been invoked.
 Source dimensions have been explicitly set by at least one call to

addTargetDimensions
public void addTargetDimensions(int... dimensions) throws IllegalArgumentException
Adds output dimensions to keep in the separated transform. The given values are target dimension indices of the transform given to the constructor.Constraints:
 All numbers shall be in the range 0 inclusive to
MathTransform.getTargetDimensions()
exclusive.  The
dimensions
values shall be in strictly increasing order.  The
dimensions
values shall be greater than all values specified by all previous calls of this method since construction or since the last call toclear()
.
 Parameters:
dimensions
 a sequence of target dimensions to keep, in strictly increasing order. Throws:
IllegalArgumentException
 ifdimensions
contains negative values or if values are not in a strictly increasing order.
 All numbers shall be in the range 0 inclusive to

addTargetDimensionRange
public void addTargetDimensionRange(int lower, int upper) throws IllegalArgumentException
Adds a range of output dimensions to keep in the separated transform. Thelower
andupper
values define a range of target dimension indices of the transform given to the constructor. Parameters:
lower
 the lower dimension, inclusive. Shall not be smaller than 0.upper
 the upper dimension, exclusive. Shall be smaller thanMathTransform.getTargetDimensions()
. Throws:
IllegalArgumentException
 iflower
orupper
are out of bounds.

getTargetDimensions
public int[] getTargetDimensions() throws IllegalStateException
Returns the output dimensions to keep or kept in the separated transform. This method performs the first applicable action in the following list: Target dimensions have been explicitly set by at least one call to
addTargetDimensions(int...)
oraddTargetDimensionRange(int, int)
since construction or since last call toclear()
. In such case, this method returns all specified target dimensions.  No target dimensions were set but
separate()
has been invoked. In such case, the target dimensions are inferred automatically from the source dimensions and the transform.  Otherwise an exception is thrown.
 Returns:
 the output dimension as a sequence of strictly increasing values.
 Throws:
IllegalStateException
 if output dimensions have not been set andseparate()
has not yet been invoked.
 Target dimensions have been explicitly set by at least one call to

separate
public MathTransform separate() throws FactoryException
Separates the math transform specified at construction time for given dimension indices. This method creates a math transform that use only the specified source dimensions and return only the specified target dimensions. If the source or target dimensions were not specified, then they will be inferred as below: If source dimensions were unspecified, then the returned transform will keep only the source dimensions needed for computing the specified target dimensions. If all source dimensions need to be kept, then they should be specified explicitly.
 If target dimensions were unspecified, then the returned transform will expect only the specified source dimensions as inputs, and the target dimensions will be inferred automatically.
 If neither source and target positions were specified, then the returned transform will have the same set of target dimensions, but only the set of source dimensions required for computing those targets. In other words, this method drops unused source dimensions.
getSourceDimensions()
orgetTargetDimensions()
after thisseparate()
method. Returns:
 the separated math transform.
 Throws:
FactoryException
 if the transform can not be separated.

filterSourceDimensions
protected MathTransform filterSourceDimensions(MathTransform step, int[] dimensions) throws FactoryException
Creates a transform for the same mathematic than the givenstep
but expecting only the given dimensions as inputs. This method is invoked byseparate()
when userspecified source dimensions need to be taken in account. The givenstep
anddimensions
are typically the values oftransform
andsourceDimensions
fields respectively, but not necessarily. In particular those arguments will differ when this method is invoked recursively for processing concatenated or subtransforms.Subclasses can override this method if they need to handle some
MathTransform
implementations in a special way. However all implementations of this method shall obey to the following contract:sourceDimensions
andtargetDimensions
should not be assumed accurate since they may be temporarily outdated or modified during recursive calls to this method.sourceDimensions
should not be modified by this method.targetDimensions
must be overwritten (not updated) by this method to the sequence of all target dimensions ofstep
that are also target dimensions of the returned transform. The indices shall be in strictly increasing order from 0 inclusive tostep.getTargetDimensions()
exclusive.
 Parameters:
step
 the transform for which to retain only a subset of the source dimensions.dimensions
 indices of the source dimensions ofstep
to retain. Returns:
 a transform expecting only the given source dimensions.
 Throws:
FactoryException
 if the given transform is not separable.

filterTargetDimensions
protected MathTransform filterTargetDimensions(MathTransform step, int[] dimensions) throws FactoryException
Creates a transform for the same mathematic than the givenstep
but producing only the given dimensions as outputs. This method is invoked byseparate()
when userspecified target dimensions need to be taken in account. The givenstep
anddimensions
are typically the values oftransform
andtargetDimensions
fields respectively, but not necessarily.Subclasses can override this method if they need to handle some
MathTransform
implementations in a special way. However all implementations of this method shall obey to the following contract:sourceDimensions
andtargetDimensions
should not be assumed accurate.sourceDimensions
should not be modified by this method.targetDimensions
should not be modified by this method.
transform
has (longitude, latitude, height) outputs, then a filtered transform may keep only the (longitude, latitude) part for the same inputs. In most cases, the filtered transform is noninvertible since it looses information. Parameters:
step
 the transform for which to retain only a subset of the target dimensions.dimensions
 indices of the target dimensions ofstep
to retain. Returns:
 a transform producing only the given target dimensions.
 Throws:
FactoryException
 if the given transform is not separable.

