This is a basic implementation of the monogenic signal for 2D images using the C++ language and the OpenCV library. As well the monogenic signal, several related quantities that can be derived from the monogenic signal, such as Feature Symmetry and Asymmetry, are also implemented.
The monogenic signal is an alternative way of representing an image, which has a number of advantages for further processing. For an introduction to the monogenic signal and derived features with references to the relevant scientific literature, please see this document (PDF). If you find this or the monogenic library useful consider citation of the work.
Python bindings are also provided using pybind11 & cvnp, allowing you to use this library from Python with seamless NumPy integration.
Functions are provided to calculate the following quantities for 2D images:
- Monogenic Signal.
- Local Energy, Local Phase and Local Orientation to describe the local properties of image.
- Feature Symmetry and Asymmetry, respond to symmetric 'blobs' and boundaries with robustness to variable contrast.
- Oriented Feature Symmetry and Asymmetry, as above but also containing the polarity of the symmetry and the orientation of the boundaries.
This implementation was written with computational efficiency as a key objective, such that it can be used for video processing applications. It is designed to avoid redundant calculations when several quantities are desired from the same input image.
However, it is also straightforward and appropriate to use for calculating single quantities from still images.
- A C++ compiler supporting the C++14 standard (requires a relatively modern version of your compiler).
- The OpenCV library. Tested on version 4.2 and 4.5.5 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.
- (Optional) If you use a C++ compiler supporting the OpenMP standard (includes most major compilers on major platforms including MSVC, g++ and clang) there may be a small speed boost due to parallelisation.
- Python 3.6 or higher
- NumPy
- OpenCV Python (
cv2
installed viapip install opencv-python
) - The project uses Pybind11 and cvnp as submodules (see building instructions below)
Important: If you wish to build the Python bindings, you must initialize the git submodules before building:
git submodule update --init --recursive
This will download the required Pybind11 and cvnp dependencies needed for the Python bindings.
To build the project, use CMake with the BUILD_PYTHON_BINDINGS
option on/off to add python bindings, by default it is disabled:
mkdir build
cd build
cmake -DBUILD_PYTHON_BINDINGS=ON ..
make -j$(nproc)
This will build:
- The monogenic C++ library
- The C++ example executable (
monogenic_image_test
) If python bindings are enabled: - The Python module (
pymonogenic
)
The implementation consists of a single C++ class (monogenicProcessor
), defined
in the src/monogenicProcessor.cpp
and include/monogenic/monogenicProcessor.h
files. To use the code in your project, you just need to include the .cpp
file in the usual way, and add the repository's include/
directory in the
include path.
There is an example program showing how to use the class in the example/cpp/
directory. The comments in this file should demonstrate the basic usage.
After building the project, the Python module pymonogenic
will be available. It may be installed in the interpreter's site-packages folder using make install
. Alternatively add to the PYTHONPATH
environment variable the path to the build folder that contains the compiled pymonogenic library (build/python
in the example above), e.g. with export PYTHONPATH=build/python:${PYTHONPATH}
.
You can use it like this:
import cv2
import pymonogenic
# Load an image
image = cv2.imread('your_image.jpg', cv2.IMREAD_GRAYSCALE)
# Create a processor
processor = pymonogenic.MonogenicProcessor(image.shape[0], image.shape[1], wavelength=50.0)
# Calculate monogenic signal
processor.findMonogenicSignal(image)
# Get results
feature_asymmetry = processor.getFeatureAsymmetry()
feature_symmetry = processor.getFeatureSymmetry()
even_part = processor.getEvenFilt()
odd_y, odd_x = processor.getOddFiltCartesian()
To compile and run the C++ example:
# Build the project first (see Building section above)
cd build
# Run the example with a video file
./monogenic_image_test path/to/your/video_file.avi
To run the Python example:
# Make sure you've built the project first
cd example/python
# Run with an image file
python monogenicImageTest.py path/to/your/image.jpg
The Python example will:
- Load and process the specified image
- Calculate all monogenic signal components
- Display the results in separate windows (Even filter, Odd Y, Odd X, Feature Symmetry, Feature Asymmetry)
- Automatically scale the display windows to fit your screen
Written by Christopher Bridge at the University of Oxford's Institute of Biomedical Engineering.