Package org.apache.sis.internal.referencing

Class PositionTransformer

java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.geometry.AbstractDirectPosition
org.apache.sis.geometry.GeneralDirectPosition
org.apache.sis.internal.referencing.PositionTransformer
All Implemented Interfaces:
Serializable, Cloneable, org.opengis.geometry.coordinate.Position, org.opengis.geometry.DirectPosition
public final class PositionTransformer extends GeneralDirectPosition
A direct position capable to transform another position from its arbitrary CRS to the CRS of this position. This class caches the last transform used in order to improve performance when source and target CRS do not change often. Using this class is faster than invoking CoordinateOperationFactory.createOperation(lastCRS, targetCRS) for every points.
  • Note 1: This class is advantageous on a performance point of view only if the same instance of PositionTransformer is used for transforming many points between arbitrary CRS and this position CRS.
  • Note 2: This convenience class is useful when the source and target CRS are not likely to change often. If you are sure that the source and target CRS will not change at all for a given set of positions, then using CoordinateOperation directly gives better performances. This is because this class checks if the CRS changed before every transformations, which may be costly.
This class should not appear in a public API. It is used as a helper private field in more complex classes. For example, suppose that MyClass needs to perform its internal working in some particular CRS, but we want robust API accepting whatever CRS the client uses. MyClass can be written as below: This class is not thread-safe.
Since:
1.0
Version:
1.0
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final org.opengis.referencing.crs.CoordinateReferenceSystem
    defaultCRS
    The default CRS to assume when transform(DirectPosition) has been invoked without associated CRS.
    private final org.opengis.referencing.operation.CoordinateOperationFactory
    factory
    The factory to use for creating new coordinate operation.
    private org.opengis.referencing.operation.MathTransform
    forward
    The forward and inverse transforms.
    private org.opengis.referencing.operation.MathTransform
    inverse
    The forward and inverse transforms.
    private org.opengis.referencing.crs.CoordinateReferenceSystem
    lastCRS
    The last CRS of a position given to transform(DirectPosition), or null.

    Fields inherited from class org.apache.sis.geometry.GeneralDirectPosition

    coordinates

  • Constructor Summary

    Constructors
    Constructor
    Description
    PositionTransformer(org.opengis.referencing.crs.CoordinateReferenceSystem defaultCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.CoordinateOperationFactory factory)
    Creates a new position which will contain the result of coordinate transformations to the given CRS.

  • Method Summary

    Modifier and Type
    Method
    Description
    private org.opengis.referencing.operation.MathTransform
    inverse()
    Returns the inverse transform, computed when first needed.
    org.opengis.geometry.DirectPosition
    inverseTransform()
    Returns a new point with the same coordinates than this one, but transformed to the default CRS.
    org.opengis.referencing.operation.Matrix
    inverseTransform(double[] target)
    Transforms this point to the default CRS and stores the result in the given array, and returns the derivative.
    void
    setCoordinateReferenceSystem(org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS)
    Sets the coordinate reference system in which the coordinate is given.
    private void
    setSourceCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Sets the lastCRS field and creates the associated forward transform.
    void
    transform(double[] point)
    Transforms the given position from the CRS of this position to the default CRS.
    org.opengis.geometry.DirectPosition
    transform(org.opengis.geometry.DirectPosition position)
    Transforms a given position from its CRS to the CRS of this PositionTransformer.

    Methods inherited from class org.apache.sis.geometry.GeneralDirectPosition

    clone, equals, getCoordinate, getCoordinateReferenceSystem, getDimension, getOrdinate, hashCode, setCoordinate, setLocation, setOrdinate, toString

    Methods inherited from class org.apache.sis.geometry.AbstractDirectPosition

    castOrCopy, formatTo, getDirectPosition, normalize

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

    print, toString, toWKT

    Methods inherited from class java.lang.Object

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

  • Field Details

    • factory

      private final org.opengis.referencing.operation.CoordinateOperationFactory factory
      The factory to use for creating new coordinate operation.

    • defaultCRS

      public final org.opengis.referencing.crs.CoordinateReferenceSystem defaultCRS
      The default CRS to assume when transform(DirectPosition) has been invoked without associated CRS. This is often the same than the target CRS, but not necessarily.

    • lastCRS

      private transient org.opengis.referencing.crs.CoordinateReferenceSystem lastCRS
      The last CRS of a position given to transform(DirectPosition), or null. This is used as the source CRS of the coordinate operation. The targetCRS will be the CRS associated with this position.
      See Also:

    • forward

      private transient org.opengis.referencing.operation.MathTransform forward
      The forward and inverse transforms. Will be created only when first needed. Those fields are left to null value if the transform is identity.
      See Also:

    • inverse

      private transient org.opengis.referencing.operation.MathTransform inverse
      The forward and inverse transforms. Will be created only when first needed. Those fields are left to null value if the transform is identity.
      See Also:

  • Constructor Details

    • PositionTransformer

      public PositionTransformer(org.opengis.referencing.crs.CoordinateReferenceSystem defaultCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.CoordinateOperationFactory factory)
      Creates a new position which will contain the result of coordinate transformations to the given CRS. The CRS associated with this position will be initially set to targetCRS.
      Parameters:
      defaultCRS - the CRS to take as the source when transform(position) is invoked with a position without associated CRS. If null, default to targetCRS.
      targetCRS - the CRS associated with this position. Will be the target of coordinate transformations until the next call to setCoordinateReferenceSystem(…) or setLocation. Cannot be null.
      factory - the factory to use for creating coordinate operations, or null for the default.

  • Method Details

    • setCoordinateReferenceSystem

      public void setCoordinateReferenceSystem(org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS) throws org.opengis.geometry.MismatchedDimensionException
      Sets the coordinate reference system in which the coordinate is given. The given CRS will be used as:
      Overrides:
      setCoordinateReferenceSystem in class GeneralDirectPosition
      Parameters:
      targetCRS - the new CRS for this direct position.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the specified CRS does not have the expected number of dimensions.

    • setSourceCRS

      private void setSourceCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs) throws org.opengis.referencing.operation.TransformException
      Sets the lastCRS field and creates the associated forward transform. This method does not create yet the inverse transform, since it may not be needed.
      Throws:
      org.opengis.referencing.operation.TransformException

    • transform

      public void transform(double[] point) throws org.opengis.referencing.operation.TransformException
      Transforms the given position from the CRS of this position to the default CRS. The result is stored in the given array.
      Parameters:
      point - the coordinates of the point to transform in-place.
      Throws:
      org.opengis.referencing.operation.TransformException - if a coordinate transformation was required and failed.

    • transform

      public org.opengis.geometry.DirectPosition transform(org.opengis.geometry.DirectPosition position) throws org.opengis.referencing.operation.TransformException
      Transforms a given position from its CRS to the CRS of this PositionTransformer. If the CRS associated to the given position is null, then that CRS is assumed to be the default CRS specified at construction time. Otherwise if that CRS is not equal to the CRS associated with this position, then a coordinates transformations are applied. The result may be stored in this instance.
      Parameters:
      position - a position using an arbitrary CRS, or null. This object will not be modified.
      Returns:
      the transformed position, either this or the given position (which may be null).
      Throws:
      org.opengis.referencing.operation.TransformException - if a coordinate transformation was required and failed.

    • inverse

      private org.opengis.referencing.operation.MathTransform inverse() throws org.opengis.referencing.operation.TransformException
      Returns the inverse transform, computed when first needed.
      Throws:
      org.opengis.referencing.operation.TransformException

    • inverseTransform

      public org.opengis.geometry.DirectPosition inverseTransform() throws org.opengis.referencing.operation.TransformException
      Returns a new point with the same coordinates than this one, but transformed to the default CRS. This method never returns this, so the returned point does not need to be cloned.
      Returns:
      the same position as this, but transformed to the default CRS.
      Throws:
      org.opengis.referencing.operation.TransformException - if a coordinate transformation was required and failed.

    • inverseTransform

      public org.opengis.referencing.operation.Matrix inverseTransform(double[] target) throws org.opengis.referencing.operation.TransformException
      Transforms this point to the default CRS and stores the result in the given array, and returns the derivative. The target array length should be ReferencingUtilities.getDimension(defaultCRS).
      Parameters:
      target - where to store the transformed coordinates.
      Returns:
      the derivative (Jacobian matrix) at the location of this point.
      Throws:
      org.opengis.referencing.operation.TransformException - if a coordinate transformation was required and failed.