1. Introduction

At this point we suppose that you succeed to build ViSP from source following one Installation from source code tutorials.

This tutorial will help you to build ViSP from source for Java on your desktop. It shows how to proceed if your desktop is running Linux, OSX or Windows.

2. Create a workspace

2.1. On Ubuntu, Debian or Mac OSX

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/3rdparty

2.2. On Windows

Follow instructions to 2. Create a workspace on Windows.

We suppose now that you have set %VISP_WS% var.

3. Install Java Development Kit (JDK)

Note: At the time this tutorial was updated, the lastest Long Term Support Java SE Development Kit (JDK) is version 21. Here we recall 8.1. How to uninstall JDK if you need to upgrade or downgrade JDK version.

3.1. On Ubuntu or Debian

From the Oracle website, download JDK 21 the latest Long Term Support release of the Java SE Platform. There exists also JDK 23 the latest release, but we experienced issues when using it in an Eclipse project on Ubuntu. That's why at the time this tutorial was updated, we considered JDK 21 and downloaded jdk-21_linux-x64_bin.tar.gz file. 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 ~/Downloads/jdk-21_linux-x64_bin.tar.gz -C $VISP_WS/3rdparty
$ echo 'export JAVA_HOME=$VISP_WS/3rdparty/jdk-21.0.6' >> ~/.bashrc
$ echo 'export PATH=${JAVA_HOME}/bin:${PATH}' >> ~/.bashrc
$ source ~/.bashrc

After installation check JDK version:

$ java --version
java 21.0.6 2025-01-21 LTS
Java(TM) SE Runtime Environment (build 21.0.6+8-LTS-188)
Java HotSpot(TM) 64-Bit Server VM (build 21.0.6+8-LTS-188, mixed mode, sharing)

3.2. On Mac OSX

There are two different ways to install JDK on Mac OSX. We recommend the way using DMG installer.

3.2.1. Install JDK with DMG installer

Navigate to Oracle website and download the DMG installer that match your OS. At the time this tutorial was updated, we downloaded jdk-23_macos-aarch64_bin.dmg that corresponds to the JDK 23 version for a Macbook Pro M1.

After installation, check that JDK and java are well detected:

$ java -version

java version "23.0.2" 2025-01-21

3.2.2. Install OpenJDK with brew

Note: If you already have an old JDK version you may remove it before installing OpenJDK:
$ ls /Library/Java/JavaVirtualMachines/

jdk-11.0.10.jdk

Here it shows that jdk-11.0.10 is installed. To remove this version, see 8.1. How to uninstall JDK.

To install OpenJDK with brew:

run:
$ brew install openjdk
To know which version is installed:
$ brew info openjdk

openjdk: stable 23.0.2 (bottled) [keg-only]
Now for the system Java wrappers to find this JDK, symlink it with:
$ sudo ln -sfn /opt/homebrew/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk

Note
Depending on the OpenJDK version, the symlink instruction can differ. To know which one is to use, follow instructions provided by brew info openjdk. At the time this tutorial was updated, we got:
$ brew info openjdk

For the system Java wrappers to find this JDK, symlink it with

sudo ln -sfn /opt/homebrew/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
Set JAVA_HOME env var to help JNI headers and libraries detection
$ echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc

$ source ~/.zshrc
After installation check that OpenJDK and java are well detected:
$ java --version

openjdk 23.0.2 2025-01-21

3.3. On Windows

From the Oracle website, download JDK 23 to get jdk-23_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-17.0.2\bin to the %PATH% environment variable.

After installation check JDK version:

C:> java -version

java version 23.0.2 2025-01-21

4. Install the latest Eclipse version

Download the latest Eclipse version at the Eclipse Download page choosing the Eclipse IDE for Java Developers version.

4.1. On Ubuntu, Debian and Mac OSX

On Ubuntu, Debian or Mac OSX 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/3rdparty/eclipse.

We suppose here that you have Eclipse installed $VISP_WS/3rdparty/eclipse:

$ ls $VISP_WS/3rdparty/eclipse

artifacts.xml configuration dropins eclipse eclipse.ini features icon.xpm p2 plugins readme

4.2. On Windows

After downloading Eclipse simply open the installer and follow default installation instructions. At the time this tutorial was updated we downloaded "Eclipse IDE 2024-12 R", getting eclipse-inst-jre-win64.exe installer.

