Package org.apache.sis.referencing.operation.builder

Class ProjectedTransformTry

java.lang.Object
org.apache.sis.referencing.operation.builder.ProjectedTransformTry
All Implemented Interfaces:
Comparable<ProjectedTransformTry>, Map.Entry<String,org.opengis.referencing.operation.MathTransform>
final class ProjectedTransformTry extends Object implements Comparable<ProjectedTransformTry>, Map.Entry<String,org.opengis.referencing.operation.MathTransform>
Information about an attempt to transform coordinates to some projection before to compute a linear approximation. This class contains only the projection to be attempted and a summary of the result. We do not keep new coordinates in order to avoid consuming too much memory when many attempts are made; LinearTransformBuilder needs only to keep the best attempt.

Purpose: localization grids in netCDF files contain (longitude, latitude) values for all pixels. LocalizationGridBuilder first computes a linear (affine) approximation of a localization grid, then stores the residuals. This approach works well when the residuals are small. However if the localization grid is non-linear, then the affine transform is a poor approximation of that grid and the residuals are high. High residuals make inverse transforms hard to compute, which sometimes cause a TransformException with "no convergence" error message.

In practice, localization grids in netCDF files are often used for storing the results of a map projection, e.g. Mercator. This class allows LocalizationGridBuilder to try to transform the grid using a given list of map projections and see if one of those projections results in a grid closer to an affine transform. In other words, we use this class for trying to guess what the projection may be. It is okay if the guess is not a perfect match; if the residuals become smalls enough, it will resolve the "no convergence" errors.

Note: compareTo(ProjectedTransformTry) is inconsistent with equals(Object). The fact that ProjectedTransformTry instances are comparable should not be visible in public API.

