mclahe 1.1.0rc1

Tensorflow implementation of the Multidimensional Contrast Limited Adaptive Histogram Equalization (MCLAHE) procedure

Multidimensional Contrast Limited Adaptive Histogram Equalization

Note: for the latest version of the software please visit VincentStimper/mclahe.

Introduction

Multidimensional Contrast Limited Adaptive Histogram Equalization (MCLAHE) is a multidimensional extension of the contrast enhancement procedure CLAHE for images. It can be applied to datasets with an arbitrary number of dimensions. This repository comprises an implementation in Tensorflow and one in NumPy only. Both can be run on multiple CPUs, and the Tensorflow implementation works with other hardware accelerators such as GPUs as well.

Installation

The Tensorflow implementation of the package can be installed via pip

pip install --upgrade https://github.com/mpes-kit/mclahe/archive/master.zip

To install the NumPy version, run

pip install --upgrade https://github.com/VincentStimper/mclahe/archive/numpy.zip

Requirements

The main package requires numpy and tensorflow. tensorflow needs to be installed manually depending on the hardware in use. The package supports tensorflow 2.0 and later versions. A comprehensive installation guide is given at the Tensorflow webpage. For the NumPy version, only numpy needs to be installed. The example notebook requires matplotlib in addition.

Sample datasets

Fluorescence microscopy

Fluorescence microscopy can be used to capture time resolved volumetric images of a developing embryo. To illustrate the effectiveness of MCLAHE we applied it to a dataset of an organism of species phallusia mammillata (available here). To reduce the noise in the data, we preprocessed it by a median filter with kernel size (2, 2, 2, 1) in the (x, y, z, t) space

            

The above image show a slice along the z-axis through the data. The unit hpf means hours post fertilization. Our hyperparameters of choice were the kernel size (20, 20, 10, 25), 256 bins in the histogram, and a clipping limit of 0.25. We used a global histogram range

Multidimensional photoemission spectroscopy

Multidimensional photoemission spectroscopy is a technique to map the electronic band structure in a 4D space consisting of two momentum (k_x, k_y), an energy (E), and a pump-probe time delay (t_pp) coordinate. In the raw data, the excited state (E > 0) is not visible. 4D CLAHE makes is visible while enhancing local features in the other states but preserving the temporal intensity changes.

Here, we used a kernel size of (30, 30, 15, 20) in (k_x, k_y, E, t_pp) space, 256 histogram bins, and a clipping limit of 0.02. We made use of the adaptive histogram range for processing this dataset.

Documentation

def mclahe(x, kernel_size=None, n_bins=128, clip_limit=0.01, adaptive_hist_range=False, use_gpu=True):
    ...

Parameters

• x: Input data as a numpy array with a arbitrary number of dimensions
• kernel_size: Tuple, list, or numpy array specifying the kernel size along the data dimensions. If kernel_size=None, the kernel size is set to 1/8 of the data size along each dimension. This is a typical choice for photographs. For more complex dataset, the kernel size should be roughly of the size of the features which shall be enhanced by MCLAHE.
• n_bins: Integer specifying the number of histogram bins used within each kernel. Typically, it is set to a power of two like 128 or 256 but any number could be chosen.
• clip_limit: Float being the share of voxels within a kernel at which the histogram shall be clipped. A clipping limit of 1 corresponds to standard histogram equalization and if it is smaller than 1 the contrast enhancement is limited. Since a relative histogram height of 1/n_bins corresponds to a uniform distribution the clipping limit should be higher than that.
• adaptive_hist_range: flag saying whether an adaptive histogram range (AHR) shall be used or not. With AHR, each histogram uses its own range determined by the minimum and maximum intensity in the kernel. Otherwise, the range is set by the global minimum and maximum within the data.
• use_gpu: flag specifying whether a GPU shall be used for computations if available. If there is no GPU available, this flag has no influence. If the dataset is very large it might be necessary to use CPUs only to not run out of memory on the GPU.

Citation

If you are using this package within your own projects, please cite it as

V. Stimper, S. Bauer, R. Ernstorfer, B. Schölkopf and R. P. Xian, "Multidimensional Contrast Limited Adaptive Histogram Equalization," in IEEE Access, vol. 7, pp. 165437-165447, 2019.

Bibtex code

@article{Stimper2019,
    author={V. {Stimper} and S. {Bauer} and R. {Ernstorfer} and B. {Schölkopf} and R. P. {Xian}},
    journal={IEEE Access},
    title={Multidimensional Contrast Limited Adaptive Histogram Equalization},
    year={2019},
    volume={7}, 
    pages={165437-165447},
    doi={10.1109/ACCESS.2019.2952899},
}