opencv_contrib

OpenCV Contributed Modules: An Introduction

The opencv_contrib repository serves as a creative space for OpenCV’s extra modules, focusing on development and contribution of additional functionalities. These modules are often experimental and may lack a stable API or comprehensive testing. As a result, they initially reside separately from the main OpenCV library to ensure the core library maintains its binary compatibility, performance standards, and stability. Modules from this repository can potentially graduate to the central OpenCV repository once they evolve and gain widespread use.

Building OpenCV with Extra Modules

To make use of the contribution modules from opencv_contrib, OpenCV can be compiled to include these new functionalities. Because these modules are continuously evolving, it's advisable to build them using the master branch or the latest releases of OpenCV. Below is a guide on how to build OpenCV with these additional modules.

Using Command Line

1. Navigate to your OpenCV build directory in the terminal.

2. Execute the following CMake command to build OpenCV with the extra modules:

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

3. This will build OpenCV in your specified directory, including all the modules from the opencv_contrib repository.

4. If there are certain modules you wish to exclude, specify them using CMake’s BUILD_opencv_* options. For instance, to exclude opencv_legacy, use:

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

5. To include samples from the "samples" folder of each module, add the -DBUILD_EXAMPLES=ON option.

Using CMake GUI

For those who prefer a graphical interface, CMake GUI can also be used to include opencv_contrib modules:

1. Start CMake GUI.
2. Select the OpenCV source code folder and the intended build directory.
3. Press the configure button to display the OpenCV build parameters.
4. Locate the OPENCV_EXTRA_MODULES_PATH field. Set it to <opencv_contrib>/modules.
5. Again press the configure, and then generate button (choose the appropriate makefile style if prompted).
6. Proceed to build the OpenCV core using your selected method.

When linking, apply linker flags for each contributing module needed for your applications. For example, to link the aruco module, use the -lopencv_aruco flag.

Documenting the Repository Updates

To effectively document the modules within opencv_contrib, certain files must be created or updated:

1. Modify the README.md within the modules folder, adding a brief description of each new module.
2. Create a README.md in your specific module's directory. This should detail available functions, include links to examples, and outline the module's intended functionalities. If there are additional build requirements, document them in this file as well.

The opencv_contrib repository enables developers to innovate and test new features without disrupting the stability of the main OpenCV library, supporting a diverse and expandable ecosystem of computer vision tools.