Eclipse was installed by default in C:\Users\USERNAME%\eclipse\java-2024-12\eclipse folder.

5. Install Prerequisites

To build ViSP for java you have also to install CMake, Apache Ant, and Python 3. If you don’t have any of these do the following:

5.1. On Ubuntu/Debian

$ sudo apt-get install cmake-curses-gui ant python3

5.2. On Fedora/CentOS

$ sudo dnf install gcc-c++ cmake ant python3

5.3. On Mac OSX

$ brew install cmake ant python3

5.4. On Windows

Download the latest CMake release for Windows win64-x64 platform from http://www.cmake.org. At the time this tutorial was written it was the file cmake-4.0.0-rc1-windows-x86_64.msi. To install just double click on the msi file.
Download the latest Python 3 release for Windows from https://www.python.org/downloads/. At the time this tutorial was written, it was Python 3.13.2.
There is also Apache Ant that is needed. Download Apache Ant binary distribution from https://ant.apache.org/bindownload.cgi. At the time this tutorial was updated we downloaded apache-ant-1.10.15-bin.zip file. Unzip the file for example in C:\Users\USERNAME%\apache-ant-1.10.15-bin. To help Ant detection, set ANT_HOME var to your installation folder. In our case it becomes
C:> setx ANT_HOME C:\Users\%USERNAME%\apache-ant-1.10.15-bin

You need also to add "ANT_HOME%\bin" to the "Path" environment variable. To this end, open the environment variables panel, and modify "Path" accordingly. In our case we added "C:\Users\USERNAME%\apache-ant-1.10.15-bin\bin" folder.
Note
You can check that the "ANT_HOME%" variable is correctly positioned by checking that the ant.bat file is in the "ANT_HOME%\bin" folder.

6. Build ViSP from source code

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

6.2. Configuring ViSP from source

In the workspace, create first a directory named visp-build that will contain all the build material; generated Makefiles or Visual Studio Solution files, object files, output libraries and binaries once build is done, and in a second stage configure ViSP using CMake.
- On Ubuntu/Debian like and on macOS
  $ mkdir $VISP_WS/visp-build
  
  $ cd $VISP_WS/visp-build
  
  $ cmake ../visp
- On Windows
  C:> mkdir %VISP_WS%\visp-build
  
  C:> cd %VISP_WS%\visp-build
  
  C:> cmake -G "Visual Studio 17 2022" -A "x64" %VISP_WS%\visp
At this point, 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:
- On Ubuntu/Debian like
  ==========================================================
  
  General configuration information for ViSP 3.6.1
  
  Version control: v3.6.0-2170-g800e1426c-dirty
  
  Platform:
  
  Timestamp: 2025-02-17T14:47:03Z
  
  Host: Linux 6.8.0-52-generic x86_64
  
  CMake: 3.28.3
  
  CMake generator: Unix Makefiles
  
  CMake build tool: /usr/bin/gmake
  
  Configuration: Release
  
  System information:
  
  Number of CPU logical cores: 32
  
  Number of CPU physical cores: 24
  
  Total physical memory (in MiB): 31774
  
  OS name: Linux
  
  OS release: 6.8.0-52-generic
  
  OS version: #53-Ubuntu SMP PREEMPT_DYNAMIC Sat Jan 11 00:06:25 UTC 2025
  
  OS platform: x86_64
  
  CPU name: Unknown P6 family
  
  CPU description: 24 core 13th Gen Intel(R) Core(TM) i9-13950HX
  
  Is the CPU 64-bit? yes
  
  Does the CPU have FPU? yes
  
  CPU optimization: SSE2 SSE3 SSSE3
  
  CPU endianness: little-endian
  
  C/C++:
  
  Built as dynamic libs?: yes
  
  C++ Compiler: /usr/bin/c++ (ver 13.3.0)
  
  C++ flags (Release): -Wall -Wextra -fopenmp -std=c++17 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
  
  C++ flags (Debug): -Wall -Wextra -fopenmp -std=c++17 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
  
  C Compiler: /usr/bin/cc
  
  C flags (Release): -Wall -Wextra -fopenmp -std=c++17 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
  
  C flags (Debug): -Wall -Wextra -fopenmp -std=c++17 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
  
  Linker flags (Release):
  
  Linker flags (Debug):
  
  Use cxx standard: 17
  
  ViSP modules:
  
  To be built: core dnn_tracker gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection mbt rbt tt tt_mi java
  
  Disabled: -
  
  Disabled by dependency: -
  
  Unavailable: -
  
  Enable visp namespace: no
  
  Enable explicit keyword: no
  
  Python 3:
  
  Interpreter: /home/username/miniforge3/bin/python3 (ver 3.12.7)
  
  Java:
  
  ant: /usr/bin/ant (ver 1.10.14)
  
  Java: no
  
  JNI: /home/username/visp-ws/3rdparty/jdk-21.0.6/include /home/username/visp-ws/3rdparty/jdk-21.0.6/include/linux /home/username/visp-ws/3rdparty/jdk-21.0.6/include
  
  Java wrappers: yes (ANT)
