Class SpecializableTransform

All Implemented Interfaces:
Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform
Direct Known Subclasses:
SpecializableTransform2D

class SpecializableTransform extends AbstractMathTransform implements Serializable
A transform having sub-areas where more accurate transforms can be used. The global transform must be a reasonable approximation of the specialized transforms. The lower and upper values of given envelopes are inclusive.
Since:
1.0
Version:
1.2
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    (package private) static class 
    The inverse of SpecializableTransform.
    private static final class 
    The region where a transform is valid, together with the transform.
    private static interface 
    Call of a MathTransform.transform(…) method with source and target arrays fixed at TransformCall creation time.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final RTreeNode
    Domains where specialized transforms are valid.
    private final org.opengis.referencing.operation.MathTransform
    The global transform to use if there is no suitable specialization.
    private org.opengis.referencing.operation.MathTransform
    The inverse of this transform, computed when first needed.
    private static final long
    For cross-version compatibility.

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

    MAXIMUM_BUFFER_SIZE, MAXIMUM_FAILURES
  • Constructor Summary

    Constructors
    Constructor
    Description
    SpecializableTransform(org.opengis.referencing.operation.MathTransform global, Map<org.opengis.geometry.Envelope,org.opengis.referencing.operation.MathTransform> specializations)
    Creates a new transform with the given global transform and some amount of specializations.
  • Method Summary

    Modifier and Type
    Method
    Description
    protected final int
    Computes a hash value for this transform.
    Invoked at construction time for creating the inverse transform.
    final org.opengis.referencing.operation.Matrix
    derivative(org.opengis.geometry.DirectPosition point)
    Gets the derivative of this transform at a point.
    final boolean
    equals(Object object, ComparisonMode mode)
    Compares the specified object with this math transform for equality.
    private org.opengis.referencing.operation.MathTransform
    forDomain(org.opengis.geometry.DirectPosition pos)
    Returns the transform to use for the given position, or global if none.
    protected final String
    formatTo(Formatter formatter)
    Formats the inner part of a Well Known Text version 1 (WKT 1) element.
    final int
    Gets the dimension of input points.
    (package private) final org.opengis.referencing.operation.MathTransform
    If this transform has no children, then returns the transform that we should use instead.
    final int
    Gets the dimension of output points.
    org.opengis.referencing.operation.MathTransform
    Returns the inverse of this transform.
    locate(org.opengis.geometry.DirectPosition pos)
    Returns the node that contains the given position, or null if none.
    Returns the SpecializableTransform.SubArea instances at the root of this class.
    final org.opengis.referencing.operation.Matrix
    transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate)
    Transforms a single coordinate tuple in an array, and optionally computes the transform derivative at that location.
    final void
    transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate tuples.
    final void
    transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate tuples.
    final void
    transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate tuples.
    final void
    transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
    Transforms a list of coordinate tuples.
    private void
    transform(SpecializableTransform.TransformCall transform, DirectPositionView src, int dstOff, int srcInc, int dstInc, int numPts)
    Transforms a list of coordinate tuples.
    final org.opengis.geometry.DirectPosition
    transform(org.opengis.geometry.DirectPosition ptSrc, org.opengis.geometry.DirectPosition ptDst)
    Transforms the specified ptSrc and stores the result in ptDst.

    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
      For cross-version compatibility.
      See Also:
    • global

      private final org.opengis.referencing.operation.MathTransform global
      The global transform to use if there is no suitable specialization.
    • domains

      private final RTreeNode domains
      Domains where specialized transforms are valid. This is the root of an R-Tree. May be null if there is no R-Tree, in which case global should be used instead.
    • inverse

      private org.opengis.referencing.operation.MathTransform inverse
      The inverse of this transform, computed when first needed. This object is included in serialization for avoiding rounding error issues.
      See Also:
  • Constructor Details

    • SpecializableTransform

      SpecializableTransform(org.opengis.referencing.operation.MathTransform global, Map<org.opengis.geometry.Envelope,org.opengis.referencing.operation.MathTransform> specializations)
      Creates a new transform with the given global transform and some amount of specializations.
      Parameters:
      global - the transform to use globally where there is no suitable specialization.
      specializations - more accurate transforms available in sub-areas.
  • Method Details

    • roots

      Returns the SpecializableTransform.SubArea instances at the root of this class. This is the domains node, unless that node is a synthetic node created by RTreeNode when it needs to contain more than one children.
    • getSubstitute

      final org.opengis.referencing.operation.MathTransform getSubstitute()
      If this transform has no children, then returns the transform that we should use instead. Otherwise returns null.
    • getSourceDimensions

      public final int getSourceDimensions()
      Gets the dimension of input points.
      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.
      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:
    • locate

      private SpecializableTransform.SubArea locate(org.opengis.geometry.DirectPosition pos)
      Returns the node that contains the given position, or null if none. This method searches from the root of the tree. It should be invoked only when we do not know what was the last search result.
    • forDomain

      private org.opengis.referencing.operation.MathTransform forDomain(org.opengis.geometry.DirectPosition pos)
      Returns the transform to use for the given position, or global if none.
    • transform

      public final org.opengis.geometry.DirectPosition transform(org.opengis.geometry.DirectPosition ptSrc, org.opengis.geometry.DirectPosition ptDst) throws org.opengis.referencing.operation.TransformException
      Transforms the specified ptSrc and stores the result in ptDst. This method delegates to the most specialized transform.
      Specified by:
      transform in interface org.opengis.referencing.operation.MathTransform
      Overrides:
      transform in class AbstractMathTransform
      Parameters:
      ptSrc - the coordinate tuple to be transformed.
      ptDst - the coordinate tuple that stores the result of transforming ptSrc, or null.
      Returns:
      the coordinate tuple after transforming ptSrc and storing the result in ptDst, or a newly created point if ptDst was null.
      Throws:
      org.opengis.referencing.operation.TransformException - if the point cannot be transformed.
    • derivative

      public final 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. This method delegates to the most specialized transform.
      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 derivative cannot be evaluated at the specified point.
    • transform

      public final 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 coordinate tuple in an array, and optionally computes the transform derivative at that location. This method delegates to the most specialized transform.
      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 point cannot be transformed or if a problem occurred while calculating the derivative.
      See Also:
    • transform

      private void transform(SpecializableTransform.TransformCall transform, DirectPositionView src, int dstOff, int srcInc, int dstInc, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms a list of coordinate tuples. This method delegates to the most specialized transform, with single transform(…) calls for coordinate sequences as long as possible.
      Parameters:
      transform - caller for a MathTransform.transform(…) method.
      src - a window over the source points. May be backed by a float[] or double[] array.
      dstOff - where to write the first coordinate in the target array.
      srcInc - the source dimension, negative if we must iterate backward.
      dstInc - the target dimension, negative if we must iterate backward.
      numPts - number of points to transform.
      Throws:
      org.opengis.referencing.operation.TransformException
    • transform

      public final void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms a list of coordinate tuples. This method delegates to the most specialized transform.
      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 a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to this.
    • transform

      public final void transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms a list of coordinate tuples. This method delegates to the most specialized transform.
      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 a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the un-transformable points with Float.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to this.
    • transform

      public final void transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms a list of coordinate tuples. This method delegates to the most specialized transform, with single transform(…) calls for coordinate sequences as long as possible.
      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 a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with Float.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to this.
    • transform

      public final void transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Transforms a list of coordinate tuples. This method delegates to the most specialized transform, with single transform(…) calls for coordinate sequences as long as possible.
      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 a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to this.
    • computeHashCode

      protected final 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 final 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 final String formatTo(Formatter formatter)
      Formats the inner part of a Well Known Text version 1 (WKT 1) element.
      Compatibility note: The SPECIALIZABLE_MT element formatted here is an Apache SIS-specific extension.
      Overrides:
      formatTo in class AbstractMathTransform
      Parameters:
      formatter - the formatter to use.
      Returns:
      the WKT element name, which is "Specializable_MT".
      See Also:
    • inverse

      public org.opengis.referencing.operation.MathTransform inverse() throws org.opengis.referencing.operation.NoninvertibleTransformException
      Returns the inverse of this transform.
      Specified by:
      inverse in interface org.opengis.referencing.operation.MathTransform
      Overrides:
      inverse in class AbstractMathTransform
      Throws:
      org.opengis.referencing.operation.NoninvertibleTransformException
    • createInverse

      SpecializableTransform.Inverse createInverse() throws org.opengis.referencing.operation.NoninvertibleTransformException
      Invoked at construction time for creating the inverse transform. Overridden by SpecializableTransform2D for the two-dimensional variant.
      Throws:
      org.opengis.referencing.operation.NoninvertibleTransformException