README.md
1Introduction
2============
3
4The [Simd Library](http://ermig1979.github.io/Simd) is a free open source image processing and machine learning library, designed for C and C++ programmers.
5It provides many useful high performance algorithms for image processing such as:
6pixel format conversion, image scaling and filtration, extraction of statistic information from images, motion detection,
7object detection (HAAR and LBP classifier cascades) and classification, neural network.
8
9The algorithms are optimized with using of different SIMD CPU extensions.
10In particular the library supports following CPU extensions:
11SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2 and AVX-512 for x86/x64, VMX(Altivec) and VSX(Power7) for PowerPC (big-endian), NEON for ARM.
12
13The Simd Library has C API and also contains useful C++ classes and functions to facilitate access to C API.
14The library supports dynamic and static linking, 32-bit and 64-bit Windows, Android and Linux,
15MSVS, G++ and Clang compilers, MSVS project and CMake build systems.
16
17Library folder's structure
18==========================
19
20The Simd Library has next folder's structure:
21
22* `simd/src/Simd/` - contains source codes of the library.
23* `simd/src/Test/` - contains test framework of the library.
24* `simd/src/Use/` - contains the use examples of the library.
25* `simd/prj/vs2013/` - contains project files of Microsoft Visual Studio 2013.
26* `simd/prj/vs2015/` - contains project files of Microsoft Visual Studio 2015.
27* `simd/prj/vs2017w/` - contains project files of Microsoft Visual Studio 2017 (for Windows).
28* `simd/prj/vs2017a/` - contains project files of Microsoft Visual Studio 2017 (for Android).
29* `simd/prj/vs2019/` - contains project files of Microsoft Visual Studio 2019.
30* `simd/prj/cmd/` - contains additional scripts needed for building of the library in Windows.
31* `simd/prj/cmake/` - contains files of CMake build systems.
32* `simd/prj/sh/` - contains additional scripts needed for building of the library in Linux.
33* `simd/prj/txt/` - contains text files needed for building of the library.
34* `simd/data/cascade/` - contains OpenCV cascades (HAAR and LBP).
35* `simd/data/image/` - contains image samples.
36* `simd/data/network/` - contains examples of trained networks.
37* `simd/docs/` - contains documentation of the library.
38
39The library building for Windows
40================================
41
42To build the library and test application for Windows 32/64 you need to use Microsoft Visual Studio 2019 (or 2013/2015/2017).
43The project files are in the directory:
44
45`simd/prj/vs2015/`
46
47By default the library is built as a DLL (Dynamic Linked Library).
48You also may build it as a static library.
49To do this you must change appropriate property (Configuration Type) of **Simd** project and also uncomment `#define SIMD_STATIC` in file:
50
51`simd/src/Simd/SimdConfig.h`
52
53Also in order to build the library you can use CMake and MinGW:
54
55 cd .\prj\cmake
56 cmake . -DTOOLCHAIN="your_toolchain\bin\g++" -DTARGET="x86_64" -DCMAKE_BUILD_TYPE="Release" -DLIBRARY="STATIC" -G "MinGW Makefiles"
57 mingw32-make
58
59The library building for Android
60================================
61
62To build the library and test application for Android(x86, x64, ARM, ARM64) you need to use Microsoft Visual Studio 2017.
63The project files are in the directory:
64
65`simd/prj/vs2017a/`
66
67By default the library is built as a SO (Dynamic Library).
68
69The library building for Linux
70==============================
71
72To build the library and test application for Linux 32/64 you need to use CMake build systems.
73Files of CMake build systems are placed in the directory:
74
75`simd/prj/cmake/`
76
77The library can be built for x86/x64, PowerPC(64, big-endian) and ARM(32/64) platforms with using of G++ or Clang compilers.
78With using of native compiler (g++) for current platform it is simple:
79
80 cd ./prj/cmake
81 cmake . -DTOOLCHAIN="" -DTARGET=""
82 make
83
84To build the library for PowerPC(64, big-endian) and ARM(32/64) platforms you can also use toolchain for cross compilation.
85There is an example of using for PowerPC (64 bit, big-endian):
86
87 cd ./prj/cmake
88 cmake . -DTOOLCHAIN="/your_toolchain/usr/bin/powerpc-linux-gnu-g++" -DTARGET="ppc64" -DCMAKE_BUILD_TYPE="Release" -DLIBRARY="STATIC"
89 make
90
91For ARM (32 bit):
92
93 cd ./prj/cmake
94 cmake . -DTOOLCHAIN="/your_toolchain/usr/bin/arm-linux-gnueabihf-g++" -DTARGET="arm" -DCMAKE_BUILD_TYPE="Release" -DLIBRARY="STATIC"
95 make
96
97And for ARM (64 bit):
98
99 cd ./prj/cmake
100 cmake . -DTOOLCHAIN="/your_toolchain/usr/bin/aarch64-linux-gnu-g++" -DTARGET="aarch64" -DCMAKE_BUILD_TYPE="Release" -DLIBRARY="STATIC"
101 make
102
103As result the library and the test application will be built in the current directory.
104
105The library using
106=================
107
108If you use the library from C code you must include:
109
110 #include "Simd/SimdLib.h"
111
112And to use the library from C++ code you must include:
113
114 #include "Simd/SimdLib.hpp"
115
116In order to use [Simd::Detection](http://ermig1979.github.io/Simd/help/struct_simd_1_1_detection.html) you must include:
117
118 #include "Simd/SimdDetection.hpp"
119
120In order to use [Simd::Neural](http://ermig1979.github.io/Simd/help/namespace_simd_1_1_neural.html) you must include:
121
122 #include "Simd/SimdNeural.hpp"
123
124In order to use [Simd::Motion](http://ermig1979.github.io/Simd/help/namespace_simd_1_1_motion.html) you must include:
125
126 #include "Simd/SimdMotion.hpp"
127
128Interaction with OpenCV
129=======================
130
131If you need use mutual conversion between Simd and OpenCV types you just have to define macro `SIMD_OPENCV_ENABLE` before including of Simd headers:
132
133 #include <opencv2/core/core.hpp>
134 #define SIMD_OPENCV_ENABLE
135 #include "Simd/SimdLib.hpp"
136
137And you can convert next types:
138
139* `cv::Point`, `cv::Size` <--> `Simd::Point`.
140* `cv::Rect` <--> `Simd::Rectangle`.
141* `cv::Mat` <--> `Simd::View`.
142
143Test Framework
144==============
145
146The test suite is needed for testing of correctness of work of the library and also for its performance testing.
147There is a set of tests for every function from API of the library.
148There is an example of test application using:
149
150 ./Test -m=a -tt=1 -f=Sobel -ot=log.txt
151
152Where next parameters were used:
153
154* `-m=a` - a auto checking mode which includes performance testing (only for library built in Release mode).
155In this case different implementations of each functions will be compared between themselves
156(for example a scalar implementation and implementations with using of different SIMD instructions such as SSE2, AVX2, and other).
157Also it can be `-m=c` (creation of test data for cross-platform testing), `-m=v` (cross-platform testing with using of early prepared test data)
158and `-m=s` (running of special tests).
159* `-tt=1` - a number of test threads.
160* `-fi=Sobel` - an include filter. In current case will be tested only functions which contain word 'Sobel' in their names.
161If you miss this parameter then full testing will be performed.
162You can use several filters - function name has to satisfy at least one of them.
163* `-ot=log.txt` - a file name with test report (in TEXT file format). The test's report also will be output to console.
164
165Also you can use parameters:
166
167* `-help` or `-?` in order to print help message.
168* `-r=../..` to set project root directory.
169* `-pa=1` to print alignment statistics.
170* `-c=512` a number of channels in test image for performance testing.
171* `-h=1080` a height of test image for performance testing.
172* `-w=1920` a width of test image for performance testing.
173* `-oh=log.html` - a file name with test report (in HTML file format).
174* `-s=sample.avi` a video source (See `Simd::Motion` test).
175* `-wt=1` a thread number used to parallelize algorithms.
176* `-fe=Abs` an exclude filter to exclude some tests.
177* `-mt=100` a minimal test execution time (in milliseconds).
178