mjunaidi / opencv

OpenCV Java bindings packaged with native libraries, seamlessly delivered as a turn-key Maven dependency.

OpenCV 2.4.9 (packaged by Pattern)

OpenCV Java bindings packaged with native libraries, seamlessly delivered as a turn-key Maven dependency.

Usage

Project

Pattern's OpenCV package is added to your project as any other dependency.

Maven

<project>
  
  <!-- ... -->
  
  <dependencies>
    
    <!-- ... -->
    
    <dependency>
      <groupId>nu.pattern</groupId>
      <artifactId>opencv</artifactId>
      <version>2.4.9-7</version>
    </dependency>
    
    <!-- ... -->
    
  </dependencies>
  
  <!-- ... -->
  
</project>

SBT

// ...

libraryDependencies += "nu.pattern" % "opencv" % "2.4.9-7"

// ...

API

Typically, using the upstream OpenCV Java bindings involves loading the native library as follows:

static {
  System.loadLibrary(org.opencv.core.Core.NATIVE_LIBRARY_NAME);
}

Fortunately, this is unchanged except for one caveat. To use the native libraries included with this package, first call nu.pattern.OpenCV.loadShared().

This call will—exactly once per class loader—first attempt to load from the system-wide installation (exactly as if System.loadLibrary(org.opencv.core.Core.NATIVE_LIBRARY_NAME); were called without any preceding steps). If that fails, the loader will select a binary from the package appropriate for the runtime environment's operating system and architecture. It will write that native library to a temporary directory (also defined by the environment), add that directory to java.library.path. This involves writing to disk, so consider the implications. Temporary files will be garbage-collected on clean shutdown.

This approach keeps most clients decoupled from Pattern's package and loader. As long as this is done sufficiently early in execution, any library using the OpenCV Java bindings can use the usual load call as documented by the OpenCV project.

There are, however, cases where Java class loaders are frequently changing (e.g., application servers, SBT projects, Scala worksheets), and spurious attempts to load the native library will result in JNI errors. As a partial work-around, this package offers an alternative API, nu.pattern.OpenCV.loadLocal(), which—also exactly once per class loader—extracts the binary appropriate for the runtime platform, and passes it to System#load(String). Ultimately, this may eventually load the library redundantly in the same JVM, which could be unsafe in production. Use with caution and understand the implications.

It's recommended developers using any JNI library read further:

• JNI 1.2 Specifications: Library and Version Management
• Holger Hoffstätte's Comments on Native Libraries, Class Loaders, and Garbage Collection

Debugging

Java logging is used to produce log messages from nu.pattern.OpenCV.

Rationale

Developers wishing to use the Java API for OpenCV would typically go through the process of building the project, and building it for each platform they wished to support (e.g., 32-bit Linux, OS X). This project provides those binaries for inclusion as a typical dependency in Maven, Ivy, and SBT projects.

Apart from testing, this package deliberately specifies no external dependencies. It does, however, make use of modern Java APIs (such as Java NIO).

Contributing

Producing native binaries is the most cumbersome process in maintaining this package. If you can contribute binaries for the current version, please make a pull request including the build artifacts and any platform definitions in nu.pattern.OpenCV.

Support

The following platforms are supported by this package:

OS	Architecture
OS X	x86_32
OS X	x86_64
Linux	x86_64
Linux	x86_32

If you can help create binaries for additional platforms, please see notes under Contributing.

Credits

This package is maintained by Michael Ahlers.

Acknowledgements

• Greg Borenstein, who's advice and OpenCV for Processing project informed this package's development.
• Alex Osborne, for helpful utility class producing temporary directories with Java NIO that are properly garbage-collected on shutdown.