Class LinearTransformBuilder
 Object

 TransformBuilder

 LinearTransformBuilder

public class LinearTransformBuilder extends TransformBuilder
Creates an affine transform which will map approximately the given source positions to the given target positions. In many cases, the source positions are grid indices and the target positions are geographic or projected coordinates, but this is not mandatory. If the source positions are known to be grid indices, then a builder created by theLinearTransformBuilder(int...)
constructor will be more efficient. Otherwise a builder created by theLinearTransformBuilder()
constructor will be able to handle randomly distributed coordinates.Builders are not threadsafe. Builders can be used only once; points can not be added or modified after
create(MathTransformFactory)
has been invoked. The transform coefficients are determined using a least squares estimation method, with the assumption that source positions are exact and all the uncertainty is in the target positions.LinearizersConsider the following situation (commonly found with netCDF files): the sources coordinates are pixel indices and the targets are (longitude, latitude) coordinates, but we suspect that the sources to targets transform is some undetermined map projection, maybe Mercator. A linear approximation between those coordinates will give poor results; the results would be much better if all (longitude, latitude) coordinates were converted to the right projection first. However that map projection may not be known, but we can try to guess it by trialsanderrors using a set of plausible projections. That set can be specified byaddLinearizers(Map, int...)
. If thecreate(MathTransformFactory)
method finds that one of the specified projections seems a good fit, it will automatically convert all target coordinates to that projection. That selected projection is given bylinearizer()
. Since:
 0.5
 See Also:
LocalizationGridBuilder
,LinearTransform
,Line
,Plane
Defined in the
sisreferencing
module


Constructor Summary
Constructors Constructor Description LinearTransformBuilder()
Creates a new linear transform builder for randomly distributed positions.LinearTransformBuilder(int... gridSize)
Creates a new linear transform builder for source positions distributed on a regular grid.

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addLinearizers(Map<String,MathTransform> projections, int... projToGrid)
Adds transforms to potentially apply on target coordinates before to compute the linear transform.double[]
correlation()
Returns the Pearson correlation coefficients of the transform created bycreate(…)
.LinearTransform
create(MathTransformFactory factory)
Creates a linear transform approximation from the source positions to the target positions.double[]
getControlPoint(int[] source)
Returns a single target coordinate for the given source coordinate, ornull
if none.Map<DirectPosition,DirectPosition>
getControlPoints()
Returns all control points as a map.int
getSourceDimensions()
Returns the number of dimensions in source positions.Envelope
getSourceEnvelope()
Returns the envelope of source points (keys of the map returned bygetControlPoints()
).int
getTargetDimensions()
Returns the number of dimensions in target positions.Envelope
getTargetEnvelope()
Returns the envelope of target points (values of the map returned bygetControlPoints()
).Optional<MathTransform>
linearizer()
If target coordinates have been projected to another space, returns that projection.void
setControlPoint(int[] source, double[] target)
Sets a single matching control point pair.void
setControlPoints(Map<? extends Position,? extends Position> sourceToTarget)
Sets all matching control point pairs, overwriting any previous setting.String
toString()
Returns a string representation of this builder for debugging purpose.



Constructor Detail

LinearTransformBuilder
public LinearTransformBuilder()
Creates a new linear transform builder for randomly distributed positions.Tip: if the source coordinates are grid indices, then theLinearTransformBuilder(int...)
constructor will create a more efficient builder.

LinearTransformBuilder
public LinearTransformBuilder(int... gridSize)
Creates a new linear transform builder for source positions distributed on a regular grid. This constructor notifiesLinearTransformBuilder
that coordinate values of all source positions will be integers in the [0 …gridSize[0]
1] range for the first dimension (typically column indices), in the [0 …gridSize[1]
1] range for the second dimension (typically row indices), etc. The dimension of all source positions is the length of the givengridSize
array.An empty array is equivalent to invoking the noargument constructor, i.e. no restriction is put on the source coordinates.
 Parameters:
gridSize
 the number of integer coordinate values in each grid dimension. Throws:
IllegalArgumentException
 if a grid size is not strictly positive, or if the product of all values (∏gridSize
) is greater thanInteger.MAX_VALUE
. Since:
 0.8


Method Detail

getSourceDimensions
public int getSourceDimensions()
Returns the number of dimensions in source positions. This is the length of thesource
array given in argument toget
/setControlPoint(int[], …)
methods. This is also the number of dimensions of theDirectPosition
keys in theMap
exchanged byget
/setControlPoints(Map)
methods. Returns:
 the dimension of source points.
 Throws:
IllegalStateException
 if the number of source dimensions is not yet known. Since:
 0.8
 See Also:
MathTransform.getSourceDimensions()

