BoofCV: a Java computer vision library for calibration, fiducials and structure from motion

What BoofCV is for, and who actually needs it

BoofCV is a real-time computer vision library written entirely in Java and released under the Apache License 2.0. The README lists its scope as low-level image processing, camera calibration, feature detection and tracking, structure from motion, classification and recognition. The topic list on the repository adds stereo vision, photogrammetry, Android, and several barcode families: QR code, Micro QR code, and Aztec code, including QR generation as well as scanning.

The audience is narrower than that list suggests. This is a library for people writing JVM software who need a specific vision primitive inside a larger application: a robot that must localise against a printed marker, an Android app that scans codes on device, a desktop tool that calibrates a camera rig, a pipeline that reconstructs a scene from photographs. If you are prototyping a model in a notebook, the JVM is the wrong place to start. If you are shipping a Java service or an Android APK and you do not want to carry native OpenCV binaries, BoofCV is aimed squarely at you.

How BoofCV is organised: modules, not one jar

The repository splits into main/ for source, integration/ for third-party glue, examples/ for readable sample code, demonstrations/ for interactive parameter tuning, applications/ for standalone tools, and data/ for optional assets used by applets and examples. The build is Gradle, driven by build.gradle.kts and settings.gradle.kts at the top level, with buildSrc/ holding build logic.

The distribution model matters more than the directory names. BoofCV is published to Maven Central as many modules, and the README states that most people will only need boofcv-core. Everything else is opt-in: boofcv-android for device-specific helpers, boofcv-swing for Swing visualisation (required by the examples and demonstrations), boofcv-pdf for rendering fiducials as PDF documents, boofcv-kotlin for Kotlin extensions, boofcv-jcodec for a pure Java video reader and writer, and boofcv-javacv and boofcv-ffmpeg for wrappers around JavaCV and FFMPEG used mainly for file IO. That separation is deliberate: a headless server doing QR decoding should not pull in Swing.

One change is worth flagging because it breaks builds. The README states that starting in BoofCV 1.5.0, native binaries for the optional boofcv-ffmpeg and boofcv-javacv modules are no longer included by default, which reduces the number of unnecessary jars downloaded. The cost is that you must now name your platform classifier explicitly.

Installing BoofCV and running your first example

The README's quick start uses the Gradle wrapper, so no separate Gradle install is needed. Java 11 or newer is required and any free distribution works; the README names Zulu as an example. Clone the SNAPSHOT branch with submodules, because the data directory depends on them:

git clone -b SNAPSHOT --recursive https://github.com/lessthanoptimal/BoofCV.git boofcv

If data/ comes out empty, you skipped --recursive. The README gives the repair:

cd boofcv
git submodule update --init --recursive

Then let Gradle do the work. The first command clears stale generated code, the second regenerates it, and the last two build and launch the example and demonstration jars:

cd boofcv
git clean -fd main
./gradlew autogenerate
./gradlew examplesJar
java -jar examples/examples.jar
./gradlew demonstrationsJar
java -jar demonstrations/demonstrations.jar

The README says the Gradle script downloads what it needs and ignores your local JDK if it is not compatible, so a mismatched system JDK should not block the build. Examples are written to be easy to read; demonstrations let you change parameters in real time. If you only want the library in an existing project, add the dependency instead of cloning:

dependencies {
    api(group: 'org.boofcv', name: 'boofcv-core', version: '1.5.0')
}

Note that this snippet appears in the README while the most recent tagged release listed for the repository is v1.4.0, so confirm the version you pin actually resolves before adopting it.

Video IO: the platform classifier you must supply

This is the part of the setup most likely to fail silently at runtime. Because 1.5.0 stopped bundling native binaries, projects that read or write video files through the JavaCV or FFMPEG wrappers have to declare the native artifact for their own platform. The README shows the shape of it, with the classifier left as a placeholder that you replace:

dependencies {
    runtimeOnly 'org.bytedeco:ffmpeg:8.1.2-1.5.14:<ENTER PLATFORM HERE>'

    runtimeOnly 'org.bytedeco:opencv:4.14.0-1.5.14:<ENTER PLATFORM HERE>'
    runtimeOnly 'org.bytedeco:openblas:0.3.34-1.5.14:<ENTER PLATFORM HERE>'
}

The README points to the JavaCV and FFMPEG listings on Maven Central for the available classifiers, and gives linux-x86_64 as the kind of value expected. If you forget this step, the README notes you will see an error beginning with java. That is the failure mode: the library compiles, the application starts, and video reading fails at the point where the native library would have been loaded. If you never touch video files, you can skip this entirely, which is the point of the change.

