org.apache.sis.referencing.operation.transform

## Class PassThroughTransform

- Object
- - FormattableObject
  - - AbstractMathTransform
    - - PassThroughTransform

- All Implemented Interfaces:
    Serializable, Parameterized, LenientComparable, MathTransform

      public class PassThroughTransform
      extends AbstractMathTransform
      implements Serializable

  Transform which passes through a subset of ordinates to another transform. This allows transforms to operate on a subset of ordinates.
  Example: giving (latitude, longitude, height) coordinates, `PassThroughTransform` 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 = PassThroughTransform.create(2, feetToMetres, 0);  // Three-dimensional conversion.

  Immutability and thread safety
  `PassThroughTransform` 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:
    `MathTransforms​.compound(MathTransform...)`, Serialized Form

  Defined in the `sis-referencing` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class AbstractMathTransform

      `AbstractMathTransform​.Inverse`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `PassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates)` Constructor for sub-classes.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected int` | `computeHashCode()` Computes a hash value for this transform.
    `static MathTransform` | `create(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates)` Creates a transform which passes through a subset of ordinates to another transform.
    `Matrix` | `derivative(DirectPosition point)` Gets the derivative of this transform at a point.
    `boolean` | `equals(Object object, ComparisonMode mode)` Compares the specified object with this math transform for equality.
    `protected String` | `formatTo(Formatter formatter)` Formats this transform as a Well Known Text version 1 (WKT 1) element.
    `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.
    `int` | `getSourceDimensions()` Gets the dimension of input points.
    `MathTransform` | `getSubTransform()` Returns the sub-transform to apply on the modified coordinates.
    `int` | `getTargetDimensions()` Gets the dimension of output points.
    `MathTransform` | `inverse()` Creates the inverse transform of this object.
    `boolean` | `isIdentity()` Tests whether this transform does not move any points.
    `Matrix` | `transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate)` Transforms a single coordinate in a list of ordinal values, and opportunistically computes the transform derivative if requested.
    `void` | `transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)` Transforms many coordinates in a list of ordinal values.
    `void` | `transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)` Transforms many coordinates in a list of ordinal values.
    `void` | `transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)` Transforms many coordinates in a list of ordinal values.
    `void` | `transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)` Transforms many coordinates in a list of ordinal values.

    - ### Methods inherited from class AbstractMathTransform

      `equals, getContextualParameters, getParameterDescriptors, getParameterValues, hashCode, transform, tryConcatenate`

    - ### Methods inherited from class FormattableObject

      `print, toString, toString, toWKT`

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface MathTransform

      `toWKT`

