# Class PassThroughTransform

Object
FormattableObject
AbstractMathTransform
PassThroughTransform

All Implemented Interfaces:
  `Serializable`, `Parameterized`, `LenientComparable`, `Printable`, `MathTransform`

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, `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 = MathTransforms.passThrough(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​.passThrough(int, MathTransform, int)`
  - `MathTransforms​.compound(MathTransform...)`
  - Serialized Form

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class AbstractMathTransform

  `AbstractMathTransform​.Inverse`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `PassThroughTransform(int firstAffectedCoordinate, MathTransform subTransform, int numTrailingCoordinates)`
  Constructor for sub-classes.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static MathTransform`
  `create(BitSet modifiedCoordinates, MathTransform subTransform, int resultDim, MathTransformFactory factory)`
  Creates a transform which passes through a subset of coordinates to another transform.
  `Matrix`
  `derivative(DirectPosition point)`
  Gets the derivative of this transform at a point.
  `protected String`
  `formatTo(Formatter formatter)`
  Formats this transform as a Well Known Text version 1 (WKT 1) element.
  `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.
  `final int`
  `getSourceDimensions()`
  Gets the dimension of input points.
  `final MathTransform`
  `getSubTransform()`
  Returns the sub-transform to apply on the modified coordinates.
  `final 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 position in a sequence of coordinate tuples, and opportunistically computes the transform derivative if requested.
  `void`
  `transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)`
  Transforms many positions in a sequence of coordinate tuples.
  `void`
  `transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)`
  Transforms many positions in a sequence of coordinate tuples.
  `void`
  `transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)`
  Transforms many positions in a sequence of coordinate tuples.
  `void`
  `transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)`
  Transforms many positions in a sequence of coordinate tuples.
  `protected void`
  `tryConcatenate(TransformJoiner context)`
  Concatenates or pre-concatenates in an optimized way this transform with a neighbor, if possible.

  ### Methods inherited from class AbstractMathTransform

  `equals, getContextualParameters, getDomain, 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 Details

  - ### PassThroughTransform

    protected PassThroughTransform(int firstAffectedCoordinate, MathTransform subTransform, int numTrailingCoordinates)
    Constructor for sub-classes. Users should invoke the static `MathTransforms​.passThrough(int, MathTransform, int)` factory method instead, since the most optimal pass-through transform for the given `subTransform` is not necessarily a `PassThroughTransform` instance.
    Parameters:
      `firstAffectedCoordinate` - index of the first affected coordinate.
      `subTransform` - the sub-transform to apply on modified coordinates.
      `numTrailingCoordinates` - number of trailing coordinates to pass through.
    See Also:
      - `MathTransforms​.passThrough(int, MathTransform, 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 `BitSet` 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 `subTransform`.

    #### 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:
      `modifiedCoordinates` - positions in a source coordinate tuple of the coordinates affected by the transform.
      `subTransform` - the sub-transform to apply on modified coordinates.
      `resultDim` - 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:
      `MismatchedDimensionException` - if the `modifiedCoordinates` bitset cardinality is not equal to the number of source dimensions in `subTransform`.
      `IllegalArgumentException` - if the index of a modified coordinates is out of bounds.
      `FactoryException` - if an error occurred while creating a transform step.
    Since:
      1.4
    See Also:
      - `MathTransforms​.passThrough(int[], MathTransform, 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:
      `getSourceDimensions` in interface `MathTransform`
    Specified by:
      `getSourceDimensions` in class `AbstractMathTransform`
    Returns:
      the number of dimensions 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 number of dimensions 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.
    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:
      `true` if this `MathTransform` is an identity transform; `false` otherwise.

  - ### transform

    public Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws TransformException
    Transforms a single position in a sequence of coordinate tuples, and opportunistically computes the transform derivative if requested.
    Specified by:
      `transform` in class `AbstractMathTransform`
    Parameters:
      `srcPts` - the array containing the source coordinates (cannot be `null`).
      `srcOff` - the offset to the point to be transformed in the source array.
      `dstPts` - the array into which the transformed coordinates is returned. May be the same as `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 positions in a sequence of coordinate tuples.
    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 as `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 positions in a sequence of coordinate tuples.
    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 as `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 positions in a sequence of coordinate tuples.
    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 positions in a sequence of coordinate tuples.
    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 tuple 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:
      The inverse transform.
    Throws:
      `NoninvertibleTransformException` - if the sub-transform is not invertible.

  - ### tryConcatenate

    protected void tryConcatenate(TransformJoiner context) throws FactoryException
    Concatenates or pre-concatenates in an optimized way this transform with a neighbor, if possible. This method applies the following special cases:
    - If the other transform is also a `PassThroughTransform`, then the two transforms may be merged in a single `PassThroughTransform` instance.
    - If the other transform discards some dimensions, verify if we still need a `PassThroughTransform`.
    Overrides:
      `tryConcatenate` in class `AbstractMathTransform`
    Parameters:
      `context` - information about the neighbor transforms, and the object where to set the result.
    Throws:
      `FactoryException` - if an error occurred while combining the transforms.
    Since:
      1.5
    See Also:
      - `DefaultMathTransformFactory​.createConcatenatedTransform(MathTransform, MathTransform)`

  - ### 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` cannot 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:
      - `DefaultMathTransformFactory​.createFromWKT(String)`