Module org.apache.sis.referencing

Package org.apache.sis.referencing.operation.transform

Class PassThroughTransform

Object

FormattableObject

AbstractMathTransform

PassThroughTransform

All Implemented Interfaces:

Serializable, Parameterized, Lenient­Comparable, Math­Transform

public class PassThroughTransform
extends AbstractMathTransform
implements Serializable

Transform which passes through a subset of coordinates to another transform. This allows transforms to operate on a subset of coordinate values.

Example

Giving (latitude, longitude, height) coordinates, Pass­Through­Transform can convert the height values from feet to meters without affecting the latitude and longitude values. Such transform can be built as below:

MathTransform feetToMetres = MathTransforms.linear(0.3048, 0);       // One-dimensional conversion.
MathTransform tr = MathTransforms.passThrough(2, feetToMetres, 0);   // Three-dimensional conversion.

Immutability and thread safety

Pass­Through­Transform is immutable and thread-safe if its subTransform is also immutable and thread-safe.

Serialization

Serialized instances of this class are not guaranteed to be compatible with future SIS versions. Serialization should be used only for short term storage or RMI between applications running the same SIS version.

Since:

0.5

See Also:

• Math­Transforms.pass­Through(int, Math­Transform, int)
• Math­Transforms.compound(Math­Transform...)
• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class AbstractMathTransform

Abstract­Math­Transform.Inverse

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Pass­Through­Transform(int first­Affected­Coordinate, Math­Transform sub­Transform, int num­Trailing­Coordinates)	Constructor for sub-classes.

Method Summary

Modifier and Type	Method	Description
protected int	compute­Hash­Code()	Computes a hash value for this transform.
static Math­Transform	create(Bit­Set modified­Coordinates, Math­Transform sub­Transform, int result­Dim, Math­Transform­Factory factory)	Creates a transform which passes through a subset of coordinates to another transform.
Matrix	derivative(Direct­Position point)	Gets the derivative of this transform at a point.
boolean	equals(Object object, Comparison­Mode mode)	Compares the specified object with this math transform for equality.
protected String	format­To(Formatter formatter)	Formats this transform as a Well Known Text version 1 (WKT 1) element.
final int[]	get­Modified­Coordinates()	Returns the ordered sequence of positive integers defining the positions in a source coordinate tuple of the coordinates affected by this pass-through operation.
final int	get­Source­Dimensions()	Gets the dimension of input points.
final Math­Transform	get­Sub­Transform()	Returns the sub-transform to apply on the modified coordinates.
final int	get­Target­Dimensions()	Gets the dimension of output points.
Math­Transform	inverse()	Creates the inverse transform of this object.
boolean	is­Identity()	Tests whether this transform does not move any points.
Matrix	transform(double[] src­Pts, int src­Off, double[] dst­Pts, int dst­Off, boolean derivate)	Transforms a single position in a list of coordinate values, and opportunistically computes the transform derivative if requested.
void	transform(double[] src­Pts, int src­Off, double[] dst­Pts, int dst­Off, int num­Pts)	Transforms many positions in a list of coordinate values.
void	transform(double[] src­Pts, int src­Off, float[] dst­Pts, int dst­Off, int num­Pts)	Transforms many positions in a list of coordinate values.
void	transform(float[] src­Pts, int src­Off, double[] dst­Pts, int dst­Off, int num­Pts)	Transforms many positions in a list of coordinate values.
void	transform(float[] src­Pts, int src­Off, float[] dst­Pts, int dst­Off, int num­Pts)	Transforms many positions in a list of coordinate values.
protected Math­Transform	try­Concatenate(boolean apply­Other­First, Math­Transform other, Math­Transform­Factory factory)	Concatenates or pre-concatenates in an optimized way this transform with the given transform, if possible.

Methods inherited from class AbstractMathTransform

equals, get­Contextual­Parameters, get­Domain, get­Parameter­Descriptors, get­Parameter­Values, hash­Code, transform

Methods inherited from class FormattableObject

print, to­String, to­String, to­WKT

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Methods inherited from interface MathTransform

to­WKT

Constructor Details

PassThroughTransform

protected PassThroughTransform(int firstAffectedCoordinate,
 MathTransform subTransform,
 int numTrailingCoordinates)

Constructor for sub-classes. Users should invoke the static Math­Transforms.pass­Through(int, Math­Transform, int) factory method instead, since the most optimal pass-through transform for the given sub­Transform is not necessarily a Pass­Through­Transform instance.

Parameters:

first­Affected­Coordinate - index of the first affected coordinate.

sub­Transform - the sub-transform to apply on modified coordinates.

num­Trailing­Coordinates - number of trailing coordinates to pass through.

See Also:

• Math­Transforms.pass­Through(int, Math­Transform, int)

Method Details

create

public static MathTransform create(BitSet modifiedCoordinates,
 MathTransform subTransform,
 int resultDim,
 MathTransformFactory factory)
                            throws FactoryException

Creates a transform which passes through a subset of coordinates to another transform. The list of modified coordinates is specified by a Bit­Set argument where each bit set to 1 identifies the dimension of a modified coordinate. The array of modified coordinates can be expanded as below:

int[] modifiedCoordinates = bitset.stream().toArray();

The bitset cardinality, which is also the length of above array, must be equal to the number of source dimensions in the given sub­Transform.

Limitation

If the modified coordinates are not at consecutive positions in source coordinate tuples, then the current implementation of this method adds the following restrictions:

• The sub-transform must have an number of target dimensions equal to the number of source dimensions.
• The sub-transform must be separable.

Above restrictions are relaxed if all modified coordinates are at consecutive positions.

Parameters:

modified­Coordinates - positions in a source coordinate tuple of the coordinates affected by the transform.

sub­Transform - the sub-transform to apply on modified coordinates.

result­Dim - total number of source dimensions of the pass-through transform to return.

factory - the factory to use for creating transforms, or null for the default.

Returns:

a pass-through transform for the given set of modified coordinates.

Throws:

Mismatched­Dimension­Exception - if the modified­Coordinates bitset cardinality is not equal to the number of source dimensions in sub­Transform.

Illegal­Argument­Exception - if the index of a modified coordinates is out of bounds.

Factory­Exception - if an error occurred while creating a transform step.

Since:

1.4

See Also:

• Math­Transforms.pass­Through(int[], Math­Transform, int)

getSourceDimensions

public final int getSourceDimensions()

Gets the dimension of input points. This the source dimension of the sub-transform plus the number of pass-through dimensions.

Specified by:

get­Source­Dimensions in interface Math­Transform

Specified by:

get­Source­Dimensions in class Abstract­Math­Transform

Returns:

the number of dimensions of input points.

See Also:

• Default­Operation­Method.get­Source­Dimensions()

getTargetDimensions

public final int getTargetDimensions()

Gets the dimension of output points. This the target dimension of the sub-transform plus the number of pass-through dimensions.

Specified by:

get­Target­Dimensions in interface Math­Transform

Specified by:

get­Target­Dimensions in class Abstract­Math­Transform

Returns:

the number of dimensions of output points.

See Also:

• Default­Operation­Method.get­Target­Dimensions()

getModifiedCoordinates

public final int[] getModifiedCoordinates()

Returns the ordered sequence of positive integers defining the positions in a source coordinate tuple of the coordinates affected by this pass-through operation.

Returns:

Zero-based indices of the modified source coordinates.

See Also:

• Default­Pass­Through­Operation.get­Modified­Coordinates()

getSubTransform

public final MathTransform getSubTransform()

Returns the sub-transform to apply on the modified coordinates. This is often the sub-transform specified at construction time, but not necessarily.

Returns:

the sub-transform.

See Also:

• Default­Pass­Through­Operation.get­Operation()

isIdentity

public boolean isIdentity()

Tests whether this transform does not move any points. A Pass­Through­Transform is identity if the sub-transform is also identity.

Specified by:

is­Identity in interface Math­Transform

Overrides:

is­Identity in class Abstract­Math­Transform

Returns:

transform

public Matrix transform(double[] srcPts,
 int srcOff,
 double[] dstPts,
 int dstOff,
 boolean derivate)
                 throws TransformException

Transforms a single position in a list of coordinate values, and opportunistically computes the transform derivative if requested.

Specified by:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source coordinates (cannot be null).

src­Off - the offset to the point to be transformed in the source array.

dst­Pts - the array into which the transformed coordinates is returned. May be the same than src­Pts. May be null if only the derivative matrix is desired.

dst­Off - the offset to the location of the transformed point that is stored in the destination array.

derivate - true for computing the derivative, or false if not needed.

Returns:

the matrix of the transform derivative at the given source position, or null if the derivate argument is false.

Throws:

Transform­Exception - if the sub-transform failed.

See Also:

• Abstract­Math­Transform.derivative(Direct­Position)
• Abstract­Math­Transform.transform(Direct­Position, Direct­Position)
• Math­Transforms.derivative­And­Transform(Math­Transform, double[], int, double[], int)

transform

public void transform(double[] srcPts,
 int srcOff,
 double[] dstPts,
 int dstOff,
 int numPts)
               throws TransformException

Transforms many positions in a list of coordinate values.

Specified by:

transform in interface Math­Transform

Overrides:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source point coordinates.

src­Off - the offset to the first point to be transformed in the source array.

dst­Pts - the array into which the transformed point coordinates are returned. May be the same than src­Pts.

dst­Off - the offset to the location of the first transformed point that is stored in the destination array.

num­Pts - the number of point objects to be transformed.

Throws:

Transform­Exception - if the sub-transform failed.

