/IJ-OpenCV

Primary LanguageJavaGNU General Public License v3.0GPL-3.0

IJ-OpenCV is a Java library that allows the communication of ImageJ - a software for image analysis that is widely employed in life sciences - and OpenCV - a well-known computer vision library.
To do so, IJ-OpenCV provide a set of converter functions between ImageJ1 object (like ImagePlus and ROI, also used in Fiji) to their OpenCV equivalent (Mat...) and vice-versa.

There are several benefits provided by the communication of ImageJ and OpenCV.
From the ImageJ perspective, this tool is enhanced with several computer vision and machine learning algorithms, avoiding the re-implementation of methods and the connection with several external libraries.
From the OpenCV point of view, this library is improved with a simple-to-use GUI and with the functionality to manage regions of interest.

Keep in mind that the conversion between OpenCV and ImageJ type can introduce slight delay in the execution, especially for large images, therefore you should avoid repetitive conversion back and forth between OpenCv and ImageJ type. You should rather perform all opencv operations successively and then convert back to the ImageJ type (if necessary).

This new version of IJ-OpenCV has been built on top of SciJava Common using SciJava converters.

IJ-OpenCV is free to use and licensed under the license GNU GPL 3.0.

Notes

OpenCV functions are by design optimised for the processing of 2D images, which are represented as 2D matrices (Mat object).
Multi-channel matrices are possible (ex: RGB) however there is thus no multi-dimensional array contrary to e.g. numpy arrays in python.
3D volume can be analyzed slice-by-slice though.

Versions and dependencies

IJ-OpenCV is currently relying on OpenCV 3.4.2 and JavaCPP 1.4.2.
All dependencies are installed when activating the IJ-OpenCV update site in Fiji.

Citation

If you use IJ-OpenCV for your research please cite :

  • Domínguez, César, Jónathan Heras, and Vico Pascual. "IJ-OpenCV: Combining ImageJ and OpenCV for processing images in biomedicine." Computers in biology and medicine 84 (2017): 189-194.

Installation

- In Fiji

In Fiji, the library and plugins can be installed by simply ticking the IJ-OpenCV update site in your Fiji updater (Help>Update>Manage Update sites).

- With Maven

You can download and install the IJ-OpenCV library using maven; namely, including the following dependency in your pom.xml file:

      <repositories>
        <repository>
            <id>ossrh</id>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
        </repository>
      </repositories>
      ...
      <dependencies>
        <dependency>
            <groupId>io.github.joheras</groupId>
            <artifactId>IJ-OpenCV</artifactId>
            <version>1.2.1-SNAPSHOT</version>
        </dependency>
      ...
      </dependencies>

By default, this will download the OpenCV dependencies for all platforms (Windows, Linux, iOS, android...).
To only download the dependencies for a given platform, you can set the javacpp.platform property in Maven to linux-x86_64or windows-x86_64 as indicated here.

- Manual installation (ex: ImageJ)

The recommended installation procedure to include IJ-OpenCV in your project is the use of maven, but you can also directly download the IJ-OpenCV 1.0 binary archive IJ-OpenCV-1.0.jar. You will also need to install the binary files of JavaCV.
In order to execute the FaceDetection plugin it is necessary to download the following file and copy it to a new subfolder lib in ImageJ installation folder.

- Test images

You can download several images to test the plugins at the following link.

System requirements

IJ-OpenCV requires that ImageJ works with Java 8.

Documentation

Have a look at the wiki section for some help about how to use IJ-OpenCV in your own scripts.
Or at the IJ-OpenCV API documentation and related OpenCV API documentation.

Source files

The source files of the IJ-OpenCV library are available at the following link.

List of IJ-OpenCV plugins

The source code of the following plugins can be found in the examples folder.

  • Adaptive threshold: Given an image, it applies either the adaptive Gaussian threshold or the adaptive mean threshold. OpenCV link to the topic.
  • BGR histogram comparison: Given a stack of images, it compares the images using the BGR histogram and employing different measures . OpenCV link to the topic.
  • Black hat: Given a grayscale image, it returns such an image after applying the black hat morphological operation. OpenCV link to the topic.
  • Canny edge detection: Given an image, it detects its using the Canny edge detection algorithm. OpenCV link to the topic.
  • Convex hull from polygon: Given a polygonal selection, it returns its convex hull . OpenCV link to the topic.
  • Detect circles: Given an image, it detects the circles of such an image using the Hough Circle transform. OpenCV link to the topic.
  • Face detection: Given an image, it detects the faces of the image. With ImageJ, it is necessary to download the following file and copy it to a new subfolder lib in ImageJ installation folder. OpenCV link to the topic.
  • Find contours: Given an image, it detects the contours of the objects of such an image. OpenCV link to the topic.
  • High dynamic range imaging: Given a stack of images, it creates a high dynamic range image using the exposure fusion. OpenCV link to the topic.
  • Hough Lines: Given an image, it computes the lines of the image using the Hough transform. OpenCV link to the topic.
  • HSV histogram comparison: Given a stack of images, it compares the images using the HSV histogram and employing different measures . OpenCV link to the topic.
  • Keypoint detector: Given an image, it detects its keypoints using different algorithms. OpenCV link to the topic.
  • Kmeans clustering: Given a stack of images, it groups them using the BGR histogram as features and the Kmeans clustering algorithm. OpenCV link to the topic.
  • Non local means denoising: Given an image, it applies non local means denoising. OpenCV link to the topic.
  • RotatedRect from a polygon ROI: Given a polygonal selection, it returns the associated rotated rectangle. OpenCV link to the topic.
  • Stitching: Given an array of images, it stitches them creating a panoramic view. OpenCV link to the topic.
  • Template Matching: Given an image, and a selection (template) in that image, it finds all the other regions of the image that match with the template. OpenCV link to the topic.
  • White Hat: Given a grayscale image, it returns such an image after applying the white hat morphological operation. OpenCV link to the topic.

Videos

We include several videos showing how the plugins developed with the IJ-OpenCV library work.

Video 1

This first video shows how the "adaptive thresholding", "BGR Histogram Comparison" and "HSV Histogram comparison" plugins work.

Everything Is AWESOME

Video 2

This second video shows how the following plugins work:

  • BlackHat and White Hat morphological operators
  • Canny edge detection
  • Convex hull from polygon ROI
  • Circle detection
  • Measure oxidation
  • Face detection
  • Find Contours
  • High Dynamic Range Imaging

Everything Is AWESOME

Issues

To report bug and/or issues, you can open a github issue provided you have a GitHub account (free).
You can also create a topic on the central image processing forum, and tagging @joheras and/or @LThomas.

Contact

Jónathan Heras (joheras@gmail.com)