https://github.com/mstorath/circlemedianfilter

Fast median filter for circle-valued data, for example signals or images describing phase or orientation
https://github.com/mstorath/circlemedianfilter

circle cpp denoising manifold matlab median-filtering orientation orientation-data phase python3 unit-circle

Last synced: 7 months ago
JSON representation

Fast median filter for circle-valued data, for example signals or images describing phase or orientation

• Host: GitHub
• URL: https://github.com/mstorath/circlemedianfilter
• Owner: mstorath
• License: mit
• Created: 2017-04-05T09:25:07.000Z (about 9 years ago)
• Default Branch: master
• Last Pushed: 2025-06-27T08:03:54.000Z (10 months ago)
• Last Synced: 2025-09-08T04:23:51.036Z (7 months ago)
• Topics: circle, cpp, denoising, manifold, matlab, median-filtering, orientation, orientation-data, phase, python3, unit-circle
• Language: C++
• Homepage: https://mstorath.github.io/CircleMedianFilter/
• Size: 2.45 MB
• Stars: 16
• Watchers: 2
• Forks: 6
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# 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.](https://doi.org/10.1109/TPAMI.2017.2692779)

IEEE Transactions on Pattern Analysis and Machine Intelligence, 	40(3):639-652, 2018  ([preprint](https://hci.iwr.uni-heidelberg.de/sites/default/files/profiles/mstorath/files/storath2017fast.pdf))

See also [![View Circle Median Filter on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://de.mathworks.com/matlabcentral/fileexchange/62509-circle-median-filter)

## Updates

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

### Example 

![alt tag](https://hci.iwr.uni-heidelberg.de/sites/default/files/publications/teaserimages/1908951751/mediancircularrevision_teaser_small.png)

*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

   ![alt tag](docs/InSAR.png)

- 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.](https://doi.org/10.1109/TPAMI.2017.2692779) 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