Visual Servoing Platform  version 3.3.1 under development (2020-04-08)
Tutorial: Installing ViSP for Java

Introduction

This tutorial will help you to install ViSP for Java on your desktop. This tutorial shows how to proceed if your desktop is running Linux or OSX. If you are rather running Windows, you need to adapt its content.

Create a workspace

First create a workspace in $HOME/visp-ws that will contain ViSP sources, build and dataset.

$ export VISP_WS=$HOME/visp-ws
$ mkdir -p $VISP_WS

Install Java Development Kit 11 (JDK)

Note
At the time this tutorial was updated, the lastest Java SE Development Kit (JDK) was version 13. We experienced that JDK 13 and JDK 12 are not compatible with the last gradle 5.6 release (see issue here) needed in Tutorial: Building ViSP SDK for Android.

That's why we recommand to install Java SE Development Kit 11.0.6 LTS (JDK 11).

On Ubuntu or Debian platform

From the Oracle website, download jdk-11.0.6_linux-x64_bin.tar.gz. After JDK download and extraction of the files from the archive, you may set JAVA_HOME environment var to help cmake to detect JDK.

$ tar xvzf jdk-11.0.6_linux-x64_bin.tar.gz -C $VISP_WS
$ echo 'export JAVA_HOME=$VISP_VS/jdk-11.0.6' >> ~/.bashrc
$ echo 'export PATH=${JAVA_HOME}/bin:${PATH}' >> ~/.bashrc
$ source ~/.bashrc

After installation check JDK version:

$ java --version
java 11.0.6 2020-01-14 LTS

On Mac OSX platform

From the Oracle website, download jdk-11.0.6_osx-x64_bin.dmg and install the package.

After installation check JDK version:

$ java --version
java 11.0.6 2020-01-14 LTS
Note
If you have a more recent version like java 13 (that comes with JDK 13) or java 12 (that comes with JDK 12), you need to uninstall it. See How to uninstall JDK to proceed.

On Windows platform

From the Oracle website, download jdk-11.0.6_windows-x64_bin.exe and run the binary. In order to make java.exe available, we had also to add its location C:\Program Files\Java\jdk-11.0.6\bin to the %PATH% environment variable.

After installation check JDK version:

$ java -version
java version 11.0.6 2020-01-14 LTS
Note
If you have a more recent version like JDK 13 or JDK 12, you need to uninstall it. See How to uninstall JDK to proceed.

Install Prerequisites

As a prerequisite, download and install first CMake and Apache Ant, if you don’t have any of these.

  • On Ubuntu/Debian you may run:
    $ sudo apt-get install cmake-curses-gui ant
  • On Fedora/CentOS you may run:
    $ sudo yum install gcc-c++ cmake ant
  • On MacOS/OSX you may run:
    $ brew cask install java
    $ brew install cmake ant

Install ViSP from source code

Getting ViSP source code

There are different ways to get ViSP source code:

  • You can download the latest release as a zip or a tarball. Once downloaded, uncompress the file using either
    $ tar xvzf visp-x.y.z.tar.gz -C $VISP_WS
    or
    $ unzip visp-x.y.z.zip -d $VISP_WS
  • You can also download a daily snapshot. Once downloaded, uncompress the file using
    $ tar xvzf visp-snapshot-yyyy-mm-dd.tar.gz -C $VISP_WS
  • Or you get the cutting-edge ViSP from GitHub repository using the following command
    $ cd $VISP_WS
    $ git clone https://github.com/lagadic/visp.git

We suppose now that ViSP source is in the directory $VISP_WS/visp. The following should be adapted if you downloaded ViSP from a zip or tarball. In that case, the source is rather in something like $VISP_WS/visp-x.y.z.

Configuring ViSP from source

  • In the workspace, create first a directory named visp-build that will contain all the build material; generated Makefiles, object files, output libraries and binaries.
    $ mkdir $VISP_WS/visp-build
  • Enter the visp-build folder and configure the build:
    $ cd $VISP_WS/visp-build
    $ cmake ../visp
    A more versatile way to configure the build is to use ccmake, the CMake GUI:
    $ ccmake ../visp
    The following image shows that this command allows to configure (just by pressing [c] key) the build in a more advanced way where some options could be easily turned ON/OFF. It allows also to see which are the 3rd parties that will be used. To generate the makefiles, just press [g] key in the ccmake gui.
    img-ccmake-ubuntu-all.png
    Snapshot of the "ccmake ../visp" command used to configure ViSP.

In $VISP_WS/visp-build/ViSP-third-party.txt you should find something similar to the following snapshot that shows that python, ant and JNI are found:

