Class AbstractMathTransform

    • Constructor Detail

      • AbstractMathTransform

        protected AbstractMathTransform()
        Constructor for subclasses.
    • Method Detail

      • getParameterValues

        public ParameterValueGroup getParameterValues()
        Returns the parameter values for this math transform, or null if unknown. This is not necessarily the parameters that the user specified at construction time, since implementations may have applied normalizations.
        Normalized and contextual parameters
        Most Apache SIS implementations of map projections perform their calculations on an ellipsoid having a semi-major axis length of 1. In such cases, the group returned by this method contains a "semi_major" parameter with a value of 1. If the real axis length is desired, we need to take in account the context of this math transform, i.e. the scales and offsets applied before and after this transform. This information is provided by get­Contextual­Parameters().
        Specified by:
        get­Parameter­Values in interface Parameterized
        Returns:
        the parameter values for this math transform, or null if unspecified. Note that those parameters may be normalized (e.g. represent a transformation of an ellipsoid of semi-major axis length of 1).
        See Also:
        get­Contextual­Parameters(), Single­Operation​.get­Parameter­Values()
      • getContextualParameters

        protected ContextualParameters getContextualParameters()
        Returns the parameters for a sequence of normalizethisdenormalize transforms (optional operation). Subclasses can override this method if they choose to split their computation in linear and non-linear parts. Such split is optional: it can leads to better performance (because SIS can concatenate efficiently consecutive linear transforms), but should not change significantly the result (ignoring differences in rounding errors). If a split has been done, then this Math­Transform represents only the non-linear step and Apache SIS needs this method for reconstructing the parameters of the complete transform.
        Returns:
        the parameters values for the sequence of normalizethisdenormalize transforms, or null if unspecified. Callers should not modify the returned parameters, since modifications (if allowed) will generally not be reflected back in this Math­Transform.
        Since:
        0.6
      • isIdentity

        public boolean isIdentity()
        Tests whether this transform does not move any points. The default implementation always returns false.
        Specified by:
        is­Identity in interface Math­Transform
      • transform

        public abstract Matrix transform​(double[] srcPts,
                                         int srcOff,
                                         double[] dstPts,
                                         int dstOff,
                                         boolean derivate)
                                  throws TransformException
        Transforms a single coordinate point in an array, and optionally computes the transform derivative at that location. Invoking this method is conceptually equivalent to running the following:
        Matrix derivative = null;
        if (derivate) {
            double[] coordinates = Arrays.copyOfRange(srcPts, srcOff, srcOff + getSourceDimensions());
            derivative = this.derivative(new GeneralDirectPosition(coordinates));
        }
        this.transform(srcPts, srcOff, dstPts, dstOff, 1);                   // May overwrite srcPts.
        return derivative;
        However this method provides two advantages:
        • It is usually easier to implement for Abstract­Math­Transform subclasses. The default transform(double[], int, double[], int, int) method implementation will invoke this method in a loop, taking care of the iteration strategy depending on the argument value.
        • When both the transformed point and its derivative are needed, this method may be significantly faster than invoking the transform and derivative methods separately because many internal calculations are the same. Computing those two information in a single step can help to reduce redundant calculation.
        Note for implementers
        The source and destination may overlap. Consequently, implementers must read all source coordinate values before to start writing the transformed coordinates in the destination array.
        Parameters:
        src­Pts - the array containing the source coordinate (can not be null).
        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. May be the same than src­Pts. May be null if only the derivative matrix is desired.
        dst­Off - the offset to the location of the transformed point that is stored in the destination array.
        derivate - true for computing the derivative, or false if not needed.
        Returns:
        the matrix of the transform derivative at the given source position, or null if the derivate argument is false.
        Throws:
        Transform­Exception - if the point can not be transformed or if a problem occurred while calculating the derivative.
        See Also:
        derivative(Direct­Position), transform(Direct­Position, Direct­Position), Math­Transforms​.derivative­And­Transform(Math­Transform, double[], int, double[], int)
      • transform

        public void transform​(double[] srcPts,
                              int srcOff,
                              double[] dstPts,
                              int dstOff,
                              int numPts)
                       throws TransformException
        Transforms a list of coordinate points. This method is provided for efficiently transforming many points. The supplied array of coordinate values will contain packed coordinate values.
        Example: if the source dimension is 3, then the coordinates will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).
        The default implementation invokes transform(double[], int, double[], int, boolean) in a loop, using an iteration strategy determined from the arguments for iterating over the points.
        Implementation note: see Iteration­Strategy javadoc for a method skeleton.
        Specified by:
        transform in interface Math­Transform
        Parameters:
        src­Pts - the array containing the source point coordinates.
        src­Off - the offset to the first point to be transformed in the source array.
        dst­Pts - the array into which the transformed point coordinates are returned. May be the same than src­Pts.
        dst­Off - the offset to the location of the first transformed point that is stored in the destination array.
        num­Pts - the number of point objects to be transformed.
        Throws:
        Transform­Exception - if a point can not be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
      • transform

        public void transform​(float[] srcPts,
                              int srcOff,
                              float[] dstPts,
                              int dstOff,
                              int numPts)
                       throws TransformException
        Transforms a list of coordinate points. The default implementation delegates to transform(double[], int, double[], int, int) using a temporary array of doubles.
        Implementation note: see Iteration­Strategy javadoc for a method skeleton.
        Specified by:
        transform in interface Math­Transform
        Parameters:
        src­Pts - the array containing the source point coordinates.
        src­Off - the offset to the first point to be transformed in the source array.
        dst­Pts - the array into which the transformed point coordinates are returned. May be the same than src­Pts.
        dst­Off - the offset to the location of the first transformed point that is stored in the destination array.
        num­Pts - the number of point objects to be transformed.
        Throws:
        Transform­Exception - if a point can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the un-transformable points with Float​.Na­N values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
      • transform

        public void transform​(double[] srcPts,
                              int srcOff,
                              float[] dstPts,
                              int dstOff,
                              int numPts)
                       throws TransformException
        Transforms a list of coordinate points. The default implementation delegates to transform(double[], int, double[], int, int) using a temporary array of doubles.
        Specified by:
        transform in interface Math­Transform
        Parameters:
        src­Pts - the array containing the source point coordinates.
        src­Off - the offset to the first point to be transformed in the source array.
        dst­Pts - the array into which the transformed point coordinates are returned.
        dst­Off - the offset to the location of the first transformed point that is stored in the destination array.
        num­Pts - the number of point objects to be transformed.
        Throws:
        Transform­Exception - if a point can not be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with Float.NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
      • transform

        public void transform​(float[] srcPts,
                              int srcOff,
                              double[] dstPts,
                              int dstOff,
                              int numPts)
                       throws TransformException
        Transforms a list of coordinate points. The default implementation delegates to transform(double[], int, double[], int, int) using a temporary array of doubles if necessary.
        Specified by:
        transform in interface Math­Transform
        Parameters:
        src­Pts - the array containing the source point coordinates.
        src­Off - the offset to the first point to be transformed in the source array.
        dst­Pts - the array into which the transformed point coordinates are returned.
        dst­Off - the offset to the location of the first transformed point that is stored in the destination array.
        num­Pts - the number of point objects to be transformed.
        Throws:
        Transform­Exception - if a point can not be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.
      • tryConcatenate

        protected MathTransform tryConcatenate​(boolean applyOtherFirst,
                                               MathTransform other,
                                               MathTransformFactory factory)
                                        throws FactoryException
        Concatenates or pre-concatenates in an optimized way this math transform with the given one, if possible. If an optimization is possible, a new math transform is created to perform the combined transformation. The apply­Other­First value determines the transformation order as bellow:
        • If apply­Other­First is true, then transforming a point p by the combined transform is equivalent to first transforming p by other and then transforming the result by this.
        • If apply­Other­First is false, then transforming a point p by the combined transform is equivalent to first transforming p by this and then transforming the result by other.
        If no optimization is available for the combined transform, then this method returns null. In the later case, the concatenation will be prepared by Default­Math­Transform­Factory using a generic implementation.

        The default implementation returns the identity transform if the other transform is the inverse of this transform, or returns null otherwise. This method is ought to be overridden by subclasses capable of concatenating some combination of transforms in a special way. Linear­Transform implementations do not need to override this method since matrix multiplications will be handled automatically, and this method does not need to handle the is­Identity() case.

        Parameters:
        apply­Other­First - true if the transformation order is other followed by this, or false if the transformation order is this followed by other.
        other - the other math transform to (pre-)concatenate with this transform.
        factory - the factory which is (indirectly) invoking this method, or null if none.
        Returns:
        the math transforms combined in an optimized way, or null if no such optimization is available.
        Throws:
        Factory­Exception - if an error occurred while combining the transforms.
        Since:
        0.8
        See Also:
        Default­Math­Transform­Factory​.create­Concatenated­Transform(Math­Transform, Math­Transform)
      • hashCode

        public final int hashCode()
        Returns a hash value for this transform. This method invokes compute­Hash­Code() when first needed and caches the value for future invocations. Subclasses shall override compute­Hash­Code() instead than this method.
        Overrides:
        hash­Code in class Object
        Returns:
        the hash code value. This value may change between different execution of the Apache SIS library.
      • computeHashCode

        protected int computeHashCode()
        Computes a hash value for this transform. This method is invoked by hash­Code() when first needed.
        Returns:
        the hash code value. This value may change between different execution of the Apache SIS library.
      • equals

        public final boolean equals​(Object object)
        Compares the specified object with this math transform for strict equality. This method is implemented as below (omitting assertions):
        return equals(other, ComparisonMode.STRICT);
        Specified by:
        equals in interface Lenient­Comparable
        Overrides:
        equals in class Object
        Parameters:
        object - the object to compare with this transform.
        Returns:
        true if the given object is a transform of the same class and using the same parameter values.
        See Also:
        Comparison­Mode​.STRICT
      • equals

        public boolean equals​(Object object,
                              ComparisonMode mode)
        Compares the specified object with this math transform for equality. Two math transforms are considered equal if, given identical source positions, their transformed positions would be equal or approximately equal. This method may conservatively returns false if unsure.

        The default implementation returns true if the following conditions are met:

        • object is an instance of the same class than this. We require the same class because there is no interface for the various kinds of transform.
        • If the hash code value has already been computed for both instances, their values are the same (opportunist performance enhancement).
        • The contextual parameters are equal according the given comparison mode.
        Specified by:
        equals in interface Lenient­Comparable
        Parameters:
        object - the object to compare with this transform.
        mode - the strictness level of the comparison. Default to STRICT.
        Returns:
        true if the given object is considered equals to this math transform.
        See Also:
        Utilities​.deep­Equals(Object, Object, Comparison­Mode)
      • formatTo

        protected String formatTo​(Formatter formatter)
        Formats the inner part of a Well Known Text version 1 (WKT 1) element. The default implementation formats all parameter values returned by get­Parameter­Values(). The parameter group name is used as the math transform name.
        Compatibility note: Param_MT is defined in the WKT 1 specification only. If the formatter convention is set to WKT 2, then this method silently uses the WKT 1 convention without raising an error (unless this Math­Transform can not be formatted as valid WKT 1 neither).
        Specified by:
        format­To in class Formattable­Object
        Parameters:
        formatter - the formatter to use.
        Returns:
        the WKT element name, which is "Param_MT" in the default implementation.
        See Also:
        Formattable­Object​.to­WKT(), Formattable­Object​.to­String()