Friday, March 27, 2015

FOSS4GNA Code Sprint Replacing Vecmath

As Torben indicated on the geoserver blog we got together for a one day sprint after the foss4gna conference. Torben stole my picture for that post so I will have to stick to content ...

Our topic of choice ... replacing vecmath. The use of vecmath library has been a long standing "technical debt" for GeoTools. How long standing? The issue tracker number is GEOT-22.

So what is the problem with vecmath

The vecmath.jar is used by gt-referencing for coordinate system transformations. We only uses a couple classes form the library: primarily to implement GeneralMatrix for use in MathTransforms.
GeneralMatrix extending GMatrix
There is one small problem with this idea - vecmath is not open source! Technically vecmath is distributed as part of Java 3D (an extensions to the Java Virtual Machine). As an extension to Java it was distributed under the same licenses (Sun Binary License and a Research License) as Java.

With the GeoGig project going through LocationTech incubation we have a couple ways to use jars:
  • prerequisite: open source jars required to run
  • works with: optional jars that extend the functionality if present. These may be proprietary like an oracle database driver.
Although the vecmath license is fine for distribution it does not meet the strictly open source policies required for the GeoGig project. In this case we want GeoTools to include matrix math and needed to shop around for a replacement.

The use of vecmath (as a non open source dependency) also causes trouble for Rich Fecher's proposal to publish GeoTools on Maven Central. 

Enter EJML

With a technical dept page capturing research, some email discussion and a great lunchtime conversation at foss4gna with Eric Engle (the overlap with EclipseCon was good for something) we settled on the recommended Efficient Java Matrix Library (EJML).

GeneralMatrix delegating to DenceMatrix64F
The strategy here is delegate to the DenseMatrix64F implementation provided by EJML, and implement the methods we expect from XMatrix in terms of this new implementation.

The EJML library has the similar arrangement with SimpleMatrix wrapping a DenseMatrix64F an API friendly to casual developers. We were able to use SimpleMatrix as a guide, saving a lot of time.

How to help

While the code sprint was a success in proving the approach, there is a bit of work to go:
  • Tyler (from GeoGig) is working on removing the dependency on vecmath (there are a few other Exceptions and data structures in our API that need to be removed).
  • Jim (from GeoMesa) wants to write up more test cases to check for regressions between vecmath and EJML
  • Although Rich Fecher (from GeoWave) was unavailable to take part in the code sprint - his inspiration to work on this now means we will be hitting him up for a review when the work is complete. Thanks Rich!
  • And there is always the question of performance ... will it be faster!
To help take part, or review our work see this branch in github:
Thanks to Boundless victoria staff, Jim and Andrea for really getting behind this work. This kind of up keep keeps the community ticking along and helps the library be used in more places.

I would also like to thank the new crop of projects using GeoTools for taking part and contributing upstream. It is important to keep our community diverse and your participation is both welcomed and appreciated.


  1. Awesome collaboration! Really great to see. Thanks so much.

  2. Awesome collaboration! Really great to see. Thanks so much.