$ more ViSP-third-party.txt
==========================================================
General configuration information for ViSP 3.3.0
Version control: 1041074e9-dirty
Platform:
Timestamp: 2020-01-27T15:37:47Z
Host: Linux 5.3.0-26-generic x86_64
CMake: 3.10.2
CMake generator: Unix Makefiles
CMake build tool: /usr/bin/make
Configuration: Release
C/C++:
Built as dynamic libs?: yes
C++ Compiler: /usr/bin/c++ (ver 7.4.0)
C++ flags (Release): -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
C++ flags (Debug): -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
C Compiler: /usr/bin/cc
C flags (Release): -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
C flags (Debug): -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
Linker flags (Release):
Linker flags (Debug):
ViSP modules:
To be built: core gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection java mbt tt tt
_mi
Disabled: -
Disabled by dependency: -
Unavailable: -
Python (for build): /usr/bin/python2.7
Java:
ant: /usr/bin/ant (ver 1.10.5)
JNI: $VISP_WS/jdk-11.0.6/include $VISP_WS/jdk-11.0.6/include/linux $VISP_WS/jdk-11.0.6/include

Building ViSP libraries

  • To build ViSP Java libraries on Linux, proceed with:
    $ cd $VISP_WS/visp-build
    $ make -j$(nproc) visp_java
  • To build ViSP Java libraries on MacOS/OSX, proceed with:
    $ cd $VISP_WS/visp-build
    $ make -j$(sysctl -n hw.ncpu) visp_java

Note that ViSP Java ARchive is now available in $VISP_WS/visp-build/bin/visp-330.jar.

Setting Up ViSP Java in Eclipse

Install the latest Eclipse version

Download the latest Eclipse version at the Eclipse Download page choosing the Eclipse IDE for Java Developers version. You don’t need to install anything. Extract the downloaded compressed file and put the resulting folder wherever you want to, for example in $VISP_WS/eclipse.

Creating a user library

Open Eclipse and select a workspace location of your choice, for example in $VISP_WS/eclipse/eclipse-workspace and press Launch button.

img-tutorial-java-eclipse-workspace.jpg

Now we propose to create a ViSP user library ready to be used on all your next Java projects. To this end enter "Window > Preferences" menu:

img-tutorial-java-eclipse1.jpeg
Open Preferences panel in Eclipse

In the Preferences panel navigate under "Java > Build Path > User Libraries" and choose New. Enter a name for the library (e.g visp) and press OK button.

img-tutorial-java-eclipse2.jpeg
Create a new User Library

Press "Add External JARs" button, browse to select $VISP_WS/visp-build/bin/visp-330.jar from your computer. After adding the jar, select "Native library location", press first "Edit", press "External Folder", browse to select the folder $VISP-WS/visp_build/lib containing ViSP libraries and finally press OK button. We recall that the libraries have the extension .so in linux, .dylib in MacOS and .dll in Windows.

img-tutorial-java-eclipse3.jpeg
Add jar and native libraries to User Library

Once done, press "Apply and Close" button.

Tips & Tricks

How to uninstall JDK

Note
At the time this tutorial was updated, the lastest Java SE Development Kit (JDK) was version 13. We experienced that JDK 13 and JDK 12 are not compatible with the last gradle 5.6 release (see issue here) needed in Tutorial: Building ViSP SDK for Android. That's why we give here some tips to uninstall JDK to be able to downgrade JDK version.

On Ubuntu or Debian platform

On Ubuntu or Debian platform there is nothing more to do than removing the folder containing JDK.

$ rm -rf $VISP_VS/jdk-11.0.6

On Mac OSX platform

To uninstall JDK on Mac OSX, you must have administrator privileges and remove the directory whose name matches the following format: /Library/Java/JavaVirtualMachines/jdkmajor.minor.macro[_update].jdk. You can proceed using:

sudo mv /Library/Java/JavaVirtualMachines/jdk-13.jdk/ /tmp

and/or:

sudo mv /Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/ /tmp

On Windows platform

To uninstall JDK on Windows, click Start menu, select "Settings > System > Apps & features". Select the program to unsinstall like Java(TM) SE Development Kit 13.0 (64-bit), then click its Uninstall button. Respond to the prompts to complete the uninstall.

How to delete an Eclipse workspace

To remove existing Eclipse workspaces, enter "Preferences > General > Startup & Shudown > Workspaces" menu, select the workspace to remove and press Remove button and then Apply and Close button.

img-tutorial-java-eclipse-remove-workspace.jpeg

Note that this does not actually delete the files from the system, it simply removes it from the list of suggested workspaces. You need to remove the workspace directory by hand.

Next tutorial

You are now ready to follow Tutorial: First java application with ViSP.