wehub/opencv--opencv
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:06:04 +08:00
commit 86c9b1c39f
7743 changed files with 3316339 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/tutorials/introduction/android_binary_package/android_dev_intro.markdown
+197
View File
@@ -0,0 +1,197 @@
Introduction into Android Development {#tutorial_android_dev_intro}
=====================================
@prev_tutorial{tutorial_clojure_dev_intro}
@next_tutorial{tutorial_dev_with_OCV_on_Android}
| | |
| -: | :- |
| Original author | Rostislav Vasilikhin |
| Compatibility | OpenCV >= 4.0 |
@tableofcontents
This guide was designed to help you in learning Android development basics and setting up your
working environment quickly. It was tested with Ubuntu 22.04 and Windows 10.
If you encounter any error after thoroughly following these steps, feel free to contact us via
OpenCV [Forum](https://forum.opencv.org). We'll do our best to help you out.
Preface
-------
Android is a Linux-based, open source mobile operating system developed by Open Handset Alliance led
by Google. See the [Android home site](http://www.android.com/about/) for general details.
Development for Android significantly differs from development for other platforms. So before
starting programming for Android we recommend you make sure that you are familiar with the following
key topics:
-# [Java](http://en.wikipedia.org/wiki/Java_(programming_language)) programming language that is
the primary development technology for Android OS. Also, you can find [Oracle docs on
Java](http://docs.oracle.com/javase/) useful.
-# [Java Native Interface (JNI)](http://en.wikipedia.org/wiki/Java_Native_Interface) that is a
technology of running native code in Java virtual machine. Also, you can find [Oracle docs on
JNI](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/) useful.
-# [Android
Activity](http://developer.android.com/training/basics/activity-lifecycle/starting.html) and its
life-cycle, that is an essential Android API class.
-# OpenCV development will certainly require some knowledge of the [Android
Camera](http://developer.android.com/guide/topics/media/camera.html) specifics.
Manual environment setup for Android development
------------------------------------------------
In this tutorial we're gonna use an official Android Studio IDE and a set of other freely available tools.
### Get tools and dependencies
Here's how to get a ready to work environment:
1. Download and install Android Studio:
* Ubuntu:
1. Download Android Studio: https://developer.android.com/studio
2. Extract the tar.gz archive
3. Follow the instructions in `Install-Linux-tar.txt`: open `android-studio/bin` folder in terminal and run `./studio.sh`
4. Perform standard installation through GUI
5. Optionally you can add a shortcut on a desktop for a quick access by clicking menu ***Tools -> Create desktop entry***. The menu appears after any project is created or opened.
* Windows:
Just download Android Studio from the official site and run installer.
2. Install fresh Android SDK and NDK:
1. Open SDK manager in Android Studio (***Customize -> All Settings -> Languages & Frameworks -> Android SDK***)
2. Enable "Show Package Details" checkbox
![](images/sdk_ndk_manager.png)
3. Check SDK and NDK of the latest versions and press OK
4. Make sure that your device support the chosen SDK versions
3. Install all the necessary packages for the build:
- `sudo apt install git cmake ninja-build openjdk-17-jdk openjdk-17-jre`
- the rest required packages are dependencies and should be installed automatically
### Check OpenCV examples
1. Download OpenCV from Android SDK from official [release page on Github](https://github.com/opencv/opencv/releases)
or [SourceForge](https://sourceforge.net/projects/opencvlibrary/).
2. Extract zip archive with your OS tools.
3. Open the project `<YOUR_OPENCV_BUILD_FOLDER>/OpenCV-android-sdk/samples` in Android Studio.
4. Connect your device
* Debugging should be enabled on a device, you can find an instruction about it across the web
* Alternatively you can use a virtual device that comes with the Android studio
![](images/choose_device.png)
5. Choose a sample from the drop-down menu (for example, `15-puzzle`) and run it.
Setup Device for Testing and Debugging
--------------------------------------
Usually the recipe above works as expected, but in some cases there are additional actions that must
be performed. In this section we'll cover some cases.
### Windows host computer
If you have Windows 10 or higher then you don't have to do additional actions to connect
a phone and run samples on it. However, earlier Windows versions require a longer procedure:
-# Enable USB debugging on the Android device (via Settings menu).
-# Attach the Android device to your PC with a USB cable.
-# Go to Start Menu and **right-click** on Computer. Select Manage in the context menu. You may be
asked for Administrative permissions.
-# Select Device Manager in the left pane and find an unknown device in the list. You may try
unplugging it and then plugging back in order to check whether it's your exact equipment appears
in the list.
![](images/usb_device_connect_01.png)
-# Try your luck installing Google USB drivers without any modifications: **right-click** on the
unknown device, select Properties menu item --\> Details tab --\> Update Driver button.
![](images/usb_device_connect_05.png)
-# Select Browse computer for driver software.
![](images/usb_device_connect_06.png)
-# Specify the path to `<Android SDK folder>/extras/google/usb_driver/` folder.
![](images/usb_device_connect_07.png)
-# If you get the prompt to install unverified drivers and report about success - you've finished
with USB driver installation.
![](images/usb_device_connect_08.png)
![](images/usb_device_connect_09.png)
-# Otherwise (getting the failure like shown below) follow the next steps.
![](images/usb_device_connect_12.png)
-# Again **right-click** on the unknown device, select Properties --\> Details --\> Hardware Ids
and copy the line like `USB\VID_XXXX&PID_XXXX&MI_XX`.
![](images/usb_device_connect_02.png)
-# Now open file `<Android SDK folder>/extras/google/usb_driver/android_winusb.inf`. Select either
Google.NTx86 or Google.NTamd64 section depending on your host system architecture.
![](images/usb_device_connect_03.png)
-# There should be a record like existing ones for your device and you need to add one manually.
![](images/usb_device_connect_04.png)
-# Save the `android_winusb.inf` file and try to install the USB driver again.
![](images/usb_device_connect_05.png)
![](images/usb_device_connect_06.png)
![](images/usb_device_connect_07.png)
-# This time installation should go successfully.
![](images/usb_device_connect_08.png)
![](images/usb_device_connect_09.png)
-# And an unknown device is now recognized as an Android phone.
![](images/usb_device_connect_10.png)
-# Successful device USB connection can be verified in console via adb devices command.
![](images/usb_device_connect_11.png)
-# Now, in Eclipse go Run -\> Run/Debug to run your application in regular or debugging mode.
Device Chooser will let you choose among the devices.
### Linux host computer
While the latest Ubuntu versions work well with connected Android devices, there can be issues on older versions.
However, most of them can be fixed easily. You have to create a new **/etc/udev/rules.d/51-android.rules** configuration file that contains
information about your Android device. You may find some Vendor ID's
[here](http://developer.android.com/tools/device.html#VendorIds) or execute lsusb command to view
VendorID of plugged Android device. Here is an example of such file for LG device:
@code{.guess}
SUBSYSTEM=="usb", ATTR{idVendor}=="1004", MODE="0666", GROUP="plugdev"
@endcode
Then restart your adb server (even better to restart the system), plug in your Android device and
execute adb devices command. You will see the list of attached devices:
```
savuor@rostislav-laptop:~/Android/Sdk/platform-tools$ ./adb devices
List of devices attached
R58MB40Q3VP device
savuor@rostislav-laptop:~/Android/Sdk/platform-tools$
```
### Mac OS host computer
No actions are required, just connect your device via USB and run adb devices to check connection.
What's next
-----------
Now, when you have your instance of OpenCV4Adroid SDK set up and configured, you may want to proceed
to using OpenCV in your own application. You can learn how to do that in a separate @ref tutorial_dev_with_OCV_on_Android tutorial.
doc/tutorials/introduction/android_binary_package/android_dnn_intro.markdown
+87
View File
@@ -0,0 +1,87 @@
# How to run deep networks on Android device {#tutorial_android_dnn_intro}
@tableofcontents
@prev_tutorial{tutorial_dev_with_OCV_on_Android}
@next_tutorial{tutorial_android_ocl_intro}
@see @ref tutorial_table_of_content_dnn
| | |
| -: | :- |
| Original author | Dmitry Kurtaev |
| Compatibility | OpenCV >= 4.9 |
@tableofcontents
## Introduction
In this tutorial you'll know how to run deep learning networks on Android device
using OpenCV deep learning module.
Tutorial was written for Android Studio 2022.2.1.
## Requirements
- Download and install Android Studio from https://developer.android.com/studio.
- Get the latest pre-built OpenCV for Android release from https://github.com/opencv/opencv/releases
and unpack it (for example, `opencv-4.X.Y-android-sdk.zip`, minimum version 4.9 is required).
- Download MobileNet object detection model from https://github.com/chuanqi305/MobileNet-SSD.
Configuration file `MobileNetSSD_deploy.prototxt` and model weights `MobileNetSSD_deploy.caffemodel`
are required.
## Create an empty Android Studio project and add OpenCV dependency
Use @ref tutorial_dev_with_OCV_on_Android tutorial to initialize your project and add OpenCV.
## Make an app
Our sample will takes pictures from a camera, forwards it into a deep network and
receives a set of rectangles, class identifiers and confidence values in range [0, 1].
- First of all, we need to add a necessary widget which displays processed
frames. Modify `app/src/main/res/layout/activity_main.xml`:
@include android/mobilenet-objdetect/res/layout/activity_main.xml
- Modify `/app/src/main/AndroidManifest.xml` to enable full-screen mode, set up
a correct screen orientation and allow to use a camera.
@code{.xml}
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application
android:label="@string/app_name">
@endcode
@snippet android/mobilenet-objdetect/gradle/AndroidManifest.xml mobilenet_tutorial
- Replace content of `app/src/main/java/com/example/myapplication/MainActivity.java` and set a custom package name if necessary:
@snippet android/mobilenet-objdetect/src/org/opencv/samples/opencv_mobilenet/MainActivity.java mobilenet_tutorial_package
@snippet android/mobilenet-objdetect/src/org/opencv/samples/opencv_mobilenet/MainActivity.java mobilenet_tutorial
- Put downloaded `deploy.prototxt` and `mobilenet_iter_73000.caffemodel`
into `app/src/main/res/raw` folder. OpenCV DNN model is mainly designed to load ML and DNN models
from file. Modern Android does not allow it without extra permissions, but provides Java API to load
bytes from resources. The sample uses alternative DNN API that initializes a model from in-memory
buffer rather than a file. The following function reads model file from resources and converts it to
`MatOfBytes` (analog of `std::vector<char>` in C++ world) object suitable for OpenCV Java API:
@snippet android/mobilenet-objdetect/src/org/opencv/samples/opencv_mobilenet/MainActivity.java mobilenet_tutorial_resource
And then the network initialization is done with the following lines:
@snippet android/mobilenet-objdetect/src/org/opencv/samples/opencv_mobilenet/MainActivity.java init_model_from_memory
See also [Android documentation on resources](https://developer.android.com/guide/topics/resources/providing-resources.html)
- Take a look how DNN model input is prepared and inference result is interpreted:
@snippet android/mobilenet-objdetect/src/org/opencv/samples/opencv_mobilenet/MainActivity.java mobilenet_handle_frame
`Dnn.blobFromImage` converts camera frame to neural network input tensor. Resize and statistical
normalization are applied. Each line of network output tensor contains information on one detected
object in the following order: confidence in range [0, 1], class id, left, top, right, bottom box
coordinates. All coordinates are in range [0, 1] and should be scaled to image size before rendering.
- Launch an application and make a fun!
![](images/11_demo.jpg)
doc/tutorials/introduction/android_binary_package/android_ocl_intro.markdown
+293
View File
@@ -0,0 +1,293 @@
Use OpenCL in Android camera preview based CV application {#tutorial_android_ocl_intro}
=====================================
@prev_tutorial{tutorial_android_dnn_intro}
@next_tutorial{tutorial_macos_install}
| | |
| -: | :- |
| Original author | Andrey Pavlenko, Alexander Panov |
| Compatibility | OpenCV >= 4.9 |
@tableofcontents
This guide was designed to help you in use of [OpenCL &trade;](https://www.khronos.org/opencl/) in Android camera preview based CV application.
Tutorial was written for [Android Studio](http://developer.android.com/tools/studio/index.html) 2022.2.1. It was tested with Ubuntu 22.04.
This tutorial assumes you have the following installed and configured:
- Android Studio (2022.2.1.+)
- JDK 17
- Android SDK
- Android NDK (25.2.9519653+)
- download OpenCV source code from [github](git@github.com:opencv/opencv.git) or from [releases](https://opencv.org/releases/) and build by [instruction on wiki](https://github.com/opencv/opencv/wiki/Custom-OpenCV-Android-SDK-and-AAR-package-build).
It also assumes that you are familiar with Android Java and JNI programming basics.
If you need help with anything of the above, you may refer to our @ref tutorial_android_dev_intro guide.
This tutorial also assumes you have an Android operated device with OpenCL enabled.
The related source code is located within OpenCV samples at
[opencv/samples/android/tutorial-4-opencl](https://github.com/opencv/opencv/tree/4.x/samples/android/tutorial-4-opencl/) directory.
How to build custom OpenCV Android SDK with OpenCL
--------------------------------------------------
1. __Assemble and configure Android OpenCL SDK.__
The JNI part of the sample depends on standard Khornos OpenCL headers, and C++ wrapper for OpenCL and libOpenCL.so.
The standard OpenCL headers may be copied from 3rdparty directory in OpenCV repository or you Linux distribution package.
C++ wrapper is available in [official Khronos reposiotry on Github](https://github.com/KhronosGroup/OpenCL-CLHPP).
Copy the header files to didicated directory in the following way:
@code{.bash}
cd your_path/ && mkdir ANDROID_OPENCL_SDK && mkdir ANDROID_OPENCL_SDK/include && cd ANDROID_OPENCL_SDK/include
cp -r path_to_opencv/opencv/3rdparty/include/opencl/1.2/CL . && cd CL
wget https://github.com/KhronosGroup/OpenCL-CLHPP/raw/main/include/CL/opencl.hpp
wget https://github.com/KhronosGroup/OpenCL-CLHPP/raw/main/include/CL/cl2.hpp
@endcode
libOpenCL.so may be provided with BSP or just downloaded from any OpenCL-cabaple Android device with relevant arhitecture.
@code{.bash}
cd your_path/ANDROID_OPENCL_SDK && mkdir lib && cd lib
adb pull /system/vendor/lib64/libOpenCL.so
@endcode
System verison of libOpenCL.so may have a lot of platform specific dependencies. `-Wl,--allow-shlib-undefined` flag allows
to ignore 3rdparty symbols if they are not used during the build.
The following CMake line allows to link the JNI part against standard OpenCL, but not include the loadLibrary into
application package. System OpenCL API is used in run-time.
@code
target_link_libraries(${target} -lOpenCL)
@endcode
2. __Build custom OpenCV Android SDK with OpenCL.__
OpenCL support (T-API) is disabled in OpenCV builds for Android OS by default.
but it's possible to rebuild locally OpenCV for Android with OpenCL/T-API enabled: use `-DWITH_OPENCL=ON` option for CMake.
You also need to specify the path to the Android OpenCL SDK: use `-DANDROID_OPENCL_SDK=path_to_your_Android_OpenCL_SDK` option for CMake.
If you are building OpenCV using `build_sdk.py` please follow [instruction on wiki](https://github.com/opencv/opencv/wiki/Custom-OpenCV-Android-SDK-and-AAR-package-build).
Set these CMake parameters in your `.config.py`, e.g. `ndk-18-api-level-21.config.py`:
@code{.py}
ABI("3", "arm64-v8a", None, 21, cmake_vars=dict('WITH_OPENCL': 'ON', 'ANDROID_OPENCL_SDK': 'path_to_your_Android_OpenCL_SDK'))
@endcode
If you are building OpenCV using cmake/ninja, use this bash script (set your NDK_VERSION and your paths instead of examples of paths):
@code{.bash}
cd path_to_opencv && mkdir build && cd build
export NDK_VERSION=25.2.9519653
export ANDROID_SDK=/home/user/Android/Sdk/
export ANDROID_OPENCL_SDK=/path_to_ANDROID_OPENCL_SDK/
export ANDROID_HOME=$ANDROID_SDK
export ANDROID_NDK_HOME=$ANDROID_SDK/ndk/$NDK_VERSION/
cmake -GNinja -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake -DANDROID_STL=c++_shared -DANDROID_NATIVE_API_LEVEL=24
-DANDROID_SDK=$ANDROID_SDK -DANDROID_NDK=$ANDROID_NDK_HOME -DBUILD_JAVA=ON -DANDROID_HOME=$ANDROID_SDK -DBUILD_ANDROID_EXAMPLES=ON
-DINSTALL_ANDROID_EXAMPLES=ON -DANDROID_ABI=arm64-v8a -DWITH_OPENCL=ON -DANDROID_OPENCL_SDK=$ANDROID_OPENCL_SDK ..
@endcode
Preface
-------
Using [GPGPU](https://en.wikipedia.org/wiki/General-purpose_computing_on_graphics_processing_units)
via OpenCL for applications performance enhancements is quite a modern trend now.
Some CV algo-s (e.g. image filtering) run much faster on a GPU than on a CPU.
Recently it has become possible on Android OS.
The most popular CV application scenario for an Android operated device is starting camera in preview mode, applying some CV algo to every frame
and displaying the preview frames modified by that CV algo.
Let's consider how we can use OpenCL in this scenario. In particular let's try two ways: direct calls to OpenCL API and recently introduced OpenCV T-API
(aka [Transparent API](https://docs.google.com/presentation/d/1qoa29N_B-s297-fp0-b3rBirvpzJQp8dCtllLQ4DVCY/present)) - implicit OpenCL accelerations of some OpenCV algo-s.
Application structure
---------------------
Starting Android API level 11 (Android 3.0) [Camera API](http://developer.android.com/reference/android/hardware/Camera.html)
allows use of OpenGL texture as a target for preview frames.
Android API level 21 brings a new [Camera2 API](http://developer.android.com/reference/android/hardware/camera2/package-summary.html)
that provides much more control over the camera settings and usage modes,
it allows several targets for preview frames and OpenGL texture in particular.
Having a preview frame in an OpenGL texture is a good deal for using OpenCL because there is an
[OpenGL-OpenCL Interoperability API (cl_khr_gl_sharing)](https://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/cl_khr_gl_sharing.html),
allowing sharing OpenGL texture data with OpenCL functions without copying (with some restrictions of course).
Let's create a base for our application that just configures Android camera to send preview frames to OpenGL texture and displays these frames
on display without any processing.
A minimal `Activity` class for that purposes looks like following:
@code{.java}
public class Tutorial4Activity extends Activity {
private MyGLSurfaceView mView;
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
requestWindowFeature(Window.FEATURE_NO_TITLE);
getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
WindowManager.LayoutParams.FLAG_FULLSCREEN);
getWindow().setFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON,
WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE);
mView = new MyGLSurfaceView(this);
setContentView(mView);
}
@Override
protected void onPause() {
mView.onPause();
super.onPause();
}
@Override
protected void onResume() {
super.onResume();
mView.onResume();
}
}
@endcode
And a minimal `View` class respectively:
@snippet samples/android/tutorial-4-opencl/src/org/opencv/samples/tutorial4/MyGLSurfaceView.java minimal_surface_view
@note we use two renderer classes: one for legacy [Camera](http://developer.android.com/reference/android/hardware/Camera.html) API
and another for modern [Camera2](http://developer.android.com/reference/android/hardware/camera2/package-summary.html).
A minimal `Renderer` class can be implemented in Java (OpenGL ES 2.0 [available](http://developer.android.com/reference/android/opengl/GLES20.html) in Java),
but since we are going to modify the preview texture with OpenCL let's move OpenGL stuff to JNI.
Here is a simple Java wrapper for our JNI stuff:
@snippet samples/android/tutorial-4-opencl/src/org/opencv/samples/tutorial4/NativePart.java native_part
Since `Camera` and `Camera2` APIs differ significantly in camera setup and control, let's create a base class for the two corresponding renderers:
@code{.java}
public abstract class MyGLRendererBase implements GLSurfaceView.Renderer, SurfaceTexture.OnFrameAvailableListener {
protected final String LOGTAG = "MyGLRendererBase";
protected SurfaceTexture mSTex;
protected MyGLSurfaceView mView;
protected boolean mGLInit = false;
protected boolean mTexUpdate = false;
MyGLRendererBase(MyGLSurfaceView view) {
mView = view;
}
protected abstract void openCamera();
protected abstract void closeCamera();
protected abstract void setCameraPreviewSize(int width, int height);
public void onResume() {
Log.i(LOGTAG, "onResume");
}
public void onPause() {
Log.i(LOGTAG, "onPause");
mGLInit = false;
mTexUpdate = false;
closeCamera();
if(mSTex != null) {
mSTex.release();
mSTex = null;
NativeGLRenderer.closeGL();
}
}
@Override
public synchronized void onFrameAvailable(SurfaceTexture surfaceTexture) {
//Log.i(LOGTAG, "onFrameAvailable");
mTexUpdate = true;
mView.requestRender();
}
@Override
public void onDrawFrame(GL10 gl) {
//Log.i(LOGTAG, "onDrawFrame");
if (!mGLInit)
return;
synchronized (this) {
if (mTexUpdate) {
mSTex.updateTexImage();
mTexUpdate = false;
}
}
NativeGLRenderer.drawFrame();
}
@Override
public void onSurfaceChanged(GL10 gl, int surfaceWidth, int surfaceHeight) {
Log.i(LOGTAG, "onSurfaceChanged("+surfaceWidth+"x"+surfaceHeight+")");
NativeGLRenderer.changeSize(surfaceWidth, surfaceHeight);
setCameraPreviewSize(surfaceWidth, surfaceHeight);
}
@Override
public void onSurfaceCreated(GL10 gl, EGLConfig config) {
Log.i(LOGTAG, "onSurfaceCreated");
String strGLVersion = GLES20.glGetString(GLES20.GL_VERSION);
if (strGLVersion != null)
Log.i(LOGTAG, "OpenGL ES version: " + strGLVersion);
int hTex = NativeGLRenderer.initGL();
mSTex = new SurfaceTexture(hTex);
mSTex.setOnFrameAvailableListener(this);
openCamera();
mGLInit = true;
}
}
@endcode
As you can see, inheritors for `Camera` and `Camera2` APIs should implement the following abstract methods:
@code{.java}
protected abstract void openCamera();
protected abstract void closeCamera();
protected abstract void setCameraPreviewSize(int width, int height);
@endcode
Let's leave the details of their implementation beyond of this tutorial, please refer the
[source code](https://github.com/opencv/opencv/tree/4.x/samples/android/tutorial-4-opencl/) to see them.
Preview Frames modification
---------------------------
The details OpenGL ES 2.0 initialization are also quite straightforward and noisy to be quoted here,
but the important point here is that the OpeGL texture to be the target for camera preview should be of type `GL_TEXTURE_EXTERNAL_OES`
(not `GL_TEXTURE_2D`), internally it keeps picture data in _YUV_ format.
That makes unable sharing it via CL-GL interop (`cl_khr_gl_sharing`) and accessing its pixel data via C/C++ code.
To overcome this restriction we have to perform an OpenGL rendering from this texture to another regular `GL_TEXTURE_2D` one
using _FrameBuffer Object_ (aka FBO).
### C/C++ code
After that we can read (_copy_) pixel data from C/C++ via `glReadPixels()` and write them back to texture after modification via `glTexSubImage2D()`.
### Direct OpenCL calls
Also that `GL_TEXTURE_2D` texture can be shared with OpenCL without copying, but we have to create OpenCL context with special way for that:
@snippet samples/android/tutorial-4-opencl/jni/CLprocessor.cpp init_opencl
Then the texture can be wrapped by a `cl::ImageGL` object and processed via OpenCL calls:
@snippet samples/android/tutorial-4-opencl/jni/CLprocessor.cpp process_pure_opencl
### OpenCV T-API
But instead of writing OpenCL code by yourselves you may want to use __OpenCV T-API__ that calls OpenCL implicitly.
All that you need is to pass the created OpenCL context to OpenCV (via `cv::ocl::attachContext()`) and somehow wrap OpenGL texture with `cv::UMat`.
Unfortunately `UMat` keeps OpenCL _buffer_ internally, that can't be wrapped over either OpenGL _texture_ or OpenCL _image_ - so we have to copy image data here:
@snippet samples/android/tutorial-4-opencl/jni/CLprocessor.cpp process_tapi
@note We have to make one more image data copy when placing back the modified image to the original OpenGL texture via OpenCL image wrapper.
Performance notes
-----------------
To compare the performance we measured FPS of the same preview frames modification (_Laplacian_) done by C/C++ code (call to `cv::Laplacian` with `cv::Mat`),
by direct OpenCL calls (using OpenCL _images_ for input and output), and by OpenCV _T-API_ (call to `cv::Laplacian` with `cv::UMat`) on _Sony Xperia Z3_ with 720p camera resolution:
* __C/C++ version__ shows __3-4 fps__
* __direct OpenCL calls__ shows __25-27 fps__
* __OpenCV T-API__ shows __11-13 fps__ (due to extra copying from `cl_image` to `cl_buffer` and back)
doc/tutorials/introduction/android_binary_package/dev_with_OCV_on_Android.markdown
+236
View File
@@ -0,0 +1,236 @@
Android Development with OpenCV {#tutorial_dev_with_OCV_on_Android}
===============================
@prev_tutorial{tutorial_android_dev_intro}
@next_tutorial{tutorial_android_dnn_intro}
| | |
| -: | :- |
| Original authors | Alexander Panov, Rostislav Vasilikhin |
| Compatibility | OpenCV >= 4.9.0 |
@tableofcontents
This tutorial has been created to help you use OpenCV library within your Android project.
This guide was checked on Ubuntu but contains no platform-dependent parts, therefore should be compatible with any OS supported by Android Studio and OpenCV4Android SDK.
This tutorial assumes you have the following installed and configured:
- Android Studio
- JDK
- Android SDK and NDK
- Optional: OpenCV for Android SDK from official [release page on Github](https://github.com/opencv/opencv/releases)
or [SourceForge](https://sourceforge.net/projects/opencvlibrary/). Advanced: as alternative the SDK may be
built from source code by [instruction on wiki](https://github.com/opencv/opencv/wiki/Custom-OpenCV-Android-SDK-and-AAR-package-build).
If you need help with anything of the above, you may refer to our @ref tutorial_android_dev_intro guide.
If you encounter any error after thoroughly following these steps, feel free to contact us via OpenCV [forum](https://forum.opencv.org). We'll do our best to help you out.
Hello OpenCV sample with SDK
----------------------------
In this section we're gonna create a simple app that does nothing but OpenCV loading. In next section we'll extend it to support camera.
In addition to this instruction you can use some video guide, for example [this one](https://www.youtube.com/watch?v=bR7lL886-uc&ab_channel=ProgrammingHut)
1. Open Android Studio and create empty project by choosing ***Empty Views Activity***
![](images/create_empty_project.png)
2. Setup the project:
- Choose ***Java*** language
- Choose ***Groovy DSL*** build configuration language
- Choose ***Minumum SDK*** with the version number not less than was used during OpenCV 4 Android build
- If you don't know it, you can find it in file `OpenCV-android-sdk/sdk/build.gradle` at `android -> defaultConfig -> minSdkVersion`
![](images/setup_project.png)
3. Click ***File -> New -> Import module...*** and select OpenCV SDK path
![](images/sdk_path.png)
4. Set module name as `OpenCV` and press `Finish`
![](images/module_name.png)
5. OpenCV also provides experiemental Kotlin support. Please add Android Kotlin plugin to `MyApplication/OpenCV/build.gradle` file:
@code{.gradle}
plugins {
id 'org.jetbrains.kotlin.android' version '1.7.10' #version may differ for your setup
}
@endcode
Like this:
![](images/gradle_ocv_fix.png)
If you don't do this, you may get an error:
@code
Task failed with an exception.
-----------
* Where:
Build file '/home/alexander/AndroidStudioProjects/MyApplication/opencv/build.gradle' line: 4
* What went wrong:
A problem occurred evaluating project ':opencv'.
> Plugin with id 'kotlin-android' not found.
@endcode
The fix was found [here](https://stackoverflow.com/questions/73225714/import-opencv-sdk-to-android-studio-chipmunk)
6. OpenCV project uses `buildConfig` feature. Please enable it in
`MyApplication/OpenCV/build.gradle` file to `android` block:
@code{.gradle}
buildFeatures{
buildConfig true
}
@endcode
Like this:
![](images/module_gradle_fix.png)
If you don't do this, you may get an error:
@code
JavaCameraView.java:15: error: cannot find symbol import org.opencv.BuildConfig; ^ symbol: class BuildConfig location: package org.opencv
@endcode
The fix was found [here](https://stackoverflow.com/questions/76374886/error-cannot-find-symbol-import-org-opencv-buildconfig-android-studio) and [here](https://forum.opencv.org/t/task-compiledebugjavawithjavac-failed/13667/4)
7. Add the module to the project:
- Click ***File -> Project structure... -> Dependencies -> All modules -> + (Add Dependency button) -> Module dependency***
![](images/add_module_1.png)
- Choose `app`
![](images/add_module_2.png)
- Select `OpenCV`
![](images/add_module_3.png)
8. Before using any OpenCV function you have to load the library first. If you application includes other OpenCV-dependent native libraries you should load them ***after*** OpenCV initialization.
Add the folowing code to load the library at app start:
@snippet samples/android/tutorial-1-camerapreview/src/org/opencv/samples/tutorial1/Tutorial1Activity.java ocv_loader_init
Like this:
![](images/sample_code.png)
9. Choose a device to check the sample on and run the code by pressing `run` button
![](images/run_app.png)
Hello OpenCV sample with Maven Central
--------------------------------------
Since OpenCV 4.9.0 OpenCV for Android package is available with Maven Central and may be installed
automatically as Gradle dependency. In this section we're gonna create a simple app that does nothing
but OpenCV loading with Maven Central.
1. Open Android Studio and create empty project by choosing ***Empty Views Activity***
![](images/create_empty_project.png)
2. Setup the project:
- Choose ***Java*** language
- Choose ***Groovy DSL*** build configuration language
- Choose ***Minumum SDK*** with the version number not less than OpenCV supports. For 4.9.0 minimal SDK version is 21.
![](images/setup_project.png)
3. Edit `build.gradle` and add OpenCV library to Dependencies list like this:
@code{.gradle}
dependencies {
implementation 'org.opencv:opencv:4.9.0'
}
@endcode
`4.9.0` may be replaced by any version available as [official release](https://central.sonatype.com/artifact/org.opencv/opencv).
4. Before using any OpenCV function you have to load the library first. If you application includes other
OpenCV-dependent native libraries you should load them ***after*** OpenCV initialization. Add the folowing
code to load the library at app start:
@snippet samples/android/tutorial-1-camerapreview/src/org/opencv/samples/tutorial1/Tutorial1Activity.java ocv_loader_init
Like this:
![](images/sample_code.png)
5. Choose a device to check the sample on and run the code by pressing `run` button
![](images/run_app.png)
Camera view sample
------------------
In this section we'll extend our empty OpenCV app created in the previous section to support camera. We'll take camera frames and display them on the screen.
1. Tell a system that we need camera permissions.
Add the following code to the file `MyApplication/app/src/main/AndroidManifest.xml`:
@snippet samples/android/tutorial-1-camerapreview/gradle/AndroidManifest.xml camera_permissions
Like this:
![](images/camera_permissions.png)
2. Go to `activity_main.xml` layout and delete TextView with text "Hello World!"
![](images/delete_text.png)
This can also be done in Code or Split mode by removing the `TextView` block from XML file.
3. Add camera view to the layout:
1. Add a scheme into layout description:
@code{.xml}
xmlns:opencv="http://schemas.android.com/apk/res-auto"
@endcode
2. Replace `TextView` with `org.opencv.android.JavaCameraView` widget:
@snippet /samples/android/tutorial-1-camerapreview/res/layout/tutorial1_surface_view.xml camera_view
3. If you get a layout warning replace `fill_parent` values by `match_parent` for `android:layout_width` and `android:layout_height` properties
You'll get a code like this:
@include /samples/android/tutorial-1-camerapreview/res/layout/tutorial1_surface_view.xml
4. Inherit the main class from `org.opencv.android.CameraActivity`. CameraActivity implements
camera perimission requiest and some other utilities needed for CV application. Methods we're
interested in to override are `onCreate`, `onDestroy`, `onPause`, `onResume` and `getCameraViewList`
5. Implement the interface `org.opencv.android.CameraBridgeViewBase.CvCameraViewListener2`
`onCameraFrame` method should return the `Mat` object with content for render.
The sample just returns camera frame for preview: `return inputFrame.rgba();`
6. Allocate `org.opencv.android.CameraBridgeViewBase` object:
- It should be created at app start (`onCreate` method) and this class should be set as a listener
- At pause/resume (`onPause`, `onResume` methods) it should be disabled/enabled
- Should be disabled at app finish (`onDestroy` method)
- Should be returned in `getCameraViewList`
7. Optionally you can forbid the phone to dim screen or lock:
@snippet samples/android/tutorial-1-camerapreview/src/org/opencv/samples/tutorial1/Tutorial1Activity.java keep_screen
Finally you'll get source code similar to this:
@include samples/android/tutorial-1-camerapreview/src/org/opencv/samples/tutorial1/Tutorial1Activity.java
This is it! Now you can run the code on your device to check it.
Let's discuss some most important steps
---------------------------------------
Every Android application with UI must implement Activity and View. By the first steps we create blank
activity and default view layout. The simplest OpenCV-centric application must perform OpenCV
initialization, create a view to show preview from camera and implement `CvCameraViewListener2` interface
to get frames from camera and process them.
First of all we create our application view using XML layout. Our layout consists of the only one
full screen component of class `org.opencv.android.JavaCameraView`. This OpenCV class is inherited from
`CameraBridgeViewBase` that extends `SurfaceView` and under the hood uses standard Android camera API.
The `CvCameraViewListener2` interface lets you add some processing steps after the frame is grabbed from
the camera and before it's rendered on the screen. The most important method is `onCameraFrame`. This is
a callback function and it's called on retrieving frame from camera. It expects that `onCameraFrame`
function returns RGBA frame that will be drawn on the screen.
The callback passes a frame from camera to our class as an object of `CvCameraViewFrame` class.
This object has `rgba()` and `gray()` methods that let a user get colored or one-channel grayscale
frame as a `Mat` class object.
@note Do not save or use `CvCameraViewFrame` object out of `onCameraFrame` callback. This object does
not have its own state and its behavior outside the callback is unpredictable!
doc/tutorials/introduction/android_binary_package/images/11_demo.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 118 KiB

doc/tutorials/introduction/android_binary_package/images/add_module_1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 243 KiB

doc/tutorials/introduction/android_binary_package/images/add_module_2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 181 KiB

doc/tutorials/introduction/android_binary_package/images/add_module_3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 235 KiB

doc/tutorials/introduction/android_binary_package/images/camera_permissions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 76 KiB

doc/tutorials/introduction/android_binary_package/images/choose_device.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 106 KiB

doc/tutorials/introduction/android_binary_package/images/create_empty_project.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 205 KiB

doc/tutorials/introduction/android_binary_package/images/delete_text.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 300 KiB

doc/tutorials/introduction/android_binary_package/images/gradle_ocv_fix.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 232 KiB

doc/tutorials/introduction/android_binary_package/images/module_gradle_fix.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

doc/tutorials/introduction/android_binary_package/images/module_name.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 103 KiB

doc/tutorials/introduction/android_binary_package/images/run_app.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

doc/tutorials/introduction/android_binary_package/images/sample_code.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 141 KiB

doc/tutorials/introduction/android_binary_package/images/sdk_ndk_manager.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 131 KiB

doc/tutorials/introduction/android_binary_package/images/sdk_path.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 217 KiB

doc/tutorials/introduction/android_binary_package/images/setup_project.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 294 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_01.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_02.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.7 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_03.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_04.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_05.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_06.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_07.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_08.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_09.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_10.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_11.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

doc/tutorials/introduction/android_binary_package/images/usb_device_connect_12.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.8 KiB

doc/tutorials/introduction/building_fastcv/building_fastcv.markdown
+318
View File
@@ -0,0 +1,318 @@
Building OpenCV with FastCV {#tutorial_building_fastcv}
===========================
| | |
| -: | :- |
| Compatibility | OpenCV >= 4.11.0 |
Enable OpenCV with FastCV for Qualcomm Chipsets
-----------------------------------------------
This document scope is to guide the Developers to enable OpenCV Acceleration with FastCV for the
Qualcomm chipsets with ARM64 architecture. Entablement of OpenCV with FastCV back-end on non-Qualcomm
chipsets or Linux platforms other than [Qualcomm Linux](https://www.qualcomm.com/developer/software/qualcomm-linux)
is currently out of scope.
About FastCV
------------
FastCV provides two main features to computer vision application developers:
- A library of frequently used computer vision (CV) functions, optimized to run efficiently on a wide variety of Qualcomm’s Snapdragon devices.
- A clean processor-agnostic hardware acceleration API, under which chipset vendors can hardware accelerate FastCV functions on Qualcomm’s Snapdragon hardware.
FastCV is released as a unified binary, a single binary containing two implementations of the algorithms:
- Generic implementation runs on Arm® architecture and is referred to as FastCV for Arm architecture.
- Implementation runs only on Qualcomm® Snapdragon™ chipsets and is called FastCV for Snapdragon.
FastCV library is Qualcomm proprietary and provides faster implementation of CV algorithms on various hardware as compared to other CV libraries.
OpenCV Acceleration with FastCV HAL and Extensions
--------------------------------------------------
OpenCV and FastCV integration is implemented in two ways:
1. FastCV-based HAL for basic computer vision and arithmetic algorithms acceleration.
2. FastCV module in opencv_contrib with custom algorithms and FastCV function wrappers that do not fit generic OpenCV interface or behaviour.
![](fastcv_hal_extns.png)
Supported Platforms
-------------------
1. Android : Qualcomm Chipsets with the Android from Snapdragon 8 Gen 1 onwards(https://www.qualcomm.com/products/mobile/snapdragon/smartphones#product-list)
2. Linux : Qualcomm Linux Program related boards mentioned in [Hardware](https://www.qualcomm.com/developer/software/qualcomm-linux/hardware)
Compiling OpenCV with FastCV for Android
----------------------------------------
1. **Follow Wiki page for OpenCV Compilation** : https://github.com/opencv/opencv/wiki/Custom-OpenCV-Android-SDK-and-AAR-package-build
Once the OpenCV repository code is cloned into the workspace, please add `-DWITH_FASTCV=ON` flag to cmake vars as below to arm64 entry
in `opencv/platforms/android/default.config.py` or create new one with the option to enable FastCV HAL and/or extenstions compilation:
```
ABI("3", "arm64-v8a", None, 24, cmake_vars=dict(WITH_FASTCV='ON')),
```
2. Remaining steps can be followed as mentioned in [the wiki page](https://github.com/opencv/opencv/wiki/Custom-OpenCV-Android-SDK-and-AAR-package-build)
Compiling OpenCV with FastCV for Qualcomm Linux
-----------------------------------------------
@note: Only Ubuntu 22.04 is supported as host platform for eSDK deployment.
1. Install eSDK by following [Qualcomm® Linux Documentation](https://docs.qualcomm.com/bundle/publicresource/topics/80-70017-51/install-sdk.html)
2. After installing the eSDK, set the ESDK_ROOT:
```
export ESDK_ROOT=<eSDK install location>
```
3. Add SDK tools and libraries to your environment:
```
source environment-setup-armv8-2a-qcom-linux
```
If you encounter the following message:
```
Your environment is misconfigured, you probably need to 'unset LD_LIBRARY_PATH'
but please check why this was set in the first place and that it's safe to unset.
The SDK will not operate correctly in most cases when LD_LIBRARY_PATH is set.
```
just unset your host `LD_LIBRARY_PATH` environment variable: `unset LD_LIBRARY_PATH`.
4. Clone OpenCV Repositories:
Clone the OpenCV main and optionally opencv_contrib repositories into any directory
(it does not need to be inside the SDK directory).
```
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git
```
5. Build OpenCV
Create a build directory, navigate into it and build the project with CMake there:
```
mkdir build
cd build
cmake -DCMAKE_SYSTEM_NAME=Linux -DCMAKE_SYSTEM_PROCESSOR=aarch64 -DWITH_FASTCV=ON -DBUILD_SHARED_LIBS=ON -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules/fastcv/ ../opencv
make -j$(nproc)
```
If the FastCV library is updated, please replace the old FastCV libraries located at:
```
<ESDK_PATH>\qcom-wayland_sdk\tmp\sysroots\qcs6490-rb3gen2-vision-kit\usr\lib
```
with the latest FastCV libraries downloaded in:
```
build\3rdparty\fastcv\libs
```
6. Validate
Push the OpenCV libraries, test binaries and test data on to the target. Execute the OpenCV conformance or performance tests.
During runtime, If libwebp.so.7 lib is missing, find the lib in the below Path and push it on the target
```
<ESDK_PATH>\qcom-wayland_sdk\tmp\sysroots\qcs6490-rb3gen2-vision-kit\usr\lib\libwebp.so.7
```
HAL and Extension list of APIs
------------------------------
**FastCV based OpenCV HAL APIs list :**
|OpenCV module |OpenCV API | Underlying FastCV API for OpenCV acceleration |
|---------------|------------------|-----------------------------------------------|
|IMGPROC |medianBlur |fcvFilterMedian3x3u8_v3 |
| |sobel |fcvFilterSobel3x3u8s16 |
| | |fcvFilterSobel5x5u8s16 |
| | |fcvFilterSobel7x7u8s16 |
| |boxFilter |fcvBoxFilter3x3u8_v3 |
| | |fcvBoxFilter5x5u8_v2 |
| | |fcvBoxFilterNxNf32 |
| |adaptiveThreshold |fcvAdaptiveThresholdGaussian3x3u8_v2 |
| | |fcvAdaptiveThresholdGaussian5x5u8_v2 |
| | |fcvAdaptiveThresholdMean3x3u8_v2 |
| | |fcvAdaptiveThresholdMean5x5u8_v2 |
| |pyrDown |fcvPyramidCreateu8_v4 |
| |cvtColor |fcvColorRGB888toYCrCbu8_v3 |
| | |fcvColorRGB888ToHSV888u8 |
| |gaussianBlur |fcvFilterGaussian5x5u8_v3 |
| | |fcvFilterGaussian3x3u8_v4 |
| |warpPerspective |fcvWarpPerspectiveu8_v5 |
| |Canny |fcvFilterCannyu8 |
| | | |
|CORE |lut | fcvTableLookupu8 |
| |norm |fcvHammingDistanceu8 |
| |multiply |fcvElementMultiplyu8u16_v2 |
| |transpose |fcvTransposeu8_v2 |
| | |fcvTransposeu16_v2 |
| | |fcvTransposef32_v2 |
| |meanStdDev |fcvImageIntensityStats_v2 |
| |flip |fcvFlipu8 |
| | |fcvFlipu16 |
| | |fcvFlipRGB888u8 |
| |rotate |fcvRotateImageu8 |
| | |fcvRotateImageInterleavedu8 |
| |multiply |fcvElementMultiplyu8 |
| | |fcvElementMultiplys16 |
| | |fcvElementMultiplyf32 |
| |addWeighted |fcvAddWeightedu8_v2 |
| |subtract |fcvImageDiffu8f32_v2 |
| |SVD & solve |fcvSVDf32_v2 |
| |gemm |fcvMatrixMultiplyf32_v2 |
| | |fcvMultiplyScalarf32 |
| | |fcvAddf32_v2 |
**FastCV based OpenCV Extensions APIs list :**
These OpenCV extension APIs are implemented under the **cv::fastcv** namespace.
|OpenCV Extension APIs |Underlying FastCV API for OpenCV acceleration |
|----------------------|----------------------------------------------|
|matmuls8s32 |fcvMatrixMultiplys8s32 |
|clusterEuclidean |fcvClusterEuclideanu8 |
|FAST10 |fcvCornerFast10InMaskScoreu8 |
| |fcvCornerFast10InMasku8 |
| |fcvCornerFast10Scoreu8 |
| |fcvCornerFast10u8 |
|FFT |fcvFFTu8 |
|IFFT |fcvIFFTf32 |
|fillConvexPoly |fcvFillConvexPolyu8 |
|houghLines |fcvHoughLineu8 |
|moments |fcvImageMomentsu8 |
| |fcvImageMomentss32 |
| |fcvImageMomentsf32 |
|runMSER |fcvMserInit |
| |fcvMserNN8Init |
| |fcvMserExtu8_v3 |
| |fcvMserExtNN8u8 |
| |fcvMserNN8u8 |
| |fcvMserRelease |
|remap |fcvRemapu8_v2 |
|remapRGBA |fcvRemapRGBA8888BLu8 |
| |fcvRemapRGBA8888NNu8 |
|resizeDown |fcvScaleDownBy2u8_v2 |
| |fcvScaleDownBy4u8_v2 |
| |fcvScaleDownMNInterleaveu8 |
| |fcvScaleDownMNu8 |
|meanShift |fcvMeanShiftu8 |
| |fcvMeanShifts32 |
| |fcvMeanShiftf32 |
|bilateralRecursive |fcvBilateralFilterRecursiveu8 |
|thresholdRange |fcvFilterThresholdRangeu8_v2 |
|bilateralFilter |fcvBilateralFilter5x5u8_v3 |
| |fcvBilateralFilter7x7u8_v3 |
| |fcvBilateralFilter9x9u8_v3 |
|calcHist |fcvImageIntensityHistogram |
|gaussianBlur |fcvFilterGaussian3x3u8_v4 |
| |fcvFilterGaussian5x5u8_v3 |
| |fcvFilterGaussian5x5s16_v3 |
| |fcvFilterGaussian5x5s32_v3 |
| |fcvFilterGaussian11x11u8_v2 |
|filter2D |fcvFilterCorrNxNu8 |
| |fcvFilterCorrNxNu8s16 |
| |fcvFilterCorrNxNu8f32 |
|sepFilter2D |fcvFilterCorrSepMxNu8 |
| |fcvFilterCorrSep9x9s16_v2 |
| |fcvFilterCorrSep11x11s16_v2 |
| |fcvFilterCorrSep13x13s16_v2 |
| |fcvFilterCorrSep15x15s16_v2 |
| |fcvFilterCorrSep17x17s16_v2 |
| |fcvFilterCorrSepNxNs16 |
|sobel3x3u8 |fcvImageGradientSobelPlanars8_v2 |
|sobel3x3u8 |fcvImageGradientSobelPlanars16_v2 |
|sobel3x3u8 |fcvImageGradientSobelPlanars16_v3 |
|sobel3x3u8 |fcvImageGradientSobelPlanarf32_v2 |
|sobel3x3u8 |fcvImageGradientSobelPlanarf32_v3 |
|sobel |fcvFilterSobel3x3u8_v2 |
| |fcvFilterSobel3x3u8s16 |
| |fcvFilterSobel5x5u8s16 |
| |fcvFilterSobel7x7u8s16 |
|DCT |fcvDCTu8 |
|iDCT |fcvIDCTs16 |
|sobelPyramid |fcvPyramidAllocate |
| |fcvPyramidAllocate_v2 |
| |fcvPyramidAllocate_v3 |
| |fcvPyramidSobelGradientCreatei8 |
| |fcvPyramidSobelGradientCreatei16 |
| |fcvPyramidSobelGradientCreatef32 |
| |fcvPyramidDelete |
| |fcvPyramidDelete_v2 |
| |fcvPyramidCreatef32_v2 |
| |fcvPyramidCreateu8_v4 |
|trackOpticalFlowLK |fcvTrackLKOpticalFlowu8_v3 |
| |fcvTrackLKOpticalFlowu8 |
|warpPerspective2Plane |fcv2PlaneWarpPerspectiveu8 |
|warpPerspective |fcvWarpPerspectiveu8_v5 |
|arithmetic_op |fcvAddu8 |
| |fcvAdds16_v2 |
| |fcvAddf32 |
| |fcvSubtractu8 |
| |fcvSubtracts16 |
|integrateYUV |fcvIntegrateImageYCbCr420PseudoPlanaru8 |
|normalizeLocalBox |fcvNormalizeLocalBoxu8 |
| |fcvNormalizeLocalBoxf32 |
|merge |fcvChannelCombine2Planesu8 |
| |fcvChannelCombine3Planesu8 |
| |fcvChannelCombine4Planesu8 |
|split |fcvDeinterleaveu8 |
| |fcvChannelExtractu8 |
|warpAffine |fcvTransformAffineu8_v2 |
| |fcvTransformAffineClippedu8_v3 |
| |fcv3ChannelTransformAffineClippedBCu8 |
**FastCV QDSP based OpenCV Extension APIs list :**
These OpenCV extension APIs are implemented under the **cv::fastcv::dsp** namespace.
This namespace provides optimized implementations that leverage QDSP (**Qualcomm's Digital Signal Processor**) acceleration using FastCV's Q-suffixed APIs. These functions require DSP initialization (fcvQ6Init).
|OpenCV Extension APIs |Underlying FastCV API for OpenCV acceleration |
|----------------------|----------------------------------------------|
|filter2D |fcvFilterCorr3x3s8_v2Q |
| |fcvFilterCorrNxNu8Q |
| |fcvFilterCorrNxNu8s16Q |
| |fcvFilterCorrNxNu8f32Q |
|FFT |fcvFFTu8Q |
|IFFT |fcvIFFTf32Q |
|fcvdspinit |fcvQ6Init |
|fcvdspdeinit |fcvQ6DeInit |
|Canny |fcvFilterCannyu8Q |
|sumOfAbsoluteDiffs |fcvSumOfAbsoluteDiffs8x8u8_v2Q |
|thresholdOtsu |fcvFilterThresholdOtsuu8Q |
**How to Use FastCV QDSP based OpenCV Extension APIs**
This section outlines the essential steps required to use OpenCV Extension APIs that are accelerated using FastCV on QDSP(**Qualcomm's Digital Signal Processor**).
1. Initialize QDSP:
- Call **cv::fastcv::dsp::fcvdspinit()** to initialize the QDSP.
2. Allocate memory using **Qualcomm's memory allocator** for all buffers that are being fed to the OpenCV extension API.:
- Use **cv::fastcv::getQcAllocator()** to assign the allocator to the buffers.
- Example:
cv::Mat src;
src.allocator = cv::fastcv::getQcAllocator(); **// Set Qualcomm's memory allocator**
\
After setting Qualcomm's memory allocator, any buffer created using methods like src.create(...), cv::imread(...) etc., will have its memory allocated using Qualcomm's memory allocator.
3. Call the OpenCV extension API from 'cv::fastcv::dsp':
- Example: **cv::fastcv::dsp::thresholdOtsu(src, dst, binaryType);**
where 'src' and 'dst' are 'cv::Mat' objects with the Qualcomm's memory allocator,
     and 'binaryType' is a boolean indicating the thresholding mode.
4. Deinitialize QDSP:
- Call **cv::fastcv::dsp::fcvdspdeinit()** to deinitialize the QDSP.
**Reference Example**:
Refer to a working test case using the OpenCV Extension APIs in the opencv_contrib repository:[opencv_contrib/modules/fastcv/test/test_thresh_dsp.cpp](https://github.com/opencv/opencv_contrib/blob/4.x/modules/fastcv/test/test_thresh_dsp.cpp)
doc/tutorials/introduction/building_fastcv/fastcv_hal_extns.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

doc/tutorials/introduction/building_tegra_cuda/building_tegra_cuda.markdown
+655
View File
@@ -0,0 +1,655 @@
Building OpenCV for Tegra with CUDA {#tutorial_building_tegra_cuda}
===================================
@prev_tutorial{tutorial_arm_crosscompile_with_cmake}
@next_tutorial{tutorial_display_image}
| | |
| -: | :- |
| Original author | Randy J. Ray |
| Compatibility | OpenCV >= 3.1.0 |
@warning
This tutorial is deprecated.
@tableofcontents
OpenCV with CUDA for Tegra
--------------------------
This document is a basic guide to building the OpenCV libraries with CUDA support for use in the Tegra environment. It covers the basic elements of building the version 3.1.0 libraries from source code for three (3) different types of platforms:
* NVIDIA DRIVE&trade; PX 2 (V4L)
* NVIDIA<sup>&reg;</sup> Tegra<sup>&reg;</sup> Linux Driver Package (L4T)
* Desktop Linux (Ubuntu 14.04 LTS and 16.04 LTS)
This document is not an exhaustive guide to all of the options available when building OpenCV. Specifically, it covers the basic options used when building each platform but does not cover any options that are not needed (or are unchanged from their default values). Additionally, the installation of the CUDA toolkit is not covered here.
This document is focused on building the 3.1.0 version of OpenCV, but the guidelines here may also work for building from the master branch of the git repository. There are differences in some of the CMake options for builds of the 2.4.13 version of OpenCV, which are summarized below in the @ref tutorial_building_tegra_cuda_opencv_24X section.
Most of the configuration commands are based on the system having CUDA 8.0 installed. In the case of the Jetson TK1, an older CUDA is used because 8.0 is not supported for that platform. These instructions may also work with older versions of CUDA, but are only tested with 8.0.
### A Note on Native Compilation vs. Cross-Compilation
The OpenCV build system supports native compilation for all the supported platforms, as well as cross-compilation for platforms such as ARM and others. The native compilation process is simpler, whereas the cross-compilation is generally faster.
At the present time, this document focuses only on native compilation.
Getting the Source Code {#tutorial_building_tegra_cuda_getting_the_code}
-----------------------
There are two (2) ways to get the OpenCV source code:
* Direct download from the [OpenCV downloads](https://opencv.org/releases) page
* Cloning the git repositories hosted on [GitHub](https://github.com/opencv)
For this guide, the focus is on using the git repositories. This is because the 3.1.0 version of OpenCV will not build with CUDA 8.0 without applying a few small upstream changes from the git repository.
### OpenCV
Start with the `opencv` repository:
# Clone the opencv repository locally:
$ git clone https://github.com/opencv/opencv.git
To build the 3.1.0 version (as opposed to building the most-recent source), you must check out a branch based on the `3.1.0` tag:
$ cd opencv
$ git checkout -b v3.1.0 3.1.0
__Note:__ This operation creates a new local branch in your clone's repository.
There are some upstream changes that must be applied via the `git cherry-pick` command. The first of these is to apply a fix for building specifically with the 8.0 version of CUDA that was not part of the 3.1.0 release:
# While still in the opencv directory:
$ git cherry-pick 10896
You will see the following output from the command:
[v3.1.0 d6d69a7] GraphCut deprecated in CUDA 7.5 and removed in 8.0
Author: Vladislav Vinogradov <vlad.vinogradov@itseez.com>
1 file changed, 2 insertions(+), 1 deletion(-)
Secondly, there is a fix for a CMake macro call that is problematic on some systems:
$ git cherry pick cdb9c
You should see output similar to:
[v3.1.0-28613 e5ac2e4] gpu samples: fix REMOVE_ITEM error
Author: Alexander Alekhin <alexander.alekhin@itseez.com>
1 file changed, 1 insertion(+), 1 deletion(-)
The last upstream fix that is needed deals with the `pkg-config` configuration file that is bundled with the developer package (`libopencv-dev`):
$ git cherry-pick 24dbb
You should see output similar to:
[v3.1.0 3a6d7ab] pkg-config: modules list contains only OpenCV modules (fixes #5852)
Author: Alexander Alekhin <alexander.alekhin@itseez.com>
1 file changed, 7 insertions(+), 4 deletions(-)
At this point, the `opencv` repository is ready for building.
### OpenCV Extra
The `opencv_extra` repository contains extra data for the OpenCV library, including the data files used by the tests and demos. It must be cloned separately:
# In the same base directory from which you cloned OpenCV:
$ git clone https://github.com/opencv/opencv_extra.git
As with the OpenCV source, you must use the same method as above to set the source tree to the 3.1.0 version. When you are building from a specific tag, both repositories must be checked out at that tag.
$ cd opencv_extra
$ git checkout -b v3.1.0 3.1.0
You may opt to not fetch this repository if you do not plan on running the tests or installing the test-data along with the samples and example programs. If it is not referenced in the invocation of CMake, it will not be used.
__Note:__ If you plan to run the tests, some tests expect the data to be present and will fail without it.
Preparation and Prerequisites {#tutorial_building_tegra_cuda_preparation}
-----------------------------
To build OpenCV, you need a directory to create the configuration and build the libraries. You also need a number of 3rd-party libraries upon which OpenCV depends.
### Prerequisites for Ubuntu Linux
These are the basic requirements for building OpenCV for Tegra on Linux:
* CMake 2.8.10 or newer
* CUDA toolkit 8.0 (7.0 or 7.5 may also be used)
* Build tools (make, gcc, g++)
* Python 2.6 or greater
These are the same regardless of the platform (DRIVE PX 2, Desktop, etc.).
A number of development packages are required for building on Linux:
* libglew-dev
* libtiff5-dev
* zlib1g-dev
* libjpeg-dev
* libpng12-dev
* libjasper-dev
* libavcodec-dev
* libavformat-dev
* libavutil-dev
* libpostproc-dev
* libswscale-dev
* libeigen3-dev
* libtbb-dev
* libgtk2.0-dev
* pkg-config
Some of the packages above are in the `universe` repository for Ubuntu Linux systems. If you have not already enabled that repository, you need to do the following before trying to install all of the packages listed above:
$ sudo apt-add-repository universe
$ sudo apt-get update
The following command can be pasted into a shell in order to install the required packages:
$ sudo apt-get install \
libglew-dev \
libtiff5-dev \
zlib1g-dev \
libjpeg-dev \
libpng12-dev \
libjasper-dev \
libavcodec-dev \
libavformat-dev \
libavutil-dev \
libpostproc-dev \
libswscale-dev \
libeigen3-dev \
libtbb-dev \
libgtk2.0-dev \
pkg-config
(Line-breaks and continuation characters are added for readability.)
If you want the Python bindings to be built, you will also need the appropriate packages for either or both of Python 2 and Python 3:
* python-dev / python3-dev
* python-numpy / python3-numpy
* python-py / python3-py
* python-pytest / python3-pytest
The commands that will do this:
$ sudo apt-get install python-dev python-numpy python-py python-pytest
# And, optionally:
$ sudo apt-get install python3-dev python3-numpy python3-py python3-pytest
Once all the necessary packages are installed, you can configure the build.
### Preparing the Build Area
Software projects that use the CMake system for configuring their builds expect the actual builds to be done outside of the source tree itself. For configuring and building OpenCV, create a directory called "build" in the same base directory into which you cloned the git repositories:
$ mkdir build
$ cd build
You are now ready to configure and build OpenCV.
Configuring OpenCV for Building {#tutorial_building_tegra_cuda_configuring}
-------------------------------
The CMake configuration options given below for the different platforms are targeted towards the functionality needed for Tegra. They are based on the original configuration options used for building OpenCV 2.4.13.
The build of OpenCV is configured with CMake. If run with no parameters, it detects what it needs to know about your system. However, it may have difficulty finding the CUDA files if they are not in a standard location, and it may try to build some options that you might otherwise not want included, so the following invocations of CMake are recommended.
In each `cmake` command listed in the following sub-sections, line-breaks and indentation are added for readability. Continuation characters are also added in examples for Linux-based platforms, allowing you to copy and paste the examples directly into a shell. When entering these commands by hand, enter the command and options as a single line. For a detailed explanation of the parameters passed to `cmake`, see the "CMake Parameter Reference" section.
For the Linux-based platforms, the shown value for the `CMAKE_INSTALL_PREFIX` parameter is `/usr`. You can set this to whatever you want, based on the layout of your system.
In each of the `cmake` invocations below, the last parameter, `OPENCV_TEST_DATA_PATH`, tells the build system where to find the test-data that is provided by the `opencv_extra` repository. When this is included, a `make install` installs this test-data alongside the libraries and example code, and a `make test` automatically provides this path to the tests that have to load data from it. If you did not clone the `opencv_extra` repository, do not include this parameter.
### Vibrante V4L Configuration
Supported platform: Drive PX 2
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_python2=ON \
-DBUILD_opencv_python3=OFF \
-DENABLE_NEON=ON \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-8.0 \
-DCUDA_ARCH_BIN=6.2 \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=OFF \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
The configuration provided above builds the Python bindings for Python 2 (but not Python 3) as part of the build process. If you want the Python 3 bindings (or do not want the Python 2 bindings), change the values of `BUILD_opencv_python2` and/or `BUILD_opencv_python3` as needed. To enable bindings, set the value to `ON`, to disable them set it to `OFF`:
-DBUILD_opencv_python2=OFF
### Jetson L4T Configuration
Supported platforms:
* Jetson TK1
* Jetson TX1
Configuration is slightly different for the Jetson TK1 and the Jetson TX1 systems.
#### Jetson TK1
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_CXX_FLAGS=-Wa,-mimplicit-it=thumb \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_python2=ON \
-DBUILD_opencv_python3=OFF \
-DENABLE_NEON=ON \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-6.5 \
-DCUDA_ARCH_BIN=3.2 \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=OFF \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
__Note:__ This uses CUDA 6.5, not 8.0.
#### Jetson TX1
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_python2=ON \
-DBUILD_opencv_python3=OFF \
-DENABLE_PRECOMPILED_HEADERS=OFF \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-8.0 \
-DCUDA_ARCH_BIN=5.3 \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=OFF \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
__Note:__ This configuration does not set the `ENABLE_NEON` parameter.
### Ubuntu Desktop Linux Configuration
Supported platforms:
* Ubuntu Desktop Linux 14.04 LTS
* Ubuntu Desktop Linux 16.04 LTS
The configuration options given to `cmake` below are targeted towards the functionality needed for Tegra. For a desktop system, you may wish to adjust some options to enable (or disable) certain features. The features enabled below are based on the building of OpenCV 2.4.13.
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_python2=ON \
-DBUILD_opencv_python3=OFF \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-8.0 \
-DCUDA_ARCH_BIN='3.0 3.5 5.0 6.0 6.2' \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=OFF \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
This configuration is nearly identical to that for V4L and L4T, except that the `CUDA_ARCH_BIN` parameter specifies multiple architectures so as to support a variety of GPU boards. For a desktop, you have the option of omitting this parameter, and CMake will instead run a small test program that probes for the supported architectures. However, the libraries produced might not work on Ubuntu systems with different cards.
As with previous examples, the configuration given above builds the Python bindings for Python 2 (but not Python 3) as part of the build process.
Building OpenCV {#tutorial_building_tegra_cuda_building}
---------------
Once `cmake` finishes configuring OpenCV, building is done using the standard `make` utility.
### Building with `make`
The only parameter that is needed for the invocation of `make` is the `-j` parameter for specifying how many parallel threads to use. This varies depending on the system and how much memory is available, other running processes, etc. The following table offers suggested values for this parameter:
|Platform|Suggested value|Notes|
|--------|---------------|-----|
|DRIVE PX 2|6| |
|Jetson TK1|3|If the build fails due to a compiler-related error, try again with a smaller number of threads. Also consider rebooting the system if it has been running for a long time since the last reboot.|
|Jetson TX1|4| |
|Ubuntu Desktop|7|The actual value will vary with the number of cores you have and the amount of physical memory. Because of the resource requirements of compiling the CUDA code, it is not recommended to go above 7.|
Based on the value you select, build (assuming you selected 6):
$ make -j6
By default, CMake hides the details of the build steps. If you need to see more detail about each compilation unit, etc., you can enable verbose output:
$ make -j6 VERBOSE=1
Testing OpenCV {#tutorial_building_tegra_cuda_testing}
--------------
Once the build completes successfully, you have the option of running the extensive set of tests that OpenCV provides. If you did not clone the `opencv_extra` repository and specify the path to `testdata` in the `cmake` invocation, then testing is not recommended.
### Testing under Linux
To run the basic tests under Linux, execute:
$ make test
This executes `ctest` to carry out the tests, as specified in CTest syntax within the OpenCV repository. The `ctest` harness takes many different parameters (too many to list here, see the manual page for CTest to see the full set), and if you wish to pass any of them, you can do so by specifying them in a `make` command-line parameter called `ARGS`:
$ make test ARGS="--verbose --parallel 3"
In this example, there are two (2) arguments passed to `ctest`: `--verbose` and `--parallel 3`. The first argument causes the output from `ctest` to be more detailed, and the second causes `ctest` to run as many as three (3) tests in parallel. As with choosing a thread count for building, base any choice for testing on the available number of processor cores, physical memory, etc. Some of the tests do attempt to allocate significant amounts of memory.
#### Known Issues with Tests
At present, not all of the tests in the OpenCV test suite pass. There are tests that fail whether or not CUDA is compiled, and there are tests that are only specific to CUDA that also do not currently pass.
__Note:__ There are no tests that pass without CUDA but fail only when CUDA is included.
As the full lists of failing tests vary based on platform, it is impractical to list them here.
Installing OpenCV {#tutorial_building_tegra_cuda_installing}
-----------------
Installing OpenCV is very straightforward. For the Linux-based platforms, the command is:
$ make install
Depending on the chosen installation location, you may need root privilege to install.
Building OpenCV 2.4.X {#tutorial_building_tegra_cuda_opencv_24X}
---------------------
If you wish to build your own version of the 2.4 version of OpenCV, there are only a few adjustments that must be made. At the time of this writing, the latest version on the 2.4 tree is 2.4.13. These instructions may work for later versions of 2.4, though they have not been tested for any earlier versions.
__Note:__ The 2.4.X OpenCV source does not have the extra modules and code for Tegra that was upstreamed into the 3.X versions of OpenCV. This part of the guide is only for cases where you want to build a vanilla version of OpenCV 2.4.
### Selecting the 2.4 Source
First you must select the correct source branch or tag. If you want a specific version such as 2.4.13, you want to make a local branch based on the tag, as was done with the 3.1.0 tag above:
# Within the opencv directory:
$ git checkout -b v2.4.13 2.4.13
# Within the opencv_extra directory:
$ git checkout -b v2.4.13 2.4.13
If you simply want the newest code from the 2.4 line of OpenCV, there is a `2.4` branch already in the repository. You can check that out instead of a specific tag:
$ git checkout 2.4
There is no need for the `git cherry-pick` commands used with 3.1.0 when building the 2.4.13 source.
### Configuring
Configuring is done with CMake as before. The primary difference is that OpenCV 2.4 only provides Python bindings for Python 2, and thus does not distinguish between Python 2 and Python 3 in the CMake parameters. There is only one parameter, `BUILD_opencv_python`. In addition, there is a build-related parameter that controls features in 2.4 that are not in 3.1.0. This parameter is `BUILD_opencv_nonfree`.
Configuration still takes place in a separate directory that must be a sibling to the `opencv` and `opencv_extra` directories.
#### Configuring Vibrante V4L
For DRIVE PX 2:
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_nonfree=OFF \
-DBUILD_opencv_python=ON \
-DENABLE_NEON=ON \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-8.0 \
-DCUDA_ARCH_BIN=6.2 \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=ON \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
#### Configuring Jetson L4T
For Jetson TK1:
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_nonfree=OFF \
-DBUILD_opencv_python=ON \
-DENABLE_NEON=ON \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-6.5 \
-DCUDA_ARCH_BIN=3.2 \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=ON \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
For Jetson TX1:
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_nonfree=OFF \
-DBUILD_opencv_python=ON \
-DENABLE_PRECOMPILED_HEADERS=OFF \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-8.0 \
-DCUDA_ARCH_BIN=5.3 \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=ON \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
#### Configuring Desktop Ubuntu Linux
For both 14.04 LTS and 16.04 LTS:
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DBUILD_PNG=OFF \
-DBUILD_TIFF=OFF \
-DBUILD_TBB=OFF \
-DBUILD_JPEG=OFF \
-DBUILD_JASPER=OFF \
-DBUILD_ZLIB=OFF \
-DBUILD_EXAMPLES=ON \
-DBUILD_JAVA=OFF \
-DBUILD_opencv_nonfree=OFF \
-DBUILD_opencv_python=ON \
-DWITH_OPENCL=OFF \
-DWITH_OPENMP=OFF \
-DWITH_FFMPEG=ON \
-DWITH_GSTREAMER=OFF \
-DWITH_GSTREAMER_0_10=OFF \
-DWITH_CUDA=ON \
-DWITH_GTK=ON \
-DWITH_VTK=OFF \
-DWITH_TBB=ON \
-DWITH_1394=OFF \
-DWITH_OPENEXR=OFF \
-DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-8.0 \
-DCUDA_ARCH_BIN='3.0 3.5 5.0 6.0 6.2' \
-DCUDA_ARCH_PTX="" \
-DINSTALL_C_EXAMPLES=ON \
-DINSTALL_TESTS=ON \
-DOPENCV_TEST_DATA_PATH=../opencv_extra/testdata \
../opencv
### Building, Testing and Installing
Once configured, the steps of building, testing, and installing are the same as above for the 3.1.0 source.
CMake Parameter Reference {#tutorial_building_tegra_cuda_parameter_reference}
-------------------------
The following is a table of all the parameters passed to CMake in the recommended invocations above. Some of these are parameters from CMake itself, while most are specific to OpenCV.
|Parameter|Our Default Value|What It Does|Notes|
|---------|-----------------|------------|-----|
|BUILD_EXAMPLES|ON|Governs whether the C/C++ examples are built| |
|BUILD_JASPER|OFF|Governs whether the Jasper library (`libjasper`) is built from source in the `3rdparty` directory| |
|BUILD_JPEG|OFF|As above, for `libjpeg`| |
|BUILD_PNG|OFF|As above, for `libpng`| |
|BUILD_TBB|OFF|As above, for `tbb`| |
|BUILD_TIFF|OFF|As above, for `libtiff`| |
|BUILD_ZLIB|OFF|As above, for `zlib`| |
|BUILD_JAVA|OFF|Controls the building of the Java bindings for OpenCV|Building the Java bindings requires OpenCV libraries be built for static linking only|
|BUILD_opencv_nonfree|OFF|Controls the building of non-free (non-open-source) elements|Used only for building 2.4.X|
|BUILD_opencv_python|ON|Controls the building of the Python 2 bindings in OpenCV 2.4.X|Used only for building 2.4.X|
|BUILD_opencv_python2|ON|Controls the building of the Python 2 bindings in OpenCV 3.1.0|Not used in 2.4.X|
|BUILD_opencv_python3|OFF|Controls the building of the Python 3 bindings in OpenCV 3.1.0|Not used in 2.4.X|
|CMAKE_BUILD_TYPE|Release|Selects the type of build (release vs. development)|Is generally either `Release` or `Debug`|
|CMAKE_INSTALL_PREFIX|/usr|Sets the root for installation of the libraries and header files| |
|CUDA_ARCH_BIN|varies|Sets the CUDA architecture(s) for which code is compiled|Usually only passed for platforms with known specific cards. OpenCV includes a small program that determines the architectures of the system's installed card if you do not pass this parameter. Here, for Ubuntu desktop, the value is a list to maximize card support.|
|CUDA_ARCH_PTX|""|Builds PTX intermediate code for the specified virtual PTX architectures| |
|CUDA_TOOLKIT_ROOT_DIR|/usr/local/cuda-8.0 (for Linux)|Specifies the location of the CUDA include files and libraries| |
|ENABLE_NEON|ON|Enables the use of NEON SIMD extensions for ARM chips|Only passed for builds on ARM platforms|
|ENABLE_PRECOMPILED_HEADERS|OFF|Enables/disables support for pre-compiled headers|Only specified on some of the ARM platforms|
|INSTALL_C_EXAMPLES|ON|Enables the installation of the C example files as part of `make install`| |
|INSTALL_TESTS|ON|Enables the installation of the tests as part of `make install`| |
|OPENCV_TEST_DATA_PATH|../opencv_extra/testdata|Path to the `testdata` directory in the `opencv_extra` repository| |
|WITH_1394|OFF|Specifies whether to include IEEE-1394 support| |
|WITH_CUDA|ON|Specifies whether to include CUDA support| |
|WITH_FFMPEG|ON|Specifies whether to include FFMPEG support| |
|WITH_GSTREAMER|OFF|Specifies whether to include GStreamer 1.0 support| |
|WITH_GSTREAMER_0_10|OFF|Specifies whether to include GStreamer 0.10 support| |
|WITH_GTK|ON|Specifies whether to include GTK 2.0 support|Only given on Linux platforms, not Microsoft Windows|
|WITH_OPENCL|OFF|Specifies whether to include OpenCL runtime support| |
|WITH_OPENEXR|OFF|Specifies whether to include ILM support via OpenEXR| |
|WITH_OPENMP|OFF|Specifies whether to include OpenMP runtime support| |
|WITH_TBB|ON|Specifies whether to include Intel TBB support| |
|WITH_VTK|OFF|Specifies whether to include VTK support| |
Copyright &copy; 2016, NVIDIA CORPORATION. All rights reserved.
doc/tutorials/introduction/clojure_dev_intro/clojure_dev_intro.markdown
+611
View File
@@ -0,0 +1,611 @@
Introduction to OpenCV Development with Clojure {#tutorial_clojure_dev_intro}
===============================================
@prev_tutorial{tutorial_java_eclipse}
@next_tutorial{tutorial_android_dev_intro}
| | |
| -: | :- |
| Original author | Mimmo Cosenza |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
@warning
This tutorial can contain obsolete information.
As of OpenCV 2.4.4, OpenCV supports desktop Java development using nearly the same interface as for
Android development.
[Clojure](http://clojure.org/) is a contemporary LISP dialect hosted by the Java Virtual Machine and
it offers a complete interoperability with the underlying JVM. This means that we should even be
able to use the Clojure REPL (Read Eval Print Loop) as and interactive programmable interface to the
underlying OpenCV engine.
What we'll do in this tutorial
------------------------------
This tutorial will help you in setting up a basic Clojure environment for interactively learning
OpenCV within the fully programmable CLojure REPL.
### Tutorial source code
You can find a runnable source code of the sample in the `samples/java/clojure/simple-sample` folder
of the OpenCV repository. After having installed OpenCV and Clojure as explained in the tutorial,
issue the following command to run the sample from the command line.
@code{.bash}
cd path/to/samples/java/clojure/simple-sample
lein run
@endcode
Preamble
--------
For detailed instruction on installing OpenCV with desktop Java support refer to the @ref tutorial_java_dev_intro "corresponding tutorial".
If you are in hurry, here is a minimum quick start guide to install OpenCV on Mac OS X:
@note
I'm assuming you already installed [xcode](https://developer.apple.com/xcode/),
[jdk](http://www.oracle.com/technetwork/java/javase/downloads/index.html) and
[Cmake](http://www.cmake.org/cmake/resources/software.html).
@code{.bash}
cd ~/
mkdir opt
git clone https://github.com/opencv/opencv.git
cd opencv
git checkout 2.4
mkdir build
cd build
cmake -DBUILD_SHARED_LIBS=OFF ..
...
...
make -j8
# optional
# make install
@endcode
Install Leiningen
-----------------
Once you installed OpenCV with desktop java support the only other requirement is to install
[Leiningeng](https://github.com/technomancy/leiningen) which allows you to manage the entire life
cycle of your CLJ projects.
The available [installation guide](https://github.com/technomancy/leiningen#installation) is very
easy to be followed:
-# [Download the script](https://raw.github.com/technomancy/leiningen/stable/bin/lein)
-# Place it on your $PATH (cf. \~/bin is a good choice if it is on your path.)
-# Set the script to be executable. (i.e. chmod 755 \~/bin/lein).
If you work on Windows, follow [this instruction](https://github.com/technomancy/leiningen#windows)
You now have both the OpenCV library and a fully installed basic Clojure environment. What is now
needed is to configure the Clojure environment to interact with the OpenCV library.
Install the localrepo Leiningen plugin
--------------------------------------
The set of commands (tasks in Leiningen parlance) natively supported by Leiningen can be very easily
extended by various plugins. One of them is the
[lein-localrepo](https://github.com/kumarshantanu/lein-localrepo) plugin which allows to install any
jar lib as an artifact in the local maven repository of your machine (typically in the
\~/.m2/repository directory of your username).
We're going to use this lein plugin to add to the local maven repository the opencv components
needed by Java and Clojure to use the opencv lib.
Generally speaking, if you want to use a plugin on project base only, it can be added directly to a
CLJ project created by lein.
Instead, when you want a plugin to be available to any CLJ project in your username space, you can
add it to the profiles.clj in the \~/.lein/ directory.
The lein-localrepo plugin will be useful to me in other CLJ projects where I need to call native
libs wrapped by a Java interface. So I decide to make it available to any CLJ project:
@code{.bash}
mkdir ~/.lein
@endcode
Create a file named profiles.clj in the \~/.lein directory and copy into it the following content:
@code{.clojure}
{:user {:plugins [[lein-localrepo "0.5.2"]]}}
@endcode
Here we're saying that the version release "0.5.2" of the lein-localrepo plugin will be available to
the :user profile for any CLJ project created by lein.
You do not need to do anything else to install the plugin because it will be automatically
downloaded from a remote repository the very first time you issue any lein task.
Install the java specific libs as local repository
--------------------------------------------------
If you followed the standard documentation for installing OpenCV on your computer, you should find
the following two libs under the directory where you built OpenCV:
- the build/bin/opencv-247.jar java lib
- the build/lib/libopencv_java247.dylib native lib (or .so in you built OpenCV a GNU/Linux OS)
They are the only opencv libs needed by the JVM to interact with OpenCV.
### Take apart the needed opencv libs
Create a new directory to store in the above two libs. Start by copying into it the opencv-247.jar
lib.
@code{.bash}
cd ~/opt
mkdir clj-opencv
cd clj-opencv
cp ~/opt/opencv/build/bin/opencv-247.jar .
@endcode
First lib done.
Now, to be able to add the libopencv_java247.dylib shared native lib to the local maven repository,
we first need to package it as a jar file.
The native lib has to be copied into a directories layout which mimics the names of your operating
system and architecture. I'm using a Mac OS X with a X86 64 bit architecture. So my layout will be
the following:
@code{.bash}
mkdir -p native/macosx/x86_64
@endcode
Copy into the x86_64 directory the libopencv_java247.dylib lib.
@code{.bash}
cp ~/opt/opencv/build/lib/libopencv_java247.dylib native/macosx/x86_64/
@endcode
If you're running OpenCV from a different OS/Architecture pair, here is a summary of the mapping you
can choose from.
@code{.bash}
OS
Mac OS X -> macosx
Windows -> windows
Linux -> linux
SunOS -> solaris
Architectures
amd64 -> x86_64
x86_64 -> x86_64
x86 -> x86
i386 -> x86
arm -> arm
sparc -> sparc
@endcode
### Package the native lib as a jar
Next you need to package the native lib in a jar file by using the jar command to create a new jar
file from a directory.
@code{.bash}
jar -cMf opencv-native-247.jar native
@endcode
Note that ehe M option instructs the jar command to not create a MANIFEST file for the artifact.
Your directories layout should look like the following:
@code{.bash}
tree
.
|__ native
| |__ macosx
| |__ x86_64
| |__ libopencv_java247.dylib
|
|__ opencv-247.jar
|__ opencv-native-247.jar
3 directories, 3 files
@endcode
### Locally install the jars
We are now ready to add the two jars as artifacts to the local maven repository with the help of the
lein-localrepo plugin.
@code{.bash}
lein localrepo install opencv-247.jar opencv/opencv 2.4.7
@endcode
Here the localrepo install task creates the 2.4.7. release of the opencv/opencv maven artifact from
the opencv-247.jar lib and then installs it into the local maven repository. The opencv/opencv
artifact will then be available to any maven compliant project (Leiningen is internally based on
maven).
Do the same thing with the native lib previously wrapped in a new jar file.
@code{.bash}
lein localrepo install opencv-native-247.jar opencv/opencv-native 2.4.7
@endcode
Note that the groupId, opencv, of the two artifacts is the same. We are now ready to create a new
CLJ project to start interacting with OpenCV.
### Create a project
Create a new CLJ project by using the lein new task from the terminal.
@code{.bash}
# cd in the directory where you work with your development projects (e.g. ~/devel)
lein new simple-sample
Generating a project called simple-sample based on the 'default' template.
To see other templates (app, lein plugin, etc), try `lein help new`.
@endcode
The above task creates the following simple-sample directories layout:
@code{.bash}
tree simple-sample/
simple-sample/
|__ LICENSE
|__ README.md
|__ doc
| |__ intro.md
|
|__ project.clj
|__ resources
|__ src
| |__ simple_sample
| |__ core.clj
|__ test
|__ simple_sample
|__ core_test.clj
6 directories, 6 files
@endcode
We need to add the two opencv artifacts as dependencies of the newly created project. Open the
project.clj and modify its dependencies section as follows:
@code{.bash}
(defproject simple-sample "0.1.0-SNAPSHOT"
description "FIXME: write description"
url "http://example.com/FIXME"
license {:name "Eclipse Public License"
url "http://www.eclipse.org/legal/epl-v10.html"}
dependencies [[org.clojure/clojure "1.5.1"]
[opencv/opencv "2.4.7"] ; added line
[opencv/opencv-native "2.4.7"]]) ;added line
@endcode
Note that The Clojure Programming Language is a jar artifact too. This is why Clojure is called an
hosted language.
To verify that everything went right issue the lein deps task. The very first time you run a lein
task it will take sometime to download all the required dependencies before executing the task
itself.
@code{.bash}
cd simple-sample
lein deps
...
@endcode
The deps task reads and merges from the project.clj and the \~/.lein/profiles.clj files all the
dependencies of the simple-sample project and verifies if they have already been cached in the local
maven repository. If the task returns without messages about not being able to retrieve the two new
artifacts your installation is correct, otherwise go back and double check that you did everything
right.
### REPLing with OpenCV
Now cd in the simple-sample directory and issue the following lein task:
@code{.bash}
cd simple-sample
lein repl
...
...
nREPL server started on port 50907 on host 127.0.0.1
REPL-y 0.3.0
Clojure 1.5.1
Docs: (doc function-name-here)
(find-doc "part-of-name-here")
Source: (source function-name-here)
Javadoc: (javadoc java-object-or-class-here)
Exit: Control+D or (exit) or (quit)
Results: Stored in vars *1, *2, *3, an exception in *e
user=>
@endcode
You can immediately interact with the REPL by issuing any CLJ expression to be evaluated.
@code{.clojure}
user=> (+ 41 1)
42
user=> (println "Hello, OpenCV!")
Hello, OpenCV!
nil
user=> (defn foo [] (str "bar"))
#'user/foo
user=> (foo)
"bar"
@endcode
When ran from the home directory of a lein based project, even if the lein repl task automatically
loads all the project dependencies, you still need to load the opencv native library to be able to
interact with the OpenCV.
@code{.clojure}
user=> (clojure.lang.RT/loadLibrary org.opencv.core.Core/NATIVE_LIBRARY_NAME)
nil
@endcode
Then you can start interacting with OpenCV by just referencing the fully qualified names of its
classes.
@note
[Here](https://docs.opencv.org/4.x/javadoc/index.html) you can find the full OpenCV Java API.
@code{.clojure}
user=> (org.opencv.core.Point. 0 0)
#<Point {0.0, 0.0}>
@endcode
Here we created a two dimensions opencv Point instance. Even if all the java packages included
within the java interface to OpenCV are immediately available from the CLJ REPL, it's very annoying
to prefix the Point. instance constructors with the fully qualified package name.
Fortunately CLJ offer a very easy way to overcome this annoyance by directly importing the Point
class.
@code{.clojure}
user=> (import 'org.opencv.core.Point)
org.opencv.core.Point
user=> (def p1 (Point. 0 0))
#'user/p1
user=> p1
#<Point {0.0, 0.0}>
user=> (def p2 (Point. 100 100))
#'user/p2
@endcode
We can even inspect the class of an instance and verify if the value of a symbol is an instance of a
Point java class.
@code{.clojure}
user=> (class p1)
org.opencv.core.Point
user=> (instance? org.opencv.core.Point p1)
true
@endcode
If we now want to use the opencv Rect class to create a rectangle, we again have to fully qualify
its constructor even if it leaves in the same org.opencv.core package of the Point class.
@code{.clojure}
user=> (org.opencv.core.Rect. p1 p2)
#<Rect {0, 0, 100x100}>
@endcode
Again, the CLJ importing facilities is very handy and let you to map more symbols in one shot.
@code{.clojure}
user=> (import '[org.opencv.core Point Rect Size])
org.opencv.core.Size
user=> (def r1 (Rect. p1 p2))
#'user/r1
user=> r1
#<Rect {0, 0, 100x100}>
user=> (class r1)
org.opencv.core.Rect
user=> (instance? org.opencv.core.Rect r1)
true
user=> (Size. 100 100)
#<Size 100x100>
user=> (def sq-100 (Size. 100 100))
#'user/sq-100
user=> (class sq-100)
org.opencv.core.Size
user=> (instance? org.opencv.core.Size sq-100)
true
@endcode
Obviously you can call methods on instances as well.
@code{.clojure}
user=> (.area r1)
10000.0
user=> (.area sq-100)
10000.0
@endcode
Or modify the value of a member field.
@code{.clojure}
user=> (set! (.x p1) 10)
10
user=> p1
#<Point {10.0, 0.0}>
user=> (set! (.width sq-100) 10)
10
user=> (set! (.height sq-100) 10)
10
user=> (.area sq-100)
100.0
@endcode
If you find yourself not remembering a OpenCV class behavior, the REPL gives you the opportunity to
easily search the corresponding javadoc documentation:
@code{.clojure}
user=> (javadoc Rect)
"http://www.google.com/search?btnI=I%27m%20Feeling%20Lucky&q=allinurl:org/opencv/core/Rect.html"
@endcode
### Mimic the OpenCV Java Tutorial Sample in the REPL
Let's now try to port to Clojure the @ref tutorial_java_dev_intro "OpenCV Java tutorial sample".
Instead of writing it in a source file we're going to evaluate it at the REPL.
Following is the original Java source code of the cited sample.
@code{.java}
import org.opencv.core.Mat;
import org.opencv.core.CvType;
import org.opencv.core.Scalar;
class SimpleSample {
static{ System.loadLibrary("opencv_java244"); }
public static void main(String[] args) {
Mat m = new Mat(5, 10, CvType.CV_8UC1, new Scalar(0));
System.out.println("OpenCV Mat: " + m);
Mat mr1 = m.row(1);
mr1.setTo(new Scalar(1));
Mat mc5 = m.col(5);
mc5.setTo(new Scalar(5));
System.out.println("OpenCV Mat data:\n" + m.dump());
}
}
@endcode
### Add injections to the project
Before start coding, we'd like to eliminate the boring need of interactively loading the native
opencv lib any time we start a new REPL to interact with it.
First, stop the REPL by evaluating the (exit) expression at the REPL prompt.
@code{.clojure}
user=> (exit)
Bye for now!
@endcode
Then open your project.clj file and edit it as follows:
@code{.clojure}
(defproject simple-sample "0.1.0-SNAPSHOT"
...
injections [(clojure.lang.RT/loadLibrary org.opencv.core.Core/NATIVE_LIBRARY_NAME)])
@endcode
Here we're saying to load the opencv native lib anytime we run the REPL in such a way that we have
not anymore to remember to manually do it.
Rerun the lein repl task
@code{.bash}
lein repl
nREPL server started on port 51645 on host 127.0.0.1
REPL-y 0.3.0
Clojure 1.5.1
Docs: (doc function-name-here)
(find-doc "part-of-name-here")
Source: (source function-name-here)
Javadoc: (javadoc java-object-or-class-here)
Exit: Control+D or (exit) or (quit)
Results: Stored in vars *1, *2, *3, an exception in *e
user=>
@endcode
Import the interested OpenCV java interfaces.
@code{.clojure}
user=> (import '[org.opencv.core Mat CvType Scalar])
org.opencv.core.Scalar
@endcode
We're going to mimic almost verbatim the original OpenCV java tutorial to:
- create a 5x10 matrix with all its elements initialized to 0
- change the value of every element of the second row to 1
- change the value of every element of the 6th column to 5
- print the content of the obtained matrix
@code{.clojure}
user=> (def m (Mat. 5 10 CvType/CV_8UC1 (Scalar. 0 0)))
#'user/m
user=> (def mr1 (.row m 1))
#'user/mr1
user=> (.setTo mr1 (Scalar. 1 0))
#<Mat Mat [ 1*10*CV_8UC1, isCont=true, isSubmat=true, nativeObj=0x7fc9dac49880, dataAddr=0x7fc9d9c98d5a ]>
user=> (def mc5 (.col m 5))
#'user/mc5
user=> (.setTo mc5 (Scalar. 5 0))
#<Mat Mat [ 5*1*CV_8UC1, isCont=false, isSubmat=true, nativeObj=0x7fc9d9c995a0, dataAddr=0x7fc9d9c98d55 ]>
user=> (println (.dump m))
[0, 0, 0, 0, 0, 5, 0, 0, 0, 0;
1, 1, 1, 1, 1, 5, 1, 1, 1, 1;
0, 0, 0, 0, 0, 5, 0, 0, 0, 0;
0, 0, 0, 0, 0, 5, 0, 0, 0, 0;
0, 0, 0, 0, 0, 5, 0, 0, 0, 0]
nil
@endcode
If you are accustomed to a functional language all those abused and mutating nouns are going to
irritate your preference for verbs. Even if the CLJ interop syntax is very handy and complete, there
is still an impedance mismatch between any OOP language and any FP language (bein Scala a mixed
paradigms programming language).
To exit the REPL type (exit), ctr-D or (quit) at the REPL prompt.
@code{.clojure}
user=> (exit)
Bye for now!
@endcode
### Interactively load and blur an image
In the next sample you will learn how to interactively load and blur and image from the REPL by
using the following OpenCV methods:
- the imread static method from the Highgui class to read an image from a file
- the imwrite static method from the Highgui class to write an image to a file
- the GaussianBlur static method from the Imgproc class to apply to blur the original image
We're also going to use the Mat class which is returned from the imread method and accepted as the
main argument to both the GaussianBlur and the imwrite methods.
### Add an image to the project
First we want to add an image file to a newly create directory for storing static resources of the
project.
![](images/lena.png)
@code{.bash}
mkdir -p resources/images
cp ~/opt/opencv/doc/tutorials/introduction/desktop_java/images/lena.png resource/images/
@endcode
### Read the image
Now launch the REPL as usual and start by importing all the OpenCV classes we're going to use:
@code{.clojure}
lein repl
nREPL server started on port 50624 on host 127.0.0.1
REPL-y 0.3.0
Clojure 1.5.1
Docs: (doc function-name-here)
(find-doc "part-of-name-here")
Source: (source function-name-here)
Javadoc: (javadoc java-object-or-class-here)
Exit: Control+D or (exit) or (quit)
Results: Stored in vars *1, *2, *3, an exception in *e
user=> (import '[org.opencv.core Mat Size CvType]
'[org.opencv.imgcodecs Imgcodecs]
'[org.opencv.imgproc Imgproc])
org.opencv.imgproc.Imgproc
@endcode
Now read the image from the resources/images/lena.png file.
@code{.clojure}
user=> (def lena (Highgui/imread "resources/images/lena.png"))
#'user/lena
user=> lena
#<Mat Mat [ 512*512*CV_8UC3, isCont=true, isSubmat=false, nativeObj=0x7f9ab3054c40, dataAddr=0x19fea9010 ]>
@endcode
As you see, by simply evaluating the lena symbol we know that lena.png is a 512x512 matrix of
CV_8UC3 elements type. Let's create a new Mat instance of the same dimensions and elements type.
@code{.clojure}
user=> (def blurred (Mat. 512 512 CvType/CV_8UC3))
#'user/blurred
user=>
@endcode
Now apply a GaussianBlur filter using lena as the source matrix and blurred as the destination
matrix.
@code{.clojure}
user=> (Imgproc/GaussianBlur lena blurred (Size. 5 5) 3 3)
nil
@endcode
As a last step just save the blurred matrix in a new image file.
@code{.clojure}
user=> (Highgui/imwrite "resources/images/blurred.png" blurred)
true
user=> (exit)
Bye for now!
@endcode
Following is the new blurred image of Lena.
![](images/blurred.png)
Next Steps
----------
This tutorial only introduces the very basic environment set up to be able to interact with OpenCV
in a CLJ REPL.
I recommend any Clojure newbie to read the [Clojure Java Interop
chapter](http://clojure.org/java_interop) to get all you need to know to interoperate with any plain
java lib that has not been wrapped in Clojure to make it usable in a more idiomatic and functional
way within Clojure.
The OpenCV Java API does not wrap the highgui module functionalities depending on Qt (e.g.
namedWindow and imshow. If you want to create windows and show images into them while interacting
with OpenCV from the REPL, at the moment you're left at your own. You could use Java Swing to fill
the gap.
### License
Copyright © 2013 Giacomo (Mimmo) Cosenza aka Magomimmo
Distributed under the BSD 3-clause License.
doc/tutorials/introduction/clojure_dev_intro/images/blurred.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 351 KiB

doc/tutorials/introduction/config_reference/config_reference.markdown
+667
View File
@@ -0,0 +1,667 @@
OpenCV configuration options reference {#tutorial_config_reference}
======================================
@prev_tutorial{tutorial_general_install}
@next_tutorial{tutorial_env_reference}
@tableofcontents
# Introduction {#tutorial_config_reference_intro}
@note
We assume you have read @ref tutorial_general_install tutorial or have experience with CMake.
Configuration options can be set in several different ways:
* Command line: `cmake -Doption=value ...`
* Initial cache files: `cmake -C my_options.txt ...`
* Interactive via GUI
In this reference we will use regular command line.
Most of the options can be found in the root cmake script of OpenCV: `opencv/CMakeLists.txt`. Some options can be defined in specific modules.
It is possible to use CMake tool to print all available options:
```.sh
# initial configuration
cmake ../opencv
# print all options
cmake -L
# print all options with help message
cmake -LH
# print all options including advanced
cmake -LA
```
Most popular and useful are options starting with `WITH_`, `ENABLE_`, `BUILD_`, `OPENCV_`.
Default values vary depending on platform and other options values.
# General options {#tutorial_config_reference_general}
## Build with extra modules {#tutorial_config_reference_general_contrib}
`OPENCV_EXTRA_MODULES_PATH` option contains a semicolon-separated list of directories containing extra modules which will be added to the build. Module directory must have compatible layout and CMakeLists.txt, brief description can be found in the [Coding Style Guide](https://github.com/opencv/opencv/wiki/Coding_Style_Guide).
Examples:
```.sh
# build with all modules in opencv_contrib
cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv
# build with one of opencv_contrib modules
cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules/bgsegm ../opencv
# build with two custom modules (semicolon must be escaped in bash)
cmake -DOPENCV_EXTRA_MODULES_PATH=../my_mod1\;../my_mod2 ../opencv
```
@note
Only 0- and 1-level deep module locations are supported, following command will raise an error:
```.sh
cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib ../opencv
```
## Build with C++ Standard setting {#tutorial_config_reference_general_cxx_standard}
`CMAKE_CXX_STANDARD` option can be used to set C++ standard settings for OpenCV building.
```.sh
cmake -DCMAKE_CXX_STANDARD=17 ../opencv
cmake --build .
```
- C++11 is default/required/recommended for OpenCV 4.x. C++17 is default/required/recomended for OpenCV 5.x.
- If your compiler does not support required C++ Standard features, OpenCV configuration should be fail.
- If you set older C++ Standard than required, OpenCV configuration should be fail.
For workaround, `OPENCV_SKIP_CMAKE_CXX_STANDARD` option can be used to skip `CMAKE_CXX_STANDARD` version check.
- If you set newer C++ Standard than recomended, numerous warnings may appear or OpenCV build may fail.
## Debug build {#tutorial_config_reference_general_debug}
`CMAKE_BUILD_TYPE` option can be used to enable debug build; resulting binaries will contain debug symbols and most of compiler optimizations will be turned off. To enable debug symbols in Release build turn the `BUILD_WITH_DEBUG_INFO` option on.
On some platforms (e.g. Linux) build type must be set at configuration stage:
```.sh
cmake -DCMAKE_BUILD_TYPE=Debug ../opencv
cmake --build .
```
On other platforms different types of build can be produced in the same build directory (e.g. Visual Studio, XCode):
```.sh
cmake <options> ../opencv
cmake --build . --config Debug
```
If you use GNU libstdc++ (default for GCC) you can turn on the `ENABLE_GNU_STL_DEBUG` option, then C++ library will be used in Debug mode, e.g. indexes will be bound-checked during vector element access.
Many kinds of optimizations can be disabled with `CV_DISABLE_OPTIMIZATION` option:
* Some third-party libraries (e.g. IPP, Lapack, Eigen)
* Explicit vectorized implementation (universal intrinsics, raw intrinsics, etc.)
* Dispatched optimizations
* Explicit loop unrolling
@see https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html
@see https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_macros.html
@see https://github.com/opencv/opencv/wiki/CPU-optimizations-build-options
## Static build {#tutorial_config_reference_general_static}
`BUILD_SHARED_LIBS` option control whether to produce dynamic (.dll, .so, .dylib) or static (.a, .lib) libraries. Default value depends on target platform, in most cases it is `ON`.
Example:
```.sh
cmake -DBUILD_SHARED_LIBS=OFF ../opencv
```
@see https://en.wikipedia.org/wiki/Static_library
`ENABLE_PIC` sets the [CMAKE_POSITION_INDEPENDENT_CODE](https://cmake.org/cmake/help/latest/variable/CMAKE_POSITION_INDEPENDENT_CODE.html) option. It enables or disable generation of "position-independent code". This option must be enabled when building dynamic libraries or static libraries intended to be linked into dynamic libraries. Default value is `ON`.
@see https://en.wikipedia.org/wiki/Position-independent_code
## Generate pkg-config info
`OPENCV_GENERATE_PKGCONFIG` option enables `.pc` file generation along with standard CMake package. This file can be useful for projects which do not use CMake for build.
Example:
```.sh
cmake -DOPENCV_GENERATE_PKGCONFIG=ON ../opencv
```
@note
Due to complexity of configuration process resulting `.pc` file can contain incomplete list of third-party dependencies and may not work in some configurations, especially for static builds. This feature is not officially supported since 4.x version and is disabled by default.
## Build tests, samples and applications {#tutorial_config_reference_general_tests}
There are two kinds of tests: accuracy (`opencv_test_*`) and performance (`opencv_perf_*`). Tests and applications are enabled by default. Examples are not being built by default and should be enabled explicitly.
Corresponding _cmake_ options:
```.sh
cmake \
-DBUILD_TESTS=ON \
-DBUILD_PERF_TESTS=ON \
-DBUILD_EXAMPLES=ON \
-DBUILD_opencv_apps=ON \
../opencv
```
## Build limited set of modules {#tutorial_config_reference_general_modules}
Each module is a subdirectory of the `modules` directory. It is possible to disable one module:
```.sh
cmake -DBUILD_opencv_calib3d=OFF ../opencv
```
The opposite option is to build only specified modules and all modules they depend on:
```.sh
cmake -DBUILD_LIST=calib3d,videoio,ts ../opencv
```
In this example we requested 3 modules and configuration script has determined all dependencies automatically:
```
-- OpenCV modules:
-- To be built: calib3d core features2d flann highgui imgcodecs imgproc ts videoio
```
## Downloaded dependencies {#tutorial_config_reference_general_download}
Configuration script can try to download additional libraries and files from the internet, if it fails to do it corresponding features will be turned off. In some cases configuration error can occur. By default all files are first downloaded to the `<source>/.cache` directory and then unpacked or copied to the build directory. It is possible to change download cache location by setting environment variable or configuration option:
```.sh
export OPENCV_DOWNLOAD_PATH=/tmp/opencv-cache
cmake ../opencv
# or
cmake -DOPENCV_DOWNLOAD_PATH=/tmp/opencv-cache ../opencv
```
In case of access via proxy, corresponding environment variables should be set before running cmake:
```.sh
export http_proxy=<proxy-host>:<port>
export https_proxy=<proxy-host>:<port>
```
Full log of download process can be found in build directory - `CMakeDownloadLog.txt`. In addition, for each failed download a command will be added to helper scripts in the build directory, e.g. `download_with_wget.sh`. Users can run these scripts as is or modify according to their needs.
## CPU optimization level {#tutorial_config_reference_general_cpu}
On x86_64 machines the library will be compiled for SSE3 instruction set level by default. This level can be changed by configuration option:
```.sh
cmake -DCPU_BASELINE=AVX2 ../opencv
```
@note
Other platforms have their own instruction set levels: `VFPV3` and `NEON` on ARM, `VSX` on PowerPC.
Some functions support dispatch mechanism allowing to compile them for several instruction sets and to choose one during runtime. List of enabled instruction sets can be changed during configuration:
```.sh
cmake -DCPU_DISPATCH=AVX,AVX2 ../opencv
```
To disable dispatch mechanism this option should be set to an empty value:
```.sh
cmake -DCPU_DISPATCH= ../opencv
```
It is possible to disable optimized parts of code for troubleshooting and debugging:
```.sh
# disable universal intrinsics
cmake -DCV_ENABLE_INTRINSICS=OFF ../opencv
# disable all possible built-in optimizations
cmake -DCV_DISABLE_OPTIMIZATION=ON ../opencv
```
@note
More details on CPU optimization options can be found in wiki: https://github.com/opencv/opencv/wiki/CPU-optimizations-build-options
## Profiling, coverage, sanitize, hardening, size optimization {#profiling_coverage_sanitize_hardening_size_optimization}
Following options can be used to produce special builds with instrumentation or improved security. All options are disabled by default.
| Option | Compiler | Description |
| -------| -------- | ----------- |
| `ENABLE_PROFILING` | GCC or Clang | Enable profiling compiler and linker options. |
| `ENABLE_COVERAGE` | GCC or Clang | Enable code coverage support. |
| `OPENCV_ENABLE_MEMORY_SANITIZER` | N/A | Enable several quirks in code to assist memory sanitizer. |
| `ENABLE_BUILD_HARDENING` | GCC, Clang, MSVC | Enable compiler options which reduce possibility of code exploitation. |
| `ENABLE_LTO` | GCC, Clang, MSVC | Enable Link Time Optimization (LTO). |
| `ENABLE_THIN_LTO` | Clang | Enable thin LTO which incorporates intermediate bitcode to binaries allowing consumers optimize their applications later. |
| `OPENCV_ALGO_HINT_DEFAULT` | Any | Set default OpenCV implementation hint value: `ALGO_HINT_ACCURATE` or `ALGO_HINT_APPROX`. Dangerous! The option changes behaviour globally and may affect accuracy of many algorithms. |
@see [GCC instrumentation](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)
@see [Build hardening](https://en.wikipedia.org/wiki/Hardening_(computing))
@see [Interprocedural optimization](https://en.wikipedia.org/wiki/Interprocedural_optimization)
@see [Link time optimization](https://gcc.gnu.org/wiki/LinkTimeOptimization)
@see [ThinLTO](https://clang.llvm.org/docs/ThinLTO.html)
## Enable IPP optimization
Following options can be used to enables IPP optimizations for each functions but increases the size of the opencv library. All options are disabled by default.
| Option | Functions | + roughly size |
| -------| --------- | -------------- |
| `OPENCV_IPP_GAUSSIAN_BLUR` | GaussianBlur() | +8Mb |
| `OPENCV_IPP_MEAN` | mean() / meanStdDev() | +0.2Mb |
| `OPENCV_IPP_MINMAX` | minMaxLoc() / minMaxIdx() | +0.2Mb |
| `OPENCV_IPP_SUM` | sum() | +0.1Mb |
# Functional features and dependencies {#tutorial_config_reference_func}
There are many optional dependencies and features that can be turned on or off. _cmake_ has special option allowing to print all available configuration parameters:
```.sh
cmake -LH ../opencv
```
## Options naming conventions
There are three kinds of options used to control dependencies of the library, they have different prefixes:
- Options starting with `WITH_` enable or disable a dependency
- Options starting with `BUILD_` enable or disable building and using 3rdparty library bundled with OpenCV
- Options starting with `HAVE_` indicate that dependency have been enabled, can be used to manually enable a dependency if automatic detection can not be used.
When `WITH_` option is enabled:
- If `BUILD_` option is enabled, 3rdparty library will be built and enabled => `HAVE_` set to `ON`
- If `BUILD_` option is disabled, 3rdparty library will be detected and enabled if found => `HAVE_` set to `ON` if dependency is found
## Heterogeneous computation {#tutorial_config_reference_func_hetero}
### CUDA support
`WITH_CUDA` (default: _OFF_)
Many algorithms have been implemented using CUDA acceleration, these functions are located in separate modules. CUDA toolkit must be installed from the official NVIDIA site as a prerequisite. For cmake versions older than 3.9 OpenCV uses own `cmake/FindCUDA.cmake` script, for newer versions - the one packaged with CMake. Additional options can be used to control build process, e.g. `CUDA_GENERATION` or `CUDA_ARCH_BIN`. These parameters are not documented yet, please consult with the `cmake/OpenCVDetectCUDA.cmake` script for details.
@note Since OpenCV version 4.0 all CUDA-accelerated algorithm implementations have been moved to the _opencv_contrib_ repository. To build _opencv_ and _opencv_contrib_ together check @ref tutorial_config_reference_general_contrib.
@cond CUDA_MODULES
@note Some tutorials can be found in the corresponding section: @ref tutorial_table_of_content_gpu
@see @ref cuda
@endcond
@see https://en.wikipedia.org/wiki/CUDA
TODO: other options: `WITH_CUFFT`, `WITH_CUBLAS`, `WITH_NVCUVID`?
### OpenCL support
`WITH_OPENCL` (default: _ON_)
Multiple OpenCL-accelerated algorithms are available via so-called "Transparent API (T-API)". This integration uses same functions at the user level as regular CPU implementations. Switch to the OpenCL execution branch happens if input and output image arguments are passed as opaque cv::UMat objects. More information can be found in [the brief introduction](https://opencv.org/opencl/) and @ref core_opencl
At the build time this feature does not have any prerequisites. During runtime a working OpenCL runtime is required, to check it run `clinfo` and/or `opencv_version --opencl` command. Some parameters of OpenCL integration can be modified using environment variables, e.g. `OPENCV_OPENCL_DEVICE`. However there is no thorough documentation for this feature yet, so please check the source code in `modules/core/src/ocl.cpp` file for details.
@see https://en.wikipedia.org/wiki/OpenCL
TODO: other options: `WITH_OPENCL_SVM`, `WITH_OPENCLAMDFFT`, `WITH_OPENCLAMDBLAS`, `WITH_OPENCL_D3D11_NV`, `WITH_VA_INTEL`
## Image reading and writing (imgcodecs module) {#tutorial_config_reference_func_imgcodecs}
### Built-in formats
Following formats can be read by OpenCV without help of any third-party library:
| Formats | Option | Default |
| --------| ------ | ------- |
| [BMP](https://en.wikipedia.org/wiki/BMP_file_format) | (Always) | _ON_ |
| [HDR](https://en.wikipedia.org/wiki/RGBE_image_format) | `WITH_IMGCODEC_HDR` | _ON_ |
| [Sun Raster](https://en.wikipedia.org/wiki/Sun_Raster) | `WITH_IMGCODEC_SUNRASTER` | _ON_ |
| [PPM, PGM, PBM, PAM](https://en.wikipedia.org/wiki/Netpbm#File_formats) | `WITH_IMGCODEC_PXM` | _ON_ |
| [PFM](https://en.wikipedia.org/wiki/Netpbm#File_formats) | `WITH_IMGCODEC_PFM` | _ON_ |
| [GIF](https://en.wikipedia.org/wiki/GIF) | `WITH_IMGCODEC_GIF` | _ON_ |
### PNG, JPEG, TIFF, WEBP, JPEG 2000, EXR, JPEG XL, AVIF support
| Formats | Library | Option | Default | Force build own |
| --------| ------- | ------ | ------- | --------------- |
| [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics) | [libpng](https://en.wikipedia.org/wiki/Libpng)| `WITH_PNG` | _ON_ | `BUILD_PNG` |
|^| [libspng(simple png)](https://libspng.org/) | `WITH_SPNG` | _OFF_ | `BUILD_SPNG` |
| [JPEG](https://en.wikipedia.org/wiki/JPEG) | [libjpeg-turbo](https://en.wikipedia.org/wiki/Libjpeg) | `WITH_JPEG` | _ON_ | `BUILD_JPEG` |
|^| [libjpeg](https://en.wikipedia.org/wiki/Libjpeg) | `WITH_JPEG` | _OFF_ | `BUILD_JPEG` with `BUILD_JPEG_TURBO_DISABLE` |
| [TIFF](https://en.wikipedia.org/wiki/TIFF) | [LibTIFF](https://en.wikipedia.org/wiki/LibTIFF) | `WITH_TIFF` | _ON_ | `BUILD_TIFF` |
| [WebP](https://en.wikipedia.org/wiki/WebP) || `WITH_WEBP` | _ON_ | `BUILD_WEBP` |
| [JPEG 2000](https://en.wikipedia.org/wiki/JPEG_2000) | [OpenJPEG](https://en.wikipedia.org/wiki/OpenJPEG) | `WITH_OPENJPEG` | _ON_ | `BUILD_OPENJPEG` |
|^| [JasPer](https://en.wikipedia.org/wiki/JasPer) | `WITH_JASPER` | _ON_ (see note) | `BUILD_JASPER` |
| [OpenEXR](https://en.wikipedia.org/wiki/OpenEXR) || `WITH_OPENEXR` | _ON_ | `BUILD_OPENEXR` |
| [JPEG XL](https://en.wikipedia.org/wiki/JPEG_XL) || `WITH_JPEGXL` | _ON_ | Not supported. (see note) |
| [AVIF](https://en.wikipedia.org/wiki/AVIF) || `WITH_AVIF` | _ON_ | Not supported. (see note) |
Most library source codes required to read/write images in these formats are bundled into OpenCV and will be built automatically if not found at the configuration stage
(except for some codecs that require external libraries, e.g. JPEG XL and AVIF).
Corresponding BUILD_* options will force building and using the bundled libraries; they are enabled by default on some platforms, e.g. Windows.
@note (All) Only one library for each image format can be enabled(e.g. In order to use JasPer for JPEG 2000 format, OpenJPEG must be disabled).
@note (JPEG 2000) OpenJPEG have higher priority than JasPer which is deprecated.
@note (JPEG XL) OpenCV doesn't contain libjxl source code, so `BUILD_JPEGXL` is not supported. Users must provide a system-wide installation of libjxl.
@note (AVIF) OpenCV doesn't contain libavif source code, so `BUILD_AVIF` is not supported. Users must provide a system-wide installation of libavif.
@warning OpenEXR ver 2.2 or earlier cannot be used in combination with C++17 or later. In this case, updating OpenEXR ver 2.3.0 or later is required.
### GDAL integration
`WITH_GDAL` (default: _OFF_)
[GDAL](https://en.wikipedia.org/wiki/GDAL) is a higher level library which supports reading multiple file formats including PNG, JPEG and TIFF. It will have higher priority when opening files and can override other backends. This library will be searched using cmake package mechanism, make sure it is installed correctly or manually set `GDAL_DIR` environment or cmake variable.
### GDCM integration
`WITH_GDCM` (default: _OFF_)
Enables [DICOM](https://en.wikipedia.org/wiki/DICOM) medical image format support through [GDCM library](https://en.wikipedia.org/wiki/GDCM). This library will be searched using cmake package mechanism, make sure it is installed correctly or manually set `GDCM_DIR` environment or cmake variable.
## Video reading and writing (videoio module) {#tutorial_config_reference_func_videoio}
TODO: how videoio works, registry, priorities
### Video4Linux
`WITH_V4L` (Linux; default: _ON_ )
Capture images from camera using [Video4Linux](https://en.wikipedia.org/wiki/Video4Linux) API. Linux kernel headers must be installed.
### FFmpeg
`WITH_FFMPEG` (default: _ON_)
Integration with [FFmpeg](https://en.wikipedia.org/wiki/FFmpeg) library for decoding and encoding video files and network streams. This library can read and write many popular video formats. It consists of several components which must be installed as prerequisites for the build:
- _avcodec_
- _avformat_
- _avutil_
- _swscale_
- _avresample_ (optional)
Exception is Windows platform where a prebuilt [plugin library containing FFmpeg](https://github.com/opencv/opencv_3rdparty/tree/ffmpeg/4.x) will be downloaded during a configuration stage and copied to the `bin` folder with all produced libraries.
@note [Libav](https://en.wikipedia.org/wiki/Libav) library can be used instead of FFmpeg, but this combination is not actively supported.
### GStreamer
`WITH_GSTREAMER` (default: _ON_)
Enable integration with [GStreamer](https://en.wikipedia.org/wiki/GStreamer) library for decoding and encoding video files, capturing frames from cameras and network streams. Numerous plugins can be installed to extend supported formats list. OpenCV allows running arbitrary GStreamer pipelines passed as strings to @ref cv::VideoCapture and @ref cv::VideoWriter objects.
Various GStreamer plugins offer HW-accelerated video processing on different platforms.
### Microsoft Media Foundation
`WITH_MSMF` (Windows; default: _ON_)
Enables MSMF backend which uses Windows' built-in [Media Foundation framework](https://en.wikipedia.org/wiki/Media_Foundation). Can be used to capture frames from camera, decode and encode video files. This backend have HW-accelerated processing support (`WITH_MSMF_DXVA` option, default is _ON_).
@note Older versions of Windows (prior to 10) can have incompatible versions of Media Foundation and are known to have problems when used from OpenCV.
### DirectShow
`WITH_DSHOW` (Windows; default: _ON_)
This backend uses older [DirectShow](https://en.wikipedia.org/wiki/DirectShow) framework. It can be used only to capture frames from camera. It is now deprecated in favor of MSMF backend, although both can be enabled in the same build.
### AVFoundation
`WITH_AVFOUNDATION` (Apple; default: _ON_)
[AVFoundation](https://en.wikipedia.org/wiki/AVFoundation) framework is part of Apple platforms and can be used to capture frames from camera, encode and decode video files.
### Other backends
There are multiple less popular frameworks which can be used to read and write videos. Each requires corresponding library or SDK installed.
| Option | Default | Description |
| ------ | ------- | ----------- |
| `WITH_1394` | _OFF_ | [IIDC IEEE1394](https://en.wikipedia.org/wiki/IEEE_1394#IIDC) support using DC1394 library |
| `WITH_OPENNI` | _OFF_ | [OpenNI](https://en.wikipedia.org/wiki/OpenNI) can be used to capture data from depth-sensing cameras. Deprecated. |
| `WITH_OPENNI2` | _OFF_ | [OpenNI2](https://structure.io/openni) can be used to capture data from depth-sensing cameras. |
| `WITH_PVAPI` | _OFF_ | [PVAPI](https://www.alliedvision.com/en/support/software-downloads.html) is legacy SDK for Prosilica GigE cameras. Deprecated. |
| `WITH_ARAVIS` | _OFF_ | [Aravis](https://github.com/AravisProject/aravis) library is used for video acquisition using Genicam cameras. |
| `WITH_XIMEA` | _OFF_ | [XIMEA](https://www.ximea.com/) cameras support. |
| `WITH_XINE` | _OFF_ | [XINE](https://en.wikipedia.org/wiki/Xine) library support. |
| `WITH_LIBREALSENSE` | _OFF_ | [RealSense](https://en.wikipedia.org/wiki/Intel_RealSense) cameras support. |
| `WITH_MFX` | _OFF_ | [MediaSDK](http://mediasdk.intel.com/) library can be used for HW-accelerated decoding and encoding of raw video streams. |
| `WITH_GPHOTO2` | _OFF_ | [GPhoto](https://en.wikipedia.org/wiki/GPhoto) library can be used to capure frames from cameras. |
| `WITH_ANDROID_MEDIANDK` | _ON_ | [MediaNDK](https://developer.android.com/ndk/guides/stable_apis#libmediandk) library is available on Android since API level 21. |
### videoio plugins
Since version 4.1.0 some _videoio_ backends can be built as plugins thus breaking strict dependency on third-party libraries and making them optional at runtime. Following options can be used to control this mechanism:
| Option | Default | Description |
| --------| ------ | ------- |
| `VIDEOIO_ENABLE_PLUGINS` | _ON_ | Enable or disable plugins completely. |
| `VIDEOIO_PLUGIN_LIST` | _empty_ | Comma- or semicolon-separated list of backend names to be compiled as plugins. Supported names are _ffmpeg_, _gstreamer_, _msmf_, _mfx_ and _all_. |
Check @ref tutorial_general_install for standalone plugins build instructions.
## Parallel processing {#tutorial_config_reference_func_core}
Some of OpenCV algorithms can use multithreading to accelerate processing. OpenCV can be built with one of threading backends.
| Backend | Option | Default | Platform | Description |
|-------- | ------ | ------- | -------- | ----------- |
| pthreads | `WITH_PTHREADS_PF` | _ON_ | Unix-like | Default backend based on [pthreads](https://en.wikipedia.org/wiki/POSIX_Threads) library is available on Linux, Android and other Unix-like platforms. Thread pool is implemented in OpenCV and can be controlled with environment variables `OPENCV_THREAD_POOL_*`. Please check sources in _modules/core/src/parallel_impl.cpp_ file for details. |
| Concurrency | N/A | _ON_ | Windows | [Concurrency runtime](https://docs.microsoft.com/en-us/cpp/parallel/concrt/concurrency-runtime) is available on Windows and will be turned _ON_ on supported platforms unless other backend is enabled. |
| GCD | N/A | _ON_ | Apple | [Grand Central Dispatch](https://en.wikipedia.org/wiki/Grand_Central_Dispatch) is available on Apple platforms and will be turned _ON_ automatically unless other backend is enabled. Uses global system thread pool. |
| TBB | `WITH_TBB` | _OFF_ | Multiple | [Threading Building Blocks](https://en.wikipedia.org/wiki/Threading_Building_Blocks) is a cross-platform library for parallel programming. |
| OpenMP | `WITH_OPENMP` | _OFF_ | Multiple | [OpenMP](https://en.wikipedia.org/wiki/OpenMP) API relies on compiler support. |
| HPX | `WITH_HPX` | _OFF_ | Multiple | [High Performance ParallelX](https://en.wikipedia.org/wiki/HPX) is an experimental backend which is more suitable for multiprocessor environments. |
@note OpenCV can download and build TBB library from GitHub, this functionality can be enabled with the `BUILD_TBB` option.
### Threading plugins
Since version 4.5.2 OpenCV supports dynamically loaded threading backends. At this moment only separate compilation process is supported: first you have to build OpenCV with some _default_ parallel backend (e.g. pthreads), then build each plugin and copy resulting binaries to the _lib_ or _bin_ folder.
| Option | Default | Description |
| ------ | ------- | ----------- |
| PARALLEL_ENABLE_PLUGINS | ON | Enable plugin support, if this option is disabled OpenCV will not try to load anything |
Check @ref tutorial_general_install for standalone plugins build instructions.
## GUI backends (highgui module) {#tutorial_config_reference_highgui}
OpenCV relies on various GUI libraries for window drawing.
| Option | Default | Platform | Description |
| ------ | ------- | -------- | ----------- |
| `WITH_GTK` | _ON_ | Linux | [GTK](https://en.wikipedia.org/wiki/GTK) is a common toolkit in Linux and Unix-like OS-es. By default version 3 will be used if found, version 2 can be forced with the `WITH_GTK_2_X` option. |
| `WITH_WIN32UI` | _ON_ | Windows | [WinAPI](https://en.wikipedia.org/wiki/Windows_API) is a standard GUI API in Windows. |
| N/A | _ON_ | macOS | [Cocoa](https://en.wikipedia.org/wiki/Cocoa_(API)) is a framework used in macOS. |
| `WITH_QT` | _OFF_ | Cross-platform | [Qt](https://en.wikipedia.org/wiki/Qt_(software)) is a cross-platform GUI framework. |
| `WITH_FRAMEBUFFER` | _OFF_ | Linux | Experimental backend using [Linux framebuffer](https://en.wikipedia.org/wiki/Linux_framebuffer). Have limited functionality but does not require dependencies. |
| `WITH_FRAMEBUFFER_XVFB` | _OFF_ | Linux | Enables special output mode of the FRAMEBUFFER backend compatible with [xvfb](https://en.wikipedia.org/wiki/Xvfb) tool. Requires some X11 headers. |
@note OpenCV compiled with Qt support enables advanced _highgui_ interface, see @ref highgui_qt for details.
### OpenGL
`WITH_OPENGL` (default: _OFF_)
OpenGL integration can be used to draw HW-accelerated windows with following backends: GTK, WIN32 and Qt. And enables basic interoperability with OpenGL, see @ref core_opengl and @ref highgui_opengl for details.
### highgui plugins
Since OpenCV 4.5.3 GTK backend can be build as a dynamically loaded plugin. Following options can be used to control this mechanism:
| Option | Default | Description |
| --------| ------ | ------- |
| `HIGHGUI_ENABLE_PLUGINS` | _ON_ | Enable or disable plugins completely. |
| `HIGHGUI_PLUGIN_LIST` | _empty_ | Comma- or semicolon-separated list of backend names to be compiled as plugins. Supported names are _gtk_, _gtk2_, _gtk3_, and _all_. |
Check @ref tutorial_general_install for standalone plugins build instructions.
## Deep learning neural networks inference backends and options (dnn module) {#tutorial_config_reference_dnn}
OpenCV have own DNN inference module which have own build-in engine, but can also use other libraries for optimized processing. Multiple backends can be enabled in single build. Selection happens at runtime automatically or manually.
| Option | Default | Description |
| ------ | ------- | ----------- |
| `WITH_PROTOBUF` | _ON_ | Enables [protobuf](https://en.wikipedia.org/wiki/Protocol_Buffers) library search. OpenCV can either build own copy of the library or use external one. This dependency is required by the _dnn_ module, if it can't be found module will be disabled. |
| `BUILD_PROTOBUF` | _ON_ | Build own copy of _protobuf_. Must be disabled if you want to use external library. |
| `PROTOBUF_UPDATE_FILES` | _OFF_ | Re-generate all .proto files. _protoc_ compiler compatible with used version of _protobuf_ must be installed. |
| `OPENCV_DNN_OPENCL` | _ON_ | Enable built-in OpenCL inference backend. |
| `WITH_INF_ENGINE` | _OFF_ | **Deprecated since OpenVINO 2022.1** Enables [Intel Inference Engine (IE)](https://github.com/openvinotoolkit/openvino) backend. Allows to execute networks in IE format (.xml + .bin). Inference Engine must be installed either as part of [OpenVINO toolkit](https://en.wikipedia.org/wiki/OpenVINO), either as a standalone library built from sources. |
| `INF_ENGINE_RELEASE` | _2020040000_ | **Deprecated since OpenVINO 2022.1** Defines version of Inference Engine library which is tied to OpenVINO toolkit version. Must be a 10-digit string, e.g. _2020040000_ for OpenVINO 2020.4. |
| `WITH_NGRAPH` | _OFF_ | **Deprecated since OpenVINO 2022.1** Enables Intel NGraph library support. This library is part of Inference Engine backend which allows executing arbitrary networks read from files in multiple formats supported by OpenCV: Caffe, TensorFlow, PyTorch, Darknet, etc.. NGraph library must be installed, it is included into Inference Engine. |
| `WITH_OPENVINO` | _OFF_ | Enable Intel OpenVINO Toolkit support. Should be used for OpenVINO>=2022.1 instead of `WITH_INF_ENGINE` and `WITH_NGRAPH`. |
| `OPENCV_DNN_CUDA` | _OFF_ | Enable CUDA backend. [CUDA](https://en.wikipedia.org/wiki/CUDA), CUBLAS and [CUDNN](https://developer.nvidia.com/cudnn) must be installed. |
| `WITH_HALIDE` | _OFF_ | Use experimental [Halide](https://en.wikipedia.org/wiki/Halide_(programming_language)) backend which can generate optimized code for dnn-layers at runtime. Halide must be installed. |
| `WITH_VULKAN` | _OFF_ | Enable experimental [Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) backend. Does not require additional dependencies, but can use external Vulkan headers (`VULKAN_INCLUDE_DIRS`). |
# Installation layout {#tutorial_config_reference_install}
## Installation root {#tutorial_config_reference_install_root}
To install produced binaries root location should be configured. Default value depends on distribution, in Ubuntu it is usually set to `/usr/local`. It can be changed during configuration:
```.sh
cmake -DCMAKE_INSTALL_PREFIX=/opt/opencv ../opencv
```
This path can be relative to current working directory, in the following example it will be set to `<absolute-path-to-build>/install`:
```.sh
cmake -DCMAKE_INSTALL_PREFIX=install ../opencv
```
After building the library, all files can be copied to the configured install location using the following command:
```.sh
cmake --build . --target install
```
To install binaries to the system location (e.g. `/usr/local`) as a regular user it is necessary to run the previous command with elevated privileges:
```.sh
sudo cmake --build . --target install
```
@note
On some platforms (Linux) it is possible to remove symbol information during install. Binaries will become 10-15% smaller but debugging will be limited:
```.sh
cmake --build . --target install/strip
```
## Components and locations {#tutorial_config_reference_install_comp}
Options cane be used to control whether or not a part of the library will be installed:
| Option | Default | Description |
| ------ | ------- | ----------- |
| `INSTALL_C_EXAMPLES` | _OFF_ | Install C++ sample sources from the _samples/cpp_ directory. |
| `INSTALL_PYTHON_EXAMPLES` | _OFF_ | Install Python sample sources from the _samples/python_ directory. |
| `INSTALL_ANDROID_EXAMPLES` | _OFF_ | Install Android sample sources from the _samples/android_ directory. |
| `INSTALL_BIN_EXAMPLES` | _OFF_ | Install prebuilt sample applications (`BUILD_EXAMPLES` must be enabled). |
| `INSTALL_TESTS` | _OFF_ | Install tests (`BUILD_TESTS` must be enabled). |
| `OPENCV_INSTALL_APPS_LIST` | _all_ | Comma- or semicolon-separated list of prebuilt applications to install (from _apps_ directory) |
Following options allow to modify components' installation locations relatively to install prefix. Default values of these options depend on platform and other options, please check the _cmake/OpenCVInstallLayout.cmake_ file for details.
| Option | Components |
| ------ | ----------- |
| `OPENCV_BIN_INSTALL_PATH` | applications, dynamic libraries (_win_) |
| `OPENCV_TEST_INSTALL_PATH` | test applications |
| `OPENCV_SAMPLES_BIN_INSTALL_PATH` | sample applications |
| `OPENCV_LIB_INSTALL_PATH` | dynamic libraries, import libraries (_win_) |
| `OPENCV_LIB_ARCHIVE_INSTALL_PATH` | static libraries |
| `OPENCV_3P_LIB_INSTALL_PATH` | 3rdparty libraries |
| `OPENCV_CONFIG_INSTALL_PATH` | cmake config package |
| `OPENCV_INCLUDE_INSTALL_PATH` | header files |
| `OPENCV_OTHER_INSTALL_PATH` | extra data files |
| `OPENCV_SAMPLES_SRC_INSTALL_PATH` | sample sources |
| `OPENCV_LICENSES_INSTALL_PATH` | licenses for included 3rdparty components |
| `OPENCV_TEST_DATA_INSTALL_PATH` | test data |
| `OPENCV_DOC_INSTALL_PATH` | documentation |
| `OPENCV_JAR_INSTALL_PATH` | JAR file with Java bindings |
| `OPENCV_JNI_INSTALL_PATH` | JNI part of Java bindings |
| `OPENCV_JNI_BIN_INSTALL_PATH` | Dynamic libraries from the JNI part of Java bindings |
Following options can be used to change installation layout for common scenarios:
| Option | Default | Description |
| ------ | ------- | ----------- |
| `INSTALL_CREATE_DISTRIB` | _OFF_ | Tune multiple things to produce Windows and Android distributions. |
| `INSTALL_TO_MANGLED_PATHS` | _OFF_ | Adds one level to several installation locations to allow side-by-side installations. For example, headers will be installed to _/usr/include/opencv-4.4.0_ instead of _/usr/include/opencv4_ with this option enabled. |
# Miscellaneous features {#tutorial_config_reference_misc}
| Option | Default | Description |
| ------ | ------- | ----------- |
| `OPENCV_ENABLE_NONFREE` | _OFF_ | Some algorithms included in the library are known to be protected by patents and are disabled by default. |
| `OPENCV_FORCE_3RDPARTY_BUILD`| _OFF_ | Enable all `BUILD_` options at once. |
| `OPENCV_IPP_ENABLE_ALL`| _OFF_ | Enable all `OPENCV_IPP_` options at once. |
| `ENABLE_CCACHE` | _ON_ (on Unix-like platforms) | Enable [ccache](https://en.wikipedia.org/wiki/Ccache) auto-detection. This tool wraps compiler calls and caches results, can significantly improve re-compilation time. |
| `ENABLE_PRECOMPILED_HEADERS` | _ON_ (for MSVC) | Enable precompiled headers support. Improves build time. |
| `BUILD_DOCS` | _OFF_ | Enable documentation build (_doxygen_, _doxygen_cpp_, _doxygen_python_, _doxygen_javadoc_ targets). [Doxygen](http://www.doxygen.org/index.html) must be installed for C++ documentation build. Python and [BeautifulSoup4](https://en.wikipedia.org/wiki/Beautiful_Soup_(HTML_parser)) must be installed for Python documentation build. Javadoc and Ant must be installed for Java documentation build (part of Java SDK). |
| `ENABLE_PYLINT` | _ON_ (when docs or examples are enabled) | Enable python scripts check with [Pylint](https://en.wikipedia.org/wiki/Pylint) (_check_pylint_ target). Pylint must be installed. |
| `ENABLE_FLAKE8` | _ON_ (when docs or examples are enabled) | Enable python scripts check with [Flake8](https://flake8.pycqa.org/) (_check_flake8_ target). Flake8 must be installed. |
| `BUILD_JAVA` | _ON_ | Enable Java wrappers build. Java SDK and Ant must be installed. |
| `BUILD_FAT_JAVA_LIB` | _ON_ (for static Android builds) | Build single _opencv_java_ dynamic library containing all library functionality bundled with Java bindings. |
| `BUILD_opencv_python2` | _ON_ | Build python2 bindings (deprecated). Python with development files and numpy must be installed. |
| `BUILD_opencv_python3` | _ON_ | Build python3 bindings. Python with development files and numpy must be installed. |
TODO: need separate tutorials covering bindings builds
## Automated builds
Some features have been added specifically for automated build environments, like continuous integration and packaging systems.
| Option | Default | Description |
| ------ | ------- | ----------- |
| `ENABLE_NOISY_WARNINGS` | _OFF_ | Enables several compiler warnings considered _noisy_, i.e. having less importance than others. These warnings are usually ignored but in some cases can be worth being checked for. |
| `OPENCV_WARNINGS_ARE_ERRORS` | _OFF_ | Treat compiler warnings as errors. Build will be halted. |
| `ENABLE_CONFIG_VERIFICATION` | _OFF_ | For each enabled dependency (`WITH_` option) verify that it has been found and enabled (`HAVE_` variable). By default feature will be silently turned off if dependency was not found, but with this option enabled cmake configuration will fail. Convenient for packaging systems which require stable library configuration not depending on environment fluctuations. |
| `OPENCV_CMAKE_HOOKS_DIR` | _empty_ | OpenCV allows to customize configuration process by adding custom hook scripts at each stage and substage. cmake scripts with predefined names located in the directory set by this variable will be included before and after various configuration stages. Examples of file names: _CMAKE_INIT.cmake_, _PRE_CMAKE_BOOTSTRAP.cmake_, _POST_CMAKE_BOOTSTRAP.cmake_, etc.. Other names are not documented and can be found in the project cmake files by searching for the _ocv_cmake_hook_ macro calls. |
| `OPENCV_DUMP_HOOKS_FLOW` | _OFF_ | Enables a debug message print on each cmake hook script call. |
## Contrib Modules
Following build options are utilized in `opencv_contrib` modules, as stated [previously](#tutorial_config_reference_general_contrib), these extra modules can be added to your final build by setting `DOPENCV_EXTRA_MODULES_PATH` option.
| Option | Default | Description |
| ------ | ------- | ----------- |
| `WITH_CLP` | _OFF_ | Will add [coinor](https://projects.coin-or.org/Clp) linear programming library build support which is required in `videostab` module. Make sure to install the development libraries of coinor-clp. |
# Other non-documented options
`BUILD_ANDROID_PROJECTS`
`BUILD_ANDROID_EXAMPLES`
`ANDROID_HOME`
`ANDROID_SDK`
`ANDROID_NDK`
`ANDROID_SDK_ROOT`
`CMAKE_TOOLCHAIN_FILE`
`WITH_CAROTENE`
`WITH_KLEIDICV`
`WITH_CPUFEATURES`
`WITH_EIGEN`
`WITH_OPENVX`
`WITH_DIRECTX`
`WITH_VA`
`WITH_LAPACK`
`WITH_QUIRC`
`BUILD_ZLIB`
`BUILD_ITT`
`WITH_IPP`
`BUILD_IPP_IW`
doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown
+71
View File
@@ -0,0 +1,71 @@
Cross referencing OpenCV from other Doxygen projects {#tutorial_cross_referencing}
====================================================
@prev_tutorial{tutorial_transition_guide}
| | |
| -: | :- |
| Original author | Sebastian Höffner |
| Compatibility | OpenCV >= 3.3.0 |
@warning
This tutorial can contain obsolete information.
Cross referencing OpenCV
------------------------
[Doxygen](http://www.doxygen.nl) is a tool to generate
documentations like the OpenCV documentation you are reading right now.
It is used by a variety of software projects and if you happen to use it
to generate your own documentation, and you are using OpenCV inside your
project, this short tutorial is for you.
Imagine this warning inside your documentation code:
@code
/**
* @warning This functions returns a cv::Mat.
*/
@endcode
Inside your generated documentation this warning will look roughly like this:
@warning This functions returns a %cv::Mat.
While inside the OpenCV documentation the `%cv::Mat` is rendered as a link:
@warning This functions returns a cv::Mat.
To generate links to the OpenCV documentation inside your project, you only
have to perform two small steps. First download the file
[opencv.tag](opencv.tag) (right-click and choose "save as...") and place it
somewhere in your project directory, for example as
`docs/doxygen-tags/opencv.tag`.
Open your Doxyfile using your favorite text editor and search for the key
`TAGFILES`. Change it as follows:
@code
TAGFILES = ./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/4.14.0
@endcode
If you had other definitions already, you can append the line using a `\`:
@code
TAGFILES = ./docs/doxygen-tags/libstdc++.tag=https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen \
./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/4.14.0
@endcode
Doxygen can now use the information from the tag file to link to the OpenCV
documentation. Rebuild your documentation right now!
@note To allow others to also use a *.tag file to link to your documentation,
set `GENERATE_TAGFILE = html/your_project.tag`. Your documentation will now
contain a `your_project.tag` file in its root directory.
References
----------
- [Doxygen: Linking to external documentation](http://www.doxygen.nl/manual/external.html)
- [opencv.tag](opencv.tag)
doc/tutorials/introduction/crosscompilation/arm_crosscompile_with_cmake.markdown
+105
View File
@@ -0,0 +1,105 @@
Cross compilation for ARM based Linux systems {#tutorial_arm_crosscompile_with_cmake}
=============================================
@prev_tutorial{tutorial_macos_install}
@next_tutorial{tutorial_crosscompile_with_multiarch}
| | |
| -: | :- |
| Original author | Alexander Smorkalov |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
@warning
This tutorial can contain obsolete information.
This steps are tested on Ubuntu Linux 12.04, but should work for other Linux distributions. I case
of other distributions package names and names of cross compilation tools may differ. There are
several popular EABI versions that are used on ARM platform. This tutorial is written for *gnueabi*
and *gnueabihf*, but other variants should work with minimal changes.
Prerequisites
-------------
- Host computer with Linux;
- Git;
- CMake 2.6 or higher;
- Cross compilation tools for ARM: gcc, libstc++, etc. Depending on target platform you need to
choose *gnueabi* or *gnueabihf* tools. Install command for *gnueabi*:
@code{.bash}
sudo apt-get install gcc-arm-linux-gnueabi
@endcode
Install command for *gnueabihf*:
@code{.bash}
sudo apt-get install gcc-arm-linux-gnueabihf
@endcode
- pkgconfig;
- Python 2.6 for host system;
- [optional] ffmpeg or libav development packages for armeabi(hf): libavcodec-dev,
libavformat-dev, libswscale-dev;
- [optional] GTK+2.x or higher, including headers (libgtk2.0-dev) for armeabi(hf);
- [optional] libdc1394 2.x;
- [optional] libjpeg-dev, libpng-dev, libtiff-dev, libjasper-dev for armeabi(hf).
Getting OpenCV Source Code
--------------------------
You can use the latest stable OpenCV version available in *sourceforge* or you can grab the latest
snapshot from our [Git repository](https://github.com/opencv/opencv.git).
### Getting the Latest Stable OpenCV Version
- Go to our [page on Sourceforge](http://sourceforge.net/projects/opencvlibrary);
- Download the source tarball and unpack it.
### Getting the Cutting-edge OpenCV from the Git Repository
Launch Git client and clone [OpenCV repository](http://github.com/opencv/opencv)
In Linux it can be achieved with the following command in Terminal:
@code{.bash}
cd ~/<my_working _directory>
git clone https://github.com/opencv/opencv.git
@endcode
Building OpenCV
---------------
-# Create a build directory, make it current and run the following command:
@code{.bash}
cmake [<some optional parameters>] -DCMAKE_TOOLCHAIN_FILE=<path to the OpenCV source directory>/platforms/linux/arm-gnueabi.toolchain.cmake <path to the OpenCV source directory>
@endcode
Toolchain uses *gnueabihf* EABI convention by default. Add -DSOFTFP=ON cmake argument to switch
on softfp compiler.
@code{.bash}
cmake [<some optional parameters>] -DSOFTFP=ON -DCMAKE_TOOLCHAIN_FILE=<path to the OpenCV source directory>/platforms/linux/arm-gnueabi.toolchain.cmake <path to the OpenCV source directory>
@endcode
For example:
@code{.bash}
cd ~/opencv/platforms/linux
mkdir -p build_hardfp
cd build_hardfp
cmake -DCMAKE_TOOLCHAIN_FILE=../arm-gnueabi.toolchain.cmake ../../..
@endcode
-# Run make in build (\<cmake_binary_dir\>) directory:
@code{.bash}
make
@endcode
@note
Optionally you can strip symbols info from the created library via install/strip make target.
This option produces smaller binary (\~ twice smaller) but makes further debugging harder.
### Enable hardware optimizations
Depending on target platform architecture different instruction sets can be used. By default
compiler generates code for armv5l without VFPv3 and NEON extensions. Add -DENABLE_VFPV3=ON to
cmake command line to enable code generation for VFPv3 and -DENABLE_NEON=ON for using NEON SIMD
extensions.
TBB is supported on multi core ARM SoCs also. Add -DWITH_TBB=ON and -DBUILD_TBB=ON to enable it.
Cmake scripts download TBB sources from official project site
<http://threadingbuildingblocks.org/> and build it.
doc/tutorials/introduction/crosscompilation/crosscompile_with_multiarch.markdown
+597
View File
@@ -0,0 +1,597 @@
# MultiArch cross-compilation with Ubuntu/Debian{#tutorial_crosscompile_with_multiarch}
@prev_tutorial{tutorial_arm_crosscompile_with_cmake}
@next_tutorial{tutorial_building_tegra_cuda}
[TOC]
| | |
| -: | :- |
| Original author | Kumataro |
| Compatibility | Ubuntu >=23.04 |
|^ | OpenCV >=4.8.0 |
@tableofcontents
@warning
This tutorial may contain obsolete information.
## What is "MultiArch"
OpenCV may use a lot of 3rdparty libraries for video and image decoding, rendering, acceleration
and complex math algorithms. The 3rd party components are found by CMake on the build host
cross-compilation allows to build OpenCV for foreign architecture or OS, but we loose that large
world of components and have to cross-compile each dependency separately and point to it during
OpenCV build.
Debian/Ubuntu MultiArch helps to fix this. It allows to install several foreign architecture
libraries on host system and use them during OpenCV dependencies resolution.
@warning
- Following these steps will make your Linux environment a little dirty.
If possible, it is better to use VMs or Container(e.g. Docker).
- This tutorial expects host and target uses same Ubuntu version.
Do not use/mix different versions for external library dependency.
- Good: Host and Target are 23.04.
- Good: Host and Target are 23.10.
- Not Good: Host is 23.04, and Target is 23.10.
- Not Good: Host is 23.10, and Target is 23.04.
- This tutorial may be used for Debian and its derivatives like Raspberry Pi OS. Please make any
necessary changes.
## Download tools
Install necessary tools and toolchains for cross-compilation.
- git, cmake, pkgconf and build-essential are required basically.
- ninja-build is to reduce compilation time(option).
- crossbuild-essential-armhf is toolchain package for armv7 target.
- crossbuild-essential-arm64 is toolchain package for aarch64 target.
@code{.bash}
sudo apt update -y
sudo apt install -y \
git \
cmake \
pkgconf \
build-essential \
ninja-build \
crossbuild-essential-armhf \
crossbuild-essential-arm64
@endcode
If you want to enable Python 3 wrapper, install these packages too.
@code{.bash}
sudo apt install -y \
python3-minimal \
python3-numpy
@endcode
## Working folder structure
In this tutorial, following working folder structure are used.
@code{.unparsed}
/home
+ kmtr - please replace your account name.
+ work
+ opencv - source, cloned from github
+ opencv_contrib - source, cloned from github
+ build4-full_arm64 - artifact(for aarch64 target), created by cmake
+ build4-full_armhf - artifact(for armhf target), created by cmake
@endcode
1. Create working folder under your home directory.
2. Clone OpenCV and OpenCV Contrib from repository to work directory.
@code{.bash}
cd ~
mkdir work
cd work
git clone --depth=1 https://github.com/opencv/opencv.git
git clone --depth=1 https://github.com/opencv/opencv_contrib.git
@endcode
## Update apt and dpkg settings
These steps are on host.
`apt` and `dpkg` are package management systems used in Ubuntu and Debian.
Following are setup steps to use MultiArch.
### Step 1. Add apt source for arm64 and armhf
Execute `sudo apt edit-sources` to add foreign arch libraries at end of file.
Example 1: arm64 and armv7 for Ubuntu 23.04
@code{.unparsed}
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-updates main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-updates universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-updates multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-backports main restricted universe multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-security main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-security universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-security multiverse
@endcode
Example 2: arm64 and armv7 for Ubuntu 23.10
@code{.unparsed}
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-updates main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-updates universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-updates multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-backports main restricted universe multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-security main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-security universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-security multiverse
@endcode
### Step 2. Update apt database
Update apt database to apply new apt sources.
Execute `sudo apt update`.
@code{.bash}
sudo apt update
@endcode
### Step 3. Update dpkg settings
Update dpkg settings to support foreign architectures.
Execute `sudo dpkg --add-architecture arm64` and/or `sudo dpkg --add-architecture armhf`.
@code{.bash}
sudo dpkg --add-architecture arm64
sudo dpkg --add-architecture armhf
@endcode
`sudo dpkg --print-architecture` shows what is host architecture.
@code{.bash}
sudo dpkg --print-architecture
amd64
@endcode
And `sudo dpkg --print-foreign-architectures` shows what foreign architectures are supported.
@code{.bash}
sudo dpkg --print-foreign-architectures
arm64
armhf
@endcode
### Confirm working pkg-config
With MultiArch, several shared libraries and pkg-config information for each architectures are stored into /usr/lib.
@code{.unparsed}
/usr
+ lib
+ aarch64-linux-gnu - shared libraries for arm64
+ pkgconfig - pkg-config files for arm64 libraries
+ arm-linux-gnueabihf - shared libraries for armhf
+ pkgconfig - pkg-config files for armhf libraries
+ share
+ pkgconfig - pkg-config files(for header files)
@endcode
Confirm to work `pkg-config` using `PKG_CONFIG_PATH`, `PKG_CONFIG_LIBDIR` and `PKG_CONFIG_SYSROOT_DIR` options.
for aarch64:
@code{.bash}
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config --list-all
@endcode
for armv7:
@code{.bash}
PKG_CONFIG_PATH=/usr/lib/arm-linux-gnueabihf/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/arm-linux-gnueabihf \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config --list-all
@endcode
## Cross-compile for aarch64
Following is to compile for target (aarch64) at host (x86-64).
### Step 1. Install external libraries for target into host
This step is on host.
Install libfreetype-dev, libharfbuzz-dev and FFmpeg packages for target (arm64) into host (x86-64).
@code{.bash}
sudo apt install -y \
libavcodec-dev:arm64 \
libavformat-dev:arm64 \
libavutil-dev:arm64 \
libswscale-dev:arm64 \
libfreetype-dev:arm64 \
libharfbuzz-dev:arm64
@endcode
If you want to enable Python 3 wrapper, install these packages too.
@code{.bash}
sudo apt install -y \
libpython3-dev:arm64
@endcode
If succeed, pkg-config can show information about these packages.
For Freetype2 and Harfbuzz:
@code{.bash}
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config freetype2 harfbuzz --cflags --libs
-I/usr/include/freetype2 -I/usr/include/libpng16 -I/usr/include/harfbuzz -I/usr/include/glib-2.0 -I/usr/lib/aarch64-linux-gnu/glib-2.0/include -L/usr/lib/aarch64-linux-gnu -lfreetype -lharfbuzz
@endcode
For FFmpeg:
@code{.bash}
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config libavcodec libavformat libavutil libswscale --cflags --libs
-I/usr/include/aarch64-linux-gnu -L/usr/lib/aarch64-linux-gnu -lavcodec -lavformat -lavutil -lswscale
@endcode
### Step 2. Configure OpenCV Settings
This step is on host.
Execute `cmake` to make cross-compile configuration for aarch64.
@note `-DCMAKE_TOOLCHAIN_FILE` should be absolute/real file path, not relative path.
@code{.bash}
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
cmake -S opencv \
-B build4-full_arm64 \
-DCMAKE_TOOLCHAIN_FILE=/home/kmtr/work/opencv/platforms/linux/aarch64-gnu.toolchain.cmake \
-DOPENCV_EXTRA_MODULES_PATH=opencv_contrib/modules \
-GNinja
@endcode
If you want to enable Python 3 wrapper, extra options are needed.
@code{.bash}
PYTHON3_REALPATH=`realpath /usr/bin/python3`
PYTHON3_BASENAME=`basename ${PYTHON3_REALPATH}`
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
cmake -S opencv \
-B build4-full_arm64 \
-DCMAKE_TOOLCHAIN_FILE=/home/kmtr/work/opencv/platforms/linux/aarch64-gnu.toolchain.cmake \
-DOPENCV_EXTRA_MODULES_PATH=opencv_contrib/modules \
-DPYTHON3_NUMPY_INCLUDE_DIRS="/usr/local/lib/${PYTHON3_BASENAME}/dist-packages/numpy/core/include/" \
-DPYTHON3_INCLUDE_PATH="/usr/include/${PYTHON3_BASENAME};/usr/include/" \
-DPYTHON3_LIBRARIES=`find /usr/lib/aarch64-linux-gnu/ -name libpython*.so` \
-DPYTHON3_EXECUTABLE="/usr/bin/${PYTHON3_BASENAME}" \
-DPYTHON3_CVPY_SUFFIX=".so" \
-GNinja
@endcode
@note
@parblock
Lastly, "python3.XX" string is needed. So this script generate it.
- Get real path from "/usr/bin/python3" to "/usr/bin/python3.xx".
- Get base name from "/usr/bin/python3.xx" to "pyhton3.xx".
@endparblock
Following is cmake outputs.
- `Host` is `Linux x86_64`.
- `Target` is `Linux aarch64`.
- FFmpeg is available.
@code{.unparsed}
-- General configuration for OpenCV 4.8.0-dev =====================================
-- Version control: 408730b
--
-- Extra modules:
-- Location (extra): /home/kmtr/work/opencv_contrib/modules
-- Version control (extra): faa5468
--
-- Platform:
-- Timestamp: 2023-12-01T22:02:14Z
-- Host: Linux 6.5.0-13-generic x86_64
-- Target: Linux 1 aarch64
-- CMake: 3.27.4
-- CMake generator: Ninja
-- CMake build tool: /usr/bin/ninja
-- Configuration: Release
--
-- CPU/HW features:
-- Baseline: NEON FP16
-- required: NEON
-- disabled: VFPV3
-- Dispatched code generation: NEON_DOTPROD NEON_FP16 NEON_BF16
-- requested: NEON_FP16 NEON_BF16 NEON_DOTPROD
-- NEON_DOTPROD (1 files): + NEON_DOTPROD
-- NEON_FP16 (2 files): + NEON_FP16
-- NEON_BF16 (0 files): + NEON_BF16
--
-- C/C++:
-- Built as dynamic libs?: YES
-- C++ standard: 11
-- C++ Compiler: /usr/bin/aarch64-linux-gnu-g++ (ver 13.2.0)
:
:
--
-- Video I/O:
-- DC1394: NO
-- FFMPEG: YES
-- avcodec: YES (60.3.100)
-- avformat: YES (60.3.100)
-- avutil: YES (58.2.100)
-- swscale: YES (7.1.100)
-- avresample: NO
-- GStreamer: NO
-- v4l/v4l2: YES (linux/videodev2.h)
--
@endcode
If enabling Python 3 wrapper is succeeded, `Python 3:` section shows more.
@code{.unparsed}
--
-- Python 3:
-- Interpreter: /usr/bin/python3.11 (ver 3.11.6)
-- Libraries: /usr/lib/aarch64-linux-gnu/libpython3.11.so
-- numpy: /usr/local/lib/python3.11/dist-packages/numpy/core/include/ (ver undefined - cannot be probed because of the cross-compilation)
-- install path: lib/python3.11/dist-packages/cv2/python-3.11
--
-- Python (for build): /usr/bin/python3.11
--
@endcode
### Step 3. Build and archive OpenCV libraries and headers
This step in in host.
Build and install.
(This `install` means only that copying artifacts to `install` folder.)
@code{.bash}
cmake --build build4-full_arm64
sudo cmake --install build4-full_arm64
@endcode
Archive artifacts(built libraries and headers) to `opencv_arm64.tgz` with tar command.
@code{.bash}
tar czvf opencv_arm64.tgz -C build4-full_arm64/install .
@endcode
And send `opencv_arm64.tgz` to target.
### Step 4. Install dependency libraries at target
This step is executed on the target system.
Install dependency run-time libraries for OpenCV/OpenCV contrib libraries at target.
@code{.bash}
sudo apt install -y \
libavcodec60 \
libavformat60 \
libavutil58 \
libswscale7 \
libfreetype6 \
libharfbuzz0b
sudo ldconfig
@endcode
If you want to enable Python 3 wrapper, install these packages too.
@code{.bash}
sudo apt install -y \
python3-minimal \
python3-numpy
@endcode
@warning
@parblock
If version of runtime libraries and/or programs are incremented, apt package names may be changed
(e.g. `libswscale6` is used for Ubuntu 23.04, but `libswscale7` is used for Ubuntu 23.10).
Looking for it with `apt search` command or https://packages.ubuntu.com/ .
@endparblock
@warning
@parblock
External library version between host and target should be same.
Please update to the latest version libraries at the same time as possible.
Even if the OS versions are the same between the Host and Target,
the versions may differ due to additional updates to the libraries.
This will cause unexpected problems.
For example)
- On Host, OpenCV has been build with external libA (v1.0) for target.
- libA (v1.1) may be updated.
- On Target, libA (v1.1) is installed to use OpenCV.
- In this case, versions of libA is difference between compiling and running.
@endparblock
@warning
@parblock
If you forget/mismatch to install some necessary libraries, OpenCV will not works well.
`ldd` command can detect dependency. If there are any "not found", please install necessary libraries.
@code{.bash}
ldd /usr/local/lib/libopencv_freetype.so
@endcode
(Not Good) `freetype module` requires `libharfbuzz.so.0`, but it has not been installed.
@code{.unparsed}
linux-vdso.so.1 (0xABCDEFG01234567)
libopencv_imgproc.so.408 => /usr/local/lib/libopencv_imgproc.so.408 (0xABCDEF001234567)
libfreetype.so.6 => /lib/aarch64-linux-gnu/libfreetype.so.6 (0xABCDEF001234567)
libharfbuzz.so.0 => not found
libopencv_core.so.408 => /usr/local/lib/libopencv_core.so.408 (0xABCDEF001234567)
:
@endcode
(Good) All libraries which are required from `freetype modules` are installed.
@code{.unparsed}
linux-vdso.so.1 (0xABCDEFG01234567)
libopencv_imgproc.so.408 => /usr/local/lib/libopencv_imgproc.so.408 (0xABCDEF001234567)
libfreetype.so.6 => /lib/aarch64-linux-gnu/libfreetype.so.6 (0xABCDEF001234567)
libharfbuzz.so.0 => /lib/aarch64-linux-gnu/libharfbuzz.so.0 (0xABCDEF001234567)
libopencv_core.so.408 => /usr/local/lib/libopencv_core.so.408 (0xABCDEF001234567)
:
@endcode
@endparblock
### Step 5. Install OpenCV libraries to target
This step is on target.
Receive `opencv_arm64.tgz` from host (generated at Step3), and extract to `/usr/local`.
@code{.bash}
sudo tar zxvf opencv_arm64.tgz -C /usr/local
sudo ldconfig
@endcode
You can use OpenCV libraries same as self-compiling. Following is OpenCV sample code. Compile and
run it on target.
Makefile
@code{.make}
a.out : main.cpp
g++ main.cpp -o a.out \
-I/usr/local/include/opencv4 \
-lopencv_core
@endcode
main.cpp
@code{.cpp}
#include <iostream>
#include <opencv2/core.hpp>
int main(void)
{
std::cout << cv::getBuildInformation() << std::endl;
return 0;
}
@endcode
Execute `make` and run it.
@code{.bash}
make a.out
./a.out
@endcode
If you want to enable Python 3 wrapper, execute following command to confirm.
@code{.bash}
python3 -c "import cv2; print(cv2.getBuildInformation())"
@endcode
## Cross-compile for armv7
Following is to compile for target (armhf) at host (x86-64).
- To resolve dependencies, `linux-libc-dev:armhf` is required.
- To optimize with neon, `-DENABLE_NEON=ON` is needed.
@code{.bash}
sudo apt install -y \
linux-libc-dev:armhf \
libavcodec-dev:armhf \
libavformat-dev:armhf \
libavutil-dev:armhf \
libswscale-dev:armhf \
libfreetype-dev:armhf \
libharfbuzz-dev:armhf
PKG_CONFIG_PATH=/usr/lib/arm-linux-gnueabihf/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/arm-linux-gnueabihf \
PKG_CONFIG_SYSROOT_DIR=/ \
cmake -S opencv \
-B build4-full_armhf \
-DENABLE_NEON=ON \
-DCMAKE_TOOLCHAIN_FILE=/home/kmtr/work/opencv/platforms/linux/arm-gnueabi.toolchain.cmake \
-DOPENCV_EXTRA_MODULES_PATH=opencv_contrib/modules \
-GNinja
cmake --build build4-full_armhf
sudo cmake --install build4-full_armhf
tar czvf opencv_armhf.tgz -C build4-full_armhf/install .
@endcode
Following is cmake outputs.
- `Host` is `Linux x86_64`.
- `Target` is `Linux arm`.
- FFmpeg is available.
@code{.unparsed}
-- General configuration for OpenCV 4.8.0-dev =====================================
-- Version control: 408730b
--
-- Extra modules:
-- Location (extra): /home/kmtr/work/opencv_contrib/modules
-- Version control (extra): faa5468
--
-- Platform:
-- Timestamp: 2023-12-02T03:39:58Z
-- Host: Linux 6.5.0-13-generic x86_64
-- Target: Linux 1 arm
-- CMake: 3.27.4
-- CMake generator: Ninja
-- CMake build tool: /usr/bin/ninja
-- Configuration: Release
--
-- CPU/HW features:
-- Baseline: NEON
-- requested: DETECT
-- required: NEON
-- disabled: VFPV3
--
-- C/C++:
-- Built as dynamic libs?: YES
-- C++ standard: 11
-- C++ Compiler: /usr/bin/arm-linux-gnueabihf-g++ (ver 13.2.0)
:
:
--
-- Video I/O:
-- DC1394: NO
-- FFMPEG: YES
-- avcodec: YES (60.3.100)
-- avformat: YES (60.3.100)
-- avutil: YES (58.2.100)
-- swscale: YES (7.1.100)
-- avresample: NO
-- GStreamer: NO
-- v4l/v4l2: YES (linux/videodev2.h)
--
@endcode
doc/tutorials/introduction/desktop_java/images/Java_logo.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

doc/tutorials/introduction/desktop_java/images/ant_output.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

doc/tutorials/introduction/desktop_java/images/cmake_output.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

doc/tutorials/introduction/desktop_java/images/faceDetection.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 500 KiB

doc/tutorials/introduction/desktop_java/images/sbt_eclipse.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 248 KiB

doc/tutorials/introduction/desktop_java/images/sbt_run.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 195 KiB

doc/tutorials/introduction/desktop_java/images/sbt_run_face.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 258 KiB

doc/tutorials/introduction/desktop_java/java_dev_intro.markdown
+340
View File
@@ -0,0 +1,340 @@
Introduction to Java Development {#tutorial_java_dev_intro}
================================
@prev_tutorial{tutorial_windows_visual_studio_image_watch}
@next_tutorial{tutorial_java_eclipse}
| | |
| -: | :- |
| Original author | Eric Christiansen and Andrey Pavlenko |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
@warning
This tutorial can contain obsolete information.
As of OpenCV 2.4.4, OpenCV supports desktop Java development using nearly the same interface as for
Android development. This guide will help you to create your first Java (or Scala) application using
OpenCV. We will use either [Apache Ant](http://ant.apache.org/) or [Simple Build Tool
(SBT)](http://www.scala-sbt.org/) to build the application.
If you want to use Eclipse head to @ref tutorial_java_eclipse. For further reading after this guide, look at
the @ref tutorial_android_dev_intro tutorials.
What we'll do in this guide
---------------------------
In this guide, we will:
- Get OpenCV with desktop Java support
- Create an Ant or SBT project
- Write a simple OpenCV application in Java or Scala
The same process was used to create the samples in the `samples/java` folder of the OpenCV
repository, so consult those files if you get lost.
Get proper OpenCV
-----------------
Starting from version 2.4.4 OpenCV includes desktop Java bindings.
### Download
The most simple way to get it is downloading the appropriate package of **version 2.4.4 or higher**
from the [OpenCV SourceForge repository](http://sourceforge.net/projects/opencvlibrary/files/).
@note Windows users can find the prebuilt files needed for Java development in the
`opencv/build/java/` folder inside the package. For other OSes it's required to build OpenCV from
sources.
Another option to get OpenCV sources is to clone [OpenCV git
repository](https://github.com/opencv/opencv/). In order to build OpenCV with Java bindings you need
JDK (Java Development Kit) (we recommend [Oracle/Sun JDK 6 or
7](http://www.oracle.com/technetwork/java/javase/downloads/)), [Apache Ant](http://ant.apache.org/)
and Python v2.6 or higher to be installed.
### Build
Let's build OpenCV:
@code{.bash}
git clone git://github.com/opencv/opencv.git
cd opencv
git checkout 2.4
mkdir build
cd build
@endcode
Generate a Makefile or a MS Visual Studio\* solution, or whatever you use for building executables
in your system:
@code{.bash}
cmake -DBUILD_SHARED_LIBS=OFF ..
@endcode
or
@code{.bat}
cmake -DBUILD_SHARED_LIBS=OFF -G "Visual Studio 10" ..
@endcode
@note When OpenCV is built as a set of **static** libraries (-DBUILD_SHARED_LIBS=OFF option) the
Java bindings dynamic library is all-sufficient, i.e. doesn't depend on other OpenCV libs, but
includes all the OpenCV code inside.
Examine the output of CMake and ensure java is one of the
modules "To be built". If not, it's likely you're missing a dependency. You should troubleshoot by
looking through the CMake output for any Java-related tools that aren't found and installing them.
![](images/cmake_output.png)
@note If CMake can't find Java in your system set the JAVA_HOME environment variable with the path to installed JDK before running it. E.g.:
@code{.bash}
export JAVA_HOME=/usr/lib/jvm/java-6-oracle
cmake -DBUILD_SHARED_LIBS=OFF ..
@endcode
Now start the build:
@code{.bash}
make -j8
@endcode
or
@code{.bat}
msbuild /m OpenCV.sln /t:Build /p:Configuration=Release /v:m
@endcode
Besides all this will create a jar containing the Java interface (`bin/opencv-244.jar`) and a native
dynamic library containing Java bindings and all the OpenCV stuff (`lib/libopencv_java244.so` or
`bin/Release/opencv_java244.dll` respectively). We'll use these files later.
Java sample with Ant
--------------------
@note The described sample is provided with OpenCV library in the `opencv/samples/java/ant`
folder.
- Create a folder where you'll develop this sample application.
- In this folder create the `build.xml` file with the following content using any text editor:
@include samples/java/ant/build.xml
@note This XML file can be reused for building other Java applications. It describes a common folder structure in the lines 3 - 12 and common targets for compiling and running the application.
When reusing this XML don't forget to modify the project name in the line 1, that is also the
name of the main class (line 14). The paths to OpenCV jar and jni lib are expected as parameters
("${ocvJarDir}" in line 5 and "${ocvLibDir}" in line 37), but you can hardcode these paths for
your convenience. See [Ant documentation](http://ant.apache.org/manual/) for detailed
description of its build file format.
- Create an `src` folder next to the `build.xml` file and a `SimpleSample.java` file in it.
- Put the following Java code into the `SimpleSample.java` file:
@code{.java}
import org.opencv.core.Core;
import org.opencv.core.Mat;
import org.opencv.core.CvType;
import org.opencv.core.Scalar;
class SimpleSample {
static{ System.loadLibrary(Core.NATIVE_LIBRARY_NAME); }
public static void main(String[] args) {
System.out.println("Welcome to OpenCV " + Core.VERSION);
Mat m = new Mat(5, 10, CvType.CV_8UC1, new Scalar(0));
System.out.println("OpenCV Mat: " + m);
Mat mr1 = m.row(1);
mr1.setTo(new Scalar(1));
Mat mc5 = m.col(5);
mc5.setTo(new Scalar(5));
System.out.println("OpenCV Mat data:\n" + m.dump());
}
}
@endcode
- Run the following command in console in the folder containing `build.xml`:
@code{.bash}
ant -DocvJarDir=path/to/dir/containing/opencv-244.jar -DocvLibDir=path/to/dir/containing/opencv_java244/native/library
@endcode
For example:
@code{.bat}
ant -DocvJarDir=X:\opencv-2.4.4\bin -DocvLibDir=X:\opencv-2.4.4\bin\Release
@endcode
The command should initiate [re]building and running the sample. You should see on the
screen something like this:
![](images/ant_output.png)
SBT project for Java and Scala
------------------------------
Now we'll create a simple Java application using SBT. This serves as a brief introduction to those
unfamiliar with this build tool. We're using SBT because it is particularly easy and powerful.
First, download and install [SBT](http://www.scala-sbt.org/) using the instructions on its [web
site](http://www.scala-sbt.org/).
Next, navigate to a new directory where you'd like the application source to live (outside `opencv`
dir). Let's call it "JavaSample" and create a directory for it:
@code{.bash}
cd <somewhere outside opencv>
mkdir JavaSample
@endcode
Now we will create the necessary folders and an SBT project:
@code{.bash}
cd JavaSample
mkdir -p src/main/java # This is where SBT expects to find Java sources
mkdir project # This is where the build definitions live
@endcode
Now open `project/build.scala` in your favorite editor and paste the following. It defines your
project:
@code{.scala}
import sbt._
import Keys._
object JavaSampleBuild extends Build {
def scalaSettings = Seq(
scalaVersion := "2.10.0",
scalacOptions ++= Seq(
"-optimize",
"-unchecked",
"-deprecation"
)
)
def buildSettings =
Project.defaultSettings ++
scalaSettings
lazy val root = {
val settings = buildSettings ++ Seq(name := "JavaSample")
Project(id = "JavaSample", base = file("."), settings = settings)
}
}
@endcode
Now edit `project/plugins.sbt` and paste the following. This will enable auto-generation of an
Eclipse project:
@code{.scala}
addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "2.1.0")
@endcode
Now run sbt from the `JavaSample` root and from within SBT run eclipse to generate an eclipse
project:
@code{.bash}
sbt # Starts the sbt console
eclipse # Running "eclipse" from within the sbt console
@endcode
You should see something like this:
![](images/sbt_eclipse.png)
You can now import the SBT project to Eclipse using Import ... -\> Existing projects into workspace.
Whether you actually do this is optional for the guide; we'll be using SBT to build the project, so
if you choose to use Eclipse it will just serve as a text editor.
To test that everything is working, create a simple "Hello OpenCV" application. Do this by creating
a file `src/main/java/HelloOpenCV.java` with the following contents:
@code{.java}
public class HelloOpenCV {
public static void main(String[] args) {
System.out.println("Hello, OpenCV");
}
@endcode
}
Now execute run from the sbt console, or more concisely, run sbt run from the command line:
@code{.bash}
sbt run
@endcode
You should see something like this:
![](images/sbt_run.png)
### Running SBT samples
Now we'll create a simple face detection application using OpenCV.
First, create a `lib/` folder and copy the OpenCV jar into it. By default, SBT adds jars in the lib
folder to the Java library search path. You can optionally rerun sbt eclipse to update your Eclipse
project.
@code{.bash}
mkdir lib
cp <opencv_dir>/build/bin/opencv_<version>.jar lib/
sbt eclipse
@endcode
Next, create the directory `src/main/resources` and download this Lena image into it:
![](images/lena.png)
Make sure it's called `"lena.png"`. Items in the resources directory are available to the Java
application at runtime.
Next, copy `lbpcascade_frontalface.xml` from `opencv/data/lbpcascades/` into the `resources`
directory:
@code{.bash}
cp <opencv_dir>/data/lbpcascades/lbpcascade_frontalface.xml src/main/resources/
@endcode
Now modify src/main/java/HelloOpenCV.java so it contains the following Java code:
@code{.java}
import org.opencv.core.Core;
import org.opencv.core.Mat;
import org.opencv.core.MatOfRect;
import org.opencv.core.Point;
import org.opencv.core.Rect;
import org.opencv.core.Scalar;
import org.opencv.imgcodecs.Imgcodecs;
import org.opencv.objdetect.CascadeClassifier;
//
// Detects faces in an image, draws boxes around them, and writes the results
// to "faceDetection.png".
//
class DetectFaceDemo {
public void run() {
System.out.println("\nRunning DetectFaceDemo");
// Create a face detector from the cascade file in the resources
// directory.
CascadeClassifier faceDetector = new CascadeClassifier(getClass().getResource("/lbpcascade_frontalface.xml").getPath());
Mat image = Imgcodecs.imread(getClass().getResource("/lena.png").getPath());
// Detect faces in the image.
// MatOfRect is a special container class for Rect.
MatOfRect faceDetections = new MatOfRect();
faceDetector.detectMultiScale(image, faceDetections);
System.out.println(String.format("Detected %s faces", faceDetections.toArray().length));
// Draw a bounding box around each face.
for (Rect rect : faceDetections.toArray()) {
Imgproc.rectangle(image, new Point(rect.x, rect.y), new Point(rect.x + rect.width, rect.y + rect.height), new Scalar(0, 255, 0));
}
// Save the visualized detection.
String filename = "faceDetection.png";
System.out.println(String.format("Writing %s", filename));
Imgcodecs.imwrite(filename, image);
}
}
public class HelloOpenCV {
public static void main(String[] args) {
System.out.println("Hello, OpenCV");
// Load the native library.
System.loadLibrary(Core.NATIVE_LIBRARY_NAME);
new DetectFaceDemo().run();
}
}
@endcode
Note the call to System.loadLibrary(Core.NATIVE_LIBRARY_NAME). This command must be executed
exactly once per Java process prior to using any native OpenCV methods. If you don't call it, you
will get UnsatisfiedLink errors. You will also get errors if you try to load OpenCV when it has
already been loaded.
Now run the face detection app using \`sbt run\`:
@code{.bash}
sbt run
@endcode
You should see something like this:
![](images/sbt_run_face.png)
It should also write the following image to `faceDetection.png`:
![](images/faceDetection.png)
You're done! Now you have a sample Java application working with OpenCV, so you can start the work
on your own. We wish you good luck and many years of joyful life!
doc/tutorials/introduction/display_image/display_image.markdown
+136
View File
@@ -0,0 +1,136 @@
Getting Started with Images {#tutorial_display_image}
===========================
@prev_tutorial{tutorial_building_tegra_cuda}
@next_tutorial{tutorial_documentation}
| | |
| -: | :- |
| Original author | Ana Huamán |
| Compatibility | OpenCV >= 3.4.4 |
@tableofcontents
@warning
This tutorial can contain obsolete information.
Goal
----
In this tutorial you will learn how to:
- Read an image from file (using @ref cv::imread)
- Display an image in an OpenCV window (using @ref cv::imshow)
- Write an image to a file (using @ref cv::imwrite)
Source Code
-----------
@add_toggle_cpp
- **Downloadable code**: Click
[here](https://github.com/opencv/opencv/tree/4.x/samples/cpp/tutorial_code/introduction/display_image/display_image.cpp)
- **Code at glance:**
@include samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
@end_toggle
@add_toggle_python
- **Downloadable code**: Click
[here](https://github.com/opencv/opencv/tree/4.x/samples/python/tutorial_code/introduction/display_image/display_image.py)
- **Code at glance:**
@include samples/python/tutorial_code/introduction/display_image/display_image.py
@end_toggle
Explanation
-----------
@add_toggle_cpp
In OpenCV 3 we have multiple modules. Each one takes care of a different area or approach towards
image processing. You could already observe this in the structure of the user guide of these
tutorials itself. Before you use any of them you first need to include the header files where the
content of each individual module is declared.
You'll almost always end up using the:
- @ref core "core" section, as here are defined the basic building blocks of the library
- @ref imgcodecs "imgcodecs" module, which provides functions for reading and writing
- @ref highgui "highgui" module, as this contains the functions to show an image in a window
We also include the *iostream* to facilitate console line output and input.
By declaring `using namespace cv;`, in the following, the library functions can be accessed without explicitly stating the namespace.
@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp includes
@end_toggle
@add_toggle_python
As a first step, the OpenCV python library is imported.
The proper way to do this is to additionally assign it the name *cv*, which is used in the following to reference the library.
@snippet samples/python/tutorial_code/introduction/display_image/display_image.py imports
@end_toggle
Now, let's analyze the main code.
As a first step, we read the image "starry_night.jpg" from the OpenCV samples.
In order to do so, a call to the @ref cv::imread function loads the image using the file path specified by the first argument.
The second argument is optional and specifies the format in which we want the image. This may be:
- IMREAD_COLOR loads the image in the BGR 8-bit format. This is the **default** that is used here.
- IMREAD_UNCHANGED loads the image as is (including the alpha channel if present)
- IMREAD_GRAYSCALE loads the image as an intensity one
After reading in the image data will be stored in a @ref cv::Mat object.
@add_toggle_cpp
@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imread
@end_toggle
@add_toggle_python
@snippet samples/python/tutorial_code/introduction/display_image/display_image.py imread
@end_toggle
@note
OpenCV offers support for the image formats Windows bitmap (bmp), portable image formats (pbm,
pgm, ppm) and Sun raster (sr, ras). With help of plugins (you need to specify to use them if you
build yourself the library, nevertheless in the packages we ship present by default) you may
also load image formats like JPEG (jpeg, jpg, jpe), JPEG 2000 (jp2 - codenamed in the CMake as
Jasper), TIFF files (tiff, tif) and portable network graphics (png). Furthermore, OpenEXR is
also a possibility.
Afterwards, a check is executed, if the image was loaded correctly.
@add_toggle_cpp
@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp empty
@end_toggle
@add_toggle_python
@snippet samples/python/tutorial_code/introduction/display_image/display_image.py empty
@end_toggle
Then, the image is shown using a call to the @ref cv::imshow function.
The first argument is the title of the window and the second argument is the @ref cv::Mat object that will be shown.
Because we want our window to be displayed until the user presses a key (otherwise the program would
end far too quickly), we use the @ref cv::waitKey function whose only parameter is just how long
should it wait for a user input (measured in milliseconds). Zero means to wait forever.
The return value is the key that was pressed.
@add_toggle_cpp
@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imshow
@end_toggle
@add_toggle_python
@snippet samples/python/tutorial_code/introduction/display_image/display_image.py imshow
@end_toggle
In the end, the image is written to a file if the pressed key was the "s"-key.
For this the cv::imwrite function is called that has the file path and the cv::Mat object as an argument.
@add_toggle_cpp
@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imsave
@end_toggle
@add_toggle_python
@snippet samples/python/tutorial_code/introduction/display_image/display_image.py imsave
@end_toggle
doc/tutorials/introduction/documenting_opencv/documentation_tutorial.markdown
+695
View File
@@ -0,0 +1,695 @@
Writing documentation for OpenCV {#tutorial_documentation}
================================
@prev_tutorial{tutorial_display_image}
@next_tutorial{tutorial_transition_guide}
| | |
| -: | :- |
| Original author | Maksim Shabunin |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
Doxygen overview {#tutorial_documentation_overview}
================
Intro {#tutorial_documentation_intro}
-----
[Doxygen] is documentation generation system with a lot of great features, such as:
- parse program sources to produce actual and accurate documentation
- check documentation for errors
- insert images and formulas
- use markdown syntax and plain HTML for precise text formatting
- generate documentation in many different formats
OpenCV library existing documentation has been converted to doxygen format.
Installation {#tutorial_documentation_install}
------------
Please, check official [download][Doxygen download] and [installation][Doxygen installation] pages.
Some linux distributions can also provide doxygen packages.
Generate documentation {#tutorial_documentation_generate}
----------------------
- Get the OpenCV sources (version 3.0 and later)
- _Optional:_ get the OpenCV_contrib sources
- Create build directory near the sources folder(s) and go into it
- Run cmake (assuming you put sources to _opencv_ folder):
@code{.sh}
cmake -DBUILD_DOCS=ON ../opencv
@endcode
Or if you get contrib sources too:
@code{.sh}
cmake -DBUILD_DOCS=ON -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv
@endcode
- Run make:
@code{.sh}
make doxygen
@endcode
- Open <i>doc/doxygen/html/index.html</i> file in your favorite browser
- Test your Python code:
@code{.sh}
make check_pylint
@endcode
@note [Pylint](https://www.pylint.org/#install) must be installed before running cmake to be
able to test Python code. You can install using your system's package manager, or with pip:
@code{.sh} pip install pylint @endcode
Quick start {#tutorial_documentation_quick_start}
===========
@note These instructions are specific to OpenCV library documentation, other projects can use
different layout scheme and documenting agreements.
Documentation locations {#tutorial_documentation_quick_start_1}
-----------------------
Whole documentation is gathered from many different places:
- __source code__ entities, like classes, functions or enumerations, should be documented in
corresponding header files, right prior entity definition. See examples in next sections.
- __pages__ are good place to put big pieces of text with images and code examples not directly
connected with any source code entity. Pages should be located in separate files and
contained in several predefined places. This tutorial is example of such page.
- __images__ can be used to illustrate described things. Usually located at the same places as pages,
images can be inserted to any place of the documentation.
- __code examples__ show how to use the library in real applications. Each sample is
self-contained file which represents one simple application. Parts of these files can be
included into documentation and tutorials to demonstrate function calls and objects collaboration.
- __BibTeX references__ are used to create one common bibliography. All science books, articles and
proceedings served as basis for library functionality should be put in this reference list.
Following scheme represents common documentation places for _opencv_ repository:
~~~
<opencv>
├── doc - doxygen config files, root page (root.markdown.in), BibTeX file (opencv.bib)
│   ├── tutorials - tutorials hierarchy (pages and images)
│   └── py_tutorials - python tutorials hierarchy (pages and images)
├── modules
│   └── <modulename>
│      ├── doc - documentation pages and images for module
│      └── include - code documentation in header files
└── samples - place for all code examples
├── cpp
│ └── tutorial_code - place for tutorial code examples
└── ...
~~~
@note Automatic code parser looks for all header files (<i>".h, .hpp"</i> except for <i>".inl.hpp;
.impl.hpp; _detail.hpp"</i>) in _include_ folder and its subfolders. Some module-specific
instructions (group definitions) and documentation should be put into
<i>"include/opencv2/<module-name>.hpp"</i> file.
@note You can put C++ template implementation and specialization to separate files
(<i>".impl.hpp"</i>) ignored by doxygen.
@note Files in _src_ subfolder are not parsed, because documentation is intended mostly for the
library users, not developers. But it still is possible to generate full documentation by
customizing processed files list in cmake script (<i>doc/CMakeLists.txt</i>) and doxygen options in
its configuration file (<i>doc/Doxyfile.in</i>).
Since version 3.0 all new modules are placed into _opencv_contrib_ repository, it has slightly
different layout:
~~~
<opencv_contrib>
└── modules
└── <modulename>
├── doc - documentation pages and images, BibTeX file (<modulename>.bib)
├── include - code documentation in header files
├── samples - place for code examples for documentation and tutorials
└── tutorials - tutorial pages and images
~~~
Example {#tutorial_documentation_quick_start_2}
-------
To add documentation for functions, classes and other entities, just insert special comment prior
its definition. Like this:
@verbatim
/** @brief Calculates the exponent of every array element.
The function exp calculates the exponent of every element of the input array:
\f[ \texttt{dst} [I] = e^{ src(I) } \f]
The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for
double-precision input. Currently, the function converts denormalized values to zeros on output.
Special values (NaN, Inf) are not handled.
@param src input array.
@param dst output array of the same size and type as src.
@sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
*/
CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
@endverbatim
Here you can see:
- special C-comment syntax denotes it is doxygen comment
@verbatim /** ... */ @endverbatim
- command `brief` denotes following paragraph is a brief description
@verbatim @brief @endverbatim
- empty line denotes paragraph end
- TeX formula between `f[` and `f]` commands
@verbatim \f[ ... \f] @endverbatim
- command `param` denotes following word is name of the parameter and following text is
description of the parameter; all parameters are placed in a list
@verbatim @param @endverbatim
- command `sa` starts "See also" paragraph containing references to some classes, methods, pages or URLs.
@verbatim @sa @endverbatim
Produced reference item looks like this:
![Reference link](doxygen-2.png)
The "More..." link brings you to the function documentation:
![Function documentation](doxygen-1.png)
Another example {#tutorial_documentation_quick_start_3}
---------------
Different comment syntax can be used for one-line short comments:
@verbatim
//! type of line
enum LineTypes {
FILLED = -1,
LINE_4 = 4, //!< 4-connected line
LINE_8 = 8, //!< 8-connected line
LINE_AA = 16 //!< antialiased line
};
@endverbatim
Here:
- special C++-comment syntax denotes it is doxygen comment
@verbatim //! @endverbatim
- additional symbol `<` denotes this comment is located _after_ documented entity
@verbatim //!< @endverbatim
Produced documentation block looks like this:
![Enumeration documentation](doxygen-3.png)
More details {#tutorial_documentation_quick_start_4}
------------
### Command prefix
Doxygen commands starts with `@` or `\` sign:
@verbatim
@brief ...
or
\brief ...
@endverbatim
### Comment syntax
Doxygen comment can have different forms:
@verbatim
C-style:
/** ... */
or
/*! ... */
C++-style
//! ...
or
/// ...
Lines can start with '*':
/**
* ...
* ...
*/
Can be placed after documented entity:
//!< ...
/**< ... */
@endverbatim
### Paragraph end
To end paragraph, insert empty line or any command starting new paragraph:
@verbatim
@brief brief description paragraph
brief continues
new paragraph
@note new note paragraph
note paragraph continues
another paragraph
paragraph continues
@endverbatim
### Naming
Pages, anchors, groups and other named entities should have unique name inside the whole project.
It is a good idea to prefix such identifiers with module name:
@verbatim
@page core_explanation_1 Usage explanation
@defgroup imgproc_transform Image transformations
@anchor mymodule_interesting_note
@endverbatim
Supported Markdown {#tutorial_documentation_quick_start_md}
------------------
Doxygen supports Markdown formatting with some extensions. Short syntax reference is described
below, for details visit [Markdown support].
### lists {#tutorial_documentation_md_list}
@verbatim
Bulleted:
- item1
- item2
Numbered:
1. item1
2. item2
or
-# item1
-# item2
@endverbatim
### emphasis {#tutorial_documentation_md_emph}
@verbatim
_italic_
__bold__
use html in complex cases:
<em>"path/to/file"</em>
@endverbatim
### links {#tutorial_documentation_md_links}
@verbatim
explicit link:
[OpenCV main site](http://opencv.org)
automatic links:
<http://opencv.org>
or even:
http://opencv.org
@endverbatim
### images {#tutorial_documentation_md_image}
@verbatim
![image caption](image path)
@endverbatim
### headers {#tutorial_documentation_md_head}
@verbatim
Level1
======
Level2
------
### Level3
#### Level4
@endverbatim
### header id {#tutorial_documentation_md_headid}
You can assign a unique identifier to any header to reference it from other places.
@verbatim
Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details
@endverbatim
### page id {#tutorial_documentation_md_page}
Each page should have additional Level1 header at the beginning with page title and identifier:
@verbatim
Writing documentation for OpenCV {#tutorial_documentation}
================================
@endverbatim
### tables {#tutorial_documentation_md_table}
Example from doxygen documentation:
@verbatim
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
@endverbatim
Commonly used commands {#tutorial_documentation_quick_start_5}
----------------------
Most often used doxygen commands are described here with short examples. For the full list of
available commands and detailed description, please visit [Command reference].
### Basic commands {#tutorial_documentation_commands_basic}
- __brief__ - paragraph with brief entity description
- __param__ - description of function argument.
Multiple adjacent statements are merged into one list. If argument with this name is not found
in actual function signature - doxygen warning will be produced. Function can have either _no_
documented parameters, either _all_ should be documented.
- __sa__ - "See also" paragraph, contains references to classes, functions, pages or URLs
- __note__ - visually highlighted "Note" paragraph. Multiple adjacent statements are merged into
one block.
- __return, returns__ - describes returned value of a function
- __overload__ - adds fixed text to the function description: <em>"This is an overloaded member
function, provided for convenience. It differs from the above function only in what argument(s)
it accepts."</em>
- __anchor__ - places invisible named anchor, which can be referenced by `ref` command. It can be
used in pages only.
- __ref__ - explicit reference to a named section, page or anchor.
If such entity can not be found - doxygen warning will be generated. This command has an
optional argument - link text.
Doxygen also generates some links automatically: if text contains word which can be found in
documented entities - reference will be generated. This functionality can be disabled by prefixing
the word with `%` symbol.
@verbatim
Explicit reference: @ref MyClass
Explicit named reference: @ref example_page "Example page"
Implicit reference: cv::abc::MyClass1 or just MyClass1
Disable implicit reference: %MyClass1
@endverbatim
- __f__ - formula
Inline formulas are bounded with `f$` command:
@verbatim
\f$ ... \f$
@endverbatim
Block formulas - with `f[` and `f]` commands:
@verbatim
\f[ ... \f]
@endverbatim
### Code inclusion commands {#tutorial_documentation_commands_include}
To mark some text as a code in documentation, _code_ and _endcode_ commands are used.
@verbatim
@code
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode
@endverbatim
Syntax will be highlighted according to the currently parsed file type (C++ for <em>.hpp</em>, C for <em>.h</em>) or
you can manually specify it in curly braces:
@verbatim
@code{.xml}
@endverbatim
To include whole example file into documentation, _include_ and _includelineno_ commands are used.
The file is searched in common samples locations, so you can specify just its name or short part of
the path. The _includelineno_ version also shows line numbers but prevents copy-pasting since
the line numbers are included.
@verbatim
@include samples/cpp/test.cpp
@endverbatim
If you want to include some parts of existing example file - use _snippet_ command.
First, mark the needed parts of the file with special doxygen comments:
@verbatim
//! [var_init]
int a = 0;
//! [var_init]
@endverbatim
Then include this snippet into documentation:
@verbatim
@snippet samples/cpp/test.cpp var_init
@endverbatim
@note Currently most of such partial inclusions are made with _dontinclude_ command for
compatibility with the old rST documentation. But newly created samples should be included with the
_snippet_ command, since this method is less affected by the changes in processed file.
### Toggle buttons inclusion commands {#tutorial_documentation_toggle_buttons_commands_include}
Toggle buttons are used to display the selected configuration (e.g. programming language, OS, IDE).
To use the buttons in documentation, _add_toggle_ and _end_toggle_ commands are used.
The command _add_toggle_ can be
- general: _add_toggle{Button Name}_
- for C++: _add_toggle_cpp_
- for Java: _add_toggle_java_
- for Python: _add_toggle_python_
Example:
@verbatim
@add_toggle{Button Name}
text / code / doxygen commands
@end_toggle
@endverbatim
For example using toggle buttons with text and [code](@ref tutorial_documentation_commands_include) snippets:
@verbatim
### Buttons Example
@add_toggle_cpp
Text for C++ button
@snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world
@end_toggle
@add_toggle_java
Text for Java button
@snippet samples/java/tutorial_code/introduction/documentation/Documentation.java hello_world
@end_toggle
@add_toggle_python
Text for Python button
@snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world
@end_toggle
@endverbatim
Result looks like this:
### Buttons Example
@add_toggle_cpp
Text for C++ button
@snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world
@end_toggle
@add_toggle_java
Text for Java button
@snippet samples/java/tutorial_code/introduction/documentation/Documentation.java hello_world
@end_toggle
@add_toggle_python
Text for Python button
@snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world
@end_toggle
As you can see, the buttons are added automatically under the previous heading.
### Grouping commands {#tutorial_documentation_commands_group}
All code entities should be put into named groups representing OpenCV modules and their internal
structure, thus each module should be associated with a group with the same name. Good place to
define groups and subgroups is the main header file for this module:
<em>"<module>/include/opencv2/<module>.hpp"</em>.
@note Doxygen groups are called "modules" and are shown on "Modules" page.
@verbatim
/**
@defgroup mymodule My great module
optional description
@{
@defgroup mymodule_basic Basic operations
optional description
@defgroup mymodule_experimental Experimental operations
optional description
@}
*/
@endverbatim
To put classes and functions into specific group, just add `ingroup` command to its documentation,
or wrap the whole code block with `addtogroup` command:
@verbatim
/** @brief Example function
@ingroup mymodule
*/
or
/**
@addtogroup mymodule_experimental
@{
*/
... several functions, classes or enumerations here
/**
@}
*/
@endverbatim
### Publication reference {#tutorial_documentation_commands_cite}
Use _cite_ command to insert reference to related publications listed in @ref citelist page.
First, add publication BibTeX record into <i>"<opencv>/doc/opencv.bib"</i> or
<i>"<opencv_contrib>/modules/<module>/doc/<module>.bib"</i> file:
@verbatim
@ARTICLE{Bradski98,
author = {Bradski, Gary R},
title = {Computer vision face tracking for use in a perceptual user interface},
year = {1998},
publisher = {Citeseer}
}
@endverbatim
@note Try not to add publication duplicates because it can confuse documentation readers and writers later.
Then make reference with _cite_ command:
@verbatim
@cite Bradski98
@endverbatim
@note To get BibTeX record for the publications one can use [Google Scholar]. Once the publication
have been found - follow its "Cite" link and then choose "BibTeX" option:
![](scholarship_cite_dialog.png)
Step-by-step {#tutorial_documentation_steps}
============
Steps described in this section can be used as checklist during documentation writing. It is not
necessary to do things in the same order, but some steps really depend on previous. And of course
these steps are just basic guidelines, there is always a place for creativity.
Document the function {#tutorial_documentation_steps_fun}
---------------------
1. Add empty doxygen comment preceding function definition.
2. Add _brief_ command with short description of function meaning at the beginning.
3. Add detailed description of the function.
4. _Optional_: insert formulas, images and blocks of example code to illustrate complex cases
5. _Optional_: describe each parameter using the _param_ command.
6. _Optional_: describe return value of the function using the _returns_ command.
7. _Optional_: add "See also" section with links to similar functions or classes
8. _Optional_: add bibliographic reference if any.
9. Test your code. (Python: "make check_pylint")
10. Generate doxygen documentation and verify results.
Write the tutorial {#tutorial_documentation_steps_tutorial}
------------------
1. Formulate the idea to be illustrated in the tutorial.
2. Make the example application, simple enough to be understood by a beginning developer. Be
laconic and write descriptive comments, don't try to avoid every possible runtime error or to make
universal utility. Your goal is to illustrate the idea. And it should fit one source file!
If you want to insert code blocks from this file into your tutorial, mark them with special doxygen comments (see [here](@ref tutorial_documentation_commands_include)).
If you want to write the tutorial in more than one programming language, use the toggle buttons for alternative comments and code (see [here](@ref tutorial_documentation_toggle_buttons_commands_include)).
3. Collect results of the application work. It can be "before/after" images or some numbers
representing performance or even a video.
Save it in appropriate format for later use in the tutorial:
- To save simple graph-like images use lossless ".png" format.
- For photo-like images - lossy ".jpg" format.
- Numbers will be inserted as plain text, possibly formatted as table.
- Video should be uploaded on YouTube.
4. Create new tutorial page (<em>".markdown"</em>-file) in corresponding location (see
[here](@ref tutorial_documentation_quick_start_1)), and place all image files near it (or in "images"
subdirectory). Also put your example application file and make sure it is compiled together with the
OpenCV library when `-DBUILD_EXAMPLES=ON` option is enabled on cmake step.
5. Modify your new page:
- Add page title and identifier, usually prefixed with <em>"tutorial_"</em> (see [here](@ref tutorial_documentation_md_page)).
You can add a link to the previous and next tutorial using the identifier
@verbatim
@prev_tutorial{identifier}
@next_tutorial{identifier}
@endverbatim
@warning Do **not** write the **hashtag (#)**, example: \n Incorrect: @verbatim @prev_tutorial{#tutorial_documentation} @endverbatim Correct: @verbatim @prev_tutorial{tutorial_documentation} @endverbatim
- Add brief description of your idea and tutorial goals.
- Describe your program and/or its interesting pieces.
- Describe your results, insert previously added images or other results.
To add a youtube video, e.g. www.youtube.com/watch?v= **ViPN810E0SU**, use _youtube_{**Video ID**}:
@verbatim
@youtube{ViPN810E0SU}
@endverbatim
- Add bibliographic references if any (see [here](@ref tutorial_documentation_commands_cite)).
6. Add newly created tutorial to the corresponding table of contents. Just find
<em>"table_of_content_*.markdown"</em> file with the needed table and place new record in it
similar to existing ones.
It is simply a list item with special _subpage_ command which marks your page as a
child and places it into the existing pages hierarchy. Also note the list item indent, empty lines between
paragraphs and special _italic_ markers.
7. Generate doxygen documentation and verify results.
References {#tutorial_documentation_refs}
==========
- [Doxygen] - main Doxygen page
- [Documenting basics] - how to include documentation in code
- [Markdown support] - supported syntax and extensions
- [Formulas support] - how to include formulas
- [Supported formula commands] - HTML formulas use MathJax script for rendering
- [Command reference] - supported commands and their parameters
<!-- invisible references list -->
[Doxygen]: http://www.doxygen.nl
[Doxygen download]: http://doxygen.nl/download.html
[Doxygen installation]: http://doxygen.nl/manual/install.html
[Documenting basics]: http://www.doxygen.nl/manual/docblocks.html
[Markdown support]: http://www.doxygen.nl/manual/markdown.html
[Formulas support]: http://www.doxygen.nl/manual/formulas.html
[Supported formula commands]: http://docs.mathjax.org/en/latest/input/tex/macros/index.html
[Command reference]: http://www.doxygen.nl/manual/commands.html
[Google Scholar]: http://scholar.google.ru/
doc/tutorials/introduction/documenting_opencv/doxygen-1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

doc/tutorials/introduction/documenting_opencv/doxygen-2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.8 KiB

doc/tutorials/introduction/documenting_opencv/doxygen-3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

doc/tutorials/introduction/documenting_opencv/scholarship_cite_dialog.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

doc/tutorials/introduction/env_reference/env_reference.markdown
+358
View File
@@ -0,0 +1,358 @@
OpenCV environment variables reference {#tutorial_env_reference}
======================================
@prev_tutorial{tutorial_config_reference}
@next_tutorial{tutorial_linux_install}
@tableofcontents
## Introduction
OpenCV can change its behavior depending on the runtime environment:
- enable extra debugging output or performance tracing
- modify default locations and search paths
- tune some algorithms or general behavior
- enable or disable workarounds, safety features and optimizations
**Notes:**
- ⭐ marks most popular variables
- variables with names like this `VAR_${NAME}` describes family of variables, where `${NAME}` should be changed to one of predefined values, e.g. `VAR_TBB`, `VAR_OPENMP`, ...
### Setting environment variable in Windows
In terminal or cmd-file (bat-file):
```.bat
set MY_ENV_VARIABLE=true
C:\my_app.exe
```
In GUI:
- Go to "Settings -> System -> About"
- Click on "Advanced system settings" in the right part
- In new window click on the "Environment variables" button
- Add an entry to the "User variables" list
### Setting environment variable in Linux
In terminal or shell script:
```.sh
export MY_ENV_VARIABLE=true
./my_app
```
or as a single command:
```.sh
MY_ENV_VARIABLE=true ./my_app
```
### Setting environment variable in Python
```.py
import os
os.environ["MY_ENV_VARIABLE"] = "True" # value must be a string
import cv2 # variables set after this may not have effect
```
@note This method may not work on all operating systems and/or Python distributions. For example, it works on Ubuntu Linux with system Python interpreter, but doesn't work on Windows 10 with the official Python package. It depends on the ability of a process to change its own environment (OpenCV uses `getenv` from C++ runtime to read variables).
@note See also:
- https://docs.python.org/3.12/library/os.html#os.environ
- https://stackoverflow.com/questions/69199708/setenvironmentvariable-does-not-seem-to-set-values-that-can-be-retrieved-by-ge
## Types
- _bool_ - `1`, `True`, `true`, `TRUE` / `0`, `False`, `false`, `FALSE`
- _number_/_size_ - unsigned number, suffixes `MB`, `Mb`, `mb`, `KB`, `Kb`, `kb`
- _string_ - plain string or can have a structure
- _path_ - to file, to directory
- _paths_ - `;`-separated on Windows, `:`-separated on others
## General, core
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_SKIP_CPU_BASELINE_CHECK | bool | false | do not check that current CPU supports all features used by the build (baseline) |
| OPENCV_CPU_DISABLE | `,` or `;`-separated | | disable code branches which use CPU features (dispatched code) |
| OPENCV_SETUP_TERMINATE_HANDLER | bool | true (Windows) | use std::set_terminate to install own termination handler |
| OPENCV_LIBVA_RUNTIME | file path | | libva for VA interoperability utils |
| OPENCV_ENABLE_MEMALIGN | bool | true (except static analysis, memory sanitizer, fuzzying, _WIN32?) | enable aligned memory allocations |
| OPENCV_BUFFER_AREA_ALWAYS_SAFE | bool | false | enable safe mode for multi-buffer allocations (each buffer separately) |
| OPENCV_KMEANS_PARALLEL_GRANULARITY | num | 1000 | tune algorithm parallel work distribution parameter `parallel_for_(..., ..., ..., granularity)` |
| OPENCV_DUMP_ERRORS | bool | true (Debug or Android), false (others) | print extra information on exception (log to Android) |
| OPENCV_DUMP_CONFIG | bool | false | print build configuration to stderr (`getBuildInformation`) |
| OPENCV_PYTHON_DEBUG | bool | false | enable extra warnings in Python bindings |
| OPENCV_TEMP_PATH | path | `/tmp/` (Linux), `/data/local/tmp/` (Android), `GetTempPathA` (Windows) | directory for temporary files |
| OPENCV_DATA_PATH_HINT | paths | | paths for findDataFile |
| OPENCV_DATA_PATH | paths | | paths for findDataFile |
| OPENCV_SAMPLES_DATA_PATH_HINT | paths | | paths for findDataFile |
| OPENCV_SAMPLES_DATA_PATH | paths | | paths for findDataFile |
Links:
- https://github.com/opencv/opencv/wiki/CPU-optimizations-build-options
## Logging
| name | type | default | description |
|------|------|---------|-------------|
| ⭐ OPENCV_LOG_LEVEL | string | | logging level (see accepted values below) |
| OPENCV_LOG_TIMESTAMP | bool | true | logging with timestamps |
| OPENCV_LOG_TIMESTAMP_NS | bool | false | add nsec to logging timestamps |
### Levels
- `0`, `O`, `OFF`, `S`, `SILENT`, `DISABLE`, `DISABLED`
- `F`, `FATAL`
- `E`, `ERROR`
- `W`, `WARNING`, `WARN`, `WARNINGS`
- `I`, `INFO`
- `D`, `DEBUG`
- `V`, `VERBOSE`
## core/parallel_for
| name | type | default | description |
|------|------|---------|-------------|
| ⭐ OPENCV_FOR_THREADS_NUM | num | 0 | set number of threads |
| OPENCV_THREAD_POOL_ACTIVE_WAIT_PAUSE_LIMIT | num | 16 | tune pthreads parallel_for backend |
| OPENCV_THREAD_POOL_ACTIVE_WAIT_WORKER | num | 2000 | tune pthreads parallel_for backend |
| OPENCV_THREAD_POOL_ACTIVE_WAIT_MAIN | num | 10000 | tune pthreads parallel_for backend |
| OPENCV_THREAD_POOL_ACTIVE_WAIT_THREADS_LIMIT | num | 0 | tune pthreads parallel_for backend |
| OPENCV_FOR_OPENMP_DYNAMIC_DISABLE | bool | false | Removed in 4.13.0. Use standard [OMP_DYNAMIC](https://www.openmp.org/spec-html/5.0/openmpsu116.html) instead |
## backends
OPENCV_LEGACY_WAITKEY
Some modules have multiple available backends, following variables allow choosing specific backend or changing default priorities in which backends will be probed (e.g. when opening a video file).
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_PARALLEL_BACKEND | string | | choose specific paralel_for backend (one of `TBB`, `ONETBB`, `OPENMP`) |
| OPENCV_PARALLEL_PRIORITY_${NAME} | num | | set backend priority, default is 1000 |
| OPENCV_PARALLEL_PRIORITY_LIST | string, `,`-separated | | list of backends in priority order |
| OPENCV_UI_BACKEND | string | | choose highgui backend for window rendering (one of `GTK`, `GTK3`, `GTK2`, `QT`, `WIN32`) |
| OPENCV_UI_PRIORITY_${NAME} | num | | set highgui backend priority, default is 1000 |
| OPENCV_UI_PRIORITY_LIST | string, `,`-separated | | list of highgui backends in priority order |
| OPENCV_VIDEOIO_PRIORITY_${NAME} | num | | set videoio backend priority, default is 1000 |
| OPENCV_VIDEOIO_PRIORITY_LIST | string, `,`-separated | | list of videoio backends in priority order |
## plugins
Some external dependencies can be detached into a dynamic library, which will be loaded at runtime (plugin). Following variables allow changing default search locations and naming pattern for these plugins.
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_CORE_PLUGIN_PATH | paths | | directories to search for _core_ plugins |
| OPENCV_CORE_PARALLEL_PLUGIN_${NAME} | string, glob | | parallel_for plugin library name (glob), e.g. default for TBB is "opencv_core_parallel_tbb*.so" |
| OPENCV_DNN_PLUGIN_PATH | paths | | directories to search for _dnn_ plugins |
| OPENCV_DNN_PLUGIN_${NAME} | string, glob | | parallel_for plugin library name (glob), e.g. default for TBB is "opencv_core_parallel_tbb*.so" |
| OPENCV_CORE_PLUGIN_PATH | paths | | directories to search for _highgui_ plugins (YES it is CORE) |
| OPENCV_UI_PLUGIN_${NAME} | string, glob | | _highgui_ plugin library name (glob) |
| OPENCV_VIDEOIO_PLUGIN_PATH | paths | | directories to search for _videoio_ plugins |
| OPENCV_VIDEOIO_PLUGIN_${NAME} | string, glob | | _videoio_ plugin library name (glob) |
## OpenCL
**Note:** OpenCL device specification format is `<Platform>:<CPU|GPU|ACCELERATOR|nothing=GPU/CPU>:<deviceName>`, e.g. `AMD:GPU:`
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_OPENCL_RUNTIME | filepath or `disabled` | | path to OpenCL runtime library (e.g. `OpenCL.dll`, `libOpenCL.so`) |
| ⭐ OPENCV_OPENCL_DEVICE | string or `disabled` | | choose specific OpenCL device. See specification format in the note above. See more details in the Links section. |
| OPENCV_OPENCL_RAISE_ERROR | bool | false | raise exception if something fails during OpenCL kernel preparation and execution (Release builds only) |
| OPENCV_OPENCL_ABORT_ON_BUILD_ERROR | bool | false | abort if OpenCL kernel compilation failed |
| OPENCV_OPENCL_CACHE_ENABLE | bool | true | enable OpenCL kernel cache |
| OPENCV_OPENCL_CACHE_WRITE | bool | true | allow writing to the cache, otherwise cache will be read-only |
| OPENCV_OPENCL_CACHE_LOCK_ENABLE | bool | true | use .lock files to synchronize between multiple applications using the same OpenCL cache (may not work on network drives) |
| OPENCV_OPENCL_CACHE_CLEANUP | bool | true | automatically remove old entries from cache (leftovers from older OpenCL runtimes) |
| OPENCV_OPENCL_VALIDATE_BINARY_PROGRAMS | bool | false | validate loaded binary OpenCL kernels |
| OPENCV_OPENCL_DISABLE_BUFFER_RECT_OPERATIONS | bool | true (Apple), false (others) | enable workaround for non-continuos data downloads |
| OPENCV_OPENCL_BUILD_EXTRA_OPTIONS | string | | pass extra options to OpenCL kernel compilation |
| OPENCV_OPENCL_ENABLE_MEM_USE_HOST_PTR | bool | true | workaround/optimization for buffer allocation |
| OPENCV_OPENCL_ALIGNMENT_MEM_USE_HOST_PTR | num | 4 | parameter for OPENCV_OPENCL_ENABLE_MEM_USE_HOST_PTR |
| OPENCV_OPENCL_DEVICE_MAX_WORK_GROUP_SIZE | num | 0 | allow to decrease maxWorkGroupSize |
| OPENCV_OPENCL_PROGRAM_CACHE | num | 0 | limit number of programs in OpenCL kernel cache |
| OPENCV_OPENCL_RAISE_ERROR_REUSE_ASYNC_KERNEL | bool | false | raise exception if async kernel failed |
| OPENCV_OPENCL_BUFFERPOOL_LIMIT | num | 1 << 27 (Intel device), 0 (others) | limit memory used by buffer bool |
| OPENCV_OPENCL_HOST_PTR_BUFFERPOOL_LIMIT | num | | same as OPENCV_OPENCL_BUFFERPOOL_LIMIT, but for HOST_PTR buffers |
| OPENCV_OPENCL_BUFFER_FORCE_MAPPING | bool | false | force clEnqueueMapBuffer |
| OPENCV_OPENCL_BUFFER_FORCE_COPYING | bool | false | force clEnqueueReadBuffer/clEnqueueWriteBuffer |
| OPENCV_OPENCL_FORCE | bool | false | force running OpenCL kernel even if usual conditions are not met (e.g. dst.isUMat) |
| OPENCV_OPENCL_PERF_CHECK_BYPASS | bool | false | force running OpenCL kernel even if usual performance-related conditions are not met (e.g. image is very small) |
### SVM (Shared Virtual Memory) - disabled by default
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_OPENCL_SVM_DISABLE | bool | false | disable SVM |
| OPENCV_OPENCL_SVM_FORCE_UMAT_USAGE | bool | false | |
| OPENCV_OPENCL_SVM_DISABLE_UMAT_USAGE | bool | false | |
| OPENCV_OPENCL_SVM_CAPABILITIES_MASK | num | | |
| OPENCV_OPENCL_SVM_BUFFERPOOL_LIMIT | num | | same as OPENCV_OPENCL_BUFFERPOOL_LIMIT, but for SVM buffers |
### Links:
- https://github.com/opencv/opencv/wiki/OpenCL-optimizations
## Tracing/Profiling
| name | type | default | description |
|------|------|---------|-------------|
| ⭐ OPENCV_TRACE | bool | false | enable trace |
| OPENCV_TRACE_LOCATION | string | `OpenCVTrace` | trace file name ("${name}-$03d.txt") |
| OPENCV_TRACE_DEPTH_OPENCV | num | 1 | |
| OPENCV_TRACE_MAX_CHILDREN_OPENCV | num | 1000 | |
| OPENCV_TRACE_MAX_CHILDREN | num | 1000 | |
| OPENCV_TRACE_SYNC_OPENCL | bool | false | wait for OpenCL kernels to finish |
| OPENCV_TRACE_ITT_ENABLE | bool | true | |
| OPENCV_TRACE_ITT_PARENT | bool | false | set parentID for ITT task |
| OPENCV_TRACE_ITT_SET_THREAD_NAME | bool | false | set name for OpenCV's threads "OpenCVThread-%03d" |
### Links:
- https://github.com/opencv/opencv/wiki/Profiling-OpenCV-Applications
## Cache
**Note:** Default tmp location is `%TMPDIR%` (Windows); `$XDG_CACHE_HOME`, `$HOME/.cache`, `/var/tmp`, `/tmp` (others)
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_CACHE_SHOW_CLEANUP_MESSAGE | bool | true | show cache cleanup message |
| OPENCV_DOWNLOAD_CACHE_DIR | path | default tmp location | cache directory for downloaded files (subdirectory `downloads`) |
| OPENCV_DNN_IE_GPU_CACHE_DIR | path | default tmp location | cache directory for OpenVINO OpenCL kernels (subdirectory `dnn_ie_cache_${device}`) |
| OPENCV_OPENCL_CACHE_DIR | path | default tmp location | cache directory for OpenCL kernels cache (subdirectory `opencl_cache`) |
## dnn
**Note:** In the table below `dump_base_name` equals to `ocv_dnn_net_%05d_%02d` where first argument is internal network ID and the second - dump level.
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_DNN_BACKEND_DEFAULT | num | 3 (OpenCV) | set default DNN backend, see dnn.hpp for backends enumeration |
| OPENCV_DNN_NETWORK_DUMP | num | 0 | level of information dumps, 0 - no dumps (default file name `${dump_base_name}.dot`) |
| OPENCV_DNN_DISABLE_MEMORY_OPTIMIZATIONS | bool | false | |
| OPENCV_DNN_CHECK_NAN_INF | bool | false | check for NaNs in layer outputs |
| OPENCV_DNN_CHECK_NAN_INF_DUMP | bool | false | print layer data when NaN check has failed |
| OPENCV_DNN_CHECK_NAN_INF_RAISE_ERROR | bool | false | also raise exception when NaN check has failed |
| OPENCV_DNN_ONNX_USE_LEGACY_NAMES | bool | false | use ONNX node names as-is instead of "onnx_node!${node_name}" |
| OPENCV_DNN_CUSTOM_ONNX_TYPE_INCLUDE_DOMAIN_NAME | bool | true | prepend layer domain to layer types ("domain.type") |
| OPENCV_VULKAN_RUNTIME | file path | | set location of Vulkan runtime library for DNN Vulkan backend |
| OPENCV_DNN_IE_SERIALIZE | bool | false | dump intermediate OpenVINO graph (default file names `${dump_base_name}_ngraph.xml`, `${dump_base_name}_ngraph.bin`) |
| OPENCV_DNN_IE_EXTRA_PLUGIN_PATH | path | | path to extra OpenVINO plugins |
| OPENCV_DNN_IE_VPU_TYPE | string | | Force using specific OpenVINO VPU device type ("Myriad2" or "MyriadX") |
| OPENCV_TEST_DNN_IE_VPU_TYPE | string | | same as OPENCV_DNN_IE_VPU_TYPE, but for tests |
| OPENCV_DNN_INFERENCE_ENGINE_HOLD_PLUGINS | bool | true | always hold one existing OpenVINO instance to avoid crashes on unloading |
| OPENCV_DNN_INFERENCE_ENGINE_CORE_LIFETIME_WORKAROUND | bool | true (Windows), false (other) | another OpenVINO lifetime workaround |
| OPENCV_DNN_OPENCL_ALLOW_ALL_DEVICES | bool | false | allow running on CPU devices, allow FP16 on non-Intel device |
| OPENCV_OCL4DNN_CONVOLUTION_IGNORE_INPUT_DIMS_4_CHECK | bool | false | workaround for OpenCL backend, see https://github.com/opencv/opencv/issues/20833 |
| OPENCV_OCL4DNN_WORKAROUND_IDLF | bool | true | another workaround for OpenCL backend |
| OPENCV_OCL4DNN_CONFIG_PATH | path | | path to kernel configuration cache for auto-tuning (must be existing directory), set this variable to enable auto-tuning |
| OPENCV_OCL4DNN_DISABLE_AUTO_TUNING | bool | false | disable auto-tuning |
| OPENCV_OCL4DNN_FORCE_AUTO_TUNING | bool | false | force auto-tuning |
| OPENCV_OCL4DNN_TEST_ALL_KERNELS | num | 0 | test convolution kernels, number of iterations (auto-tuning) |
| OPENCV_OCL4DNN_DUMP_FAILED_RESULT | bool | false | dump extra information on errors (auto-tuning) |
| OPENCV_OCL4DNN_TUNING_RAISE_CHECK_ERROR | bool | false | raise exception on errors (auto-tuning) |
## Tests
| name | type | default | description |
|------|------|---------|-------------|
| ⭐ OPENCV_TEST_DATA_PATH | dir path | | set test data search location (e.g. `/home/user/opencv_extra/testdata`) |
| ⭐ OPENCV_DNN_TEST_DATA_PATH | dir path | `$OPENCV_TEST_DATA_PATH/dnn` | set DNN model search location for tests (used by _dnn_, _gapi_, _objdetect_, _video_ modules) |
| OPENCV_OPEN_MODEL_ZOO_DATA_PATH | dir path | `$OPENCV_DNN_TEST_DATA_PATH/omz_intel_models` | set OpenVINO models search location for tests (used by _dnn_, _gapi_ modules) |
| INTEL_CVSDK_DIR | | | some _dnn_ tests can search OpenVINO models here too |
| OPENCV_TEST_DEBUG | num | 0 | debug level for tests, same as `--test_debug` (0 - no debug (default), 1 - basic test debug information, >1 - extra debug information) |
| OPENCV_TEST_REQUIRE_DATA | bool | false | same as `--test_require_data` option (fail on missing non-required test data instead of skip) |
| OPENCV_TEST_CHECK_OPTIONAL_DATA | bool | false | assert when optional data is not found |
| OPENCV_IPP_CHECK | bool | false | default value for `--test_ipp_check` and `--perf_ipp_check` |
| OPENCV_PERF_VALIDATION_DIR | dir path | | location of files read/written by `--perf_read_validation_results`/`--perf_write_validation_results` |
| ⭐ OPENCV_PYTEST_FILTER | string (glob) | | test filter for Python tests |
### Links:
* https://github.com/opencv/opencv/wiki/QA_in_OpenCV
## videoio
**Note:** extra FFmpeg options should be pased in form `key;value|key;value|key;value`, for example `hwaccel;cuvid|video_codec;h264_cuvid|vsync;0` or `vcodec;x264|vprofile;high|vlevel;4.0`
| name | type | default | description |
|------|------|---------|-------------|
| ⭐ OPENCV_FFMPEG_CAPTURE_OPTIONS | string (see note) | | extra options for VideoCapture FFmpeg backend |
| ⭐ OPENCV_FFMPEG_WRITER_OPTIONS | string (see note) | | extra options for VideoWriter FFmpeg backend |
| OPENCV_FFMPEG_THREADS | num | | set FFmpeg thread count |
| OPENCV_FFMPEG_DEBUG | bool | false | enable logging messages from FFmpeg |
| OPENCV_FFMPEG_LOGLEVEL | num | | set FFmpeg logging level |
| OPENCV_FFMPEG_SKIP_LOG_CALLBACK | bool | false | do not install OpenCV's FFmpeg log callback (preserve default/user callback) |
| OPENCV_FFMPEG_DLL_DIR | dir path | | directory with FFmpeg plugin (legacy) |
| OPENCV_FFMPEG_IS_THREAD_SAFE | bool | false | enabling this option will turn off thread safety locks in the FFmpeg backend (use only if you are sure FFmpeg is built with threading support, tested on Linux) |
| OPENCV_FFMPEG_READ_ATTEMPTS | num | 4096 | number of failed `av_read_frame` attempts before failing read procedure |
| OPENCV_FFMPEG_DECODE_ATTEMPTS | num | 64 | number of failed `avcodec_receive_frame` attempts before failing decoding procedure |
| OPENCV_VIDEOIO_GSTREAMER_CALL_DEINIT | bool | false | close GStreamer instance on end |
| OPENCV_VIDEOIO_GSTREAMER_START_MAINLOOP | bool | false | start GStreamer loop in separate thread |
| OPENCV_VIDEOIO_MFX_IMPL | num | | set specific MFX implementation (see MFX docs for enumeration) |
| OPENCV_VIDEOIO_MFX_EXTRA_SURFACE_NUM | num | 1 | add extra surfaces to the surface pool |
| OPENCV_VIDEOIO_MFX_POOL_TIMEOUT | num | 1 | timeout for waiting for free surface from the pool (in seconds) |
| OPENCV_VIDEOIO_MFX_BITRATE_DIVISOR | num | 300 | this option allows to tune encoding bitrate (video quality/size) |
| OPENCV_VIDEOIO_MFX_WRITER_TIMEOUT | num | 1 | timeout for encoding operation (in seconds) |
| OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS | bool | true | allow HW-accelerated transformations (DXVA) in MediaFoundation processing graph (may slow down camera probing process) |
| OPENCV_DSHOW_DEBUG | bool | false | enable verbose logging in the DShow backend |
| OPENCV_DSHOW_SAVEGRAPH_FILENAME | file path | | enable processing graph tump in the DShow backend |
| OPENCV_VIDEOIO_V4L_RANGE_NORMALIZED | bool | false | use (0, 1) range for properties (V4L) |
| OPENCV_VIDEOIO_V4L_SELECT_TIMEOUT | num | 10 | timeout for select call (in seconds) (V4L) |
| OPENCV_VIDEOCAPTURE_DEBUG | bool | false | enable debug messages for VideoCapture |
| OPENCV_VIDEOWRITER_DEBUG | bool | false | enable debug messages for VideoWriter |
| ⭐ OPENCV_VIDEOIO_DEBUG | bool | false | debug messages for both VideoCapture and VideoWriter |
### videoio tests
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_TEST_VIDEOIO_BACKEND_REQUIRE_FFMPEG | bool | false | test app will exit if no FFmpeg backend is available |
| OPENCV_TEST_V4L2_VIVID_DEVICE | file path | | path to VIVID virtual camera device for V4L2 test (e.g. `/dev/video5`) |
| OPENCV_TEST_PERF_CAMERA_LIST | paths | | cameras to use in performance test (waitAny_V4L test) |
| OPENCV_TEST_CAMERA_%d_FPS | num | | fps to set for N-th camera (0-based index) (waitAny_V4L test) |
## gapi
| name | type | default | description |
|------|------|---------|-------------|
| ⭐ GRAPH_DUMP_PATH | file path | | dump graph (dot format) |
| PIPELINE_MODELS_PATH | dir path | | pipeline_modeling_tool sample application uses this var |
| OPENCV_GAPI_INFERENCE_ENGINE_CORE_LIFETIME_WORKAROUND | bool | true (Windows, Apple), false (others) | similar to OPENCV_DNN_INFERENCE_ENGINE_CORE_LIFETIME_WORKAROUND |
### gapi tests/samples
| name | type | default | description |
|------|------|---------|-------------|
| PLAIDML_DEVICE | string | | specific to PlaidML backend test |
| PLAIDML_TARGET | string | | specific to PlaidML backend test |
| OPENCV_GAPI_ONNX_MODEL_PATH | dir path | | search location for ONNX models test |
| OPENCV_TEST_FREETYPE_FONT_PATH | file path | | location of TrueType font for one of tests |
### Links:
* https://github.com/opencv/opencv/wiki/Using-G-API-with-OpenVINO-Toolkit
* https://github.com/opencv/opencv/wiki/Using-G-API-with-MS-ONNX-Runtime
## highgui
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_LEGACY_WAITKEY | bool | false | switch `waitKey` return result (default behavior: `return code & 0xff` (or -1), legacy behavior: `return code`) |
| $XDG_RUNTIME_DIR | | | Wayland backend specific - create shared memory-mapped file for interprocess communication (named `opencv-shared-??????`) |
| OPENCV_HIGHGUI_FB_MODE | string | `FB` | Selects output mode for the framebuffer backend (`FB` - regular frambuffer, `EMU` - emulation, perform internal checks but does nothing, `XVFB` - compatible with _xvfb_ virtual frambuffer) |
| OPENCV_HIGHGUI_FB_DEVICE | file path | | Path to frambuffer device to use (will be checked first) |
| FRAMEBUFFER | file path | `/dev/fb0` | Same as OPENCV_HIGHGUI_FB_DEVICE, commonly used variable for the same purpose (will be checked second) |
## imgproc
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_OPENCL_IMGPROC_MORPH_SPECIAL_KERNEL | bool | true (Apple), false (others) | use special OpenCL kernel for small morph kernel (Intel devices) |
| OPENCV_GAUSSIANBLUR_CHECK_BITEXACT_KERNELS | bool | false | validate Gaussian kernels before running (src is CV_16U, bit-exact version) |
## imgcodecs
| name | type | default | description |
|------|------|---------|-------------|
| OPENCV_IMGCODECS_AVIF_MAX_FILE_SIZE | num | 64MB | limit input AVIF size |
| OPENCV_IMGCODECS_WEBP_MAX_FILE_SIZE | num | 64MB | limit input WEBM size |
| OPENCV_IO_MAX_IMAGE_PARAMS | num | 50 | limit maximum allowed number of parameters in imwrite and imencode |
| OPENCV_IO_MAX_IMAGE_WIDTH | num | 1 << 20, limit input image size to avoid large memory allocations | |
| OPENCV_IO_MAX_IMAGE_HEIGHT | num | 1 << 20 | |
| OPENCV_IO_MAX_IMAGE_PIXELS | num | 1 << 30 | |
| OPENCV_IO_ENABLE_OPENEXR | bool | true (set build option OPENCV_IO_FORCE_OPENEXR or use external OpenEXR), false (otherwise) | enable OpenEXR backend |
| OPENCV_IO_ENABLE_JASPER | bool | true (set build option OPENCV_IO_FORCE_JASPER), false (otherwise) | enable Jasper backend |
### Note
* OpenEXR support in OpenCV is optional. Source builds may include a bundled 3rdparty OpenEXR 2.3.0, but runtime support must be explicitly enabled via `OPENCV_IO_ENABLE_OPENEXR`. Users can also build OpenCV against a system-installed OpenEXR library.
* Support is disabled by default due to historical security considerations with malformed EXR files in older OpenEXR versions. Upgrading to OpenEXR 3.x is not a drop-in change and requires API and ABI adaptations.
doc/tutorials/introduction/general_install/general_install.markdown
+148
View File
@@ -0,0 +1,148 @@
OpenCV installation overview {#tutorial_general_install}
============================
@next_tutorial{tutorial_config_reference}
@tableofcontents
There are two ways of installing OpenCV on your machine: download prebuilt version for your platform or compile from sources.
# Prebuilt version {#tutorial_general_install_prebuilt}
In many cases you can find prebuilt version of OpenCV that will meet your needs.
## Packages by OpenCV core team {#tutorial_general_install_prebuilt_core}
Packages for Android, iOS and Windows built with default parameters and recent compilers are published for each release, they do not contain _opencv_contrib_ modules.
- GitHub releases: https://github.com/opencv/opencv/releases
- SourceForge.net: https://sourceforge.net/projects/opencvlibrary/files/
## Third-party packages {#tutorial_general_install_prebuilt_thirdparty}
Other organizations and people maintain their own binary distributions of OpenCV. For example:
- System packages in popular Linux distributions (https://pkgs.org/search/?q=opencv)
- PyPI (https://pypi.org/search/?q=opencv)
- Conda (https://anaconda.org/search?q=opencv)
- Conan (https://conan.io/center/recipes/opencv)
- vcpkg (https://github.com/microsoft/vcpkg/tree/master/ports/opencv)
- NuGet (https://www.nuget.org/packages?q=opencv)
- Brew (https://formulae.brew.sh/formula/opencv)
- Maven (https://search.maven.org/search?q=opencv)
# Build from sources {#tutorial_general_install_sources}
It can happen that existing binary packages are not applicable for your use case, then you'll have to build custom version of OpenCV by yourself. This section gives a high-level overview of the build process, check tutorial for specific platform for actual build instructions.
OpenCV uses [CMake](https://cmake.org/) build management system for configuration and build, so this section mostly describes generalized process of building software with CMake.
## Step 0: Prerequisites {#tutorial_general_install_sources_0}
Install C++ compiler and build tools. On \*NIX platforms it is usually GCC/G++ or Clang compiler and Make or Ninja build tool. On Windows it can be Visual Studio IDE or MinGW-w64 compiler. Native toolchains for Android are provided in the Android NDK. XCode IDE is used to build software for OSX and iOS platforms.
Install CMake from the official site or some other source.
Get other third-party dependencies: libraries with extra functionality like decoding videos or showing GUI elements; libraries providing optimized implementations of selected algorithms; tools used for documentation generation and other extras. Check @ref tutorial_config_reference for available options and corresponding dependencies.
## Step 1: Get software sources {#tutorial_general_install_sources_1}
Typical software project consists of one or several code repositories. OpenCV have two repositories with code: _opencv_ - main repository with stable and actively supported algorithms and _opencv_contrib_ which contains experimental and non-free (patented) algorithms; and one repository with test data: _opencv_extra_.
You can download a snapshot of repository in form of an archive or clone repository with full history.
To download snapshot archives:
- Go to https://github.com/opencv/opencv/releases and download "Source code" archive from any release.
- (optionally) Go to https://github.com/opencv/opencv_contrib/releases and download "Source code" archive for the same release as _opencv_
- (optionally) Go to https://github.com/opencv/opencv_extra/releases and download "Source code" archive for the same release as _opencv_
- Unpack all archives to some location
To clone repositories run the following commands in console (_git_ [must be installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)):
```.sh
git clone https://github.com/opencv/opencv
git -C opencv checkout <some-tag>
# optionally
git clone https://github.com/opencv/opencv_contrib
git -C opencv_contrib checkout <same-tag-as-opencv>
# optionally
git clone https://github.com/opencv/opencv_extra
git -C opencv_extra checkout <same-tag-as-opencv>
```
@note
If you want to build software using more than one repository, make sure all components are compatible with each other. For OpenCV it means that _opencv_ and _opencv_contrib_ repositories must be checked out at the same tag or that all snapshot archives are downloaded from the same release.
@note
When choosing which version to download take in account your target platform and development tools versions, latest versions of OpenCV can have build problems with very old compilers and vice versa. We recommend using latest release and fresh OS/compiler combination.
## Step 2: Configure {#tutorial_general_install_sources_2}
At this step CMake will verify that all necessary tools and dependencies are available and compatible with the library and will generate intermediate files for the chosen build system. It could be Makefiles, IDE projects and solutions, etc. Usually this step is performed in newly created build directory:
```
cmake -G<generator> <configuration-options> <source-directory>
```
@note
`cmake-gui` application allows to see and modify available options using graphical user interface. See https://cmake.org/runningcmake/ for details.
## Step 3: Build {#tutorial_general_install_sources_3}
During build process source files are compiled into object files which are linked together or otherwise combined into libraries and applications. This step can be run using universal command:
```
cmake --build <build-directory> <build-options>
```
... or underlying build system can be called directly:
```
make
```
## (optional) Step 3: Install {#tutorial_general_install_sources_4}
During installation procedure build results and other files from build directory will be copied to the install location. Default installation location is `/usr/local` on UNIX and `C:/Program Files` on Windows. This location can be changed at the configuration step by setting `CMAKE_INSTALL_PREFIX` option. To perform installation run the following command:
```
cmake --build <build-directory> --target install <other-options>
```
@note
This step is optional, OpenCV can be used directly from the build directory.
@note
If the installation root location is a protected system directory, so the installation process must be run with superuser or administrator privileges (e.g. `sudo cmake ...`).
## (optional) Step 4: Build plugins {#tutorial_general_install_plugins_4}
It is possible to decouple some of OpenCV dependencies and make them optional by extracting parts of the code into dynamically-loaded plugins. It helps to produce adaptive binary distributions which can work on systems with less dependencies and extend functionality just by installing missing libraries. For now modules _core_, _videoio_ and _highgui_ support this mechanism for some of their dependencies. In some cases it is possible to build plugins together with OpenCV by setting options like `VIDEOIO_PLUGIN_LIST` or `HIGHGUI_PLUGIN_LIST`, more options related to this scenario can be found in the @ref tutorial_config_reference. In other cases plugins should be built separately in their own build procedure and this section describes such standalone build process.
@note It is recommended to use compiler, configuration and build options which are compatible to the one used for OpenCV build, otherwise resulting library can refuse to load or cause other runtime problems. Note that some functionality can be limited or work slower when backends are loaded dynamically due to extra barrier between OpenCV and corresponding third-party library.
Build procedure is similar to the main OpenCV build, but you have to use special CMake projects located in corresponding subdirectories, these folders can also contain reference scripts and Docker images. It is important to use `opencv_<module>_<backend>` name prefix for plugins so that loader is able to find them. Each supported prefix can be used to load only one library, however multiple candidates can be probed for a single prefix. For example, you can have _libopencv_videoio_ffmpeg_3.so_ and _libopencv_videoio_ffmpeg_4.so_ plugins and the first one which can be loaded successfully will occupy internal slot and stop probing process. Possible prefixes and project locations are presented in the table below:
| module | backends | location |
| ------ | -------- | -------- |
| core | parallel_tbb, parallel_onetbb, parallel_openmp | _opencv/modules/core/misc/plugins_ |
| highgui | gtk, gtk2, gtk3 | _opencv/modules/highgui/misc/plugins_ |
| videoio | ffmpeg, gstreamer, intel_mfx, msmf | _opencv/modules/videoio/misc_ |
Example:
```.sh
# set-up environment for TBB detection, for example:
# export TBB_DIR=<dir-with-tbb-cmake-config>
cmake -G<generator> \
-DOPENCV_PLUGIN_NAME=opencv_core_tbb_<suffix> \
-DOPENCV_PLUGIN_DESTINATION=<dest-folder> \
-DCMAKE_BUILD_TYPE=<config> \
<opencv>/modules/core/misc/plugins/parallel_tbb
cmake --build . --config <config>
```
@note On Windows plugins must be linked with existing OpenCV build. Set `OpenCV_DIR` environment or CMake variable to the directory with _OpenCVConfig.cmake_ file, it can be OpenCV build directory or some path in the location where you performed installation.
doc/tutorials/introduction/java_eclipse/images/1-window-preferences.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

doc/tutorials/introduction/java_eclipse/images/10-new-project-created.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

doc/tutorials/introduction/java_eclipse/images/11-the-code.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

doc/tutorials/introduction/java_eclipse/images/2-user-library-new.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

doc/tutorials/introduction/java_eclipse/images/3-library-name.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

doc/tutorials/introduction/java_eclipse/images/4-add-external-jars.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

doc/tutorials/introduction/java_eclipse/images/5-native-library.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

doc/tutorials/introduction/java_eclipse/images/6-external-folder.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

doc/tutorials/introduction/java_eclipse/images/7-user-library-final.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

doc/tutorials/introduction/java_eclipse/images/7_5-new-java-project.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

doc/tutorials/introduction/java_eclipse/images/8-add-library.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

doc/tutorials/introduction/java_eclipse/images/9-select-user-lib.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

doc/tutorials/introduction/java_eclipse/java_eclipse.markdown
+114
View File
@@ -0,0 +1,114 @@
Using OpenCV Java with Eclipse {#tutorial_java_eclipse}
==============================
@prev_tutorial{tutorial_java_dev_intro}
@next_tutorial{tutorial_clojure_dev_intro}
| | |
| -: | :- |
| Original author | Barış Evrim Demiröz |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
@warning
This tutorial can contain obsolete information.
Since version 2.4.4 [OpenCV supports Java](http://opencv.org/opencv-java-api.html). In this tutorial
I will explain how to setup development environment for using OpenCV Java with Eclipse in
**Windows**, so you can enjoy the benefits of garbage collected, very refactorable (rename variable,
extract method and whatnot) modern language that enables you to write code with less effort and make
less mistakes. Here we go.
Configuring Eclipse
-------------------
First, obtain a fresh release of OpenCV [from download page](https://opencv.org/releases) and
extract it under a simple location like `C:\OpenCV-2.4.6\`. I am using version 2.4.6, but the steps
are more or less the same for other versions.
Now, we will define OpenCV as a user library in Eclipse, so we can reuse the configuration for any
project. Launch Eclipse and select Window --\> Preferences from the menu.
![](images/1-window-preferences.png)
Navigate under Java --\> Build Path --\> User Libraries and click New....
![](images/2-user-library-new.png)
Enter a name, e.g. OpenCV-2.4.6, for your new library.
![](images/3-library-name.png)
Now select your new user library and click Add External JARs....
![](images/4-add-external-jars.png)
Browse through `C:\OpenCV-2.4.6\build\java\` and select opencv-246.jar. After adding the jar,
extend the opencv-246.jar and select Native library location and press Edit....
![](images/5-native-library.png)
Select External Folder... and browse to select the folder `C:\OpenCV-2.4.6\build\java\x64`. If you
have a 32-bit system you need to select the x86 folder instead of x64.
![](images/6-external-folder.png)
Your user library configuration should look like this:
![](images/7-user-library-final.png)
Testing the configuration on a new Java project
-----------------------------------------------
Now start creating a new Java project.
![](images/7_5-new-java-project.png)
On the Java Settings step, under Libraries tab, select Add Library... and select OpenCV-2.4.6, then
click Finish.
![](images/8-add-library.png)
![](images/9-select-user-lib.png)
Libraries should look like this:
![](images/10-new-project-created.png)
Now you have created and configured a new Java project it is time to test it. Create a new java
file. Here is a starter code for your convenience:
@code{.java}
import org.opencv.core.Core;
import org.opencv.core.CvType;
import org.opencv.core.Mat;
public class Hello
{
public static void main( String[] args )
{
System.loadLibrary( Core.NATIVE_LIBRARY_NAME );
Mat mat = Mat.eye( 3, 3, CvType.CV_8UC1 );
System.out.println( "mat = " + mat.dump() );
}
}
@endcode
When you run the code you should see 3x3 identity matrix as output.
![](images/11-the-code.png)
That is it, whenever you start a new project just add the OpenCV user library that you have defined
to your project and you are good to go. Enjoy your powerful, less painful development environment :)
Running Java code with OpenCV and MKL dependency
------------------------------------------------
You may get the following error (e.g. on Ubuntu) if you have built OpenCV with MKL library with some Java code that calls OpenCV functions
that use Intel MKL:
> Intel MKL FATAL ERROR: Cannot load libmkl_avx2.so or libmkl_def.so.
One solution to solve this on Linux consists in preloading the Intel MKL library (either run the command in a terminal or add it to your `.bashrc` file).
Your command line should be something similar to this (add `$LD_PRELOAD:` before if you have already set the `LD_PRELOAD` variable):
> export LD_PRELOAD=/opt/intel/mkl/lib/intel64/libmkl_core.so:/opt/intel/mkl/lib/intel64/libmkl_sequential.so
Then, run the Eclipse IDE from a terminal that have this environment variable set (`echo $LD_PRELOAD`) and the error should disappear.
doc/tutorials/introduction/linux_eclipse/images/a0.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.5 KiB

doc/tutorials/introduction/linux_eclipse/images/a1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

doc/tutorials/introduction/linux_eclipse/images/a10.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

doc/tutorials/introduction/linux_eclipse/images/a12.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

doc/tutorials/introduction/linux_eclipse/images/a14.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

doc/tutorials/introduction/linux_eclipse/images/a15.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

doc/tutorials/introduction/linux_eclipse/images/a3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

doc/tutorials/introduction/linux_eclipse/images/a4.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

doc/tutorials/introduction/linux_eclipse/images/a7.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.1 KiB

doc/tutorials/introduction/linux_eclipse/images/a9.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

doc/tutorials/introduction/linux_eclipse/linux_eclipse.markdown
+212
View File
@@ -0,0 +1,212 @@
Using OpenCV with Eclipse (plugin CDT) {#tutorial_linux_eclipse}
======================================
@prev_tutorial{tutorial_linux_gcc_cmake}
@next_tutorial{tutorial_windows_install}
| | |
| -: | :- |
| Original author | Ana Huamán |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
@warning
This tutorial can contain obsolete information.
Prerequisites
-------------
Two ways, one by forming a project directly, and another by CMake Prerequisites
-# Having installed [Eclipse](http://www.eclipse.org/) in your workstation (only the CDT plugin for
C/C++ is needed). You can follow the following steps:
- Go to the Eclipse site
- Download [Eclipse IDE for C/C++
Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/heliossr2) .
Choose the link according to your workstation.
-# Having installed OpenCV. If not yet, go @ref tutorial_linux_install "here".
Making a project
----------------
-# Start Eclipse. Just run the executable that comes in the folder.
-# Go to **File -\> New -\> C/C++ Project**
![](images/a0.png)
-# Choose a name for your project (i.e. DisplayImage). An **Empty Project** should be okay for this
example.
![](images/a1.png)
-# Leave everything else by default. Press **Finish**.
-# Your project (in this case DisplayImage) should appear in the **Project Navigator** (usually at
the left side of your window).
![](images/a3.png)
-# Now, let's add a source file using OpenCV:
- Right click on **DisplayImage** (in the Navigator). **New -\> Folder** .
![](images/a4.png)
- Name your folder **src** and then hit **Finish**
- Right click on your newly created **src** folder. Choose **New source file**:
- Call it **DisplayImage.cpp**. Hit **Finish**
![](images/a7.png)
-# So, now you have a project with a empty .cpp file. Let's fill it with some sample code (in other
words, copy and paste the snippet below):
@code{.cpp}
#include <opencv2/opencv.hpp>
using namespace cv;
int main( int argc, char** argv )
{
Mat image;
image = imread( argv[1], IMREAD_COLOR );
if( argc != 2 || !image.data )
{
printf( "No image data \n" );
return -1;
}
namedWindow( "Display Image", WINDOW_AUTOSIZE );
imshow( "Display Image", image );
waitKey(0);
return 0;
}
@endcode
-# We are only missing one final step: To tell OpenCV where the OpenCV headers and libraries are.
For this, do the following:
- Go to **Project--\>Properties**
- In **C/C++ Build**, click on **Settings**. At the right, choose the **Tool Settings** Tab.
Here we will enter the headers and libraries info:
-# In **GCC C++ Compiler**, go to **Includes**. In **Include paths(-l)** you should
include the path of the folder where opencv was installed. In our example, this is
/usr/local/include/opencv.
![](images/a9.png)
@note If you do not know where your opencv files are, open the **Terminal** and type:
@code{.bash}
pkg-config --cflags opencv
@endcode
For instance, that command gave me this output:
@code{.bash}
-I/usr/local/include/opencv -I/usr/local/include
@endcode
-# Now go to **GCC C++ Linker**,there you have to fill two spaces:
First in **Library search path (-L)** you have to write the path to where the opencv libraries
reside, in my case the path is: :
/usr/local/lib
Then in **Libraries(-l)** add the OpenCV libraries that you may need. Usually just the 4 first
on the list below are enough (for simple applications) . In my case, I am putting all of them
since I plan to use the whole bunch:
opencv_core opencv_imgproc opencv_imgcodecs opencv_highgui opencv_ml opencv_videoio opencv_video opencv_features2d
opencv_calib3d opencv_objdetect opencv_flann
![](images/a10.png)
If you don't know where your libraries are (or you are just psychotic and want to make sure
the path is fine), type in **Terminal**:
@code{.bash}
pkg-config --libs opencv
@endcode
My output (in case you want to check) was:
@code{.bash}
-L/usr/local/lib -lopencv_core -lopencv_imgproc -lopencv_highgui -lopencv_ml -lopencv_video -lopencv_features2d -lopencv_calib3d -lopencv_objdetect -lopencv_videoio -lopencv_imgcodecs -lopencv_flann
@endcode
Now you are done. Click **OK**
- Your project should be ready to be built. For this, go to **Project-\>Build all**
In the Console you should get something like
![](images/a12.png)
If you check in your folder, there should be an executable there.
Running the executable
----------------------
So, now we have an executable ready to run. If we were to use the Terminal, we would probably do
something like:
@code{.bash}
cd <DisplayImage_directory>
cd src
./DisplayImage ../images/HappyLittleFish.png
@endcode
Assuming that the image to use as the argument would be located in
\<DisplayImage_directory\>/images/HappyLittleFish.png. We can still do this, but let's do it from
Eclipse:
-# Go to **Run-\>Run Configurations**
-# Under C/C++ Application you will see the name of your executable + Debug (if not, click over
C/C++ Application a couple of times). Select the name (in this case **DisplayImage Debug**).
-# Now, in the right side of the window, choose the **Arguments** Tab. Write the path of the image
file we want to open (path relative to the workspace/DisplayImage folder). Let's use
**HappyLittleFish.png**:
![](images/a14.png)
-# Click on the **Apply** button and then in Run. An OpenCV window should pop up with the fish
image (or whatever you used).
![](images/a15.jpg)
-# Congratulations! You are ready to have fun with OpenCV using Eclipse.
### V2: Using CMake+OpenCV with Eclipse (plugin CDT)
Say you have or create a new file, *helloworld.cpp* in a directory called *foo*:
@code{.cpp}
#include <opencv2/opencv.hpp>
using namespace cv;
int main ( int argc, char **argv )
{
Mat img(480, 640, CV_8U);
putText(img, "Hello World!", Point( 200, 400 ), FONT_HERSHEY_SIMPLEX | FONT_ITALIC, 1.0, Scalar( 255, 255, 0 ));
imshow("My Window", img);
waitKey();
return 0;
}
@endcode
-# Create a build directory, say, under *foo*: mkdir /build. Then cd build.
-# Put a `CmakeLists.txt` file in build:
@code{.bash}
PROJECT( helloworld_proj )
FIND_PACKAGE( OpenCV REQUIRED )
ADD_EXECUTABLE( helloworld helloworld.cxx )
TARGET_LINK_LIBRARIES( helloworld \f${OpenCV_LIBS} )
@endcode
-# Run: cmake-gui .. and make sure you fill in where opencv was built.
-# Then click configure and then generate. If it's OK, **quit cmake-gui**
-# Run `make -j4` (the -j4 is optional, it just tells the compiler to build in 4 threads). Make
sure it builds.
-# Start eclipse. Put the workspace in some directory but **not** in foo or `foo\build`
-# Right click in the Project Explorer section. Select Import And then open the C/C++ filter.
Choose *Existing Code* as a Makefile Project.
-# Name your project, say *helloworld*. Browse to the Existing Code location `foo\build` (where
you ran your cmake-gui from). Select *Linux GCC* in the *"Toolchain for Indexer Settings"* and
press *Finish*.
-# Right click in the Project Explorer section. Select Properties. Under C/C++ Build, set the
*build directory:* from something like `${workspace_loc:/helloworld}` to
`${workspace_loc:/helloworld}/build` since that's where you are building to.
-# You can also optionally modify the Build command: from make to something like
`make VERBOSE=1 -j4` which tells the compiler to produce detailed symbol files for debugging and
also to compile in 4 parallel threads.
-# Done!
doc/tutorials/introduction/linux_gcc_cmake/images/GCC_CMake_Example_Tutorial.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

doc/tutorials/introduction/linux_gcc_cmake/linux_gcc_cmake.markdown
+90
View File
@@ -0,0 +1,90 @@
Using OpenCV with gcc and CMake {#tutorial_linux_gcc_cmake}
===============================
@prev_tutorial{tutorial_linux_gdb_pretty_printer}
@next_tutorial{tutorial_linux_eclipse}
| | |
| -: | :- |
| Original author | Ana Huamán |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
@warning
This tutorial can contain obsolete information.
@note We assume that you have successfully installed OpenCV in your workstation.
- The easiest way of using OpenCV in your code is to use [CMake](http://www.cmake.org/). A few
advantages (taken from the Wiki):
-# No need to change anything when porting between Linux and Windows
-# Can easily be combined with other tools by CMake( i.e. Qt, ITK and VTK )
- If you are not familiar with CMake, checkout the
[tutorial](http://www.cmake.org/cmake/help/cmake_tutorial.html) on its website.
Steps
-----
### Create a program using OpenCV
Let's use a simple program such as DisplayImage.cpp shown below.
@code{.cpp}
#include <stdio.h>
#include <opencv2/opencv.hpp>
using namespace cv;
int main(int argc, char** argv )
{
if ( argc != 2 )
{
printf("usage: DisplayImage.out <Image_Path>\n");
return -1;
}
Mat image;
image = imread( argv[1], IMREAD_COLOR );
if ( !image.data )
{
printf("No image data \n");
return -1;
}
namedWindow("Display Image", WINDOW_AUTOSIZE );
imshow("Display Image", image);
waitKey(0);
return 0;
}
@endcode
### Create a CMake file
Now you have to create your CMakeLists.txt file. It should look like this:
@code{.cmake}
cmake_minimum_required(VERSION 3.5)
project( DisplayImage )
find_package( OpenCV REQUIRED )
include_directories( ${OpenCV_INCLUDE_DIRS} )
add_executable( DisplayImage DisplayImage.cpp )
target_link_libraries( DisplayImage ${OpenCV_LIBS} )
@endcode
### Generate the executable
This part is easy, just proceed as with any other project using CMake:
@code{.bash}
cd <DisplayImage_directory>
cmake .
make
@endcode
### Result
By now you should have an executable (called DisplayImage in this case). You just have to run it
giving an image location as an argument, i.e.:
@code{.bash}
./DisplayImage lena.jpg
@endcode
You should get a nice window as the one shown below:
![](images/GCC_CMake_Example_Tutorial.jpg)
doc/tutorials/introduction/linux_gdb_pretty_printer/images/example.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

doc/tutorials/introduction/linux_gdb_pretty_printer/linux_gdb_pretty_printer.markdown
+38
View File
@@ -0,0 +1,38 @@
Using OpenCV with gdb-powered IDEs {#tutorial_linux_gdb_pretty_printer}
=====================
@prev_tutorial{tutorial_oneapi_install}
@next_tutorial{tutorial_linux_gcc_cmake}
| | |
| -: | :- |
| Original author | Egor Smirnov |
| Compatibility | OpenCV >= 4.0 |
@tableofcontents
# Capabilities {#tutorial_linux_gdb_pretty_printer_capabilities}
This pretty-printer can show element type, `is_continuous`, `is_submatrix` flags and (possibly truncated) matrix. It is known to work in Clion, VS Code and gdb.
![Clion example](images/example.png)
# Installation {#tutorial_linux_gdb_pretty_printer_installation}
Move into `opencv/samples/gdb/`. Place `mat_pretty_printer.py` in a convenient place, rename `gdbinit` to `.gdbinit` and move it into your home folder. Change 'source' line of `.gdbinit` to point to your `mat_pretty_printer.py` path.
In order to check version of python bundled with your gdb, use the following commands from the gdb shell:
python
import sys
print(sys.version_info)
end
If the version of python 3 installed in your system doesn't match the version in gdb, create a new virtual environment with the exact same version, install `numpy` and change the path to python3 in `.gdbinit` accordingly.
# Usage {#tutorial_linux_gdb_pretty_printer_usage}
The fields in a debugger prefixed with `view_` are pseudo-fields added for convenience, the rest are left as is.
If you feel that the number of elements in truncated view is too low, you can edit `mat_pretty_printer.py` - `np.set_printoptions` controls everything matrix display-related.
doc/tutorials/introduction/linux_install/linux_install.markdown
+126
View File
@@ -0,0 +1,126 @@
Installation in Linux {#tutorial_linux_install}
=====================
@prev_tutorial{tutorial_env_reference}
@next_tutorial{tutorial_oneapi_install}
| | |
| -: | :- |
| Original author | Ana Huamán |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
# Quick start {#tutorial_linux_install_quick_start}
## Build core modules {#tutorial_linux_install_quick_build_core}
@snippet linux_quick_install.sh body
## Build with opencv_contrib {#tutorial_linux_install_quick_build_contrib}
@snippet linux_quick_install_contrib.sh body
# Detailed process {#tutorial_linux_install_detailed}
This section provides more details of the build process and describes alternative methods and tools. Please refer to the @ref tutorial_general_install tutorial for general installation details and to the @ref tutorial_config_reference for configuration options documentation.
## Install compiler and build tools {#tutorial_linux_install_detailed_basic_compiler}
- To compile OpenCV you will need a C++ compiler. Usually it is G++/GCC or Clang/LLVM:
- Install GCC...
@snippet linux_install_a.sh gcc
- ... or Clang:
@snippet linux_install_b.sh clang
- OpenCV uses CMake build configuration tool:
@snippet linux_install_a.sh cmake
- CMake can generate scripts for different build systems, e.g. _make_, _ninja_:
- Install Make...
@snippet linux_install_a.sh make
- ... or Ninja:
@snippet linux_install_b.sh ninja
- Install tool for getting and unpacking sources:
- _wget_ and _unzip_...
@snippet linux_install_a.sh wget
- ... or _git_:
@snippet linux_install_b.sh git
## Download sources {#tutorial_linux_install_detailed_basic_download}
There are two methods of getting OpenCV sources:
- Download snapshot of repository using web browser or any download tool (~80-90Mb) and unpack it...
@snippet linux_install_a.sh download
- ... or clone repository to local machine using _git_ to get full change history (>470Mb):
@snippet linux_install_b.sh download
@note
Snapshots of other branches, releases or commits can be found on the [GitHub](https://github.com/opencv/opencv) and the [official download page](https://opencv.org/releases).
## Configure and build {#tutorial_linux_install_detailed_basic_build}
- Create build directory:
@snippet linux_install_a.sh prepare
- Configure - generate build scripts for the preferred build system:
- For _make_...
@snippet linux_install_a.sh configure
- ... or for _ninja_:
@snippet linux_install_b.sh configure
- Build - run actual compilation process:
- Using _make_...
@snippet linux_install_a.sh build
- ... or _ninja_:
@snippet linux_install_b.sh build
@note
_Configure_ process can download some files from the internet to satisfy library dependencies, connection failures can cause some of modules or functionalities to be turned off or behave differently. Refer to the @ref tutorial_general_install and @ref tutorial_config_reference tutorials for details and full configuration options reference.
@note
If you experience problems with the build process, try to clean or recreate the build directory. Changes in the configuration like disabling a dependency, modifying build scripts or switching sources to another branch are not handled very well and can result in broken workspace.
@note
_Make_ can run multiple compilation processes in parallel, `-j<NUM>` option means "run <NUM> jobs simultaneously". _Ninja_ will automatically detect number of available processor cores and does not need `-j` option.
## Check build results {#tutorial_linux_install_detailed_basic_verify}
After successful build you will find libraries in the `build/lib` directory and executables (test, samples, apps) in the `build/bin` directory:
@snippet linux_install_a.sh check
CMake package files will be located in the build root:
@snippet linux_install_a.sh check cmake
## Install
@warning
The installation process only copies files to predefined locations and does minor patching. Installing using this method does not integrate opencv into the system package registry and thus, for example, opencv can not be uninstalled automatically. We do not recommend system-wide installation to regular users due to possible conflicts with system packages.
By default OpenCV will be installed to the `/usr/local` directory, all files will be copied to following locations:
* `/usr/local/bin` - executable files
* `/usr/local/lib` - libraries (.so)
* `/usr/local/cmake/opencv4` - cmake package
* `/usr/local/include/opencv4` - headers
* `/usr/local/share/opencv4` - other files (e.g. trained cascades in XML format)
Since `/usr/local` is owned by the root user, the installation should be performed with elevated privileges (`sudo`):
@snippet linux_install_a.sh install
or
@snippet linux_install_b.sh install
Installation root directory can be changed with `CMAKE_INSTALL_PREFIX` configuration parameter, e.g. `-DCMAKE_INSTALL_PREFIX=$HOME/.local` to install to current user's local directory. Installation layout can be changed with `OPENCV_*_INSTALL_PATH` parameters. See @ref tutorial_config_reference for details.
doc/tutorials/introduction/load_save_image/load_save_image.markdown
+4
View File
@@ -0,0 +1,4 @@
Load, Modify, and Save an Image {#tutorial_load_save_image}
===============================
Tutorial content has been moved: @ref tutorial_display_image
doc/tutorials/introduction/macos_install/macos_install.markdown
+181
View File
@@ -0,0 +1,181 @@
Installation in MacOS {#tutorial_macos_install}
=====================
@prev_tutorial{tutorial_android_ocl_intro}
@next_tutorial{tutorial_arm_crosscompile_with_cmake}
| | |
| -: | :- |
| Original author | `@sajarindider` |
| Compatibility | OpenCV >= 3.4 |
The following steps have been tested for macOS (Mavericks) but should work with other versions as well.
Required Packages
-----------------
- CMake 3.9 or higher
- Git
- Python 3.x and NumPy 1.5 or later
This tutorial will assume you have [Python](https://docs.python.org/3/using/mac.html),
[NumPy](https://numpy.org/install/) and
[Git](https://git-scm.com/downloads/mac) installed on your machine.
@note
- macOS up to 12.2 (Monterey): Comes with Python 2.7 pre-installed.
- macOS 12.3 and later: Python 2.7 has been removed, and no version of Python is included by default.
It is recommended to install the latest version of Python 3.x (at least Python 3.8) for compatibility with the latest OpenCV Python bindings.
@note
If you have Xcode and Xcode Command Line Tools installed, Git is already available on your machine.
Installing CMake
----------------
-# Find the version for your system and download CMake from their release's [page](https://cmake.org/download/)
-# Install the `.dmg` package and launch it from Applications. That will give you the UI app of CMake
-# From the CMake app window, choose menu Tools --> How to Install For Command Line Use. Then, follow the instructions from the pop-up there.
-# The install folder will be `/usr/local/bin/` by default. Complete the installation by choosing Install command line links.
-# Test that CMake is installed correctly by running:
@code{.bash}
cmake --version
@endcode
@note You can use [Homebrew](https://brew.sh/) to install CMake with:
@code{.bash}
brew install cmake
@endcode
Getting OpenCV Source Code
--------------------------
You can use the latest stable OpenCV version or you can grab the latest snapshot from our
[Git repository](https://github.com/opencv/opencv.git).
### Getting the Latest Stable OpenCV Version
- Go to our [OpenCV releases page](https://opencv.org/releases).
- Download the source archive of the latest version (e.g., OpenCV 4.x) and unpack it.
### Getting the Cutting-edge OpenCV from the Git Repository
Launch Git client and clone [OpenCV repository](https://github.com/opencv/opencv).
If you need modules from [OpenCV contrib repository](https://github.com/opencv/opencv_contrib) then clone it as well.
For example:
@code{.bash}
cd ~/<your_working_directory>
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git
@endcode
Building OpenCV from Source Using CMake
---------------------------------------
-# Create a temporary directory, which we denote as `build_opencv`, where you want to put
the generated Makefiles, project files as well the object files and output binaries and enter
there.
For example:
@code{.bash}
mkdir build_opencv
cd build_opencv
@endcode
@note It is good practice to keep your source code directories clean. Create the build directory outside of the source tree.
-# Configuring. Run `cmake [<some optional parameters>] <path to the OpenCV source directory>`
For example:
@code{.bash}
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=ON ../opencv
@endcode
Alternatively, you can use the CMake GUI (`cmake-gui`):
- set the OpenCV source code path to, e.g. `/Users/your_username/opencv`
- set the binary build path to your CMake build directory, e.g. `/Users/your_username/build_opencv`
- set optional parameters
- run: "Configure"
- run: "Generate"
-# Description of some parameters
- build type: `-DCMAKE_BUILD_TYPE=Release` (or `Debug`).
- include Extra Modules: If you cloned the `opencv_contrib` repository and want to include its modules, set:
@code{.bash}
-DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules
@endcode
- set `-DBUILD_DOCS=ON` for building documents (doxygen is required)
- set `-DBUILD_EXAMPLES=ON` to build all examples
-# [optional] Building python. Set the following python parameters:
- `-DPYTHON3_EXECUTABLE=$(which python3)`
- `-DPYTHON3_INCLUDE_DIR=$(python3 -c "from sysconfig import get_paths as gp; print(gp()['include'])")`
- `-DPYTHON3_NUMPY_INCLUDE_DIRS=$(python3 -c "import numpy; print(numpy.get_include())")`
@note
Python 2 has reached its end of life. It is recommended to use Python 3 for building Python bindings.
-# Build. From build directory execute *make*, it is recommended to do this in several threads
For example:
@code{.bash}
make -j$(sysctl -n hw.ncpu) # runs the build using all available CPU cores
@endcode
-# After building, you can install OpenCV system-wide using:
@code{.bash}
sudo make install
@endcode
-# To use OpenCV in your CMake-based projects through `find_package(OpenCV)`, specify the `OpenCV_DIR` variable pointing to the build or install directory.
For example:
@code{.bash}
cmake -DOpenCV_DIR=~/build_opencv ..
@endcode
### Verifying the OpenCV Installation
After building (and optionally installing) OpenCV, you can verify the installation by checking the version using Python:
@code{.bash}
python3 -c "import cv2; print(cv2.__version__)"
@endcode
This command should output the version of OpenCV you have installed.
@note
You can also use a package manager like [Homebrew](https://brew.sh/)
or [pip](https://pip.pypa.io/en/stable/) to install releases of OpenCV only (Not the cutting edge).
- Installing via Homebrew:
For example:
@code{.bash}
brew install opencv
@endcode
- Installing via pip:
For example:
@code{.bash}
pip install opencv-python
@endcode
@note To access the extra modules from `opencv_contrib`, install the `opencv-contrib-python` package using `pip install opencv-contrib-python`.
doc/tutorials/introduction/oneapi_install/oneapi_install.markdown
+106
View File
@@ -0,0 +1,106 @@
Building OpenCV with oneAPI {#tutorial_oneapi_install}
===========================
@prev_tutorial{tutorial_linux_install}
@next_tutorial{tutorial_linux_gcc_cmake}
| | |
| -: | :- |
| Original author | Alessandro de Oliveira Faria |
| Compatibility | OpenCV >= 4.11.0 |
@tableofcontents
# Quick start {#tutorial_oneapi_install_quick_start}
**oneAPI** is Intel's open initiative (now also maintained by the UXL Foundation) that combines a specification and a set of toolkits for programming CPUs, GPUs, FPGAs and NPUs with a single code base. The core is the SYCL standard (single-source C++ for parallelism), complemented by high-performance libraries — oneTBB (parallelism), oneMKL (linear algebra), oneDNN (neural networks), oneVPL (video), etc. Thus, when you compile with oneAPI's DPC++ (icpx) compiler, the binary gains optimized execution paths that choose, at runtime, the best vector instructions or the available device, without changing the source code.
## Why compile OpenCV with the oneAPI ecosystem when targeting the CPU:
* Simple, because by enabling the CMake options -DWITH_SYCL=ON -DWITH_TBB=ON -DWITH_ONEDNN=ON -DWITH_IPP=ON and using the icpx compiler, the OpenCV core starts to directly invoke oneAPI libraries.
* oneDNN replaces the generic kernels of the cv::dnn layer with implementations that exploit AVX2, AVX-512, AMX and VNNI, accelerating convolutions, matmul and network post-processing by up to 3-5× on modern CPUs.
* oneTBB takes over the thread pool, scheduling filters like cv::resize, cv::GaussianBlur or the G-API pipeline across all cores without busy-wait.
* IPP (now distributed via oneAPI Base Toolkit) provides optimized intrinsic routines for elementary operations (SAD, DFT, median blur), which OpenCV calls when it encounters the HAVE_IPP macro.
* All this happens transparently: the source code that uses cv::Mat remains the same, but the linked symbols point to vectorized versions, and the internal dispatcher selects the appropriate vector width at runtime.
## CPU Processor Requirements
Systems based on Intel® 64 architectures below are supported both as host and target platforms.
* Intel® Core™ processor family or higher
* Intel® Xeon® processor family
* Intel® Xeon® Scalable processor family
### Requirements for Accelerators
* Integrated GEN9 (and higher) GPUs. See source in Intel® Graphics Compiler for OpenCL™
* FPGA Card: see Intel(R) DPC++ Compiler System Requirements.
### Disk Space Requirements
* 3.3 GB of disk space (minimum) on a standard installation.
@note: During the installation process, the installer may need up to 6 GB of additional temporary disk storage to manage the download and intermediate installation files.
### Memory Requirements
* 8 GB RAM recommended
## How To install oneAPI
Installing oneAPI: To quickly set up the oneAPI ecosystem on openSUSE, simply follow the official guide https://www.intel.com/content/www/us/en/developer/articles/guide/installation-guide-for-oneapi-toolkits.html, which shows you how to enable the distribution’s dedicated repository (zypper ar … oneAPI) and install the metapackages ― for example, intel-basekit (DPC++, TBB, oneDNN, IPP compilers) and, optionally, intel-hpckit or intel-renderkit if you need HPC or graphics tools. The guide also explains post-installation tweaks, such as loading the environment with source /opt/intel/oneapi/setvars.sh , ensuring that the binaries (icpx, dpcpp) and libraries are immediately available in your shell for compiling and running accelerated applications.
## Download, Github Instruction, Build and Install
1. Below are the commands to download last version (latest release on the date of publication of this text):
```
git clone https://github.com/opencv/opencv.git
```
2. and make sure you are using branch 4.*:
```
git status
On branch 4.x
```
3. Navigate to OpenCV repository and prepare the build folder:
```
cd opencv
mkdir build
cd build
```
4. Set up Intel oneAPI environment variables. For default installation:
```
source /opt/intel/oneapi/setvars.sh
```
5. Run CMake * with Intel® oneAPI DPC++/C++ Compiler to configure the project:
```
cmake -DCMAKE_C_COMPILER=icx \
-DCMAKE_CXX_COMPILER=icpx
-DCMAKE_CXX_FLAGS="-march=native -mavx -mfma -msse -msse2" ..
cmake --build .
```
6. Now Make sure openCV* is compiled with Intel® oneAPI DPC++/C++ Compiler and install:
```
readelf -p .comment bin/opencv_annotation
String dump of section '.comment':
[ 0] GCC: (SUSE Linux) 13.3.1 20250313 [revision 4ef1d8c84faeebffeb0cc01ee22e891b41e5c4e0]
[ 56] GCC: (SUSE Linux) 12.3.0
[ 6f] Intel(R) oneAPI DPC++/C++ Compiler 2025.1.1 (2025.1.1.20250418)
make install
```
Have fun...
doc/tutorials/introduction/table_of_content_introduction.markdown
+47
View File
@@ -0,0 +1,47 @@
Introduction to OpenCV {#tutorial_table_of_content_introduction}
======================
@tableofcontents
- @subpage tutorial_general_install
- @subpage tutorial_config_reference
- @subpage tutorial_env_reference
##### Linux
- @subpage tutorial_linux_install
- @subpage tutorial_oneapi_install
- @subpage tutorial_linux_gdb_pretty_printer
- @subpage tutorial_linux_gcc_cmake
- @subpage tutorial_linux_eclipse
##### Windows
- @subpage tutorial_windows_install
- @subpage tutorial_windows_visual_studio_opencv
- @subpage tutorial_windows_visual_studio_image_watch
- @subpage tutorial_windows_msys2_vscode
- @subpage tutorial_windows_armpl
##### Java & Android
- @subpage tutorial_java_dev_intro
- @subpage tutorial_java_eclipse
- @subpage tutorial_clojure_dev_intro
- @subpage tutorial_android_dev_intro
- @subpage tutorial_dev_with_OCV_on_Android
- @subpage tutorial_android_dnn_intro
- @subpage tutorial_android_ocl_intro
##### Other platforms
- @subpage tutorial_macos_install
- @subpage tutorial_arm_crosscompile_with_cmake
- @subpage tutorial_crosscompile_with_multiarch
- @subpage tutorial_building_tegra_cuda
- @subpage tutorial_building_fastcv
- @ref tutorial_ios_install
##### Usage basics
- @subpage tutorial_display_image - We will learn how to load an image from file and display it using OpenCV
##### Miscellaneous
- @subpage tutorial_documentation - This tutorial describes new documenting process and some useful Doxygen features.
- @subpage tutorial_transition_guide - This document describes some aspects of 2.4 -> 3.0 transition process.
- @subpage tutorial_cross_referencing - This document outlines how to create cross references to the OpenCV documentation from other Doxygen projects.
doc/tutorials/introduction/transition_guide/transition_guide.markdown
+299
View File
@@ -0,0 +1,299 @@
Transition guide {#tutorial_transition_guide}
================
@prev_tutorial{tutorial_documentation}
@next_tutorial{tutorial_cross_referencing}
| | |
| -: | :- |
| Original author | Maksim Shabunin |
| Compatibility | OpenCV >= 3.0 |
@tableofcontents
Changes overview {#tutorial_transition_overview}
================
This document is intended to software developers who want to migrate their code to OpenCV 3.0.
OpenCV 3.0 introduced many new algorithms and features comparing to version 2.4. Some modules have been rewritten, some have been reorganized. Although most of the algorithms from 2.4 are still present, the interfaces can differ.
This section describes most notable changes in general, all details and examples of transition actions are in the next part of the document.
##### Contrib repository
<https://github.com/opencv/opencv_contrib>
This is a place for all new, experimental and non-free algorithms. It does not receive so much attention from the support team comparing to main repository, but the community makes an effort to keep it in a good shape.
To build OpenCV with _contrib_ repository, add the following option to your cmake command:
@code{.sh}
-DOPENCV_EXTRA_MODULES_PATH=<path-to-opencv_contrib>/modules
@endcode
##### Headers layout
In 2.4 all headers are located in corresponding module subfolder (_opencv2/\<module\>/\<module\>.hpp_), in 3.0 there are top-level module headers containing the most of the module functionality: _opencv2/\<module\>.hpp_ and all C-style API definitions have been moved to separate headers (for example opencv2/core/core_c.h).
##### Algorithm interfaces
General algorithm usage pattern has changed: now it must be created on heap wrapped in smart pointer cv::Ptr. Version 2.4 allowed both stack and heap allocations, directly or via smart pointer.
_get_ and _set_ methods have been removed from the cv::Algorithm class along with _CV_INIT_ALGORITHM_ macro. In 3.0 all properties have been converted to the pairs of _getProperty/setProperty_ pure virtual methods. As a result it is __not__ possible to create and use cv::Algorithm instance by name (using generic _Algorithm::create(String)_ method), one should call corresponding factory method explicitly.
##### Changed modules
- _ml_ module has been rewritten
- _highgui_ module has been split into parts: _imgcodecs_, _videoio_ and _highgui_ itself
- _features2d_ module have been reorganized (some feature detectors has been moved to _opencv_contrib/xfeatures2d_ module)
- _legacy_, _nonfree_ modules have been removed. Some algorithms have been moved to different locations and some have been completely rewritten or removed
- CUDA API has been updated (_gpu_ module -> several _cuda_ modules, namespace _gpu_ -> namespace _cuda_)
- OpenCL API has changed (_ocl_ module has been removed, separate _ocl::_ implementations -> Transparent API)
- Some other methods and classes have been relocated
Transition hints {#tutorial_transition_hints}
================
This section describes concrete actions with examples.
Prepare 2.4 {#tutorial_transition_hints_24}
-----------
Some changes made in the latest 2.4.11 OpenCV version allow you to prepare current codebase to migration:
- cv::makePtr function is now available
- _opencv2/\<module\>.hpp_ headers have been created
New headers layout {#tutorial_transition_hints_headers}
------------------
__Note:__
Changes intended to ease the migration have been made in OpenCV 3.0, thus the following instructions are not necessary, but recommended.
1. Replace inclusions of old module headers:
@code{.cpp}
// old header
#include "opencv2/<module>/<module>.hpp"
// new header
#include "opencv2/<module>.hpp"
@endcode
Modern way to use algorithm {#tutorial_transition_algorithm}
---------------------------
1. Algorithm instances must be created with cv::makePtr function or corresponding static factory method if available:
@code{.cpp}
// good ways
Ptr<SomeAlgo> algo = makePtr<SomeAlgo>(...);
Ptr<SomeAlgo> algo = SomeAlgo::create(...);
@endcode
Other ways are deprecated:
@code{.cpp}
// bad ways
Ptr<SomeAlgo> algo = new SomeAlgo(...);
SomeAlgo * algo = new SomeAlgo(...);
SomeAlgo algo(...);
Ptr<SomeAlgo> algo = Algorithm::create<SomeAlgo>("name");
@endcode
2. Algorithm properties should be accessed via corresponding virtual methods, _getSomeProperty/setSomeProperty_, generic _get/set_ methods have been removed:
@code{.cpp}
// good way
double clipLimit = clahe->getClipLimit();
clahe->setClipLimit(clipLimit);
// bad way
double clipLimit = clahe->getDouble("clipLimit");
clahe->set("clipLimit", clipLimit);
clahe->setDouble("clipLimit", clipLimit);
@endcode
3. Remove `initModule_<moduleName>()` calls
Machine learning module {#tutorial_transition_hints_ml}
-----------------------
Since this module has been rewritten, it will take some effort to adapt your software to it. All algorithms are located in separate _ml_ namespace along with their base class _StatModel_. Separate _SomeAlgoParams_ classes have been replaced with a sets of corresponding _getProperty/setProperty_ methods.
The following table illustrates correspondence between 2.4 and 3.0 machine learning classes.
| 2.4 | 3.0 |
| --------- | --------- |
| CvStatModel | cv::ml::StatModel |
| CvNormalBayesClassifier | cv::ml::NormalBayesClassifier |
| CvKNearest | cv::ml::KNearest |
| CvSVM | cv::ml::SVM |
| CvDTree | cv::ml::DTrees |
| CvBoost | cv::ml::Boost |
| CvGBTrees | _Not implemented_ |
| CvRTrees | cv::ml::RTrees |
| CvERTrees | _Not implemented_ |
| EM | cv::ml::EM |
| CvANN_MLP | cv::ml::ANN_MLP |
| _Not implemented_ | cv::ml::LogisticRegression |
| CvMLData | cv::ml::TrainData |
Although rewritten _ml_ algorithms in 3.0 allow you to load old trained models from _xml/yml_ file, deviations in prediction process are possible.
The following code snippets from the `points_classifier.cpp` example illustrate differences in model training process:
@code{.cpp}
using namespace cv;
// ======== version 2.4 ========
Mat trainSamples, trainClasses;
prepare_train_data( trainSamples, trainClasses );
CvBoost boost;
Mat var_types( 1, trainSamples.cols + 1, CV_8UC1, Scalar(CV_VAR_ORDERED) );
var_types.at<uchar>( trainSamples.cols ) = CV_VAR_CATEGORICAL;
CvBoostParams params( CvBoost::DISCRETE, // boost_type
100, // weak_count
0.95, // weight_trim_rate
2, // max_depth
false, //use_surrogates
0 // priors
);
boost.train( trainSamples, CV_ROW_SAMPLE, trainClasses, Mat(), Mat(), var_types, Mat(), params );
// ======== version 3.0 ========
Ptr<Boost> boost = Boost::create();
boost->setBoostType(Boost::DISCRETE);
boost->setWeakCount(100);
boost->setWeightTrimRate(0.95);
boost->setMaxDepth(2);
boost->setUseSurrogates(false);
boost->setPriors(Mat());
boost->train(prepare_train_data()); // 'prepare_train_data' returns an instance of ml::TrainData class
@endcode
Features detect {#tutorial_transition_hints_features}
---------------
Some algorithms (FREAK, BRIEF, SIFT, SURF) has been moved to _opencv_contrib_ repository, to _xfeatures2d_ module, _xfeatures2d_ namespace. Their interface has been also changed (inherit from `cv::Feature2D` base class).
List of _xfeatures2d_ module classes:
- cv::xfeatures2d::BriefDescriptorExtractor - Class for computing BRIEF descriptors (2.4 location: _features2d_)
- cv::xfeatures2d::FREAK - Class implementing the FREAK (Fast Retina Keypoint) keypoint descriptor (2.4 location: _features2d_)
- cv::xfeatures2d::StarDetector - The class implements the CenSurE detector (2.4 location: _features2d_)
- cv::xfeatures2d::SIFT - Class for extracting keypoints and computing descriptors using the Scale Invariant Feature Transform (SIFT) algorithm (2.4 location: _nonfree_)
- cv::xfeatures2d::SURF - Class for extracting Speeded Up Robust Features from an image (2.4 location: _nonfree_)
Following steps are needed:
1. Add _opencv_contrib_ to compilation process
2. Include `opencv2/xfeatures2d.h` header
3. Use namespace `xfeatures2d`
4. Replace `operator()` calls with `detect`, `compute` or `detectAndCompute` if needed
Some classes now use general methods `detect`, `compute` or `detectAndCompute` provided by `Feature2D` base class instead of custom `operator()`
Following code snippets illustrate the difference (from `video_homography.cpp` example):
@code{.cpp}
using namespace cv;
// ====== 2.4 =======
#include "opencv2/features2d/features2d.hpp"
BriefDescriptorExtractor brief(32);
GridAdaptedFeatureDetector detector(new FastFeatureDetector(10, true), DESIRED_FTRS, 4, 4);
// ...
detector.detect(gray, query_kpts); //Find interest points
brief.compute(gray, query_kpts, query_desc); //Compute brief descriptors at each keypoint location
// ====== 3.0 =======
#include "opencv2/features2d.hpp"
#include "opencv2/xfeatures2d.hpp"
using namespace cv::xfeatures2d;
Ptr<BriefDescriptorExtractor> brief = BriefDescriptorExtractor::create(32);
Ptr<FastFeatureDetector> detector = FastFeatureDetector::create(10, true);
// ...
detector->detect(gray, query_kpts); //Find interest points
brief->compute(gray, query_kpts, query_desc); //Compute brief descriptors at each keypoint location
@endcode
OpenCL {#tutorial_transition_hints_opencl}
------
All specialized `ocl` implementations has been hidden behind general C++ algorithm interface. Now the function execution path can be selected dynamically at runtime: CPU or OpenCL; this mechanism is also called "Transparent API".
New class cv::UMat is intended to hide data exchange with OpenCL device in a convenient way.
Following example illustrate API modifications (from [OpenCV site](https://opencv.org/opencl)):
- OpenCL-aware code OpenCV-2.x
@code{.cpp}
// initialization
VideoCapture vcap(...);
ocl::OclCascadeClassifier fd("haar_ff.xml");
ocl::oclMat frame, frameGray;
Mat frameCpu;
vector<Rect> faces;
for(;;){
// processing loop
vcap >> frameCpu;
frame = frameCpu;
ocl::cvtColor(frame, frameGray, BGR2GRAY);
ocl::equalizeHist(frameGray, frameGray);
fd.detectMultiScale(frameGray, faces, ...);
// draw rectangles …
// show image …
}
@endcode
- OpenCL-aware code OpenCV-3.x
@code{.cpp}
// initialization
VideoCapture vcap(...);
CascadeClassifier fd("haar_ff.xml");
UMat frame, frameGray; // the only change from plain CPU version
vector<Rect> faces;
for(;;){
// processing loop
vcap >> frame;
cvtColor(frame, frameGray, BGR2GRAY);
equalizeHist(frameGray, frameGray);
fd.detectMultiScale(frameGray, faces, ...);
// draw rectangles …
// show image …
}
@endcode
CUDA {#tutorial_transition_hints_cuda}
----
CUDA modules has been moved into opencv_contrib repository.
@cond CUDA_MODULES
- _cuda_ - @ref cuda
- _cudaarithm_ - @ref cudaarithm
- _cudabgsegm_ - @ref cudabgsegm
- _cudacodec_ - @ref cudacodec
- _cudafeatures2d_ - @ref cudafeatures2d
- _cudafilters_ - @ref cudafilters
- _cudaimgproc_ - @ref cudaimgproc
- _cudalegacy_ - @ref cudalegacy
- _cudaoptflow_ - @ref cudaoptflow
- _cudastereo_ - @ref cudastereo
- _cudawarping_ - @ref cudawarping
- _cudev_ - @ref cudev
@endcond
Documentation format {#tutorial_transition_docs}
--------------------
Documentation has been converted to Doxygen format. You can find updated documentation writing guide in _Tutorials_ section of _OpenCV_ reference documentation (@ref tutorial_documentation).
Support both versions {#tutorial_transition_both}
---------------------
In some cases it is possible to support both versions of OpenCV.
### Source code
To check library major version in your application source code, the following method should be used:
@code{.cpp}
#include "opencv2/core/version.hpp"
#if CV_MAJOR_VERSION == 2
// do opencv 2 code
#elif CV_MAJOR_VERSION == 3
// do opencv 3 code
#endif
@endcode
@note Do not use __CV_VERSION_MAJOR__, it has different meaning for 2.4 and 3.x branches!
### Build system
It is possible to link different modules or enable/disable some of the features in your application by checking library version in the build system. Standard cmake or pkg-config variables can be used for this:
- `OpenCV_VERSION` for cmake will contain full version: "2.4.11" or "3.0.0" for example
- `OpenCV_VERSION_MAJOR` for cmake will contain only major version number: 2 or 3
- pkg-config file has standard field `Version`
Example:
@code{.cmake}
if(OpenCV_VERSION VERSION_LESS "3.0")
# use 2.4 modules
else()
# use 3.x modules
endif()
@endcode
doc/tutorials/introduction/windows_armpl/windows_armpl_opencv.markdown
+169
View File
@@ -0,0 +1,169 @@
Building OpenCV with ARM Performance Libraries (ARMPL) on Windows {#tutorial_windows_armpl}
==================================================================
@prev_tutorial{tutorial_windows_install}
@next_tutorial{tutorial_linux_install}
| | |
| -: | :- |
@tableofcontents
Introduction {#tutorial_windows_armpl_intro}
============
This tutorial explains how to build OpenCV on Windows (AArch64) with
[ARM Performance Libraries (ARMPL)](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Libraries)
as a math backend. ARMPL provides optimized BLAS and LAPACK routines for Arm-based hardware
and can significantly accelerate OpenCV operations such as DFT and DCT.
Step 1: Download and Install ARM Performance Libraries {#tutorial_windows_armpl_download}
=====================================================
1. Open a browser and go to the
[ARM Performance Libraries Downloads page](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Libraries#Downloads).
2. Under **Windows / AArch64**, download the installer for your preferred toolchain:
| File | Architecture | Size |
|------|--------------|------|
| `arm-performance-libraries_26.01_Windows.msi` | AArch64 | ~240 MiB |
3. Run the downloaded `.msi` installer and follow the on-screen instructions.
The default installation directory is:
```
C:\Program Files\Arm Performance Libraries\armpl_26.01
```
Step 2: Configure System Environment Variables {#tutorial_windows_armpl_env}
=============================================
OpenCV's CMake scripts (and the ARMPL runtime itself) need to find the library files at both
build time and run time. Add the following entries to the **System** `PATH` variable:
1. Open **System Properties**, click **Advanced**, then **Environment Variables**.
2. Under **System variables**, select `Path` and click **Edit**.
3. Add the two paths below (adjust the version number if yours differs):
```
C:\Program Files\Arm Performance Libraries\armpl_26.01\lib
C:\Program Files\Arm Performance Libraries\armpl_26.01\bin
```
4. Click **OK** on every dialog to save.
Step 3: Clone OpenCV {#tutorial_windows_armpl_clone}
====================
```bat
git clone https://github.com/opencv/opencv.git
cd opencv
```
If you also need the extra modules:
```bat
git clone https://github.com/opencv/opencv_contrib.git
```
Step 4: Configure with CMake {#tutorial_windows_armpl_cmake}
============================
Create a build directory and run CMake with ARMPL support enabled.
**Without OpenMP (single-threaded ARMPL):**
```bat
mkdir build && cd build
cmake -G "Visual Studio 17 2022" -A ARM64 ^
-DWITH_ARMPL=ON ^
-DARMPL_ROOT_DIR="C:\Program Files\Arm Performance Libraries\armpl_26.01" ^
-DWITH_OPENMP=OFF ^
..
```
**With OpenMP (multi-threaded ARMPL):**
ARMPL ships both serial and OpenMP-enabled library variants. To use the multi-threaded variant,
enable OpenMP in CMake:
```bat
mkdir build && cd build
cmake -G "Visual Studio 17 2022" -A ARM64 ^
-DWITH_ARMPL=ON ^
-DARMPL_ROOT_DIR="C:\Program Files\Arm Performance Libraries\armpl_26.01" ^
-DWITH_OPENMP=ON ^
..
```
@note Enabling `WITH_OPENMP=ON` causes CMake to link against the `armpl_lp64_mp` (multi-threaded)
variant of ARMPL. Disabling it links against the serial `armpl_lp64` variant. Only one variant
should be enabled at a time to avoid symbol conflicts.
Step 5: Build and Install {#tutorial_windows_armpl_build}
=========================
Open the generated `.sln` file in Visual Studio and build the **Release** configuration, or
build from the command line:
```bat
cmake --build . --config Release --parallel
cmake --install . --config Release
```
Step 6: Verify the Build {#tutorial_windows_armpl_verify}
=========================
After a successful build, confirm that OpenCV detects ARMPL by running:
```bat
opencv_version --verbose 2>&1 | findstr /i armpl
```
You should see a line similar to:
```
ARMPL: YES (armpl_26.01)
```
Alternatively, check the CMake configuration log for the line:
```
-- ARMPL support: YES
```
Troubleshooting {#tutorial_windows_armpl_troubleshoot}
===============
**CMake cannot find ARMPL:**
Make sure `ARMPL_ROOT_DIR` points to the folder that contains both `include\` and `lib\`
sub-directories:
```
C:\Program Files\Arm Performance Libraries\armpl_26.01
bin\
include\
lib\
```
**Runtime error: DLL not found:**
Ensure that both the `lib\` and `bin\` directories are on the system `PATH` and that
you opened a new Command Prompt after adding them (changes are not picked up by already-open
sessions).
**Linker errors with OpenMP:**
If you see duplicate symbol errors when `WITH_OPENMP=ON`, make sure you are not also linking
against the serial ARMPL library. Pass `-DWITH_OPENMP=ON` consistently and clean the build
directory before re-running CMake.
See also {#tutorial_windows_armpl_seealso}
=========
- @ref tutorial_windows_install - Generic Windows build guide
- [ARM Performance Libraries documentation](https://developer.arm.com/documentation/101004/)
- @ref tutorial_general_install - General installation guide
doc/tutorials/introduction/windows_install/images/CMakeBuildOptionsOpenCV.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

doc/tutorials/introduction/windows_install/images/CMakeBuildWithWindowsGUI.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

doc/tutorials/introduction/windows_install/images/CMakeOutputPackageNotFound.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

doc/tutorials/introduction/windows_install/images/CMakePackageNotFoundWindows.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.9 KiB

doc/tutorials/introduction/windows_install/images/CMakeSelectBin.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

doc/tutorials/introduction/windows_install/images/CMake_Configure_Windows.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

doc/tutorials/introduction/windows_install/images/ChangeBuildVisualStudio.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

doc/tutorials/introduction/windows_install/images/IntelTBB.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

Some files were not shown because too many files have changed in this diff Show More