Module org.opengis.geoapi.conformance
Package org.opengis.test.referencing

Class TransformTestCase

Object
TestCase
TransformTestCase
Direct Known Subclasses:
AffineTransformTest, ParameterizedTransformTest
public abstract class TransformTestCase extends TestCase
Base class for MathTransform implementation tests. Subclasses shall assign a value to the transform field before to invoke any method in this class. The specified math transform shall support the following mandatory operations: All other operations are optional. However subclasses shall declare which methods, if any, are unsupported. By default every operations are assumed supported. Tests can be disabled on a case-by-case basis by setting the appropriate is<Operation>Supported fields to false.

After TransformTestCase has been setup, subclasses can invoke any of the verify methods in their JUnit test methods. Callers must supply the input coordinate points to be used for testing purpose, since the range of valid values is usually transform-dependent.

Some general rules:

  • Coordinate values, or information used for computing coordinate values, are always specified as arguments to the verify methods. Everything else are fields in the TransformTestCase object.
  • The methods in this class do not validate the transform. It is caller responsibility to validate the transform if wanted.
  • Unless otherwise indicated, every verify methods are independent. For example, invoking verifyConsistency(float[]) does not imply a call to verifyInverse(float[]) or verifyDerivative(double[]). The later methods must be invoked explicitly if wanted.
