Package org.apache.sis.referencing.operation.transform

Class SpecializableTransform

java.lang.Object

org.apache.sis.io.wkt.FormattableObject

org.apache.sis.referencing.operation.transform.AbstractMathTransform

org.apache.sis.referencing.operation.transform.SpecializableTransform

All Implemented Interfaces:

Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform

Direct Known Subclasses:

SpecializableTransform2D

class SpecializableTransform
extends AbstractMathTransform
implements Serializable

A transform having sub-areas where more accurate transforms can be used. The global transform must be a reasonable approximation of the specialized transforms. The lower and upper values of given envelopes are inclusive.

Since:

1.0

Version:

1.2

See Also:

• MathTransforms.specialize(MathTransform, Map)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	SpecializableTransform.Inverse	The inverse of SpecializableTransform.
private static final class	SpecializableTransform.SubArea	The region where a transform is valid, together with the transform.
private static interface	SpecializableTransform.TransformCall	Call of a MathTransform.transform(…) method with source and target arrays fixed at TransformCall creation time.

Field Summary

Fields

Modifier and Type	Field	Description
private final RTreeNode	domains	Domains where specialized transforms are valid.
private final org.opengis.referencing.operation.MathTransform	global	The global transform to use if there is no suitable specialization.
private org.opengis.referencing.operation.MathTransform	inverse	The inverse of this transform, computed when first needed.
private static final long	serialVersionUID	For cross-version compatibility.

Fields inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform

MAXIMUM_BUFFER_SIZE, MAXIMUM_FAILURES

Constructor Summary

Constructors

Constructor	Description
SpecializableTransform(org.opengis.referencing.operation.MathTransform global, Map<org.opengis.geometry.Envelope,org.opengis.referencing.operation.MathTransform> specializations)	Creates a new transform with the given global transform and some amount of specializations.

Method Summary

Modifier and Type	Method	Description
protected final int	computeHashCode()	Computes a hash value for this transform.
(package private) SpecializableTransform.Inverse	createInverse()	Invoked at construction time for creating the inverse transform.
final org.opengis.referencing.operation.Matrix	derivative(org.opengis.geometry.DirectPosition point)	Gets the derivative of this transform at a point.
final boolean	equals(Object object, ComparisonMode mode)	Compares the specified object with this math transform for equality.
private org.opengis.referencing.operation.MathTransform	forDomain(org.opengis.geometry.DirectPosition pos)	Returns the transform to use for the given position, or global if none.
protected final String	formatTo(Formatter formatter)	Formats the inner part of a Well Known Text version 1 (WKT 1) element.
final int	getSourceDimensions()	Gets the dimension of input points.
(package private) final org.opengis.referencing.operation.MathTransform	getSubstitute()	If this transform has no children, then returns the transform that we should use instead.
final int	getTargetDimensions()	Gets the dimension of output points.
org.opengis.referencing.operation.MathTransform	inverse()	Returns the inverse of this transform.
private SpecializableTransform.SubArea	locate(org.opengis.geometry.DirectPosition pos)	Returns the node that contains the given position, or null if none.
private List<SpecializableTransform.SubArea>	roots()	Returns the SpecializableTransform.SubArea instances at the root of this class.
final org.opengis.referencing.operation.Matrix	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate)	Transforms a single coordinate tuple in an array, and optionally computes the transform derivative at that location.
final void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate tuples.
final void	transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate tuples.
final void	transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate tuples.
final void	transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate tuples.
private void	transform(SpecializableTransform.TransformCall transform, DirectPositionView src, int dstOff, int srcInc, int dstInc, int numPts)	Transforms a list of coordinate tuples.
final org.opengis.geometry.DirectPosition	transform(org.opengis.geometry.DirectPosition ptSrc, org.opengis.geometry.DirectPosition ptDst)	Transforms the specified ptSrc and stores the result in ptDst.

Methods inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform

beforeFormat, equals, getContextualParameters, getDomain, getParameterDescriptors, getParameterValues, hashCode, isIdentity, isInverseEquals, mismatchedDimension, tryConcatenate

Methods inherited from class org.apache.sis.io.wkt.FormattableObject

print, toString, toString, toWKT

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.opengis.referencing.operation.MathTransform

toWKT

Field Details

serialVersionUID

private static final long serialVersionUID

For cross-version compatibility.

See Also:

• Constant Field Values

global

private final org.opengis.referencing.operation.MathTransform global

The global transform to use if there is no suitable specialization.

domains

private final RTreeNode domains

Domains where specialized transforms are valid. This is the root of an R-Tree. May be null if there is no R-Tree, in which case global should be used instead.

inverse

private org.opengis.referencing.operation.MathTransform inverse

