Tutorial: First java application with ViSP

1. 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.

2. Create a new project

• Open Eclipse and create a new Java project entering "File > New > Java Project" menu.
  
• 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 corresponding to the version of your JDK (ie. JavaSE-23 if you install JDK 23, JavaSE-21 if you install JDK 21 LTS, ...). Then press "Finish" button.
  

  Note

  We recall that on Ubuntu 24.04, we recommend to install JDK 21 LTS. Thus in JRE section you have to select JavaSE-21. At the time this tutorial was updated, installing JDK 23 on Ubuntu, and selecting JavaSE-23 doesn't allow to add "JRE System Library [JavaSE-23]" part of the project.

• In the left panel, open the "Package Explorer" and expand the "src" folder
  
• Remove module-info.java file from your project.
  

3. 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...".

• Select "User Library" and click on "Next":

• 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 7. Creating a user library in Eclipse.

• In the "Package Explorer" panel, you should see "visp" library
  

4. 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.
  
• Then choose a class name like Started and press "Finish" button.
  
• Once "Finish" button is pressed you should see something similar to the following:
  
• 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:

  package visp_java_started;
   
  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_java361");
    }
    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:
  
• You can now try to build and run this application entering"Run > Run" menu. You should have the following output:

5. Known issues

5.1. 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

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.

5.2 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/username/visp-ws/visp-build/lib]

• 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");

5.3. 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.

5.4. Error no visp_java361 in java.library.path

If you face the following error:

Exception in thread "main" java.lang.UnsatisfiedLinkError: no visp_java361 in java.library.path: C:\visp-ws\visp-java\x64\vc17\bin\Release
    at java.base/java.lang.ClassLoader.loadLibrary(ClassLoader.java:2458)
    at java.base/java.lang.Runtime.loadLibrary0(Runtime.java:916)
    at java.base/java.lang.System.loadLibrary(System.java:2063)
    at visp_started/visp_started.Started.<clinit>(Started.java:12)

Run the following command:

C:> java -XshowSettings:properties -version

In the result of the command, check the value of java.library.path:

Property settings:
    file.encoding = UTF-8
    file.separator = \
    java.class.path =
    java.class.version = 65.0
    java.home = C:\Program Files\Java\jdk-21
    java.io.tmpdir = C:\Users\username\AppData\Local\Temp\
    java.library.path = $LIST_OF_FOLDERS

Ensure that the .dll and .lib of visp (visp_core.dll, visp_java${VERSION_NUMBER}.dll) and so on are located in one of these folders.

Issues with the includes

If Oracle complains about the import statements, add in the module-info.java the following lines:

module ${APPLICATION_PACKAGE_NAME} {
    requires visp;
}

where ${APPLICATION_PACKAGE_NAME} must be replaced by the name that appears in the package statement in the Started.java file.

6. Next tutorial

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