Class MathTransforms


  • public final class MathTransforms
    extends Static
    Utility methods creating or working on Math­Transform instances. This class centralizes in one place some of the most commonly used functions this package. The Math­Transforms class provides the following services:
    • Create various SIS implementations of Math­Transform.
    • Perform non-standard operations on arbitrary instances.
    The factory static methods are provided as convenient alternatives to the GeoAPI Math­Transform­Factory interface. However users seeking for more implementation neutrality are encouraged to limit themselves to the GeoAPI factory interfaces instead.
    Since:
    0.5
    See Also:
    Math­Transform­Factory

    Defined in the sis-referencing module

    • Method Detail

      • identity

        public static LinearTransform identity​(int dimension)
        Returns an identity transform of the specified dimension.

        Special cases:

        Parameters:
        dimension - number of dimensions of the transform to be returned.
        Returns:
        an identity transform of the specified dimension.
      • uniformTranslation

        public static LinearTransform uniformTranslation​(int dimension,
                                                         double offset)
        Creates an affine transform which applies the same translation for all dimensions. For each dimension, input values x are converted into output values y using the following equation:
        y = x + offset
        Parameters:
        dimension - number of input and output dimensions.
        offset - the offset term in the linear equation.
        Returns:
        an affine transform applying the specified translation.
        Since:
        1.0
      • translation

        public static LinearTransform translation​(double... vector)
        Creates an affine transform which applies the given translation. The source and target dimensions of the transform are the length of the given vector.
        Parameters:
        vector - the translation vector.
        Returns:
        an affine transform applying the specified translation.
        Since:
        1.0
      • scale

        public static LinearTransform scale​(double... factors)
        Creates an affine transform which applies the given scale. The source and target dimensions of the transform are the length of the given vector.
        Parameters:
        factors - the scale factors.
        Returns:
        an affine transform applying the specified scales.
        Since:
        1.0
      • linear

        public static LinearTransform linear​(double scale,
                                             double offset)
        Creates a one-dimensional affine transform for the given coefficients. Input values x will be converted into output values y using the following equation:
        y  =  xscale + offset
        Parameters:
        scale - the scale term in the linear equation.
        offset - the offset term in the linear equation.
        Returns:
        the linear transform for the given scale and offset.
        See Also:
        Units​.converter(Number, Number)
      • linear

        public static LinearTransform linear​(Matrix matrix)
        Creates an arbitrary linear transform from the specified matrix. Usually the matrix is affine, but this is not mandatory. Non-affine matrix will define a projective transform.

        If the transform input dimension is M, and output dimension is N, then the given matrix shall have size [N+1][M+1]. The +1 in the matrix dimensions allows the matrix to do a shift, as well as a rotation. The [M][j] element of the matrix will be the j'th coordinate of the moved origin.

        Parameters:
        matrix - the matrix used to define the linear transform.
        Returns:
        the linear (usually affine) transform.
        See Also:
        get­Matrix(Math­Transform), Default­Math­Transform­Factory​.create­Affine­Transform(Matrix)
      • linear

        public static LinearTransform linear​(MathTransform transform,
                                             DirectPosition position)
                                      throws TransformException
        Returns a linear (usually affine) transform which approximates the given transform in the vicinity of the given position. If the given transform is already an instance of Linear­Transform, then it is returned as-is. Otherwise an approximation for the given position is created using the transform derivative at that position.

        Invariant: transforming the given position using the given transform produces the same result (ignoring rounding error) than transforming the same position using the returned transform. This invariant holds only for that particular position; the transformation of any other positions may produce different results.

        Parameters:
        transform - the transform to approximate by an affine transform.
        position - position in source CRS around which to get the an affine transform approximation.
        Returns:
        a transform approximating the given transform around the given position.
        Throws:
        Transform­Exception - if an error occurred while transforming the given position or computing the derivative at that position.
        Since:
        1.0
        See Also:
        get­Matrix(Math­Transform, Direct­Position)
      • interpolate

        public static MathTransform1D interpolate​(double[] preimage,
                                                  double[] values)
        Creates a transform for the y=f(x) function where y are computed by a linear interpolation. Both preimage (the x) and values (the y) arguments can be null:
        • If both preimage and values arrays are non-null, then they must have the same length.
        • If both preimage and values arrays are null, then this method returns the identity transform.
        • If only preimage is null, then the x values are taken as {0, 1, 2, …, values​.length - 1}.
        • If only values is null, then the y values are taken as {0, 1, 2, …, preimage​.length - 1}.
        All preimage elements shall be real numbers (not NaN) sorted in increasing or decreasing order. Elements in the values array do not need to be ordered, but the returned transform will be invertible only if all values are real numbers sorted in increasing or decreasing order. Furthermore the returned transform is affine (i.e. implement the Linear­Transform interface) if the interval between each preimage and values element is constant.

        The current implementation uses linear interpolation. This may be changed in a future SIS version.

        Parameters:
        preimage - the input values (x) in the function domain, or null.
        values - the output values (y) in the function range, or null.
        Returns:
        the y=f(x) function.
        Since:
        0.7
      • specialize

        public static MathTransform specialize​(MathTransform global,
                                               Map<Envelope,​MathTransform> specializations)
        Creates a transform defined as one transform applied globally except in sub-areas where more accurate transforms are available. Such constructs appear in some datum shift files. The result of transforming a point by the returned Math­Transform is as if iterating over all given Envelopes in no particular order, find the smallest one containing the point to transform (envelope border considered inclusive), then use the associated Math­Transform for transforming the point. If the point is not found in any envelope, then the global transform is applied.

        The following constraints apply:

        • The global transform must be a reasonable approximation of the specialized transforms (this is required for calculating the inverse transform).
        • All transforms in the specializations map must have the same number of source and target dimensions than the global transform.
        • All envelopes in the specializations map must have the same number of dimensions than the global transform source dimensions.
        • In current implementation, each envelope must either be fully included in another envelope, or not overlap any other envelope.
        Parameters:
        global - the transform to use globally where there is no suitable specialization.
        specializations - more accurate transforms available in some sub-areas.
        Returns:
        a transform applying the given global transform except in sub-areas where specializations are available.
        Throws:
        Illegal­Argument­Exception - if a constraint is not met.
        Since:
        1.0
      • passThrough

        public static MathTransform passThrough​(int firstAffectedCoordinate,
                                                MathTransform subTransform,
                                                int numTrailingCoordinates)
        Creates a transform which passes through a subset of coordinates to another transform. This method returns a transform having the following dimensions:
        Source: firstAffectedCoordinate + subTransform.getSourceDimensions() + numTrailingCoordinates
        Target: firstAffectedCoordinate + subTransform.getTargetDimensions() + numTrailingCoordinates
        Affected coordinates will range from first­Affected­Coordinate inclusive to dim­Target - num­Trailing­Coordinates exclusive.
        Parameters:
        first­Affected­Coordinate - index of the first affected coordinate.
        sub­Transform - the sub-transform to apply on modified coordinates.
        num­Trailing­Coordinates - number of trailing coordinates to pass through.
        Returns:
        a pass-through transform, potentially as a Pass­Through­Transform instance but not necessarily.
        Since:
        1.0
      • compound

        public static MathTransform compound​(MathTransform... components)
        Puts together a list of independent math transforms, each of them operating on a subset of coordinate values. This method is often used for defining 4-dimensional (x,y,z,t) transform as an aggregation of 3 simpler transforms operating on (x,y), (z) and (t) values respectively.

        Invariants:

        • The source dimensions of the returned transform is equals to the sum of the source dimensions of all given transforms.
        • The target dimensions of the returned transform is equals to the sum of the target dimensions of all given transforms.
        Parameters:
        components - the transforms to aggregate in a single transform, in the given order.
        Returns:
        the aggregation of all given transforms, or null if the given components array was empty.
        Since:
        0.6
        See Also:
        Pass­Through­Transform, CRS​.compound(Coordinate­Reference­System...), Envelopes​.compound(Envelope...)
      • getSteps

        public static List<MathTransform> getSteps​(MathTransform transform)
        Returns all single components of the given (potentially concatenated) transform. This method makes the following choice:
        • If transform is null, returns an empty list.
        • Otherwise if transform is the result of a call to a concatenate(…) method, returns all components. All nested concatenated transforms (if any) will be flattened.
        • Otherwise returns the given transform in a list of size 1.
        Parameters:
        transform - the transform for which to get the components, or null.
        Returns:
        all single math transforms performed by this concatenated transform.
      • getMatrix

        public static Matrix getMatrix​(MathTransform transform,
                                       DirectPosition position)
                                throws TransformException
        Returns the coefficients of an affine transform in the vicinity of the given position. If the given transform is linear, then this method produces a result identical to get­Matrix(Math­Transform). Otherwise the returned matrix can be used for building a linear transform which can be used as an approximation of the given transform for short distances around the given position.
        Parameters:
        transform - the transform to approximate by an affine transform.
        position - position in source CRS around which to get the coefficients of an affine transform approximation.
        Returns:
        the matrix of the given transform around the given position.
        Throws:
        Transform­Exception - if an error occurred while transforming the given position or computing the derivative at that position.
        Since:
        1.0
        See Also:
        linear(Math­Transform, Direct­Position)
      • derivativeAndTransform

        public static Matrix derivativeAndTransform​(MathTransform transform,
                                                    double[] srcPts,
                                                    int srcOff,
                                                    double[] dstPts,
                                                    int dstOff)
                                             throws TransformException
        A buckle method for calculating derivative and coordinate transformation in a single step. The transform result is stored in the given destination array, and the derivative matrix is returned. Invoking this method is equivalent to the following code, except that it may execute faster with some Math­Transform implementations:
        DirectPosition ptSrc = ...;
        DirectPosition ptDst = ...;
        Matrix matrixDst = derivative(ptSrc);
        ptDst = transform(ptSrc, ptDst);
        Parameters:
        transform - the transform to use.
        src­Pts - the array containing the source coordinate.
        src­Off - the offset to the point to be transformed in the source array.
        dst­Pts - the array into which the transformed coordinate is returned.
        dst­Off - the offset to the location of the transformed point that is stored in the destination array.
        Returns:
        the matrix of the transform derivative at the given source position.
        Throws:
        Transform­Exception - if the point can't be transformed or if a problem occurred while calculating the derivative.