OpenCV is a powerfull open source Computer Vision library written mainly in C++. Today, the most common way to use OpenCV from Java is to use its Java bindings. Technically, those bindings rely on the traditional JNI approach.

OpenCV offers ‘official’ distributions for Windows, iOS and Android but none for Linux and macOS.

This ‘how-to’ explains how to build the latest version of OpenCV (4.2+) with its Java JNI bindings on Linux and macOS.

❕A follow-up article will detail how to use OpenCV with the Java Module System, ex. how to package ‘OpenCV modules’ as Java Modules, how to use jmod and jlink, etc.

The latest Java version, 14 at the time of writing, is used as all the OpenCV Java material seems to be stuck on Java 8 (and OpenCV 3). The latest and greatest OpenCV and Java versions are used but this obviously work using different versions. Producing builds on Windows is just a matter of properly installing and configuring the native toolchain, and configure the respective Java paths.

Panama is an OpenJDK project whose goal is to improve and enrich the connections between the JVM and well-defined “foreign”, i.e. non-Java APIs. Panama is under active development, its current focus is on C but C++ support should be added later. It will then be worthwhile to revisit this and use Panama’s approach instead of the old JNI approach.

Building OpenCV and its Java bindings is straight forward but it takes time! The bulk of the time is spent in building natively OpenCV for the target platform, then the Java bindings will be built for that same platform. To do this, we need a native C++ toolchain (g++, ld, make, …) and a Java toolchain, i.e. a JDK and a recent version of Apache Ant.

Install the native C++ toolchain

Unless you are using a stripped down Linux distribution, most of the native tools are probably already installed (ex. ld, nm, objcopy, objdump, make, etc.). On a fresh Ubuntu, I only had to install g++ and cmake. Optionally and given that there are over 300 options to build OpenCV, using a configuration front-end such as ccmake or cmake-gui can be helpful. Note that Python is also required for the build phase.

sudo apt install g++
sudo apt install cmake
sudo apt install cmake-curses-gui

On macOS, you will need to have XCode installed.

Install the Java toolchain

Install the JDK, e.g. on Linux…

wget https://download.java.net/java/GA/jdk14/076bab302c7b4508975440c56f6cc26a/36/GPL/openjdk-14_linux-x64_bin.tar.gz
gzip -d openjdk-14_linux-x64_bin.tar.gz
sudo mkdir /usr/lib/jvm
sudo cp -r jdk-14/ /usr/lib/jvm/
sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk-14/bin/java" 1
sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk-14/bin/javac" 1

… and Apache Ant.

sudo snap install ant --classic

Configure the build

mkdir workspace;cd workspace
git clone https://github.com/opencv/opencv.git
mkdir build

Using ccmake, create the build files and point it to the OpenCV codebase directory and to the newly created build directory.

ccmake -S opencv/ -B build/

Alternatively, you can use cmake-gui which offers a GUI. Simillarly, you should specify the OpenCV codebase location and the directory where it should be build.

Both ccmake and cmake-gui works the same way. You first need to hit “C” (configure) to scan your envorinoment, this will scan your environment and configure related entries (ex. compilers location, Java paths, supported hardware extensions, …). Then and if required, you can manually configure some entries, just make sure to press “T” to toggle the advanced mode. Once done, you should press “G” to generate the Makfile.

Most of settings should be fine by default but if you have simply unpacked the JDK, cmake will not find the related paths so make sure they are correctly configured.

• JAVA_AWT_INCLUDE_PATH

↪ Linux /usr/lib/jvm/jdk-14/include/

↪ macOS /Library/Java/JavaVirtualMachines/jdk-14.jdk/Contents/Home/include/

• JAVA_AWT_LIBRARY

↪ Linux /usr/lib/jvm/jdk-14/lib/libjawt.so

↪ macOS /Library/Java/JavaVirtualMachines/jdk-14.jdk/Contents/Home/lib/libawt.dylib

• JAVA_INCLUDE_PATH

↪ Linux /usr/lib/jvm/jdk-14/include/