- - ### Constructor Detail

    - #### PassThroughTransform

          protected PassThroughTransform(int firstAffectedOrdinate,
                                         MathTransform subTransform,
                                         int numTrailingOrdinates)

      Constructor for sub-classes. Users should invoke the static `create(int, MathTransform, int)` factory method instead, since the most optimal pass-through transform for the given `subTransform` is not necessarily a `PassThroughTransform` instance.
      Parameters:
        `firstAffectedOrdinate` - index of the first affected ordinate.
        `subTransform` - the sub-transform to apply on modified coordinates.
        `numTrailingOrdinates` - number of trailing ordinates to pass through.
      See Also:
        `create(int, MathTransform, int)`

  - ### Method Detail

    - #### create

          public static MathTransform create(int firstAffectedOrdinate,
                                             MathTransform subTransform,
                                             int numTrailingOrdinates)

      Creates a transform which passes through a subset of ordinates to another transform. This method returns a transform having the following dimensions:

          Source: firstAffectedOrdinate + subTransform.getSourceDimensions() + numTrailingOrdinates
          Target: firstAffectedOrdinate + subTransform.getTargetDimensions() + numTrailingOrdinates

      Affected ordinates will range from `firstAffectedOrdinate` inclusive to `dimTarget - numTrailingOrdinates` exclusive.
      Parameters:
        `firstAffectedOrdinate` - index of the first affected ordinate.
        `subTransform` - the sub-transform to apply on modified coordinates.
        `numTrailingOrdinates` - number of trailing ordinates to pass through.
      Returns:
        a pass-through transform, not necessarily a `PassThroughTransform` instance.

    - #### 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:
        `getSourceDimensions` in interface `MathTransform`
      Specified by:
        `getSourceDimensions` in class `AbstractMathTransform`
      Returns:
        the dimension of input points.
      See Also:
        `DefaultOperationMethod​.getSourceDimensions()`

    - #### 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:
        `getTargetDimensions` in interface `MathTransform`
      Specified by:
        `getTargetDimensions` in class `AbstractMathTransform`
      Returns:
        the dimension of output points.
      See Also:
        `DefaultOperationMethod​.getTargetDimensions()`

    - #### 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 `modifiedCoordinates` array. Instead, SIS uses the `firstAffectedOrdinate` and `numTrailingOrdinates` 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 `modifiedCoordinates` array in a future SIS version.
      Returns:
        Zero-based indices of the modified source coordinates.
      See Also:
        `DefaultPassThroughOperation​.getModifiedCoordinates()`

    - #### 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:
        `DefaultPassThroughOperation​.getOperation()`

    - #### isIdentity

          public boolean isIdentity()

      Tests whether this transform does not move any points. A `PassThroughTransform` is identity if the sub-transform is also identity.
      Specified by:
        `isIdentity` in interface `MathTransform`
      Overrides:
        `isIdentity` in class `AbstractMathTransform`
      Returns:

    - #### transform

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

      Transforms a single coordinate in a list of ordinal values, and opportunistically computes the transform derivative if requested.
      Specified by:
        `transform` in class `AbstractMathTransform`
      Parameters:
        `srcPts` - the array containing the source coordinate (can not be `null`).
        `srcOff` - the offset to the point to be transformed in the source array.
        `dstPts` - the array into which the transformed coordinate is returned. May be the same than `srcPts`. May be `null` if only the derivative matrix is desired.
        `dstOff` - 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:
        `TransformException` - if the sub-transform failed.
      See Also:
        `AbstractMathTransform​.derivative(DirectPosition)`, `AbstractMathTransform​.transform(DirectPosition, DirectPosition)`, `MathTransforms​.derivativeAndTransform(MathTransform, double[], int, double[], int)`

    - #### 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 `MathTransform`
      Overrides:
        `transform` in class `AbstractMathTransform`
      Parameters:
        `srcPts` - the array containing the source point coordinates.
        `srcOff` - the offset to the first point to be transformed in the source array.
        `dstPts` - the array into which the transformed point coordinates are returned. May be the same than `srcPts`.
        `dstOff` - the offset to the location of the first transformed point that is stored in the destination array.
        `numPts` - the number of point objects to be transformed.
      Throws:
        `TransformException` - 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 `MathTransform`
      Overrides:
        `transform` in class `AbstractMathTransform`
      Parameters:
        `srcPts` - the array containing the source point coordinates.
        `srcOff` - the offset to the first point to be transformed in the source array.
        `dstPts` - the array into which the transformed point coordinates are returned. May be the same than `srcPts`.
        `dstOff` - the offset to the location of the first transformed point that is stored in the destination array.
        `numPts` - the number of point objects to be transformed.
      Throws:
        `TransformException` - 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 `MathTransform`
      Overrides:
        `transform` in class `AbstractMathTransform`
      Parameters:
        `srcPts` - the array containing the source point coordinates.
        `srcOff` - the offset to the first point to be transformed in the source array.
        `dstPts` - the array into which the transformed point coordinates are returned.
        `dstOff` - the offset to the location of the first transformed point that is stored in the destination array.
        `numPts` - the number of point objects to be transformed.
      Throws:
        `TransformException` - 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 `MathTransform`
      Overrides:
        `transform` in class `AbstractMathTransform`
      Parameters:
        `srcPts` - the array containing the source point coordinates.
        `srcOff` - the offset to the first point to be transformed in the source array.
        `dstPts` - the array into which the transformed point coordinates are returned.
        `dstOff` - the offset to the location of the first transformed point that is stored in the destination array.
        `numPts` - the number of point objects to be transformed.
      Throws:
        `TransformException` - 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 `MathTransform`
      Overrides:
        `derivative` in class `AbstractMathTransform`
      Parameters:
        `point` - the coordinate point where to evaluate the derivative.
      Returns:
        the derivative at the specified point (never `null`).
      Throws:
        `TransformException` - if the sub-transform failed.

    - #### inverse

          public MathTransform inverse()
                                throws NoninvertibleTransformException

      Creates the inverse transform of this object.
      Specified by:
        `inverse` in interface `MathTransform`
      Overrides:
        `inverse` in class `AbstractMathTransform`
      Returns:
      Throws:
        `NoninvertibleTransformException` - if the sub-transform is not invertible.

    - #### computeHashCode

          protected int computeHashCode()

      Computes a hash value for this transform. This method is invoked by `AbstractMathTransform​.hashCode()` when first needed.
      Overrides:
        `computeHashCode` in class `AbstractMathTransform`
      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 `LenientComparable`
      Overrides:
        `equals` in class `AbstractMathTransform`
      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​.deepEquals(Object, Object, ComparisonMode)`

    - #### formatTo

          protected String formatTo(Formatter formatter)

      Formats this transform as a Well Known Text version 1 (WKT 1) element.
      Compatibility note: `PassThrough_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 `PassThroughTransform` can not be formatted as valid WKT 1 neither).
      Overrides:
        `formatTo` in class `AbstractMathTransform`
      Parameters:
        `formatter` - the formatter to use.
      Returns:
        the WKT element name, which is `"PassThrough_MT"`.
      See Also:
        `FormattableObject​.toWKT()`, `FormattableObject​.toString()`

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.