- On macOS
  $ more ViSP-third-party.txt
  
  ==========================================================
  
  General configuration information for ViSP 3.6.1
  
  Version control: 4471cea29-dirty
  
  Platform:
  
  Timestamp: 2025-02-18T16:42:59Z
  
  Host: Darwin 24.3.0 arm64
  
  CMake: 3.31.5
  
  CMake generator: Unix Makefiles
  
  CMake build tool: /usr/bin/make
  
  Configuration: Release
  
  System information:
  
  Number of CPU logical cores: 10
  
  Number of CPU physical cores: 10
  
  Total physical memory (in MiB): 32768
  
  OS name: macOS
  
  OS release: 15.3.1
  
  OS version: 24D70
  
  OS platform: arm64
  
  CPU name: Apple M1 Pro
  
  CPU description: 10 core Apple M1 Pro
  
  Is the CPU 64-bit? yes
  
  Does the CPU have FPU? yes
  
  CPU optimization: NEON
  
  CPU endianness: little-endian
  
  C/C++:
  
  Built as dynamic libs?: yes
  
  C++ Compiler: /Library/Developer/CommandLineTools/usr/bin/c++ (ver 16.0.0.16000026)
  
  C++ flags (Release): -Wall -Wextra -Xclang -fopenmp -std=c++17 -fvisibility=hidden -fPIC -O3 -DNDEBUG
  
  C++ flags (Debug): -Wall -Wextra -Xclang -fopenmp -std=c++17 -fvisibility=hidden -fPIC -g
  
  C Compiler: /Library/Developer/CommandLineTools/usr/bin/cc
  
  C flags (Release): -Wall -Wextra -Xclang -fopenmp -std=c++17 -fvisibility=hidden -fPIC -O3 -DNDEBUG
  
  C flags (Debug): -Wall -Wextra -Xclang -fopenmp -std=c++17 -fvisibility=hidden -fPIC -g
  
  Linker flags (Release):
  
  Linker flags (Debug):
  
  Use cxx standard: 17
  
  ViSP modules:
  
  To be built: core dnn_tracker gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection mbt rbt tt tt_mi java
  
  Disabled: -
  
  Disabled by dependency: -
  
  Unavailable: -
  
  Enable visp namespace: no
  
  Enable explicit keyword: no
  
  Python 3:
  
  Interpreter: /Users/user/miniforge3/bin/python3.10 (ver 3.10.13)
  
  Java:
  
  ant: /opt/homebrew/bin/ant (ver 1.10.15)
  
  Java: no
  
  JNI: /opt/homebrew/Cellar/openjdk/23.0.2/libexec/openjdk.jdk/Contents/Home/include /opt/homebrew/Cellar/openjdk/23.0.2/libexec/openjdk.jdk/Contents/Home/include/darwin /opt/homebrew/Cellar/openjdk/23.0.2/libexec/openjdk.jdk/Contents/Home/include
  
  Java wrappers: yes (ANT)
