Rotation Invariant Features
A small C++ library for calculating rotation invariant image features.
The purpose of this library is to calculate rotation invariant features from 2D images. These are a set of features that describe circular image patches in an image in a way that is invariant to the orientation of the patch. They can therefore be used to detect objects in any orientation in a straightforward way.
The emphasis is on providing a highly efficient implementation that:
- Integrates well with random forests machine learning algorithms.
- Only calculates the required features 'on-the-fly'.
- Uses Fourier-domain calculations to improve calculation speeds.
- Is thread-safe to allow learning algorithms using OpenMP multi-threading to use extract features avoiding data-races (note that only the functions that are explicitly described as thread-safe in the documentation should be used within parallel segments).
A detailed description of how the feature extraction method works, an evalution, and citations of relevant scientific literature can be found in my DPhil (PhD) thesis. You can find out more about how I am using the library on my website.
Disclaimer This is research-quality code I have provided to enable others to understand, reproduce and develop my research. It is not intended to be production quality code. It expects to be used in a certain way and there are many ways to break it by not using it in this way resulting in runtime crashes or unexpected results. There is very minimal error checking to detect these cases. Follow the examples and documentation closely though and it should be easy to use it correctly.
- A C++ compiler supporting the C++11 standard (requires a relatively modern version of your compiler).
- A C++ compiler supporting the OpenMP standard (includes most major compilers on major platforms including MSVC, g++ and clang).
- The OpenCV library. Tested on version 3.1.0 but most fairly recent versions should be compatible. If you are using GNU/Linux, there will probably be a suitable packaged version in your distribution's repository.
- The boost special functions library. Again there is likely to be a suitable packaged version on your GNU/Linux distribution.
Installation and Compilation
The library consists of a shared object library (
Windows) and a set of headers.
In order to use the library you will need to compile all the source files in the
src directory to create the object file and install it somewhere on the dynamic linker
path on your system. You will also need to copy the header files (in the
directory) to somewhere your compiler will find them, or point your compiler at them each time.
A makefile is provided to automate these tasks on most GNU/Linux operating systems
g++ compiler. To use this, navigate to the
build directory and
execute the following commands:
$ make $ sudo make install
You can also compile and install a debug version of the library (
$ make debug $ sudo make install-debug
You can uninstall both the release and debug versions with:
$ sudo make uninstall
For other environments you will need to work out how to do these steps yourself.
Once installed, to use the library in your C++ code, you just need to include the following header file in your source files:
Then when compiling your code, make sure to link against OpenCV and the
shared object, as well as using c++11 or later and the OpenMP extensions. E.g. to compile a source file called
my_program.cpp to produce an executable called
my_program, use something like the following:
$ g++ -std=c++11 -fopenmp -o my_program my_program.cpp `pkg-config --libs opencv` -lrifeatures
If you have decided not to install the library on your system as above, you just
need to add the
include directory to the list of directories your compiler looks at
for headers, and add the compiled shared object file to the linker dependencies.
The repository includes an example file (
example/rotinv_test.cpp) with plenty of comments that demonstrates how to use the basic functionality of the library.
You can compile it (once the library has been installed, as above) by running the
following from the
$ make example
You can then run it with on a video file (
$ ./example path/to/some/video/file.avi
$ doygen Doxyfile
This will generate an html version of the documentation in the
which you can view by opening
index.html in your browser.
This library was used in the following publications:
- C.P. Bridge, “Computer-Aided Analysis of Fetal Cardiac Ultrasound Videos”, DPhil Thesis, University of Oxford, 2017. Available on my website.
- C.P. Bridge, C. Ioannou, and J.A. Noble, “Automated Annotation and Quantitative Description of Ultrasound Videos of the Fetal Heart”, Medical Image Analysis 36 (Feb. 2017), pp. 147-161
- C.P. Bridge, Christos Ioannou, and J.A. Noble, “Localizing Cardiac Structures in Fetal Heart Ultrasound Video”, Machine Learning in Medical Imaging Workshop, MICCAI, 2017, pp. 246-255. Original article available here. Authors' manuscript available on my website.
If you use this library in your research, please consider citing these papers. Other relevant publications include:
- C.P. Bridge and J.A. Noble, “Object Localisation In Fetal Ultrasound Images Using Invariant Features”. Proceedings of the IEEE International Symposium on Biomedical Imaging, New York City, 2015
Finally, much of this work is based heavily on the following paper, with which I have no association:
- K. Liu et al. “Rotation-Invariant HOG Descriptors Using Fourier Analysis in Polar and Spherical Coordinates”. In: International Journal of Computer Vision 106.3 (2014), pp. 342–364
Written by Christopher Bridge at the University of Oxford's Institute of Biomedical Engineering.
The repository also includes some code written by J-P Moreau for calculation of the
struve function (the two functions in
struve.cpp) that was put up with no licensing
information here. For convenience I have included a slightly modified versions of these files. If you feel
that I have misappropriated your code, please get in touch.
This library is available under the GNU General Public License (GPL v3). For more information, see the licence file.