This is an automated email from the ASF dualhosted git repository.
desruisseaux pushed a commit to branch geoapi4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
commit 40a34e92c5ac6aca03076d40a36a693d5c24410f
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Fri Apr 12 12:22:58 2019 +0200
Add explanation about the "compute linear regression in reverse way" approach that we
reverted in previous commit, so if we want to try it again we know which commit to revert.

.../sis/referencing/operation/builder/readme.html  48 ++++++++++++++++++++++
1 file changed, 48 insertions(+)
diff git a/core/sisreferencing/src/main/java/org/apache/sis/referencing/operation/builder/readme.html
b/core/sisreferencing/src/main/java/org/apache/sis/referencing/operation/builder/readme.html
new file mode 100644
index 0000000..bef92a0
 /dev/null
+++ b/core/sisreferencing/src/main/java/org/apache/sis/referencing/operation/builder/readme.html
@@ 0,0 +1,48 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Implementation notes</title>
+ <meta charset="UTF8">
+ <style>
+ p {
+ textalign: justify;
+ }
+ </style>
+ </head>
+ <body>
+ <h1>Implementation notes</h1>
+ <h2>Choice of errors in linear regression method</h2>
+ <p>
+ Before to compute a localization grid, <code>LocalizationGridBuilder</code>
+ first computes an <em>affine transform</em> from grid indices to geospatial
coordinates.
+ That affine transform is an approximation computed by linear regression using leastsquares
method.
+ In an equation of the form <var>y</var> = <var>C₀</var> + <var>C₁</var> × <var>x</var>
+ where the <var>C₀</var> and <var>C₁</var> coefficients
are determined by linear regression,
+ typical linear regression method assumes that <var>x</var> values are exact
and all errors are in <var>y</var> values.
+ Applied to the <code>LocalizationGridBuilder</code> context, it means that
linear regression method
+ assumes that grid indices are exact and all errors are in geospatial coordinates.
+ This is a reasonable assumption if the linear regression is used directly.
+ But in <code>LocalizationGridBuilder</code> context, having the smallest
errors on geospatial coordinates
+ may not be so important because those errors are corrected by the residual grids during
<em>forward</em> transformations.
+ However during <em>inverse</em> transformations, it may be useful that
grid indices estimated by the linear regression
+ are as close as possible to the real grid indices in order to allow iterations to converge
faster
+ (such iterations exist only in inverse operations, not in forward operations).
+ For that reason, <code>LocalizationGridBuilder</code> may want to minimize
errors on grid indices instead than geospatial coordinates.
+ We can achieve this result by computing linear regression coefficients for an equation
of the form
+ <var>x</var> = <var>C₀</var> + <var>C₁</var> × <var>y</var>,
then inverting that equation.
+ This approach was attempted in a previous version and gave encouraging results, but
we nevertheless reverted that change.
+ One reason is that even if inverting the linear regression calculation allowed iterations
to converge more often with curved
+ localization grids, it was not sufficient anyway: we still had too many cases where
inverse transformations did not converge.
+ Since a more sophisticated iteration method is needed anyway, we can avoid the additional
complexity introduced by application
+ of linear regression in reverse way. Some examples of additional complexities were
<code>LinearTransformBuilder.correlation()</code>
+ getting a meaning different than what its Javadoc said (values for each source dimensions
instead than target dimensions),
+ additional constraints brought by that approach (source coordinates must be a twodimensional
grid,
+ source and target dimensions must be equal in order to have a square matrix), <i>etc.</i>
+ A more minor reason is that keeping the original approach (minimize errors on geospatial
coordinates) help to improve accuracy
+ by resulting in storage of smaller values in <code>float[]</code> arrays
of <code>ResidualGrid</code>.
+ </p>
+ <p>
+ For experimenting linear regressions in the reverse way, revert commit <code>c0944afb6e2cd77194ea71504ce6d74b651f72b7</code>.
+ </p>
+ </body>
+</html>
