Module ffmbindings.eigen

module ffmbindings.eigen
Java FFM bindings to eigen

ffmbindings.eigen provides FFM memory layout definitions to some of Eigen classes. It allows:

  • create Eigen matrices, vectors directly from Java primitive arrays without need to call any native functions (no JNI or FFM downcalls).
  • pass created Eigen objects to native functions (works for both JNI and FFM)
  • map Java Eigen classes directly to Eigen objects which were created in native side
  • access values inside Eigen objects directly from Java and update them

Many C++ libraries (for ML, robotics, CV, ...) use Eigen types as part of their APIs. With ffmbindings.eigen it is possible to interact with such APIs directly from Java.

For example, imagine if we want to call C++ library API function CppLibrary::call which accepts transformation matrix (in Eigen::Matrix4d format) as a parameter: 


 var tx = createEigenMatrix4d(new double[] {
    1, 0, 0, 0,
    0, 1, 0, 0,
    0, 0, 1, 0,
    0, 0, 0, 1});
 CppLibrary.call(tx);

Previously createEigenMatrix4d would end up calling a JNI function to create Eigen::Matrix4d, populate it with input values and return pointer to newly created Eigen::Matrix4d object back to Java. Having JNI function to do that has a lot of drawbacks:

  • need to maintain one more native library for it
  • calls from Java to native and back affects performance
  • need to make sure to release the pointer to Eigen::Matrix4d at the end (which most likely would mean calling another JNI function)

With ffmbindings.eigen there is no need for separate native library as it allows to allocate new memory for Eigen::Matrix4d and populate it directly from Java. Additionally there is no need to manually release the pointer as GC will take care of that (ffmbindings.eigen relies on Arena.ofShared()).

ffmbindings.eigen does not provide bindings to Eigen operations (like multiplication etc). Instead its goal is to provide mapping to Eigen objects in memory (using FFM). This allows to create Eigen objects from Java similar to how they are created by Eigen itself and access its data values.

Usage

  • Eigen objects are created with factory classes (EigenMatrix3dFactory, EigenVector2iFactory etc)

  • Some of ffmbindings.eigen API (like mapTo factory methods etc.) require native access be enabled in the JVM: --enable-native-access=ffmbindings.eigen

See Also: