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

Class PassThroughTransform

java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.referencing.operation.transform.AbstractMathTransform
org.apache.sis.referencing.operation.transform.PassThroughTransform
All Implemented Interfaces:
Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform
Direct Known Subclasses:
PassThroughTransform2D
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:

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
Version:
1.0
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform

    AbstractMathTransform.Inverse

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final int
    firstAffectedCoordinate
    Index of the first affected coordinate.
    (package private) PassThroughTransform
    inverse
    The inverse transform.
    (package private) final int
    numTrailingCoordinates
    Number of unaffected coordinates after the affected ones.
    private static final long
    serialVersionUID
    Serial number for inter-operability with different versions.
    (package private) final org.opengis.referencing.operation.MathTransform
    subTransform
    The sub-transform to apply on the modified coordinates.

    Fields inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform

    MAXIMUM_BUFFER_SIZE, MAXIMUM_FAILURES

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    PassThroughTransform(int firstAffectedCoordinate, org.opengis.referencing.operation.MathTransform subTransform, int numTrailingCoordinates)
    Constructor for sub-classes.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected int
    computeHashCode()
    Computes a hash value for this transform.
    (package private) static org.opengis.referencing.operation.MathTransform
    create(int firstAffectedCoordinate, org.opengis.referencing.operation.MathTransform subTransform, int numTrailingCoordinates)
    Creates a transform which passes through a subset of coordinates to another transform.
    org.opengis.referencing.operation.Matrix
    derivative(org.opengis.geometry.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.
    private static org.opengis.referencing.operation.Matrix
    expand(MatrixSIS subMatrix, int firstAffectedCoordinate, int numTrailingCoordinates, int affine)
    Creates a pass-through transform from a matrix.
    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 org.opengis.referencing.operation.MathTransform
    getSubTransform()
    Returns the sub-transform to apply on the modified coordinates.
    final int
    getTargetDimensions()
    Gets the dimension of output points.
    org.opengis.referencing.operation.MathTransform
    inverse()
    Creates the inverse transform of this object.
    boolean
    isIdentity()
    Tests whether this transform does not move any points.
    private static long
    maskLowBits(int n)
    Returns a mask for the n lowest bits.
    private static Object
    newArray(Object array, int length)
    Creates a new array of the same kind than the given array.
    private static PassThroughTransform
    newInstance(int firstAffectedCoordinate, org.opengis.referencing.operation.MathTransform subTransform, int numTrailingCoordinates)
    Constructs the general PassThroughTransform object.
    private static LinearTransform
    newInstance(int firstAffectedCoordinate, org.opengis.referencing.operation.Matrix subTransform, int numTrailingCoordinates)
    Special case for transformation backed by a matrix.
    private org.opengis.referencing.operation.Matrix
    toSubMatrix(boolean applyOtherFirst, org.opengis.referencing.operation.Matrix matrix)
    If the given matrix to be concatenated to this transform, can be concatenated to the sub-transform instead, returns the matrix to be concatenated to the sub-transform.
    org.opengis.referencing.operation.Matrix
    transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate)
    Transforms a single position in a list of coordinate values, 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 list of coordinate values.
    void
    transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
    Transforms many positions in a list of coordinate values.
    void
    transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
    Transforms many positions in a list of coordinate values.
    void
    transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
    Transforms many positions in a list of coordinate values.
    private void
    transformOverlapping(Object srcPts, int srcOff, Object dstPts, int dstOff, int numPts)
    Transforms an array of points with potentially overlapping source and target.
    protected org.opengis.referencing.operation.MathTransform
    tryConcatenate(boolean applyOtherFirst, org.opengis.referencing.operation.MathTransform other, org.opengis.referencing.operation.MathTransformFactory factory)
    Concatenates or pre-concatenates in an optimized way this transform with the given transform, if possible.

    Methods inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform

    beforeFormat, equals, getContextualParameters, getDomain, getParameterDescriptors, getParameterValues, hashCode, isInverseEquals, mismatchedDimension, transform

    Methods inherited from class org.apache.sis.io.wkt.FormattableObject

    print, toString, toString, toWKT

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.opengis.referencing.operation.MathTransform

    toWKT

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:

    • firstAffectedCoordinate

      final int firstAffectedCoordinate
      Index of the first affected coordinate.
      See Also:

    • numTrailingCoordinates

      final int numTrailingCoordinates
      Number of unaffected coordinates after the affected ones.
      See Also:

    • subTransform

      final org.opengis.referencing.operation.MathTransform subTransform
      The sub-transform to apply on the modified coordinates. This is often the sub-transform specified at construction time, but not necessarily.

    • inverse

      PassThroughTransform inverse
      The inverse transform. This field will be computed only when needed, but is part of serialization in order to avoid rounding error.

  • Constructor Details

    • PassThroughTransform

      protected PassThroughTransform(int firstAffectedCoordinate, org.opengis.referencing.operation.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:

  • Method Details

    • create

      static org.opengis.referencing.operation.MathTransform create(int firstAffectedCoordinate, org.opengis.referencing.operation.MathTransform subTransform, int numTrailingCoordinates)
      Creates a transform which passes through a subset of coordinates to another transform. This method returns a transform having the following dimensions: Affected coordinates will range from firstAffectedCoordinate inclusive to dimTarget - numTrailingCoordinates exclusive.
      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.
      Returns:
      a pass-through transform, not necessarily a PassThroughTransform instance.

    • newInstance

      private static LinearTransform newInstance(int firstAffectedCoordinate, org.opengis.referencing.operation.Matrix subTransform, int numTrailingCoordinates)
      Special case for transformation backed by a matrix. Is is possible to use a new matrix for such transform, instead of wrapping the sub-transform into a PassThroughTransform object. It is faster and easier to concatenate.

    • newInstance

      private static PassThroughTransform newInstance(int firstAffectedCoordinate, org.opengis.referencing.operation.MathTransform subTransform, int numTrailingCoordinates)
      Constructs the general PassThroughTransform object. An optimization is done right in the constructor for the case where the sub-transform is already a PassThroughTransform. It is caller's responsibility to ensure that the argument values are valid.

    • 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 org.opengis.referencing.operation.MathTransform
      Specified by:
      getSourceDimensions in class AbstractMathTransform
      Returns:
      the number of dimensions of input points.
      See Also:

    • 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 org.opengis.referencing.operation.MathTransform
      Specified by:
      getTargetDimensions in class AbstractMathTransform
      Returns:
      the number of dimensions of output points.
      See Also:

    • 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 firstAffectedCoordinate and numTrailingCoordinates 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:

    • getSubTransform

      public final org.opengis.referencing.operation.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:

    • 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 org.opengis.referencing.operation.MathTransform
      Overrides:
      isIdentity in class AbstractMathTransform
      Returns:

    • transform

      public org.opengis.referencing.operation.Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws org.opengis.referencing.operation.TransformException
      Transforms a single position in a list of coordinate values, 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 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:
      org.opengis.referencing.operation.TransformException - if the sub-transform failed.
      See Also:

    • newArray

      private static Object newArray(Object array, int length)
      Creates a new array of the same kind than the given array. This is used for creating float[] or double[] arrays.

    • transformOverlapping

      private void transformOverlapping(Object srcPts, int srcOff, Object dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms an array of points with potentially overlapping source and target.
      Parameters:
      srcPts - the point to transform, as a float[] or double[] array.
      srcOff - the offset to the point to be transformed in the array.
      dstPts - where to store the transformed points, as an array of same type than srcPts.
      dstOff - the offset to the location of the transformed point that is stored in the destination array.
      numPts - number of points to transform.
      Throws:
      org.opengis.referencing.operation.TransformException

    • transform

      public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms many positions in a list of coordinate values.
      Specified by:
      transform in interface org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if the sub-transform failed.

    • transform

      public void transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms many positions in a list of coordinate values.
      Specified by:
      transform in interface org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if the sub-transform failed.

    • transform

      public void transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms many positions in a list of coordinate values.
      Specified by:
      transform in interface org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if the sub-transform failed.

    • transform

      public void transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms many positions in a list of coordinate values.
      Specified by:
      transform in interface org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if the sub-transform failed.

    • derivative

      public org.opengis.referencing.operation.Matrix derivative(org.opengis.geometry.DirectPosition point) throws org.opengis.referencing.operation.TransformException
      Gets the derivative of this transform at a point.
      Specified by:
      derivative in interface org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if the sub-transform failed.

    • expand

      private static org.opengis.referencing.operation.Matrix expand(MatrixSIS subMatrix, int firstAffectedCoordinate, int numTrailingCoordinates, int affine)
      Creates a pass-through transform from a matrix. This method is invoked when the sub-transform can be expressed as a matrix. It is also invoked for computing the matrix returned by derivative(org.opengis.geometry.DirectPosition).
      Parameters:
      subMatrix - the sub-transform as a matrix.
      firstAffectedCoordinate - index of the first affected coordinate.
      numTrailingCoordinates - number of trailing coordinates to pass through.
      affine - 0 if the matrix do not contains translation terms, or 1 if the matrix is an affine transform with translation terms.

    • inverse

      public org.opengis.referencing.operation.MathTransform inverse() throws org.opengis.referencing.operation.NoninvertibleTransformException
      Creates the inverse transform of this object.
      Specified by:
      inverse in interface org.opengis.referencing.operation.MathTransform
      Overrides:
      inverse in class AbstractMathTransform
      Returns:
      Throws:
      org.opengis.referencing.operation.NoninvertibleTransformException - if the sub-transform is not invertible.

    • toSubMatrix

      private org.opengis.referencing.operation.Matrix toSubMatrix(boolean applyOtherFirst, org.opengis.referencing.operation.Matrix matrix)
      If the given matrix to be concatenated to this transform, can be concatenated to the sub-transform instead, returns the matrix to be concatenated to the sub-transform. Otherwise returns null.

      This method does not verify if the matrix size is compatible with this transform dimension.

      Parameters:
      applyOtherFirst - true if the transformation order is matrix followed by this, or false if the transformation order is this followed by matrix.

    • tryConcatenate

      protected org.opengis.referencing.operation.MathTransform tryConcatenate(boolean applyOtherFirst, org.opengis.referencing.operation.MathTransform other, org.opengis.referencing.operation.MathTransformFactory factory) throws org.opengis.util.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 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:
      applyOtherFirst - 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:
      org.opengis.util.FactoryException - if an error occurred while combining the transforms.
      Since:
      1.0
      See Also:

    • maskLowBits

      private static long maskLowBits(int n)
      Returns a mask for the n lowest bits. This is a convenience method for a frequently used operation in tryConcatenate(boolean, MathTransform, MathTransformFactory).

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

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