1. Introduction

This tutorial is designed to help you build ViSP Android SDK which can be used to create Android Apps supporting ViSP Java functionalities.

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

This tutorial assumes you have the following software installed and configured: Java Development Kit (JDK), Android SDK and NDK, Python Interpreter, Apache Ant, CMake, Ninja and ccache.

3.1. On Ubuntu or debian

Install Java Development Kit (JDK) following 3. Install Java Development Kit (JDK) tutorial.
Note
At the time this tutorial was updated "Java SE Development Kit 21" was used.
To install Android SDK and NDK follow the link to Android Studio, download and install Android Studio. Once installed start Android Studio using default settings. This allows to download Android SDK that will be installed in $HOME/Android/Sdk on Ubuntu.

Now to install Android NDK, open Android Studio and start a new Native C++ Android project using the default configuration.

From this new project enter "File > Settings... > Languages & Frameworks > Android SDK" menu. Select the "SDK Tools" tab and check the boxes next to "Android SDK Build-Tools", "NDK (Side by side)" and "CMake".

As visible in the previous and next images, we will download and install NDK 28. Confirm changes pressing "OK" button.

Once all the tools are downloaded, you can exit Android Studio.
Now to install Python Interpreter (prefer version 3.x), CMake, Ninja and ccache (a compiler cache for a faster build) run the following:
$ sudo apt-get install python3 ant cmake-curses-gui ninja-build ccache
At the time this tutorial was written, on Ubuntu 24.04 LTS we got Android Studio BumbleBee 2024.2.14, NDK 28.0 (see 6.1. How to know Android NDK version) and the following other tools versions:
$ java --version

java 21.0.6 2025-01-21 LTS

$ python3 --version

Python 3.12.7

$ ant -version

Apache Ant(TM) version 1.10.14 compiled on September 25 2023

$ cmake -version

cmake version 3.28.3

$ ninja --version

1.11.1

$ ccache --version

ccache version 4.9.1

3.2. On Mac OSX

Install Java Development Kit (JDK) following 3. Install Java Development Kit (JDK) tutorial.
To install Android SDK and NDK follow the link to Android Studio, download and install Android Studio from dmg. Once installed start Android Studio using default settings. This allows to download Android SDK that will be installed in $HOME/Library/Android/sdk folder on OSX.

Now to install Android NDK, open Android Studio and start a new Native C++ Android project using the default configuration.

From this new project enter "Android Studio > Settings... > Languages & Frameworks > Android SDK" menu. Select the "SDK Tools" tab and check the boxes next to "Android SDK Build-Tools", "NDK (Side by side)" and "CMake".

As visible in the previous and next images, we will download and install NDK 28. Confirm changes pressing "OK" button.

Once all the tools are downloaded, you can exit Android Studio.
Now to install Python Interpreter (prefer versions 3.x), CMake, Ninja and ccache (a compiler cache for a faster build) run the following:
$ brew install python3 ant cmake ninja ccache
At the time this tutorial was written, on macOS Sequoia 15.3.1 we got Android Studio Ladybug 2024.2.2.13, NDK 28.0 (see 6.1. How to know Android NDK version) and the following other tools versions:
$ java --version

java version "23.0.2" 2025-01-21

$ python3 --version

Python 3.10.13

$ ant -version

Apache Ant(TM) version 1.10.15 compiled on August 25 2024

$ cmake -version

cmake version 3.31.5

$ ninja --version

1.12.1

$ ccache --version

ccache version 4.10.2

3.3. On Windows

Install Java Development Kit (JDK) following 3. Install Java Development Kit (JDK) tutorial.
To install Android SDK and NDK follow the link to Android Studio, download and install Android Studio for Windows 64-bit. Once installed start Android Studio using default settings. This allows to download Android SDK that will be installed in "C:\Users\username\AppData\Local\Android\Sdk" folder on Windows.

Now to install Android NDK, open Android Studio and start a new Native C++ Android project using the default configuration.

From this new project enter "File > Settings... > Languages & Frameworks > Android SDK" menu. Select the "SDK Tools" tab and check the boxes next to "Android SDK Build-Tools", "NDK (Side by side)" and "CMake".

As visible in the previous and next images, we will download and install NDK 28. Confirm changes pressing "OK" button.

Once all the tools are downloaded, you can exit Android Studio.
Now install Python Interpreter without forgetting to add Python to environment variables.
Download and install latest CMake release using Windows win64-x64 installer without forgetting to add CMake to the system PATH for all users.
Download Ninja for windows. Place ninja.exe in a suitable spot. For example, in %VISP_WS%\3rdparty\ninja-win. Now make sure that CMake can find ninja.exe by adding %VISP_WS%\3rdparty\ninja-win to your %Path% environment var.
Download ccache for Windows from github and add its location (%VISP_WS%\3rdparty\ccache-win64) to your %Path% environment variable
C:> cd %VISP_WS%/3rdparty

C:> git clone https://github.com/nagayasu-shinya/ccache-win64.git
At the time this tutorial was written, on Windows 11 we got Android Studio Ladybug 2024.2.2.13, NDK 28.0 (see 6.1. How to know Android NDK version) and the following other tools versions:
C:> java -version

java version 23.0.2 2025-01-21

C:> python --version

Python 3.13.2

C:> cmake -version

cmake version 4.0.0-rc1

C:> ninja --version

1.12.1

C:> ccache --version

ccache version 3.7.4

4. Get 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.

5. Build ViSP Android SDK

5.1. Overview

Note that the scripts for building the SDK are included in the source code.

