Visual Servoing Platform  version 3.4.1 under development (2021-05-18)
Tutorial: First java application with ViSP

Introduction

We assume that you have already followed the previous tutorial Tutorial: Installing ViSP for Java.

This tutorial will guide you through the creation of a simple Java console application using ViSP library in Eclipse.

Create a new project

Open Eclipse and create a new Java project entering "File > New > Java Project" menu.

img-tutorial-java-eclipse-create-new-project.jpeg

In the "New Java Project" dialog write the name of your project (let say visp-java-started). In JRE section, select the appropriate execution environment (JavaSE-11 if you install JDK 11, or JavaSE-15 if you install JDK 15). Then press "Finish" button.

img-tutorial-java-eclipse-java-started.jpeg

In the "New module-info.java" dialog that may appear, press "Don't Create" button.

img-tutorial-java-eclipse-dont-create.jpeg

Add a user library

If you followed Tutorial: Installing ViSP for Java, you should already have ViSP library set in your workspace’s user libraries; if not please check out Tutorial: Installing ViSP for Java. Now you should be ready to add ViSP library to your project.

  • Inside Eclipse’s Package Explorer just right-click on your project’s folder and go to "Build Path > Add Libraries...".
img-tutorial-java-eclipse-add-libraries.jpeg
  • Select "User Library" and click on "Next":
img-tutorial-java-eclipse-add-libraries2.jpeg
  • Check the checkbox of the ViSP library and press "Finish" button. At this point, if you don't see visp, it means that you didn't follow the section Creating a user library.
img-tutorial-java-eclipse-add-libraries3.jpeg

Create a simple application

To create a simple application that uses ViSP:

  • First add a new class to your project by right-clicking on your project’s folder and entering "New > Class" menu.
img-tutorial-java-eclipse-new-class.jpeg
  • Then choose a class name like Started and press "Finish" button.
img-tutorial-java-eclipse-new-class2.jpeg

Now we are ready to add the code of our first application in Started.java file. The code of the Started class is the following:

import org.visp.core.VpCameraParameters;
import org.visp.core.VpColVector;
import org.visp.core.VpImageRGBa;
import org.visp.core.VpImageUChar;
import org.visp.core.VpMatrix;
import org.visp.core.VpRGBa;
public class Started {
static {
System.loadLibrary("visp_java340");
}
public static void main(String[] args) {
// VpMatrix
VpMatrix vp = new VpMatrix(2,3,1.5);
System.out.println(vp.getCol(0));
System.out.println(vp.transpose());
// VpColVector
VpColVector vpColVector = new VpColVector(10,1.5);
System.out.println(vpColVector.infinityNorm());
// VpImageUChar
VpImageUChar imageUChar = new VpImageUChar(2, 4, (byte)220);
System.out.println(imageUChar);
// VpImageRGBa
VpImageRGBa colorImage = new VpImageRGBa(3, 5, new VpRGBa((char)255,(char)0,(char)0,(char)255));
System.out.println(colorImage);
// VpCameraParameters
VpCameraParameters vpCameraParameters = new VpCameraParameters(1.0, 1.0, 1.0, 1.0);
System.out.println(vpCameraParameters.get_K());
}
}
  • As you can see, at the beginning we import the main classes part of core module (VpCameraParameters, VpColVector, VpImageRGBa, VpImageUChar, VpMatrix and VpRGBa). Then we load visp_java library. After we continue defining the main() method that shows how to manipulate ViSP classes in Java.
  • Now you should copy/paste the code in your visp-java-started project in Started.java file to have something similar to:
img-tutorial-java-eclipse-started-code.jpeg
  • You can now try to build and run this application entering"Run > Run" menu. You should have the following output:
img-tutorial-java-eclipse-started-console.jpeg

Known issues

Exception Unsupported Class Version Error

As shown in the next image, if you get the following issue on Ubuntu 18.04:

Exception in thread "main" java.lang.UnsupportedClassVersionError: org/visp/core/VpMatrix has been compiled by a more recent version of the Java Runtime (class file version 57.0), this version of the Java Runtime only recognizes class file versions up to 55.0
img-tutorial-java-issue-jdk-version.jpg

it means probably that you use JRE System Library 11 installed in /usr/lib/jvm/java-1.11.0-openjdk-amd64 while ViSP is build with a more recent java version obtained after downloading JDK 13 for example.

To fix this issue, as explained in Tutorial: Installing ViSP for Java install JDK 11 and do a fresh ViSP build using java 11.

Exception Unsatisfied Link Error

As shown in the next image, if you experience the following exception after entering "Run > Run" menu:

Exception in thread "main" java.lang.UnsatisfiedLinkError: no visp_java321 in java.library.path: [/home/fspindle/visp_ws/visp-build/lib]
img-tutorial-java-issue-visp-version.jpg
  • check that visp-<version>.jar is present in $VISP_DIR/visp-build/bin:
    $ ls $VISP_DIR/visp-build/bin
    visp-331.jar
    
    If this java archive is missing and if you follow Tutorial: Installing ViSP for Java it means that JDK was not detected during CMake configuration or that you didn't build ViSP
  • modify the following line to match ViSP version present in $VISP_DIR/visp-build/bin
        System.loadLibrary("visp_java331");
    

Error running Java app with Intel MKL

Running any Java app based on ViSP can lead to the following issue:

  INTEL MKL ERROR: /opt/intel/compilers_and_libraries_2020.0.166/linux/mkl/lib/intel64_lin/libmkl_avx2.so: undefined symbol: mkl_sparse_optimize_bsr_trsm_i8.
  Intel MKL FATAL ERROR: Cannot load libmkl_avx2.so or libmkl_def.so.

There is no other satisfactory solution than to disable the use of Intel MKL 3rd party, configure and rebuilt ViSP libraries without MKL support.

To this end, in a terminal launch ccmake ../visp and set USE_BLAS/LAPACK option to an other value than MKL; it could be OpenBLAS, Atlas, GSL, Netlib or OFF. It is recommended to set this var to OFF only when there is no other Blas/Lapack 3rd party available.

A complete discussion about this issue is given here in issue #806.

Next tutorial

You are now ready to continue with Tutorial: AprilTag detection in java with ViSP.