↪ macOS /Library/Java/JavaVirtualMachines/jdk-14.jdk/Contents/Home/include/

• JAVA_INCLUDE_PATH2

↪ Linux /usr/lib/jvm/jdk-14/include/linux/

↪ macOS /Library/Java/JavaVirtualMachines/jdk-14.jdk/Contents/Home/include/darwin/

• JAVA_JVM_LIBRARY

↪ Linux /usr/lib/jvm/jdk-14/lib/server/libjvm.so

↪ macOS /Library/Java/JavaVirtualMachines/jdk-14.jdk/Contents/Home/lib/server/libjvm.dylib

💡 Building OpenCV takes time, anywhere between 5 minutes and +60 minutes depending on your configuration, the selected OpenCV modules and options, …; so it’s a good idea to first do a minimal build to check that eveything is OK.

To reduce the build time, disable the following entries:

• BUILD_IPP_IW

• BUILD_ITT

• BUILD_OPENEXR

• BUILD_PERF_TESTS

• BUILD_TESTS

• BUILD_TIFF

• BUILD_WEBP

• BUILD_opencv_calib3d

• BUILD_opencv_dnn

• BUILD_opencv_features2d

• BUILD_opencv_flann

• BUILD_opencv_gapi

• BUILD_opencv_highgui

• BUILD_opencv_ml

• BUILD_opencv_objdetect

• BUILD_opencv_photo

• BUILD_opencv_python_bindings_generator

• BUILD_opencv_python_tests

• BUILD_opencv_stitching

• BUILD_opencv_ts

• BUILD_opencv_video

• BUILD_opencv_videoio

• VIDEOIO_ENABLE_PLUGINS

• VIDEOIO_ENABLE_STRICT_PLUGIN_CHECK

The sample below uses OpenCV’s PNG suport so make sure to keep WITH_PNG enabled and unselect all others WIDTH_* entries.

Disabling those options will reduce the build time from ~50 minutes to ~5 minutes (YMMV!). Once your build process is OK, you can selectevely re-enable the features you plan to use. And realistically, you will need additional modules and features (dnn, features2d, objdetect, …) to unleash the power of OpenCV!

The following OpenCV modules are the bare minimum to use OpenCV from Java.

• BUILD_opencv_core

• BUILD_opencv_imgcodecs

• BUILD_opencv_imgproc

• BUILD_JAVA

• BUILD_opencv_java

• BUILD_opencv_java_bindings_gen

Once you are your have configured the entries, just press “G” to generate the Makefile.

Build OpenCV

cmake --build build/ or make --directory=build/

To use OpenCV from Java, you need the build/bin/opencv-430.jar jar and the native libraries located in build/lib.

This basic Test class converts a picture from the default BGR colorspace to gray.

import org.opencv.core.*;
import org.opencv.imgcodecs.Imgcodecs;
import org.opencv.imgproc.Imgproc;
...

public class Test {
  public static void main(String[] args) {

    System.loadLibrary(Core.NATIVE_LIBRARY_NAME);

    var srcImage = Imgcodecs.imread("duke.png", Imgcodecs.IMREAD_UNCHANGED);

    List<Mat> channels = new ArrayList<>();
    Core.split(srcImage, channels);
    var chAlpha = channels.get(3); // 4th channel = Alpha

    Imgproc.cvtColor(srcImage, srcImage, Imgproc.COLOR_BGRA2GRAY);

    List<Mat> greyChannel = new ArrayList<>();
    Core.split(srcImage, greyChannel);
    var chGray = greyChannel.get(0);

    Mat grayDuke = new Mat();
    var listMat = Arrays.asList(chGray, chGray, chGray, chAlpha); // 3 channels + Alpha
    Core.merge(listMat, grayDuke);

    Imgcodecs.imwrite("duke_gray.png", grayDuke);

    }
}

Run it…

javac -cp build/bin/opencv-430.jar Test.java
java -Djava.library.path=build/lib/ -cp build/bin/opencv-430.jar:. Test

And now, you can re-enable the OpenCV features that you plan to use, and produce a new build…