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

Class 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

    Defined in the sis-referencing module

    • Constructor Detail

      • 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 Detail

      • create

        @Deprecated
public static MathTransform create​(int firstAffectedCoordinate,
                                   MathTransform subTransform,
                                   int numTrailingCoordinates)
        Deprecated.
        Moved to Math­Transforms​.pass­Through(int, Math­Transform, int).
        Creates a transform which passes through a subset of coordinates to another transform. This method returns a transform having the following dimensions: 
        Source: firstAffectedCoordinate + subTransform.getSourceDimensions() + numTrailingCoordinates
Target: firstAffectedCoordinate + subTransform.getTargetDimensions() + numTrailingCoordinates
        Affected coordinates will range from first­Affected­Coordinate inclusive to dim­Target - num­Trailing­Coordinates exclusive.
        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.
        Returns:
        a pass-through transform, not necessarily a Pass­Through­Transform instance.

      • 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.
        API note: this method is final for now because most of Apache SIS code do not use the modified­Coordinates array. Instead, SIS uses the first­Affected­Coordinate and num­Trailing­Coordinates information provided to the constructor. Consequently overriding this method may be misleading since it would be ignored by SIS. We do not want to make the "really used" fields public in order to keep the flexibility to replace them by a modified­Coordinates array in a future SIS version.
        Returns:
        Zero-based indices of the modified source coordinates.
        See Also:
        Default­Pass­Through­Operation​.get­Modified­Coordinates()

      • transform

        public void transform​(double[] srcPts,
                      int srcOff,
                      double[] dstPts,
                      int dstOff,
                      int numPts)
               throws TransformException
        Transforms many coordinates in a list of ordinal 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 coordinates in a list of ordinal 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 coordinates in a list of ordinal 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 coordinates in a list of ordinal 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.

      • 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)

      • 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.