Where BoofCV is the wrong choice

The most obvious limitation is the licensing of the optional native path. The README states the library itself is Apache License 2.0, and the repository carries LICENSE-2.0.txt at the top level. But the video modules depend on bytedeco artifacts wrapping FFMPEG and OpenCV, which carry their own terms. Pulling in boofcv-ffmpeg or boofcv-javacv means your dependency graph is no longer purely Apache 2.0, and the README does not discuss that. If your organisation has a policy about FFMPEG or OpenCV licensing, you need to check the bytedeco artifacts yourself, and the pure Java boofcv-jcodec reader is the alternative the README offers.

Second, the documentation surface is thin in places. The README is a build and module guide, not an API reference. It tells you which module to depend on and how to launch the examples, but it does not document algorithm parameters, accuracy expectations, or migration between 1.x releases. The examples and demonstrations directories are effectively the tutorial, which the README acknowledges by pointing there first.

Third, consider what the project is not. The README's functionality list ends at classification and recognition, with no mention of deep learning, GPU acceleration, or trained model inference. If your problem is object detection from a neural network, BoofCV gives you image processing and geometry, not the model.

Finally, the README does not document a rollback path or an API stability policy for the 1.x line, and the version shown in its own dependency snippet does not match the most recent tag listed for the repository. Treat upgrades as something to test rather than assume.

BoofCV versus OpenCV, and the narrower alternatives

The comparison people reach for is OpenCV, and the difference is structural rather than a matter of which is faster. OpenCV is a C++ library with bindings for many languages, including a Java binding, and it carries its own native binaries and its own build and packaging story. BoofCV is Java source, distributed through Maven Central, so a JVM build resolves it like any other dependency and the JVM's tooling and debugging apply throughout. That is the trade: you get a pure JVM dependency graph, and you give up the breadth of OpenCV's algorithm catalogue and its non-Java ecosystem.

The modules make the boundary visible. boofcv-javacv exists specifically because JavaCV is a wrapper around OpenCV, and the README describes it as being used mainly for file IO. In other words, when BoofCV users need OpenCV, they tend to need it for reading video, not for vision algorithms. If your work is dominated by video decoding and codec support, you are closer to the JavaCV and FFMPEG world than to BoofCV's core.

For a narrower job, a dedicated library may fit better than either. If all you need is QR generation and scanning, a single-purpose barcode library carries less surface area than a general vision toolkit, at the cost of the calibration, stereo and structure-from-motion code that BoofCV also provides.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-09-05. The release history shows v1.2.4 in October 2025, v1.3.0 in January 2026, v1.4.0 in May 2026, with the dependency snippet in the README referencing 1.5.0. That cadence suggests a project that ships several times a year rather than continuously, and the 1.x numbering means minor releases may carry API changes.

The upgrade cost concentrates in two places. First, native artifacts: the 1.5.0 change to unbundled FFMPEG and JavaCV binaries means anyone upgrading across that boundary must add platform classifiers to their build, and anyone maintaining a multi-platform build must keep those classifiers in sync. Second, generated code: the quick start runs ./gradlew autogenerate after git clean -fd main, which implies parts of the source tree are produced by a generator. If you build from source rather than consuming Maven artifacts, that generation step is part of your build, not an optional extra.

On licensing, the top-level LICENSE-2.0.txt and the README's Apache License 2.0 statement cover the library. The bytedeco dependencies for video IO are separate artifacts with their own terms, and the README does not analyse them. This is not legal advice; if FFMPEG or OpenCV redistribution matters to your product, read those licences directly.

Editorial conclusion

Adopt BoofCV when your application is already JVM-based and you want camera calibration, fiducial detection or stereo and structure-from-motion building blocks without a native OpenCV dependency. Do not adopt it if you need a trained deep learning stack, a Python-first workflow, or a library that guarantees binary compatibility across minor releases, because the README gives no such promise and the project is still at 1.x. Before committing, verify three things yourself: that the artifact version you pin exists on Maven Central, that your target platform has a matching bytedeco classifier if you need video IO, and that the specific algorithm you need is present in the module you plan to depend on rather than only in the examples or demonstrations directories.

Frequently asked questions

Official sources

1. Issues
2. lessthanoptimal/BoofCV on GitHub
3. Project website
4. README
5. Releases