change from vecmath to ejml

Details:

• Contact: tyler
• Tracker: GEOT-22
• Tagline: matrix magic
• Branch: https://github.com/geotools/geotools/tree/matrix

Description

We have a long standing technical debt to Replace Vecmath (see link for technical and license reasons). The EJML has been suggested as a good alternative for the project. This task is a blocker for Publish to Maven Central Repository and will need to be resolved for GeoGig and uDig incubation with LocationTech.

We have two uses of vecmath:

• As a data structure GeneralMatrix (which extends GMatrix) with the operations that are used are multiply, invert, negate, and transform.
• Delegating to Matrix3d.multiply and Matrix4d.muiltiply

References:

• Replace Vecmath
• efficient-java-matrix-library
• geotools-devel email discussion
• SimpleMatrix (javadoc)
• SimpleMatrix.java (src)

Status

This proposal is under construction.

Voting has not started yet:

• Andrea Aime +1
• Ben Caradoc-Davies +1
• Christian Mueller +1
• Ian Turton
• Justin Deoliveira +1
• Jody Garnett
• Simone Giannecchini

Tasks

2. ✅ Add dependency on EJML and use SimpleMatrix for the two cases where we need to delegate a 3D and 4D Matrix
3. ✅ Change GeneralMatrix to delegate to DenseMatrix64F (using SimpleMatrix / BaseMatrix as a guide on how to do this).
4. ✅ Implement the XMatrix and Matrix (for method compatibility) using the DenseMatrix64F delegate
5. ✅ Remove the pom.xml dependency on vecmath.
6. ✅ replace other uses of vecmath classes (in org.geotools.math.Line and org.geotools.math.Plane classes)
   1. Point3d - can probably use one of the java classes or roll our own here
   2. Change from MismatchedSizeException to IllegalArgumentException
7. ✅ Ask downstream applications for a sanity check
   • GeoServer: GEOS-7009 two regressions based on accuracy change
   • GeoMesa
   • GeoWave
   • uDig
8. ✅ Warn users about the change in the update instructions

API Changes

GeneralMatrix

BEFORE:

    public class GeneralMatrix extends GMatrix implements XMatrix {
        public GeneralMatrix(final int size) {
            super(size, size);
        }
        public GeneralMatrix(final int numRow, final int numCol) {
            super(numRow, numCol);
        }
        // public void invert() provided by superclass
    }

AFTER:

    public class GeneralMatrix implements XMatrix {
        DenseMatrix64F mat;
        public GeneralMatrix(final int size) {
            super(size, size);
        }
        public GeneralMatrix(final int numRow, final int numCol) {
            mat = new DenseMatrix64F( numRows, numCol);
        }
        // invert matrix in place (no copy)
        public void invert() {
            if( !CommonOps.invert(mat,mat) ) {
                throw new SingularMatrixException();
            }
       }
       ...
    }

Documentation Changes

No documentation changes are expected.