Package org.opengis.test.referencing

Class 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

    • Constructor Detail

      • TransformTestCase

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

    • Method Detail

      • tolerance

        @Deprecated
protected double tolerance​(double ordinate)
        Deprecated.
        Replaced by toleranceModifier.
        Returns the tolerance threshold for comparing the given ordinate 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(ordinate);
        Parameters:
        ordinate - the ordinate value being compared.
        Returns:
        the absolute tolerance threshold to use for comparing the given ordinate.

      • 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 equals (within a positive delta) to the expected ones. If the difference between an expected and actual ordinate 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:
        isInverseTransformSupported

      • 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 ordinate 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 ordinate 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 than 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:
        isDoubleToDoubleSupported, isFloatToFloatSupported, isDoubleToFloatSupported, isFloatToDoubleSupported, isOverlappingArraySupported

      • verifyDerivative

        protected void verifyDerivative​(double... coordinate)
                         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. Implementors can override the later method, for example in order to overwrite the tolerance values.
        Parameters:
        coordinate - the point where to compute the derivative, in units of the source CRS.
        Throws:
        TransformException - if the derivative can not be computed, or a point can not be transformed.
        Since:
        3.1
        See Also:
        MathTransform.derivative(DirectPosition), assertMatrixEquals(String, Matrix, Matrix, Matrix)

      • 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 ordinate values of the domain where to test the transform.
        maxOrdinates - the maximal ordinate 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 can not 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 ordinate where the failure was found.
        Parameters:
        message - the message to print in case of failure.
        expected - the array of expected ordinate values.
        actual - the array of ordinate 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 ordinate 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 ordinate where the failure was found.
        Parameters:
        message - the message to print in case of failure.
        expected - the array of expected ordinate values.
        actual - the array of ordinate 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 ordinate 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 ordinate where the failure was found.
        Parameters:
        message - the message to print in case of failure.
        expected - the array of expected ordinate values.
        actual - the array of ordinate 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 ordinate 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 ordinate where the failure was found.
        Parameters:
        message - the message to print in case of failure.
        expected - the array of expected ordinate values.
        actual - the array of ordinate 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 ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate 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 ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate 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 ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate 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 ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate 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 ordinate 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 ordinate values.
        actual - the array of ordinate 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, ordinate 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 ordinate values.
        actual - the array of ordinate 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, ordinate 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 ordinate values.
        actual - the array of ordinate 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, ordinate 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 ordinate values.
        actual - the array of ordinate 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, ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate in the actualPts array.
        numPoints - number of coordinate points to compare.
        strict - true for ignoring the tolerance threshold. In such case, ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate in the actualPts array.
        numPoints - number of coordinate points to compare.
        strict - true for ignoring the tolerance threshold. In such case, ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate in the actualPts array.
        numPoints - number of coordinate points to compare.
        strict - true for ignoring the tolerance threshold. In such case, ordinate 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 ordinate in the expectedPts array.
        actualPts - the array of coordinate values to check against the expected ones.
        actualOffset - index of the first valid ordinate in the actualPts array.
        numPoints - number of coordinate points to compare.
        strict - true for ignoring the tolerance threshold. In such case, ordinate 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 equals 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:
        verifyDerivative(double[]), Assert.assertMatrixEquals(String, Matrix, Matrix, double)

      • 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 ordinate 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 ordinate values directly using the DirectPosition.setOrdinate(int, double) method.

        Parameters:
        expected - the expected ordinate value provided by the test case.
        actual - the ordinate 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