In the workspace create a build folder

$ mkdir $VISP_WS/visp-build-android

Enter the directory $VISP_WS/platforms/android having the python build script and check which are the command line options that are available.

$ cd $VISP_WS/visp/platforms/android

$ python3 build_sdk.py --help

Generally the script has to be used like:

$ python3 build_sdk.py --config <ndk-*.config.py> --sdk_path <path-to-Android-Sdk> --ndk_path <path-to-Android-Sdk>/ndk-bundle <installation-directory> <visp-source-code-directory>

Note: It is possible to directly pass some CMake arguments using the --additional_cmake_flags option. The values it accepts must respect the pattern NAME_OPT_1=VALUE,NAME_OPT_2=VAL_2, i.e. it must contain tuples CMakeOptionName=CmakeOptionValue separated by commas (without space). An example of such a command would be:
$ mkdir $VISP_WS/visp-build-android

$ cd $VISP_WS/visp/platforms/android

$ python3 build_sdk.py --config ndk-28.config.py --sdk_path $HOME/Android/Sdk --ndk_path $HOME/Android/Sdk/ndk/28.0.13004108 $VISP_WS/visp-build-android $VISP_WS/visp --additional_cmake_flags USE_OPENCV=TRUE,OpenCV_FOUND=ON,OpenCV_VERSION=4.10.0

In $VISP_WS/visp/platforms/android folder we provide different NDK config files:

$ ls ndk-*.config.py
ndk-10.config.py  ndk-17.config.py               ndk-18.config.py  ndk-22.config.py
ndk-16.config.py  ndk-18-api-level-21.config.py  ndk-20.config.py  ndk-23.config.py ndk-28.config.py

The file that should be used after --config option should match your NDK version (see 6.1. How to know Android NDK version).

Above command will build SDK for multiple Android architectures. If you're aware on what Android architecture you'll be working on (refer here), say x86_64, you can do a minimal build by changing contents of ndk-*.config.py file

ABIs = [
    ABI("5", "x86_64",      None)
]

This will speed up the installation process.

Once build ViSP Android SDK will be available in $VISP_WS/visp-build-android/visp-android-sdk/sdk folder. Its content should be similar to the following:

$ cd $VISP_WS/visp-build-android/visp-android-sdk/sdk
$ find . -maxdepth 3 -type d
./native
./native/3rdparty
./native/3rdparty/libs
./native/staticlibs
./native/staticlibs/x86_64
./native/staticlibs/arm64-v8a
./native/staticlibs/x86
./native/staticlibs/armeabi-v7a
./native/libs
./native/libs/x86_64
./native/libs/arm64-v8a
./native/libs/x86
./native/libs/armeabi-v7a
./native/jni
./native/jni/abi-armeabi-v7a
./native/jni/include
./native/jni/abi-x86_64
./native/jni/abi-arm64-v8a
./native/jni/abi-x86
./java
./java/src
./java/src/org
./java/javadoc
./java/res
./java/res/values
./etc
./etc/data
./etc/data/robot-simulator
./etc/data/wireframe-simulator

5.2. On Linux or Debian

For example, on Ubuntu 20.04 the command might look like

$ mkdir $VISP_WS/visp-build-android
$ cd $VISP_WS/visp/platforms/android
$ python3 build_sdk.py --config ndk-28.config.py --sdk_path $HOME/Android/Sdk --ndk_path $HOME/Android/Sdk/ndk/28.0.13004108 $VISP_WS/visp-build-android $VISP_WS/visp

5.3. On Mac OSX

For example, on Mac OSX the command might rather look like

$ mkdir $VISP_WS/visp-build-android
$ cd $VISP_WS/visp/platforms/android
$ python3 build_sdk.py --config ndk-28.config.py --sdk_path $HOME/Library/Android/sdk --ndk_path $HOME/Library/Android/sdk/ndk/28.0.13004108 $VISP_WS/visp-build-android $VISP_WS/visp

5.4. On Windows

For example, on Windows the command might rather look like

C:> mkdir %VISP_WS%\visp-build-android
C:> cd %VISP_WS%\visp\platforms\android
C:> python3 build_sdk.py --config ndk-23.config.py --sdk_path %USERPROFILE%\AppData\Local\Android\Sdk --ndk_path %USERPROFILE%\AppData\Local\Android\Sdk\ndk\23.1.7779620 %VISP_WS%\visp-build-android %VISP_WS%\visp

5.5. Known issue

If you're experiencing problems with ccache or if you don't install ccache, you can try a build without it adding --no_ccache command line option like the following on Ubuntu:

$ python3 build_sdk.py --no_ccache --config ndk-18.config.py --sdk_path $HOME/Android/Sdk --ndk_path $HOME/Android/Sdk/ndk-bundle $VISP_WS/visp-build-android $VISP_WS/visp

6. Tips & tricks

6.1. How to know Android NDK version

Start Android Studio
on Ubuntu enter "File > Settings... > Appearance > System Settings" menu, while on Mac OSX enter "Android Studio > Preferences... > Appearance & Behavior > System Settings" menu, then select Android SDK in the left part and select "SDK Tools" tab to see which is the NDK version that you are using. The following swnapshot shows that NDK 18.1 is used:

This other snapshot shows that NDK 20.0 is used:

This other snapshot taken on Ubuntu 20.04 with Android Studio 4.1.2 shows that NDK 22.0 is used:

7. Next tutorial

You are now ready to follow Tutorial: Creating a simple Android App with ViSP where you'll be creating a sample Android App using ViSP SDK.