opencv_contrib README

The project's README from github.com/opencv/opencv_contrib. As one markdown file: README.md.

Repository for OpenCV's extra modules

This repository is intended for the development of so-called "extra" modules, contributed functionality. New modules quite often do not have stable API, and they are not well-tested. Thus, they shouldn't be released as a part of the official OpenCV distribution, since the library maintains binary compatibility, and tries to provide decent performance and stability.

So, all the new modules should be developed separately, and published in the opencv_contrib repository at first. Later, when the module matures and gains popularity, it is moved to the central OpenCV repository, and the development team provides production-quality support for this module.

How to build OpenCV with extra modules

You can build OpenCV, so it will include the modules from this repository. Contrib modules are under constant development and it is recommended to use them alongside the master branch or latest releases of OpenCV.

Here is the CMake command for you:

$ cd <opencv_build_directory>
$ cmake -DOPENCV_EXTRA_MODULES_PATH=<opencv_contrib>/modules <opencv_source_directory>
$ make -j5

As the result, OpenCV will be built in the <opencv_build_directory> with all modules from opencv_contrib repository. If you don't want all of the modules, use CMake's BUILD_opencv_* options. Like in this example:

$ cmake -DOPENCV_EXTRA_MODULES_PATH=<opencv_contrib>/modules -DBUILD_opencv_legacy=OFF <opencv_source_directory>

If you also want to build the samples from the "samples" folder of each module, also include the "-DBUILD_EXAMPLES=ON" option.

If you prefer using the GUI version of CMake (cmake-gui), then, you can add opencv_contrib modules within opencv core by doing the following:

  1. Start cmake-gui.

  2. Select the opencv source code folder and the folder where binaries will be built (the 2 upper forms of the interface).

  3. Press the configure button. You will see all the opencv build parameters in the central interface.

  4. Browse the parameters and look for the form called OPENCV_EXTRA_MODULES_PATH (use the search form to focus rapidly on it).

  5. Complete this OPENCV_EXTRA_MODULES_PATH by the proper pathname to the <opencv_contrib>/modules value using its browse button.

  6. Press the configure button followed by the generate button (the first time, you will be asked which makefile style to use).

  7. Build the opencv core with the method you chose (make and make install if you chose Unix makefile at step 6).

  8. To run, linker flags to contrib modules will need to be added to use them in your code/IDE. For example to use the aruco module, "-lopencv_aruco" flag will be added.

Update the repository documentation

In order to keep a clean overview containing all contributed modules, the following files need to be created/adapted:

  1. Update the README.md file under the modules folder. Here, you add your model with a single-line description.

  2. Add a README.md inside your own module folder. This README explains which functionality (separate functions) is available, links to the corresponding samples, and explains in somewhat more detail what the module is expected to do. If any extra requirements are needed to build the module without problems, add them here also.

opencv_contrib (opencv/opencv_contrib)

Searching Database…

10.2K ·GitHub
Opencv_contrib
What is this?This is the repository for OpenCV's extra modules — contributed computer vision functionality that isn't stable or tested enough for the core OpenCV distribution yet.
Is this a standalone library or an add-on to something else?It's an add-on: a set of extra modules (like aruco) that you build together with the main OpenCV source tree, not a library you use on its own.
How do I build OpenCV with these extra modules?Run CMake against the main OpenCV source with the OPENCV_EXTRA_MODULES_PATH option pointing to this repo's modules folder, then build as usual (make/make install on Unix).
Do I need the main OpenCV repo to use this?Yes, this repo only contains extra modules and must be built alongside the core OpenCV source code (preferably matching master branch or latest release).
Are these modules production-ready?No — modules here often lack a stable API and aren't well-tested, which is exactly why they're kept out of the main OpenCV distribution until they mature.
Can I build only specific extra modules instead of all of them?Yes, you can use CMake's BUILD_opencv_ options to selectively enable or disable individual contrib modules.
What happens to a module once it becomes stable and popular?It gets moved from opencv_contrib into the central OpenCV repository, where the core team provides production-quality support for it.
What kind of module is an example of what's included here?The aruco module (for ArUco marker detection) is mentioned as an example extra module, linked at compile time with a flag like -lopencv_aruco.
Where do I find documentation for a specific module?Each module folder has its own README.md explaining its functionality, available functions, samples, and any extra build requirements.
What are similar projects?opencv, dlib, Detectron, EasyOCR, detectron2, X-AnyLabeling, openpose, kornia
Which topics is it in?opencv, image-classification, object-detection, cmake, algorithms, neural-network, 3d, image-processing, computer-vision, cuda, c++, deep-learning
Creator
opencv
Size
151.1 MB
Stars
10.2K
Updated
CommitOct 09
Age
13y
Commits · 90 Days