The inverse of this transform, computed when first needed. This object is included in serialization for avoiding rounding error issues.

See Also:

• inverse()

Constructor Details

SpecializableTransform

SpecializableTransform(org.opengis.referencing.operation.MathTransform global,
 Map<org.opengis.geometry.Envelope,org.opengis.referencing.operation.MathTransform> specializations)

Creates a new transform with the given global transform and some amount of specializations.

Parameters:

global - the transform to use globally where there is no suitable specialization.

specializations - more accurate transforms available in sub-areas.

Method Details

roots

private List<SpecializableTransform.SubArea> roots()

Returns the SpecializableTransform.SubArea instances at the root of this class. This is the domains node, unless that node is a synthetic node created by RTreeNode when it needs to contain more than one children.

getSubstitute

final org.opengis.referencing.operation.MathTransform getSubstitute()

If this transform has no children, then returns the transform that we should use instead. Otherwise returns null.

getSourceDimensions

public final int getSourceDimensions()

Gets the dimension of input points.

Specified by:

getSourceDimensions in interface org.opengis.referencing.operation.MathTransform

Specified by:

getSourceDimensions in class AbstractMathTransform

Returns:

the number of dimensions of input points.

See Also:

• DefaultOperationMethod.getSourceDimensions()

getTargetDimensions

public final int getTargetDimensions()

Gets the dimension of output points.

Specified by:

getTargetDimensions in interface org.opengis.referencing.operation.MathTransform

Specified by:

getTargetDimensions in class AbstractMathTransform

Returns:

the number of dimensions of output points.

See Also:

• DefaultOperationMethod.getTargetDimensions()

locate

private SpecializableTransform.SubArea locate(org.opengis.geometry.DirectPosition pos)

Returns the node that contains the given position, or null if none. This method searches from the root of the tree. It should be invoked only when we do not know what was the last search result.

forDomain

private org.opengis.referencing.operation.MathTransform forDomain(org.opengis.geometry.DirectPosition pos)

Returns the transform to use for the given position, or global if none.

transform

public final org.opengis.geometry.DirectPosition transform(org.opengis.geometry.DirectPosition ptSrc,
 org.opengis.geometry.DirectPosition ptDst)
                                                    throws org.opengis.referencing.operation.TransformException

Transforms the specified ptSrc and stores the result in ptDst. This method delegates to the most specialized transform.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

ptSrc - the coordinate tuple to be transformed.

ptDst - the coordinate tuple that stores the result of transforming ptSrc, or null.

Returns:

the coordinate tuple after transforming ptSrc and storing the result in ptDst, or a newly created point if ptDst was null.

Throws:

org.opengis.referencing.operation.TransformException - if the point cannot be transformed.

derivative

public final org.opengis.referencing.operation.Matrix derivative(org.opengis.geometry.DirectPosition point)
                                                          throws org.opengis.referencing.operation.TransformException

Gets the derivative of this transform at a point. This method delegates to the most specialized transform.

Specified by:

derivative in interface org.opengis.referencing.operation.MathTransform

Overrides:

derivative in class AbstractMathTransform

Parameters:

point - the coordinate tuple where to evaluate the derivative.

Returns:

the derivative at the specified point (never null).

Throws:

org.opengis.referencing.operation.TransformException - if the derivative cannot be evaluated at the specified point.

transform

public final org.opengis.referencing.operation.Matrix transform(double[] srcPts,
 int srcOff,
 double[] dstPts,
 int dstOff,
 boolean derivate)
                                                         throws org.opengis.referencing.operation.TransformException

Transforms a single coordinate tuple in an array, and optionally computes the transform derivative at that location. This method delegates to the most specialized transform.

Specified by:

transform in class AbstractMathTransform

Parameters:

srcPts - the array containing the source coordinates (cannot be null).

srcOff - the offset to the point to be transformed in the source array.

dstPts - the array into which the transformed coordinates is returned. May be the same than srcPts. May be null if only the derivative matrix is desired.

dstOff - 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:

org.opengis.referencing.operation.TransformException - if the point cannot be transformed or if a problem occurred while calculating the derivative.

See Also:

• AbstractMathTransform.derivative(DirectPosition)
• AbstractMathTransform.transform(DirectPosition, DirectPosition)
• MathTransforms.derivativeAndTransform(MathTransform, double[], int, double[], int)

transform

private void transform(SpecializableTransform.TransformCall transform,
 DirectPositionView src,
 int dstOff,
 int srcInc,
 int dstInc,
 int numPts)
                throws org.opengis.referencing.operation.TransformException

Transforms a list of coordinate tuples. This method delegates to the most specialized transform, with single transform(…) calls for coordinate sequences as long as possible.