Since:
2.2

  • Field Details

  • Constructor Details

    • TransformTestCase

      protected TransformTestCase()
      Creates a new test without factory. This constructor is provided for subclasses that instantiate their MathTransform directly, without using any factory.

    • TransformTestCase

      protected TransformTestCase(Factory... factories)
      Creates a test case initialized to default values. The transform is initially null, the tolerance threshold is initially zero and all is<Operation>Supported are set to true.
      Parameters:
      factories - the factories to be used by the test.

  • Method Details

    • configuration

      public Configuration configuration()
      Returns information about the configuration of the test which has been run. This method returns a map containing:
      Overrides:
      configuration in class TestCase
      Returns:
      the configuration of the test being run, or an empty map if none. This method returns a modifiable map in order to allow subclasses to modify it.
      Since:
      3.1

    • tolerance

      @Deprecated protected double tolerance(double coordinate)
      Deprecated.
      Replaced by toleranceModifier.
      Returns the tolerance threshold for comparing the given coordinate value. The default implementation returns the tolerance value directly, thus implementing an absolute tolerance threshold. If a subclass needs a relative tolerance threshold instead, it can override this method as below:
      return tolerance * Math.abs(coordinate);
      Parameters:
      coordinate - the coordinate value being compared.
      Returns:
      the absolute tolerance threshold to use for comparing the given coordinate.

    • assertAllTestsEnabled

      @Deprecated protected void assertAllTestsEnabled()
      Deprecated.
      No replacement.
      Ensures that all is<Operation>Supported fields are set to true. This method can be invoked before testing a math transform which is expected to be fully implemented.

    • verifyTransform

      protected void verifyTransform(double[] coordinates, double[] expected) throws TransformException
      Transforms the given coordinates and verifies that the result is equal (within a positive delta) to the expected ones. If the difference between an expected and actual coordinate value is greater than the tolerance threshold (after optional tolerance modification), then the assertion fails.

      If isInverseTransformSupported is true, then this method will also transform the expected coordinate points using the inverse transform and compare with the source coordinates.

      Parameters:
      coordinates - the coordinate points to transform.
      expected - the expect result of the transformation, or null if coordinates is expected to be null.
      Throws:
      TransformException - if the transformation failed.
      See Also:

    • verifyInverse

      protected void verifyInverse(double... coordinates) throws TransformException
      Transforms the given coordinates, applies the inverse transform and compares with the original values. If a difference between the expected and actual coordinate values is greater than the tolerance threshold (after optional tolerance modification), then the assertion fails.

      At the difference of verifyTransform(double[],double[]), this method does not require an array of expected values. The expected values are calculated from the transform itself.

      Parameters:
      coordinates - the source coordinates to transform.
      Throws:
      TransformException - if at least one coordinate can't be transformed.

    • verifyInverse

      protected void verifyInverse(float... coordinates) throws TransformException
      Transforms the given coordinates, applies the inverse transform and compares with the original values. If a difference between the expected and actual coordinate values is greater than the tolerance threshold (after optional tolerance modification), then the assertion fails.

      The default implementation delegates to verifyInverse(double[]).

      Parameters:
      coordinates - the source coordinates to transform.
      Throws:
      TransformException - if at least one coordinate can't be transformed.

    • verifyConsistency

      protected float[] verifyConsistency(float... sourceFloats) throws TransformException
      Transforms coordinates using various versions of MathTransform.transform(…) and verifies that they produce the same numerical values. The values calculated by MathTransform.transform(DirectPosition,DirectPosition) are used as the reference. Other transform methods (operating on arrays) will be compared against that reference, unless their checks were disabled (see class javadoc for details).

      This method expects an array of float values instead of double for making sure that the MathTransform.transform(float[], …) and MathTransform.transform(double[], …) methods produces the same numerical values. The double values may show extra digits when formatted in base 10, but this is not significant if their IEEE 754 representation (which use base 2) are equivalent.

      This method does not verify the inverse transform or the derivatives. If desired, those later methods can be verified with the verifyInverse(float[]) and verifyDerivative(double[]) methods respectively.

      Parameters:
      sourceFloats - the source coordinates to transform as an array of float values.
      Returns:
      the transformed coordinates, returned for convenience.
      Throws:
      TransformException - if at least one coordinate can't be transformed.
      See Also:

    • verifyDerivative

      protected void verifyDerivative(double... coordinates) throws TransformException
      Computes the derivative at the given point and compares the result with the finite differences approximation.

      All the three common forms of finite differences (forward difference, backward difference and central difference) are computed. If the finite difference method was a "perfect" approximation, all those three forms would produce identical results. In practice the results will differ, especially in areas where the derivative function varies fast. The difference between the results will be used as an estimation of the approximation accuracy.

      The distance between the two points used by the central difference approximation shall be specified in the derivativeDeltas array, in units of the source CRS. If the length of the derivativeDeltas array is smaller than the number of source dimensions, then the last delta value is used for all additional dimensions. This allows specifying a single delta value (in an array of length 1) for all dimensions.

      This method created the following objects:

      • expected - the expected derivative result estimated by the central difference method.
      • tolmat - a tolerance matrix containing, for each matrix element, the largest difference found between the three approximation methods. The values in this matrix will not be lower than the modified tolerance threshold.
      Those information are then passed to the assertMatrixEquals(String, Matrix, Matrix, Matrix) method. Implementers can override the latter method, for example in order to overwrite the tolerance values.
      Parameters:
      coordinates - the point where to compute the derivative, in units of the source CRS.
      Throws:
      TransformException - if the derivative cannot be computed, or a point cannot be transformed.
      Since:
      3.1
      See Also:

    • verifyInDomain

      protected float[] verifyInDomain(double[] minOrdinates, double[] maxOrdinates, int[] numOrdinates, Random randomGenerator) throws TransformException
      Verifies all supported transform operations in the given domain. First, this method creates a grid of regularly spaced points along all source dimensions in the given envelope. Next, if the given random number generator is non-null, then this method adds small random displacements to every points and shuffle the coordinates in random order. Finally this method delegates the resulting array of coordinates to the following methods: The generated coordinates array is returned in case callers want to perform more tests in addition to the above-cited verifications.
      Parameters:
      minOrdinates - the minimal coordinate values of the domain where to test the transform.
      maxOrdinates - the maximal coordinate values of the domain where to test the transform.
      numOrdinates - the number of points along each dimension.
      randomGenerator - an optional random number generator, or null for testing using a regular grid.
      Returns:
      the generated random coordinates inside the given domain of validity.
      Throws:
      TransformException - if a transform or a derivative cannot be computed.
      Since:
      3.1

    • assertCoordinateEquals

      protected final void assertCoordinateEquals(String message, float[] expected, float[] actual, int index, CalculationType mode) throws TransformFailure
      Asserts that a single coordinate is equal to the expected one within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - the index of the coordinate point being compared, for message formatting.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinateEquals

      protected final void assertCoordinateEquals(String message, float[] expected, double[] actual, int index, CalculationType mode) throws TransformFailure
      Asserts that a single coordinate is equal to the expected one within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - the index of the coordinate point being compared, for message formatting.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinateEquals

      protected final void assertCoordinateEquals(String message, double[] expected, float[] actual, int index, CalculationType mode) throws TransformFailure
      Asserts that a single coordinate is equal to the expected one within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - the index of the coordinate point being compared, for message formatting.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinateEquals

      protected final void assertCoordinateEquals(String message, double[] expected, double[] actual, int index, CalculationType mode) throws TransformFailure
      Asserts that a single coordinate is equal to the expected one within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - the index of the coordinate point being compared, for message formatting.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinatesEqual

      protected final void assertCoordinatesEqual(String message, int dimension, float[] expectedPts, int expectedOffset, float[] actualPts, int actualOffset, int numPoints, CalculationType mode) throws TransformFailure
      Asserts that coordinate values are equal to the expected ones within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinatesEqual

      protected final void assertCoordinatesEqual(String message, int dimension, float[] expectedPts, int expectedOffset, double[] actualPts, int actualOffset, int numPoints, CalculationType mode) throws TransformFailure
      Asserts that coordinate values are equal to the expected ones within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinatesEqual

      protected final void assertCoordinatesEqual(String message, int dimension, double[] expectedPts, int expectedOffset, float[] actualPts, int actualOffset, int numPoints, CalculationType mode) throws TransformFailure
      Asserts that coordinate values are equal to the expected ones within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinatesEqual

      protected final void assertCoordinatesEqual(String message, int dimension, double[] expectedPts, int expectedOffset, double[] actualPts, int actualOffset, int numPoints, CalculationType mode) throws TransformFailure
      Asserts that coordinate values are equal to the expected ones within a positive delta. If the comparison fails, the given message is completed with the expected and actual values, and the index of the coordinate where the failure was found.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Throws:
      TransformFailure - if at least one coordinate value is not equal to the expected value.

    • assertCoordinateEquals

      @Deprecated protected final void assertCoordinateEquals(String message, float[] expected, float[] actual, int index, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - the index of the coordinate point being compared, for message formatting.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertCoordinateEquals

      @Deprecated protected final void assertCoordinateEquals(String message, float[] expected, double[] actual, int index, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - the index of the coordinate point being compared, for message formatting.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertCoordinateEquals

      @Deprecated protected final void assertCoordinateEquals(String message, double[] expected, float[] actual, int index, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - the index of the coordinate point being compared, for message formatting.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertCoordinateEquals

      @Deprecated protected final void assertCoordinateEquals(String message, double[] expected, double[] actual, int index, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      expected - the array of expected coordinate values.
      actual - the array of coordinate values to check against the expected ones.
      index - he index of the coordinate point being compared, for message formatting.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertCoordinatesEqual

      @Deprecated protected final void assertCoordinatesEqual(String message, int dimension, float[] expectedPts, int expectedOffset, float[] actualPts, int actualOffset, int numPoints, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertCoordinatesEqual

      @Deprecated protected final void assertCoordinatesEqual(String message, int dimension, float[] expectedPts, int expectedOffset, double[] actualPts, int actualOffset, int numPoints, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertCoordinatesEqual

      @Deprecated protected final void assertCoordinatesEqual(String message, int dimension, double[] expectedPts, int expectedOffset, float[] actualPts, int actualOffset, int numPoints, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertCoordinatesEqual

      @Deprecated protected final void assertCoordinatesEqual(String message, int dimension, double[] expectedPts, int expectedOffset, double[] actualPts, int actualOffset, int numPoints, boolean strict)
      Deprecated.
      The boolean argument has been replaced by a CalculationType argument.
      Parameters:
      message - the message to print in case of failure.
      dimension - the dimension of each coordinate points in the arrays.
      expectedPts - the array of expected coordinate values.
      expectedOffset - index of the first valid coordinate in the expectedPts array.
      actualPts - the array of coordinate values to check against the expected ones.
      actualOffset - index of the first valid coordinate in the actualPts array.
      numPoints - number of coordinate points to compare.
      strict - true for ignoring the tolerance threshold. In such case, coordinate values are checked for strict equality.

    • assertMatrixEquals

      protected void assertMatrixEquals(String message, Matrix expected, Matrix actual, Matrix tolmat) throws DerivativeFailure
      Asserts that a matrix of derivatives is equal to the expected ones within a positive delta. If the comparison fails, the given message is completed with the expected and actual matrixes values.

      For each matrix element, the tolerance value is given by the corresponding element in the tolmat matrix. This tolerance matrix is initialized by the verifyDerivative(double[]) method to the differences found between the 3 forms of finite difference (forward, backward, central). Developers can override this method and overwrite the tolmat elements if they wish different tolerance values.

      Parameters:
      message - the message to print in case of failure.
      expected - the expected matrix of derivative values, estimated by finite differences.
      actual - the actual matrix computed by the transform to be tested.
      tolmat - the tolerance value for each matrix elements, or null for a strict comparison.
      Throws:
      DerivativeFailure - if at least one matrix element is not equal to the expected value.
      Since:
      3.1
      See Also:

    • normalize

      protected void normalize(DirectPosition expected, DirectPosition actual, CalculationType mode)
      Invoked by all assertCoordinateEqual(…) methods before two positions are compared. This method allows subclasses to replace some equivalent coordinate values by a unique value. For example, implementations may ensure that longitude values are contained in the ±180° range, applying 360° shifts if needed.

      The default implementation does nothing. Subclasses can modify the actual coordinate values directly using the DirectPosition.setOrdinate(int, double) method.

      Parameters:
      expected - the expected coordinate value provided by the test case.
      actual - the coordinate value computed by the transform being tested.
      mode - indicates if the coordinates being compared are the result of a direct or inverse transform, or if strict equality is requested.
      Since:
      3.1