getTargetDimensions
public int getTargetDimensions()
Returns the number of dimensions in target positions. This is the length of thetarget
array exchanged byget
/setControlPoint(…, double[])
methods. This is also the number of dimensions of theDirectPosition
values in theMap
exchanged byget
/setControlPoints(Map)
methods. Returns:
 the dimension of target points.
 Throws:
IllegalStateException
 if the number of target dimensions is not yet known. Since:
 0.8
 See Also:
MathTransform.getTargetDimensions()

getSourceEnvelope
public Envelope getSourceEnvelope()
Returns the envelope of source points (keys of the map returned bygetControlPoints()
). The number of dimensions is equal togetSourceDimensions()
. This method returns the known minimum and maximum values (inclusive) for each dimension, not expanded to encompass full cell surfaces. In other words, the returned envelope encompasses only cell centers.If a grid size was
specified at construction time
, then those minimums and maximums are inferred from the grid size and are always integer values. Otherwise, the minimums and maximums are extracted from the control points and may be any floating point values. In any cases, the lower and upper values are inclusive. Returns:
 the envelope of source points (cell centers), inclusive.
 Throws:
IllegalStateException
 if the source points are not yet known. Since:
 1.0

getTargetEnvelope
public Envelope getTargetEnvelope()
Returns the envelope of target points (values of the map returned bygetControlPoints()
). The number of dimensions is equal togetTargetDimensions()
. The lower and upper values are inclusive. If a linearizer has been applied, then coordinates of the returned envelope are projected by that linearizer. Returns:
 the envelope of target points.
 Throws:
IllegalStateException
 if the target points are not yet known. Since:
 1.0

setControlPoints
public void setControlPoints(Map<? extends Position,? extends Position> sourceToTarget) throws MismatchedDimensionException
Sets all matching control point pairs, overwriting any previous setting. The source positions are the keys in the given map, and the target positions are the associated values in the map. The map should not contain two entries with the same source position. Coordinate reference systems are ignored. Null positions are silently ignored. Positions with NaN or infinite coordinates cause an exception to be thrown.All source positions shall have the same number of dimensions (the source dimension), and all target positions shall have the same number of dimensions (the target dimension). However the source dimension does not need to be the same than the target dimension. Apache SIS currently supports only one or twodimensional source positions, together with arbitrary target dimension.
If this builder has been created with the
LinearTransformBuilder(int...)
constructor, then the coordinate values of all source positions shall be integers in the [0 …gridSize[0]
1] range for the first dimension (typically column indices), in the [0 …gridSize[1]
1] range for the second dimension (typically row indices), etc. This constraint does not apply for builders created with theLinearTransformBuilder()
constructor. Parameters:
sourceToTarget
 a map of source positions to target positions. Source positions are assumed precise and target positions are assumed uncertain. Throws:
IllegalStateException
 ifcreate(…)
has already been invoked.IllegalArgumentException
 if the given positions contain NaN or infinite coordinate values.IllegalArgumentException
 if this builder has been created for a grid but some source coordinates are not indices in that grid.MismatchedDimensionException
 if some positions do not have the expected number of dimensions. Since:
 0.8

getControlPoints
public Map<DirectPosition,DirectPosition> getControlPoints()
Returns all control points as a map. Values are source coordinates and keys are target coordinates. The map is unmodifiable and is guaranteed to contain only nonnull keys and values. The map is a view: changes in this builder are immediately reflected in the returned map.If
linearizer()
returns a nonempty value, then the values in the returned map are projected using that linearizer. This may happen only aftercreate(…)
has been invoked. Returns:
 all control points in this builder.
 Since:
 1.0

setControlPoint
public void setControlPoint(int[] source, double[] target)
Sets a single matching control point pair. Source position is assumed precise and target position is assumed uncertain. If the given source position was already associated with another target position, then the old target position is discarded.Performance note: current implementation is efficient for builders created for a grid but inefficient for builders created for randomly distributed points. In the later case, thesetControlPoints(Map)
method is a more efficient alternative. Parameters:
source
 the source coordinates. If this builder has been created with theLinearTransformBuilder(int...)
constructor, then for every index i thesource[i]
value shall be in the [0 …gridSize[i]
1] range inclusive. If this builder has been created with theLinearTransformBuilder()
constructor, then no constraint apply.target
 the target coordinates, assumed uncertain. Throws:
IllegalStateException
 ifcreate(…)
has already been invoked.IllegalArgumentException
 if this builder has been created for a grid but some source coordinates are out of index range, or iftarget
contains NaN of infinite numbers.MismatchedDimensionException
 if the source or target position does not have the expected number of dimensions. Since:
 0.8