Parameters:

transform - caller for a MathTransform.transform(…) method.

src - a window over the source points. May be backed by a float[] or double[] array.

dstOff - where to write the first coordinate in the target array.

srcInc - the source dimension, negative if we must iterate backward.

dstInc - the target dimension, negative if we must iterate backward.

numPts - number of points to transform.

Throws:

org.opengis.referencing.operation.TransformException

transform

public final void transform(double[] srcPts,
 int srcOff,
 double[] dstPts,
 int dstOff,
 int numPts)
                     throws org.opengis.referencing.operation.TransformException

Transforms a list of coordinate tuples. This method delegates to the most specialized transform.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - the array containing the source point coordinates.

srcOff - the offset to the first point to be transformed in the source array.

dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.

dstOff - the offset to the location of the first transformed point that is stored in the destination array.

numPts - the number of point objects to be transformed.

Throws:

org.opengis.referencing.operation.TransformException - if a point cannot 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 latter case should set the last completed transform to this.

transform

public final void transform(float[] srcPts,
 int srcOff,
 float[] dstPts,
 int dstOff,
 int numPts)
                     throws org.opengis.referencing.operation.TransformException

Transforms a list of coordinate tuples. This method delegates to the most specialized transform.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - the array containing the source point coordinates.

srcOff - the offset to the first point to be transformed in the source array.

dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.

dstOff - the offset to the location of the first transformed point that is stored in the destination array.

numPts - the number of point objects to be transformed.

Throws:

org.opengis.referencing.operation.TransformException - if a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the un-transformable points with Float.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to this.

transform

public final void transform(double[] srcPts,
 int srcOff,
 float[] dstPts,
 int dstOff,
 int numPts)
                     throws org.opengis.referencing.operation.TransformException

Transforms a list of coordinate tuples. This method delegates to the most specialized transform, with single transform(…) calls for coordinate sequences as long as possible.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - the array containing the source point coordinates.

srcOff - the offset to the first point to be transformed in the source array.

dstPts - the array into which the transformed point coordinates are returned.

dstOff - the offset to the location of the first transformed point that is stored in the destination array.

numPts - the number of point objects to be transformed.

Throws:

org.opengis.referencing.operation.TransformException - if a point cannot 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 latter case should set the last completed transform to this.

transform

public final void transform(float[] srcPts,
 int srcOff,
 double[] dstPts,
 int dstOff,
 int numPts)
                     throws org.opengis.referencing.operation.TransformException

Transforms a list of coordinate tuples. This method delegates to the most specialized transform, with single transform(…) calls for coordinate sequences as long as possible.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - the array containing the source point coordinates.

srcOff - the offset to the first point to be transformed in the source array.

dstPts - the array into which the transformed point coordinates are returned.

dstOff - the offset to the location of the first transformed point that is stored in the destination array.

numPts - the number of point objects to be transformed.

Throws:

org.opengis.referencing.operation.TransformException - if a point cannot 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 latter case should set the last completed transform to this.

computeHashCode

protected final int computeHashCode()

Computes a hash value for this transform. This method is invoked by AbstractMathTransform.hashCode() when first needed.

Overrides:

computeHashCode in class AbstractMathTransform

Returns:

the hash code value. This value may change between different execution of the Apache SIS library.

equals

public final boolean equals(Object object,
 ComparisonMode mode)

Compares the specified object with this math transform for equality.

Specified by:

equals in interface LenientComparable

Overrides:

equals in class AbstractMathTransform

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.deepEquals(Object, Object, ComparisonMode)

formatTo

protected final String formatTo(Formatter formatter)

Formats the inner part of a Well Known Text version 1 (WKT 1) element.

Compatibility note: The SPECIALIZABLE_MT element formatted here is an Apache SIS-specific extension.

Overrides:

formatTo in class AbstractMathTransform

Parameters:

formatter - the formatter to use.

Returns:

the WKT element name, which is "Specializable_MT".

See Also:

• DefaultMathTransformFactory.createFromWKT(String)

inverse

public org.opengis.referencing.operation.MathTransform inverse()
                                                        throws org.opengis.referencing.operation.NoninvertibleTransformException

Returns the inverse of this transform.

Specified by:

inverse in interface org.opengis.referencing.operation.MathTransform

Overrides:

inverse in class AbstractMathTransform

Throws:

org.opengis.referencing.operation.NoninvertibleTransformException

createInverse

SpecializableTransform.Inverse createInverse()
                                      throws org.opengis.referencing.operation.NoninvertibleTransformException

Invoked at construction time for creating the inverse transform. Overridden by SpecializableTransform2D for the two-dimensional variant.

Throws:

org.opengis.referencing.operation.NoninvertibleTransformException