Request for changes-110: Histogram Equalization

From OTBWiki
Jump to: navigation, search

Status

Summary

The aim here was to create an application allowing the user to improve a visual product by optimizing the contrast. The method used is an equalization of histogram, allowing the use of the whole available dynamic. It has been adapted to support also local equalization.

Implementation details

Classes and files

The modified files are those concerning CMake in the AppFiltering module

M       Modules/Applications/AppFiltering/app/CMakeLists.txt
M       Modules/Applications/AppFiltering/otb-module.cmake

A new module has been created in the Filtering groupe :

A       Modules/Filtering/Contrast/CMakeLists.txt
A       Modules/Filtering/Contrast/include/otbApplyGainFilter.h
A       Modules/Filtering/Contrast/include/otbApplyGainFilter.txx
A       Modules/Filtering/Contrast/include/otbComputeGainLutFilter.h
A       Modules/Filtering/Contrast/include/otbComputeGainLutFilter.txx
A       Modules/Filtering/Contrast/include/otbComputeHistoFilter.h
A       Modules/Filtering/Contrast/include/otbComputeHistoFilter.txx
A       Modules/Filtering/Contrast/include/otbCLHistogramEqualizationFilter.h
A       Modules/Filtering/Contrast/include/otbCLHistogramEqualizationFilter.txx
A       Modules/Filtering/Contrast/otb-module.cmake

Those three filters are small steps in the algorithm :

  • ComputeHistoFilter : compute the histogram (True story!) of the image, and applying the limitation if any is asked. The output is a vector image where a pixel represents the histogram of a tile.
  • ComputeGainLutFilter : compute the gain associated to each equalization of each tile. The output is a look up table (vector image) where a pixel represents the gain of the associated tile.
  • ApplyGainFilter : interpolate the gain in order to have a smooth transition between tiles.
  • CLHistogramEqualizationFilter : it is the a composite filter implementing CLAHE algorithm in order to allow people to use this method easily.

We also have this new filter :

A        Modules/Filtering/ImageManipulation/include/otbInPlacePassFilter.h

which is needed to correctly use and propagate requested regions.

Applications

An application has been created :

A       Modules/Applications/AppFiltering/app/otbContrastEnhancement.cxx
Block diagram

Here is the block diagram of the application. Only GainLut image is entirely stocked (output of the streaming filter). All the other images are streamed.

Tests

  • TU for each filter : done
  • TV for each filter : done
  • TV for application : done

Documentation

  • doxygen : done, but open to suggestion if it is too light
  • application documentation : done

Additional notes

To understand the algorithm here is the Wikipedia Link that gives a good explanation of what is done here. The difference will be for the L (limitation). Here the limitation is done with a factor (let us call it t). In this algorithm you have a histogram and you need to compute its target. For now the target is a flat histogram, meaning that its computation is quiet complicated : you need to divide the number of pixel in the histogram and divide it by the number of bin, you get hTarget the height of each bin (a number of pixel). Now, we state that in every bin of the input histogram its number of pixel should not be over t*hTarget. If it is then the bin is clip and the remaining pixel are equally re-distributed in all the histogram. A great improbement would be to allow a different input for the computation of the look up table, and image with a lower resolution for example.


Parameters: 
MISSING -in                  <string>         Input Image  (mandatory)
MISSING -out                 <string> [pixel] Output Image  [pixel=uint8/uint16/int16/uint32/int32/float/double] (default value is float) (mandatory)
        -bins                <int32>          Number of bin  (mandatory, default value is 256)
        -hfact               <float>          Contrast Limitation  (optional, off by default)
        -nodata              <float>          Nodata Value  (optional, off by default)
        -spatial             <string>         Spatial parameters for the histogram computation [local/global] (mandatory, default value is local)
MISSING -spatial.local.h     <int32>          Thumbnail height in pixel  (mandatory)
MISSING -spatial.local.w     <int32>          Thumbnail width in pixel  (mandatory)
        -minmax              <string>         Minimum and maximum definition [auto/manuel] (mandatory, default value is auto)
        -minmax.auto.global  <boolean>        Global  (optional, off by default)
        -minmax.manuel.min   <float>          Minimum  (optional, off by default)
        -minmax.manuel.max   <float>          Maximum  (optional, off by default)
        -mode                <string>         What to equalized [each/lum] (mandatory, default value is each)
        -mode.lum.red        <group>          Red Channel 
        -mode.lum.red.ch     <int32>          Red Channel  (mandatory, default value is 0)
        -mode.lum.red.coef   <float>          Value for luminance computation  (mandatory, default value is 0.21)
        -mode.lum.green      <group>          Green Channel 
        -mode.lum.green.ch   <int32>          Greenen Channel  (mandatory, default value is 1)
        -mode.lum.green.coef <float>          Value for luminance computation  (mandatory, default value is 0.71)
        -mode.lum.blue       <group>          Blue Channel 
        -mode.lum.blue.ch    <int32>          Blue Channel  (mandatory, default value is 2)
        -mode.lum.blue.coef  <float>          Value for luminance computation  (mandatory, default value is 0.08)
        -ram                 <int32>          Available RAM (Mb)  (optional, off by default, default value is 128)
        -inxml               <string>         Load otb application from xml file  (optional, off by default)
        -progress            <boolean>        Report progress 
        -help                <string list>    Display long help (empty list), or help for given parameters keys