pycirclemedianfilter 0.1.7

Fast median filtering for circle-valued (phase / orientation) data — Python bindings for the C++ reference implementation

Circle median filter toolbox (CMF)

This toolbox contains a fast algorithm for median filtering of signals and images with values on the unit circle, for example phase or orientation data. The (arc distance) median filter for an image y with values on the unit circle is given by

where d denotes the arc distance length of two angles, and r, t are the horizontal and vertical "radii" of the filter mask.

The code is a reference implementation (in C++ with Matlab wrappers) of the algorithms described in the paper:

Martin Storath, Andreas Weinmann. Fast median filtering for phase or orientation data. IEEE Transactions on Pattern Analysis and Machine Intelligence, 40(3):639-652, 2018 (preprint)

See also

Updates

• 2025/02/18: Added Python bindings for the core C++ filtering code. See installation notes below.

Example

Left: A circle-valued image, i.e. every pixel takes its value on the unit circle (or in angular representation a value in (-pi, pi]). The values are visualized as hue component in the HSV color space. Right: Effect of the circle-median filter using a filter mask of size 7 × 7.

Runtime comparison

The time complexity w.r.t. the size of the filter mask is

• linear for non-quantized data
• constant for quantized data

Applications

• Smoothing of phase data, e.g. interferometric SAR images

• Smoothing of orientation data, e.g. wind directions

  

• Smoothing of vector fields in polar coordinates, e.g. optical flow images

Contents

• demos: some demos, self explanatory (implemented in Matlab)
• auxiliary: some useful helper functions (implemented in Matlab)
• filters: the fast algorithms for median filtering of circle valued data (implemented in C++ with Matlab wrappers)

Installation and usage

Python

• Installation via pip install pycirclemedianfilter.
• Important: The underlying implementation expects column-major order arrays. So convert data by data = np.asfortranarray(data) if necessary before calling the filter function. See the demos_python folder for examples.

Matlab

• From Matlab: Run CMF_install.m in the Matlab console and follow the demos
• From C++: Compile CMF_library.cpp. The relevant functions are medfiltCirc2D and medfiltCirc2DQuant. Their usage is described as comment in the CMF_library.cpp file.

References

How to cite

• M. Storath, A. Weinmann. Fast median filtering for phase or orientation data. IEEE Transactions on Pattern Analysis and Machine Intelligence, 40(3):639-652, 2018

Selected user applications

• S. Quan et al. Derivation of the Orientation Parameters in Built-Up Areas: With Application to Model-Based Decomposition. IEEE Transactions on Geoscience and Remote Sensing, 2018
• H. Salmane et al. A method for the automated detection of solar radio bursts in dynamic spectra. J. Space Weather Space Clim. 2018
• S. Quan et al., Derivation of the Orientation Parameters in Built-Up Areas: With Application to Model-Based Decomposition. IEEE Transactions on Geoscience and Remote Sensing. 2018
• B. Guo, J. Wen, Y. Han. Deep Material Recognition in Light-Fields via Disentanglement of Spatial and Angular Information. ECCV 2020