transform

public void transform(float[] srcPts,
 int srcOff,
 float[] dstPts,
 int dstOff,
 int numPts)
               throws TransformException

Transforms many positions in a list of coordinate values.

Specified by:

transform in interface Math­Transform

Overrides:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source point coordinates.

src­Off - the offset to the first point to be transformed in the source array.

dst­Pts - the array into which the transformed point coordinates are returned. May be the same than src­Pts.

dst­Off - the offset to the location of the first transformed point that is stored in the destination array.

num­Pts - the number of point objects to be transformed.

Throws:

Transform­Exception - if the sub-transform failed.

transform

public void transform(double[] srcPts,
 int srcOff,
 float[] dstPts,
 int dstOff,
 int numPts)
               throws TransformException

Transforms many positions in a list of coordinate values.

Specified by:

transform in interface Math­Transform

Overrides:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source point coordinates.

src­Off - the offset to the first point to be transformed in the source array.

dst­Pts - the array into which the transformed point coordinates are returned.

dst­Off - the offset to the location of the first transformed point that is stored in the destination array.

num­Pts - the number of point objects to be transformed.

Throws:

Transform­Exception - if the sub-transform failed.

transform

public void transform(float[] srcPts,
 int srcOff,
 double[] dstPts,
 int dstOff,
 int numPts)
               throws TransformException

Transforms many positions in a list of coordinate values.

Specified by:

transform in interface Math­Transform

Overrides:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source point coordinates.

src­Off - the offset to the first point to be transformed in the source array.

dst­Pts - the array into which the transformed point coordinates are returned.

dst­Off - the offset to the location of the first transformed point that is stored in the destination array.

num­Pts - the number of point objects to be transformed.

Throws:

Transform­Exception - if the sub-transform failed.

derivative

public Matrix derivative(DirectPosition point)
                  throws TransformException

Gets the derivative of this transform at a point.

Specified by:

derivative in interface Math­Transform

Overrides:

derivative in class Abstract­Math­Transform

Parameters:

point - the coordinate tuple where to evaluate the derivative.

Returns:

the derivative at the specified point (never null).

Throws:

Transform­Exception - if the sub-transform failed.

inverse

public MathTransform inverse()
                      throws NoninvertibleTransformException

Creates the inverse transform of this object.

Specified by:

inverse in interface Math­Transform

Overrides:

inverse in class Abstract­Math­Transform

Returns:

Throws:

Noninvertible­Transform­Exception - if the sub-transform is not invertible.

tryConcatenate

protected MathTransform tryConcatenate(boolean applyOtherFirst,
 MathTransform other,
 MathTransformFactory factory)
                                throws FactoryException

Concatenates or pre-concatenates in an optimized way this transform with the given transform, if possible. This method applies the following special cases:

• If the other transform is also a Pass­Through­Transform, then the two transforms may be merged in a single Pass­Through­Transform instance.
• If the other transform discards some dimensions, verify if we still need a Pass­Through­Transform.

Overrides:

try­Concatenate in class Abstract­Math­Transform

Parameters:

apply­Other­First - true if the transformation order is other followed by this, or false if the transformation order is this followed by other.

other - the other math transform to (pre-)concatenate with this transform.

factory - the factory which is (indirectly) invoking this method, or null if none.

Returns:

the simplified transform, or null if no such optimization is available.

Throws:

Factory­Exception - if an error occurred while combining the transforms.

Since:

1.0

See Also:

• Default­Math­Transform­Factory.create­Concatenated­Transform(Math­Transform, Math­Transform)

computeHashCode

protected int computeHashCode()

Computes a hash value for this transform. This method is invoked by Abstract­Math­Transform.hash­Code() when first needed.

Overrides:

compute­Hash­Code in class Abstract­Math­Transform

Returns:

the hash code value. This value may change between different execution of the Apache SIS library.

equals

public boolean equals(Object object,
 ComparisonMode mode)

Compares the specified object with this math transform for equality.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Abstract­Math­Transform

Parameters:

object - the object to compare with this transform.

mode - the strictness level of the comparison. Default to STRICT.

Returns:

true if the given object is considered equals to this math transform.

See Also:

• Utilities.deep­Equals(Object, Object, Comparison­Mode)

formatTo

protected String formatTo(Formatter formatter)

Formats this transform as a Well Known Text version 1 (WKT 1) element.

Compatibility note

Pass­Through_MT is defined in the WKT 1 specification only. If the formatter convention is set to WKT 2, then this method silently uses the WKT 1 convention without raising an error (unless this Pass­Through­Transform cannot be formatted as valid WKT 1 neither).

Overrides:

format­To in class Abstract­Math­Transform

Parameters:

formatter - the formatter to use.

Returns:

the WKT element name, which is "Pass­Through_MT".

See Also:

• Default­Math­Transform­Factory.create­From­WKT(String)