public abstract class AbstractMathTransform extends FormattableObject implements MathTransform, Parameterized, LenientComparable
MathTransform
interface.
A MathTransform
is an object that actually does the work of applying a
formula to coordinate values.
The math transform does not know or care how the coordinates relate to positions in the real world.
For example if an affine transform scales z values by a factor of 1000,
then it could be converting metres to millimetres, or it could be converting kilometres to metres.
AbstractMathTransform
provides a convenient base class from which MathTransform
implementations
can be easily derived. It also defines a few additional SIS-specific methods for convenience of performance.
The simplest way to implement this abstract class is to provide an implementation for the following methods only:
transform(…)
methods as well.
MathTransform
are immutable and thread-safe.
It is highly recommended that third-party implementations be immutable and thread-safe too.
This means that unless otherwise noted in the javadoc, MathTransform
instances can
be shared by many objects and passed between threads without synchronization.
MathTransform
may or may not be serializable, at implementation choices.
Most Apache SIS implementations are serializable, but the serialized objects are not guaranteed to be compatible
with future SIS versions. Serialization should be used only for short term storage or RMI between applications
running the same SIS version.DefaultMathTransformFactory
,
AbstractCoordinateOperation
Defined in the sis-referencing
module
Modifier and Type | Class and Description |
---|---|
protected class |
AbstractMathTransform.Inverse
Base class for implementations of inverse math transforms.
|
Modifier | Constructor and Description |
---|---|
protected |
AbstractMathTransform()
Constructor for subclasses.
|
Modifier and Type | Method and Description |
---|---|
protected int |
computeHashCode()
Computes a hash value for this transform.
|
Matrix |
derivative(DirectPosition point)
Gets the derivative of this transform at a point.
|
boolean |
equals(Object object)
Compares the specified object with this math transform for strict equality.
|
boolean |
equals(Object object,
ComparisonMode mode)
Compares the specified object with this math transform for equality.
|
protected String |
formatTo(Formatter formatter)
Formats the inner part of a Well Known Text version 1 (WKT 1) element.
|
protected ContextualParameters |
getContextualParameters()
Returns the parameters for a sequence of normalize →
this → denormalize
transforms (optional operation). |
ParameterDescriptorGroup |
getParameterDescriptors()
Returns the parameter descriptors for this math transform, or
null if unknown. |
ParameterValueGroup |
getParameterValues()
Returns the parameter values for this math transform, or
null if unknown. |
abstract int |
getSourceDimensions()
Gets the dimension of input points.
|
abstract int |
getTargetDimensions()
Gets the dimension of output points.
|
int |
hashCode()
Returns a hash value for this transform.
|
MathTransform |
inverse()
Returns the inverse transform of this object.
|
boolean |
isIdentity()
Tests whether this transform does not move any points.
|
DirectPosition |
transform(DirectPosition ptSrc,
DirectPosition ptDst)
Transforms the specified
ptSrc and stores the result in ptDst . |
abstract Matrix |
transform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff,
boolean derivate)
Transforms a single coordinate point in an array, and optionally computes the transform
derivative at that location.
|
void |
transform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff,
int numPts)
Transforms a list of coordinate points.
|
void |
transform(double[] srcPts,
int srcOff,
float[] dstPts,
int dstOff,
int numPts)
Transforms a list of coordinate points.
|
void |
transform(float[] srcPts,
int srcOff,
double[] dstPts,
int dstOff,
int numPts)
Transforms a list of coordinate points.
|
void |
transform(float[] srcPts,
int srcOff,
float[] dstPts,
int dstOff,
int numPts)
Transforms a list of coordinate points.
|
protected MathTransform |
tryConcatenate(boolean applyOtherFirst,
MathTransform other,
MathTransformFactory factory)
Concatenates or pre-concatenates in an optimized way this math transform with the given one, if possible.
|
print, toString, toString, toWKT
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
toWKT
protected AbstractMathTransform()
public abstract int getSourceDimensions()
getSourceDimensions
in interface MathTransform
DefaultOperationMethod.getSourceDimensions()
public abstract int getTargetDimensions()
getTargetDimensions
in interface MathTransform
DefaultOperationMethod.getTargetDimensions()
public ParameterDescriptorGroup getParameterDescriptors()
null
if unknown.
OperationMethod.getParameters()
, except that typical
MathTransform
implementations return parameters in standard units (usually
metres or
decimal degrees).
getParameterDescriptors
in interface Parameterized
null
if unspecified.DefaultOperationMethod.getParameters()
public ParameterValueGroup getParameterValues()
null
if unknown.
This is not necessarily the parameters that the user specified at construction time,
since implementations may have applied normalizations.
"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 getContextualParameters()
.getParameterValues
in interface Parameterized
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).getContextualParameters()
,
AbstractSingleOperation.getParameterValues()
protected ContextualParameters getContextualParameters()
this
→ denormalize
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 MathTransform
represents only the non-linear step and Apache SIS
needs this method for reconstructing the parameters of the complete transform.this
→ denormalize
transforms, or null
if unspecified.
Callers should not modify the returned parameters, since modifications (if allowed)
will generally not be reflected back in this MathTransform
.public boolean isIdentity()
false
.isIdentity
in interface MathTransform
public DirectPosition transform(DirectPosition ptSrc, DirectPosition ptDst) throws TransformException
ptSrc
and stores the result in ptDst
.
The default implementation performs the following steps:
transform(double[], int, double[], int, boolean)
method.CoordinateReferenceSystem
value.transform
in interface MathTransform
ptSrc
- the coordinate point to be transformed.ptDst
- the coordinate point that stores the result of transforming ptSrc
, or null
.ptSrc
and storing the result in ptDst
,
or a newly created point if ptDst
was null.MismatchedDimensionException
- if ptSrc
or ptDst
doesn't have the expected dimension.TransformException
- if the point can not be transformed.public abstract Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws TransformException
Matrix derivative = null; if (derivate) { double[] ordinates = Arrays.copyOfRange(srcPts, srcOff, srcOff + getSourceDimensions()); derivative = this.derivative(new GeneralDirectPosition(ordinates)); } this.transform(srcPts, srcOff, dstPts, dstOff, 1); // May overwrite srcPts. return derivative;However this method provides two advantages:
AbstractMathTransform
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.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.srcPts
- the array containing the source coordinate (can not be null
).srcOff
- the offset to the point to be transformed in the source array.dstPts
- the array into which the transformed coordinate 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.null
if the derivate
argument is false
.TransformException
- if the point can not be transformed or
if a problem occurred while calculating the derivative.derivative(DirectPosition)
,
transform(DirectPosition, DirectPosition)
,
MathTransforms.derivativeAndTransform(MathTransform, double[], int, double[], int)
public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
transform(double[], int, double[], int, boolean)
in a loop,
using an iteration strategy determined from the arguments for iterating
over the points.
IterationStrategy
javadoc for a method skeleton.transform
in interface MathTransform
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.TransformException
- 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
.public void transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws TransformException
transform(double[], int, double[], int, int)
using a temporary array of doubles.
IterationStrategy
javadoc for a method skeleton.transform
in interface MathTransform
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.TransformException
- 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.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
.public void transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws TransformException
transform(double[], int, double[], int, int)
using a temporary array of doubles.transform
in interface MathTransform
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.TransformException
- 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
.public void transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
transform(double[], int, double[], int, int)
using a temporary array of doubles
if necessary.transform
in interface MathTransform
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.TransformException
- 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
.public Matrix derivative(DirectPosition point) throws TransformException
point
dimension is equals to this math transform
source dimensions.transform(double[], int, double[], int, boolean)
method,
with the derivate
boolean argument set to true
.TransformException
.derivative
in interface MathTransform
point
- the coordinate point where to evaluate the derivative.null
).NullPointerException
- if the derivative depends on coordinate and point
is null
.MismatchedDimensionException
- if point
does not have the expected dimension.TransformException
- if the derivative can not be evaluated at the specified point.public MathTransform inverse() throws NoninvertibleTransformException
this
if this transform is an identity transform,
or throws an exception otherwise. Subclasses should override this method.
AbstractMathTransform.Inverse
inner class can be used as
a base for inverse transform implementations.inverse
in interface MathTransform
NoninvertibleTransformException
protected MathTransform tryConcatenate(boolean applyOtherFirst, MathTransform other, MathTransformFactory factory) throws FactoryException
applyOtherFirst
value determines the transformation order as bellow:
applyOtherFirst
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
.applyOtherFirst
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
.null
.
In the later case, the concatenation will be prepared by DefaultMathTransformFactory
using a generic
implementation.
The default implementation always returns null
. This method is ought to be overridden
by subclasses capable of concatenating some combination of transforms in a special way.
applyOtherFirst
- 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.null
if no such optimization is available.FactoryException
- if an error occurred while combining the transforms.DefaultMathTransformFactory.createConcatenatedTransform(MathTransform, MathTransform)
public final int hashCode()
computeHashCode()
when first needed and caches the value for future invocations. Subclasses shall override
computeHashCode()
instead than this method.protected int computeHashCode()
hashCode()
when first needed.public final boolean equals(Object object)
return equals(other, ComparisonMode.STRICT);
equals
in interface LenientComparable
equals
in class Object
object
- the object to compare with this transform.true
if the given object is a transform of the same class and using the same parameter values.ComparisonMode.STRICT
public boolean equals(Object object, ComparisonMode mode)
false
if unsure.
The default implementation returns true
if the following conditions are meet:
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.equals
in interface LenientComparable
object
- the object to compare with this transform.mode
- the strictness level of the comparison. Default to STRICT
.true
if the given object is considered equals to this math transform.Utilities.deepEquals(Object, Object, ComparisonMode)
protected String formatTo(Formatter formatter)
getParameterValues()
.
The parameter group name is used as the math transform name.
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 MathTransform
can not be formatted as valid WKT 1 neither).formatTo
in class FormattableObject
formatter
- the formatter to use."Param_MT"
in the default implementation.FormattableObject.toWKT()
,
FormattableObject.toString()
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.