- On Windows
  C:> type ViSP-third-party.txt
  
  ==========================================================
  
  General configuration information for ViSP 3.6.1
  
  Version control: 564643c39
  
  Platform:
  
  Timestamp: 2025-02-20T17:46:12Z
  
  Host: Windows 10.0.19044 AMD64
  
  CMake: 4.0.0-rc1
  
  CMake generator: Visual Studio 17 2022
  
  CMake build tool: C:/Program Files/Microsoft Visual Studio/2022/Community/MSBuild/Current/Bin/amd64/MSBuild.exe
  
  MSVC: 1935
  
  System information:
  
  Number of CPU logical cores: 4
  
  Number of CPU physical cores: 4
  
  Total physical memory (in MiB): 16057
  
  OS name: Windows
  
  OS release: Professional
  
  OS version: (Build 19044)
  
  OS platform: AMD64
  
  CPU name: Pentium II (0.25 micron)
  
  CPU description: 4 core 3192 MHz GenuineIntel Pentium II (0.25 micron)
  
  Is the CPU 64-bit? yes
  
  Does the CPU have FPU? yes
  
  CPU optimization: SSE2 SSE3 SSSE3 SSE4_1 SSE4_2
  
  CPU endianness: little-endian
  
  C/C++:
  
  Built as dynamic libs?: yes
  
  C++ Compiler: C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.35.32215/bin/Hostx64/x64/cl.exe (ver 19.35.32215.0)
  
  C++ flags (Release): /DWIN32 /D_WINDOWS /W3 /GR /EHsc /EHa -openmp /Gy /bigobj /MD /O2 /Ob2 /DNDEBUG
  
  C++ flags (Debug): /DWIN32 /D_WINDOWS /W3 /GR /EHsc /EHa -openmp /Gy /bigobj /MDd /Zi /Ob0 /Od /RTC1
  
  C Compiler: C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.35.32215/bin/Hostx64/x64/cl.exe
  
  C flags (Release): /DWIN32 /D_WINDOWS /W3 /EHa -openmp /MD /O2 /Ob2 /DNDEBUG
  
  C flags (Debug): /DWIN32 /D_WINDOWS /W3 /EHa -openmp /MDd /Zi /Ob0 /Od /RTC1
  
  Linker flags (Release): /machine:x64 /INCREMENTAL:NO
  
  Linker flags (Debug): /machine:x64 /debug /INCREMENTAL /ignore:4099
  
  Use cxx standard: 17
  
  ViSP modules:
  
  To be built: core dnn_tracker gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi java
  
  Disabled: -
  
  Disabled by dependency: -
  
  Unavailable: -
  
  Enable visp namespace: no
  
  Enable explicit keyword: no
  
  Windows RT support: no
  
  Python 3:
  
  Interpreter: C:/Users/user/AppData/Local/Programs/Python/Python313/python.exe (ver 3.13.2)
  
  Java:
  
  ant: C:/Users/user/apache-ant-1.10.15/bin/ant.bat (ver 1.10.15)
  
  Java: no
  
  JNI: C:/Program Files/Java/jdk-23/include C:/Program Files/Java/jdk-23/include/win32 C:/Program Files/Java/jdk-23/include
  
  Java wrappers: yes (ANT)
Note
If JNI is not found (ie. the line starting with JNI: is empty), we recommend to do a fresh build removing all the files in the build folder and configuring again from scratch with CMake.

6.3. Building ViSP libraries

Depending on you platform, you can now build visp_java module:

On Ubuntu/Debian like, proceed with:
$ cd $VISP_WS/visp-build

$ make -j$(nproc) visp_java
On macOS, proceed with:
$ cd $VISP_WS/visp-build

$ make -j$(sysctl -n hw.ncpu) visp_java
On Windows, proceed with:
C:> cd %VISP_WS%\visp-build

C:> cmake --build . --config Release --target visp_java

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

7. Creating a user library in Eclipse

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

Now we propose to create a ViSP user library ready to be used on all your next Java projects. To this end,

if you are on OS X enter "Eclipse > Preferences..." menu
otherwise enter "Window > Preferences" menu:

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.

Create a new User Library

Press "Add External JARs" button, browse to select $VISP_WS/visp-build/bin/visp-361.jar from your computer.

Add external JARs

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.

Add native library location

Once done, press "Apply and Close" button.

8. Tips & Tricks

8.1. How to uninstall JDK

Here we give here some tips to uninstall JDK to be able to downgrade or upgrade JDK version.

On Ubuntu or Debian platform On Ubuntu or Debian platform remove first the folder containing JDK.
$ rm -rf $VISP_VS/jdk-11.0.6

Then in ~/.bashrc remove any reference to JAVA_HOME env var deleting the lines similar to:
export JAVA_HOME=$VISP_VS/jdk-11.0.6

export PATH=${JAVA_HOME}/bin:${PATH}
On macOS 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.

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

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.

9. Next tutorial

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