Since:
1.0
Version:
1.1

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int
    BUFFER_CAPACITY
    Number of points in the temporary buffer used for transforming data.
    (package private) float
    correlation
    A global correlation factor, stored for information purpose only.
    private org.opengis.referencing.operation.TransformException
    error
    If an error occurred during coordinate operations, the error.
    private final String
    name
    A name by witch this projection attempt is identified.
    (package private) final org.opengis.referencing.operation.MathTransform
    projection
    A conversion from a non-linear grid (typically with longitude and latitude values) to something that may be more linear (typically, but not necessarily, a map projection).
    private final int[]
    projToGrid
    Maps projection dimensions to LinearTransformBuilder target dimensions.
    (package private) final boolean
    reverseAfterLinearization
    Whether the inverse of projection shall be concatenated to the final interpolated transform.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ProjectedTransformTry(String name, org.opengis.referencing.operation.MathTransform projection, int[] projToGrid, int expectedDimension, boolean reverseAfterLinearization)
    Prepares a new attempt to project a localization grid.
    ProjectedTransformTry(ProjectedTransformTry other)
    Creates a new instance initialized to a copy of the given instance but without result.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(ProjectedTransformTry other)
    Orders by the inverse of correlation coefficients.
    boolean
    equals(Object obj)
    Implements the Map.Entry.equals(Object) contract.
    (package private) static org.opengis.referencing.operation.TransformException
    getError(List<ProjectedTransformTry> linearizers)
    Returns the first error in the given list of linearizers.
    String
    getKey()
    Returns the name by witch this projection attempt is identified.
    org.opengis.referencing.operation.MathTransform
    getValue()
    Returns the projection, taking in account axis swapping if projToGrid is not an arithmetic progression.
    int
    hashCode()
    Implements the Map.Entry.hashCode() contract.
    (package private) static void
    recycle(double[][] arrays, Queue<double[]> pool)
    Makes the given arrays available for reuse by other transforms.
    (package private) final double[][]
    replaceTransformed(double[][] targets, double[][] newValues)
    Replaces old target arrays by new values in the dimensions where a projection has been applied.
    (package private) final double[]
    replaceTransformed(double[] correlations, double[] newValues)
    Replaces old correlation values by new values in the dimensions where a projection has been applied.
    (package private) final MatrixSIS
    replaceTransformed(MatrixSIS transform, MatrixSIS newValues)
    Replaces old transform coefficients by new values in the dimensions where a projection has been applied.
    org.opengis.referencing.operation.MathTransform
    setValue(org.opengis.referencing.operation.MathTransform value)
    Do not allow modification of this entry.
    (package private) final NumberFormat
    summarize(TableAppender table, NumberFormat nf, Locale locale)
    Formats a summary of this projection attempt.
    String
    toString()
    Returns a string representation of this projection attempt for debugging purpose.
    (package private) final double[][]
    transform(double[][] coordinates, int numPoints, Queue<double[]> pool)
    Transforms target coordinates of a localization grid.
    private boolean
    useSameDimensions()
    Returns true if projToGrid[i] == i for all i.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • BUFFER_CAPACITY

      private static final int BUFFER_CAPACITY
      Number of points in the temporary buffer used for transforming data. The buffer length will be this capacity multiplied by the number of dimensions.
      See Also:

    • name

      private final String name
      A name by witch this projection attempt is identified.
      See Also:

    • projection

      final org.opengis.referencing.operation.MathTransform projection
      A conversion from a non-linear grid (typically with longitude and latitude values) to something that may be more linear (typically, but not necessarily, a map projection).
      See Also:

    • projToGrid

      private final int[] projToGrid
      Maps projection dimensions to LinearTransformBuilder target dimensions. For example if this array is {2,1}, then dimensions 0 and 1 of projection (both source and target dimensions) will map dimensions 2 and 1 of LinearTransformBuilder.targets. The length of this array shall be equal to the number of projection source dimensions.

    • reverseAfterLinearization

      final boolean reverseAfterLinearization
      Whether the inverse of projection shall be concatenated to the final interpolated transform. If true, the projection effect will be cancelled in the final result, i.e. the target coordinates will be approximately the same as if no projection were applied. In such case, the advantage of applying a projection is to improve numerical stability with a better linear approximation in the first step of the coordinate transformation process.

    • correlation

      float correlation
      A global correlation factor, stored for information purpose only.

    • error

      private org.opengis.referencing.operation.TransformException error
      If an error occurred during coordinate operations, the error. Otherwise null.
      See Also:

  • Constructor Details

    • ProjectedTransformTry

      ProjectedTransformTry(ProjectedTransformTry other)
      Creates a new instance initialized to a copy of the given instance but without result. This is used by copy constructors.
      See Also:

    • ProjectedTransformTry

      ProjectedTransformTry(String name, org.opengis.referencing.operation.MathTransform projection, int[] projToGrid, int expectedDimension, boolean reverseAfterLinearization)
      Prepares a new attempt to project a localization grid. All arguments are stored as-is (arrays are not cloned).
      Parameters:
      name - a name by witch this projection attempt is identified.
      projection - conversion from non-linear grid to something that may be more linear.
      projToGrid - maps projection dimensions to LinearTransformBuilder target dimensions.
      expectedDimension - number of LinearTransformBuilder target dimensions.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the projection does not have the expected number of dimensions.

  • Method Details

    • getKey

      public String getKey()
      Returns the name by witch this projection attempt is identified.
      Specified by:
      getKey in interface Map.Entry<String,org.opengis.referencing.operation.MathTransform>

    • getValue

      public org.opengis.referencing.operation.MathTransform getValue()
      Returns the projection, taking in account axis swapping if projToGrid is not an arithmetic progression.
      Specified by:
      getValue in interface Map.Entry<String,org.opengis.referencing.operation.MathTransform>

    • setValue

      public org.opengis.referencing.operation.MathTransform setValue(org.opengis.referencing.operation.MathTransform value)
      Do not allow modification of this entry.
      Specified by:
      setValue in interface Map.Entry<String,org.opengis.referencing.operation.MathTransform>

    • transform

      final double[][] transform(double[][] coordinates, int numPoints, Queue<double[]> pool)
      Transforms target coordinates of a localization grid. The coordinates argument is the value of LinearTransformBuilder.targets, without clone (this method will only read those arrays). Only arrays at indices given by projToGrid will be read; the other arrays will be ignored. The coordinate operation result will be stored in arrays of size [numDimensions][numPoints] where numDimensions is the length of the projToGrid array. Indices are as below, with 0 ≤ d ≤ numDimensions:
      1. results[d] contains the coordinates in dimension d.
      2. results[d][i] is a coordinate of the point at index i.
      The returned target shall be given to replaceTransformed(double[][], double[][]) before final storage in LinearTransformBuilder.

      Pool of arrays

      The pool queue is initially empty. Arrays created by this method and later discarded will be added to that queue, for recycling if this method is invoked again for another ProjectedTransformTry instance.
      Parameters:
      coordinates - the LinearTransformBuilder.targets arrays of coordinates to transform.
      numPoints - number of points to transform: numPoints ≤ coordinates[i].length.
      pool - pre-allocated arrays of length numPoints that can be recycled.
      Returns:
      results of coordinate operations (see method javadoc), or null if an error occurred.

    • recycle

      static void recycle(double[][] arrays, Queue<double[]> pool)
      Makes the given arrays available for reuse by other transforms.

    • useSameDimensions

      private boolean useSameDimensions()
      Returns true if projToGrid[i] == i for all i.

    • replaceTransformed

      final double[][] replaceTransformed(double[][] targets, double[][] newValues)
      Replaces old target arrays by new values in the dimensions where a projection has been applied. The targets array is copied if necessary, then values are replaced in the copied array. May return newValues directly if suitable.
      Parameters:
      targets - the original targets values. This array will not be modified.
      newValues - targets computed by transform(…) for the dimensions specified at construction time.
      Returns:
      a copy of the given targets array with new values overwriting the old values.

    • replaceTransformed

      final double[] replaceTransformed(double[] correlations, double[] newValues)
      Replaces old correlation values by new values in the dimensions where a projection has been applied. The correlations array is copied if necessary, then values are replaced in the copied array. May return newValues directly if suitable.
      Parameters:
      correlations - the original correlation values. This array will not be modified.
      newValues - correlations computed by LinearTransformBuilder for the dimensions specified at construction time.
      Returns:
      a copy of the given correlation array with new values overwriting the old values.

    • replaceTransformed

      final MatrixSIS replaceTransformed(MatrixSIS transform, MatrixSIS newValues)
      Replaces old transform coefficients by new values in the dimensions where a projection has been applied. The transform matrix is copied if necessary, then values are replaced in the copied matrix. May return newValues directly if suitable.
      Parameters:
      transform - the original affine transform. This matrix will not be modified.
      newValues - coefficients computed by LinearTransformBuilder for the dimensions specified at construction time.
      Returns:
      a copy of the given transform matrix with new coefficients overwriting the old values.

    • getError

      static org.opengis.referencing.operation.TransformException getError(List<ProjectedTransformTry> linearizers)
      Returns the first error in the given list of linearizers. Errors after the first one are added as suppressed exceptions. If no error are found, this method returns null.

    • compareTo

      public int compareTo(ProjectedTransformTry other)
      Orders by the inverse of correlation coefficients. Highest coefficients (best correlations) are first, lower coefficients are next, Float.NaN values are last.

      Note: this comparison is inconsistent with equals(Object). The fact that ProjectedTransformTry instances are comparable should not be visible in public API.

      Specified by:
      compareTo in interface Comparable<ProjectedTransformTry>

    • equals

      public boolean equals(Object obj)
      Implements the Map.Entry.equals(Object) contract.
      Specified by:
      equals in interface Map.Entry<String,org.opengis.referencing.operation.MathTransform>
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Implements the Map.Entry.hashCode() contract.
      Specified by:
      hashCode in interface Map.Entry<String,org.opengis.referencing.operation.MathTransform>
      Overrides:
      hashCode in class Object

    • summarize

      final NumberFormat summarize(TableAppender table, NumberFormat nf, Locale locale)
      Formats a summary of this projection attempt. This method formats the following columns:
      1. The projection name.
      2. The corelation coefficient, or the error message if an error occurred.
      Parameters:
      table - the table where to write a row.
      nf - format to use for writing coefficients, or null if not yet created.
      locale - the locale to use for messages or if a number format must be created.
      Returns:
      format used for writing coefficients, or null.

    • toString

      public String toString()
      Returns a string representation of this projection attempt for debugging purpose.
      Overrides:
      toString in class Object