getControlPoint
public double[] getControlPoint(int[] source)
Returns a single target coordinate for the given source coordinate, ornull
if none. This method can be used for retrieving points set by previous calls tosetControlPoint(int[], double[])
orsetControlPoints(Map)
.If
linearizer()
returns a nonempty value, then the returned values are projected using that linearizer. This may happen only if this method is invoked aftercreate(…)
.Performance note: current implementation is efficient for builders created for a grid but inefficient for builders created for randomly distributed points. Parameters:
source
 the source coordinates. If this builder has been created with theLinearTransformBuilder(int...)
constructor, then for every index i thesource[i]
value shall be in the [0 …gridSize[i]
1] range inclusive. If this builder has been created with theLinearTransformBuilder()
constructor, then no constraint apply. Returns:
 the target coordinates associated to the given source, or
null
if none.  Throws:
IllegalArgumentException
 if this builder has been created for a grid but some source coordinates are out of index range.MismatchedDimensionException
 if the source position does not have the expected number of dimensions. Since:
 0.8

addLinearizers
public void addLinearizers(Map<String,MathTransform> projections, int... projToGrid)
Adds transforms to potentially apply on target coordinates before to compute the linear transform. This method can be invoked if one suspects that the source to target transform may be more linear when the target is another space than the current space of target coordinates. If linearizers have been specified, then thecreate(MathTransformFactory)
method will try to apply each transform on target coordinates and check which one results in the best correlation coefficients. It may be none.The linearizers are specified as
MathTransform
s from current target coordinates to other spaces where sources to new targets transforms may be more linear. Keys in the map are arbitrary identifiers used intoString()
for debugging purpose. Values in the map are nonLinearTransform
s (linear transforms are not forbidden, but are useless for this process).The
projToGrid
argument mapsprojections
dimensions to this builder target dimensions. For example ifprojToGrid
array is{2,1}
, then dimensions 0 and 1 of givenprojections
(both source and target dimensions) will map to dimensions 2 and 1 of this builder target dimensions, respectively. TheprojToGrid
argument can be omitted or null, in which {0, 1, 2 …getTargetDimensions()
 1} is assumed. All givenprojections
shall have a number of source and target dimensions equals to the length of the given or assumedprojToGrid
array. It is possible to invoke this method many times with differentprojToGrid
argument values. Parameters:
projections
 projections from current target coordinates to other spaces which may result in more linear transforms.projToGrid
 the target dimensions to project, or null or omitted for projecting all target dimensions. Throws:
IllegalStateException
 ifcreate(…)
has already been invoked. Since:
 1.0
 See Also:
linearizer()
,correlation()

create
public LinearTransform create(MathTransformFactory factory) throws FactoryException
Creates a linear transform approximation from the source positions to the target positions. This method assumes that source positions are precise and that all uncertainty is in the target positions. If linearizers have been specified, then this method may project all target coordinates using one of those linearizers in order to get a more linear transform. If such projection is applied, thenlinearizer()
will return a nonempty value after this method call.If this method is invoked more than once, the previously created transform instance is returned.
 Specified by:
create
in classTransformBuilder
 Parameters:
factory
 the factory to use for creating the transform, ornull
for the default factory. TheMathTransformFactory.createAffineTransform(Matrix)
method of that factory shall returnLinearTransform
instances. Returns:
 the fitted linear transform.
 Throws:
FactoryException
 if the transform can not be created, for example because the source or target points have not be specified. Since:
 0.8

linearizer
public Optional<MathTransform> linearizer()
If target coordinates have been projected to another space, returns that projection. This method returns a nonempty value only if all the following conditions are met:addLinearizers(Map, int...)
has been invoked.create(MathTransformFactory)
has been invoked. The
create(…)
method at step 2 found that projecting target coordinates using one of the linearizers specified at step 1 results in a more linear transform.
getTargetEnvelope()
and all control points returned bygetControlPoint(int[])
are projected by this transform. The returned transform includes axes swapping specified by thedimensions
argument given toaddLinearizers(…, dimensions)
. Returns:
 the projection applied on target coordinates before to compute a linear transform.
 Since:
 1.0

correlation
public double[] correlation()
Returns the Pearson correlation coefficients of the transform created bycreate(…)
. The closer those coefficients are to +1 or 1, the better the fit. This method returnsnull
ifcreate(…)
has not yet been invoked. If nonnull, the array length is equal to the number of target dimensions. Returns:
 estimation of Pearson correlation coefficients for each target dimension,
or
null
ifcreate(…)
has not been invoked yet.

toString
public String toString()
Returns a string representation of this builder for debugging purpose. Current implementation shows the following information: Number of points.
 Linearizers and their correlation coefficients (if available).
 The linear transform (if already computed).

