Native CLAHE support

Discuss digital image processing techniques and algorithms. We encourage its application to ImageMagick but you can discuss any software solutions here.
User avatar
whugemann
Posts: 289
Joined: 2011-03-28T07:11:31-07:00
Authentication code: 8675308
Location: Münster, Germany 52°N,7.6°E

Native CLAHE support

Post by whugemann »

I have been using Fiji's/ImageJ's built-in CLAHE filter a lot in recent years, and I have always wondered whether ImageMagick could provide a native CLAHE filter. The problem with Fiji is, that you have to apply the filter to each image individually (or write a yourself a script that does so for image sequences).

I have just seen that the original C code by Karel Zuiderveld is freely available at GitHub (https://gist.github.com/shellqiqi/3f498 ... 8e1a361cd0).

I know about Snipgo's implementation of CLAHE in Windows batch code at http://im.snibgo.com/eqlimit.htm#clahe, but could not get that code to work. (As far as I was able to find out, my standard Windows compilation lacks some feature that the code relies on. Debugging the batch code is very difficult.)

So how about native CLAHE support in IM?
Wolfgang Hugemann
User avatar
fmw42
Posts: 25562
Joined: 2007-07-02T17:14:51-07:00
Authentication code: 1152
Location: Sunnyvale, California, USA

Re: Native CLAHE support

Post by fmw42 »

It was no my list of enhancements to recommend when the developers have time. But their time is rather limited these days to bug fixes.

You can post this to the developers forum to put it on their list of features for the future. Or someone can contribute compatible code.
snibgo
Posts: 12159
Joined: 2010-01-23T23:01:33-07:00
Authentication code: 1151
Location: England, UK

Re: Native CLAHE support

Post by snibgo »

IM contains code to do all the operations for CLAHE, except for creating histograms as images. If it had that code, then adding CLAHE would be easily done by gluing the pieces together.
snibgo's IM pages: im.snibgo.com
User avatar
fmw42
Posts: 25562
Joined: 2007-07-02T17:14:51-07:00
Authentication code: 1152
Location: Sunnyvale, California, USA

Re: Native CLAHE support

Post by fmw42 »

snibgo wrote: 2018-11-19T10:47:55-07:00 IM contains code to do all the operations for CLAHE, except for creating histograms as images. If it had that code, then adding CLAHE would be easily done by gluing the pieces together.
So is your mkhisto code the missing piece or something similar that should be added to imagemagick first. Enhanced histograms (normalized and cumulative, with image output options) was on my list of recommendation also.
snibgo
Posts: 12159
Joined: 2010-01-23T23:01:33-07:00
Authentication code: 1151
Location: England, UK

Re: Native CLAHE support

Post by snibgo »

Yes. We've seen on 3 Implementations for Adaptive Gamma Correction that histograms are the foundation of many enhancement operations. IM contains most operations we want to apply to histograms, provided thay are Nx1 (or 1xN) images.
snibgo's IM pages: im.snibgo.com
User avatar
whugemann
Posts: 289
Joined: 2011-03-28T07:11:31-07:00
Authentication code: 8675308
Location: Münster, Germany 52°N,7.6°E

Re: Native CLAHE support

Post by whugemann »

As I said, Karel Zuiderveld published the original C code, which is rather concise.

Today I found out that ImageJ has a headless mode in which you can run it from the command line just like ImageMagick and use all its features and even macros and plugins. This sounds like a solution to my problem, as soon I will have got a little more aquainted to the ImageJ macro language ...

I will post a link to this discussion on the developers forum.
Wolfgang Hugemann
User avatar
fmw42
Posts: 25562
Joined: 2007-07-02T17:14:51-07:00
Authentication code: 1152
Location: Sunnyvale, California, USA

Re: Native CLAHE support

Post by fmw42 »

whugemann wrote: 2018-11-19T13:10:52-07:00 As I said, Karel Zuiderveld published the original C code, which is rather concise.

Is that code open source or restricted by some license?
kzuiderveld
Posts: 1
Joined: 2018-11-20T07:40:10-07:00
Authentication code: 1152

Re: Native CLAHE support

Post by kzuiderveld »

Howdy all,

I'm the original author of the CLAHE code. It was written in 1993 and published in Graphics Gems IV (K Zuiderveld, Contrast limited adaptive historam equalization. In: T. Heckbert, ed. Graphics Gems IV. Bosten: Academic Press, 1994, pp 474-485. The book is copyrighted (although I found a pdf of it on the web), but the code was put into the public domain. I have not revisited my code since I wrote it 25 years ago, but I think it's awesome that folks are using it.

After publishing the CLAHE code, I moved on to other things and I expected never to hear from CLAHE again. Interestingly, others have integrated my CLAHE code (often as-is) into other software (like matlab, imageJ, etc.) and meanwhile I accumulated thousands of citations from scientific articles in many applications areas (including deep learning) - CLAHE is now widely used.

So, please, feel free to grab my code and add it to Imagemagick!

Cheers, Karel
User avatar
whugemann
Posts: 289
Joined: 2011-03-28T07:11:31-07:00
Authentication code: 8675308
Location: Münster, Germany 52°N,7.6°E

Re: Native CLAHE support

Post by whugemann »

This seems to have been fixed: https://github.com/ImageMagick/ImageMagick/issues/1393

But how do I get in reach of the "latest beta"? I tried https://www.imagemagick.org/download/beta and downloaded https://www.imagemagick.org/download/be ... 86-dll.exe, but it has no -clahe option. I am still working with IM 6.x. Are new features also built into version 6 or do I have to switch to IM 7?
Wolfgang Hugemann
User avatar
magick
Site Admin
Posts: 11064
Joined: 2003-05-31T11:32:55-07:00

Re: Native CLAHE support

Post by magick »

New features are typically no longer added to IMv6, only IMv7. We will of course continue to support IMv6 and add relevant security patches as needed.
User avatar
whugemann
Posts: 289
Joined: 2011-03-28T07:11:31-07:00
Authentication code: 8675308
Location: Münster, Germany 52°N,7.6°E

Re: Native CLAHE support

Post by whugemann »

OK, I downloaded ImageMagick-7.0.8-14-Q16-x86-dll.exe and verified that is has a -clahe option. But how do I find out about the parameters it expects? I would expect three parameters: block size, histogram bins, maximum slope and, optional, 'fast or detailed mode', i.e. something along the line of

Code: Select all

magick in.jpg -clahe 127 256 3 out.jpg
but this only causes magick to crash.
Wolfgang Hugemann
User avatar
magick
Site Admin
Posts: 11064
Joined: 2003-05-31T11:32:55-07:00

Re: Native CLAHE support

Post by magick »

User avatar
whugemann
Posts: 289
Joined: 2011-03-28T07:11:31-07:00
Authentication code: 8675308
Location: Münster, Germany 52°N,7.6°E

Re: Native CLAHE support

Post by whugemann »

OK, got it. It would help if one would know about the default values and the range for the maximum contrast parameter. Usage:

Code: Select all

magick in.jpg -clahe 4x3+127+3 out.jpg
or, basically:

Code: Select all

magick in.jpg -clahe 4x out.jpg
  • I think there is a bug in the filter, as it produces diagobal stripes if the tiles are not square.
  • It crashes reliably when applied to larger images.
  • I also did not succeed in controlling the maximum contrast.
Nevertheless, it principially works.
Wolfgang Hugemann
User avatar
magick
Site Admin
Posts: 11064
Joined: 2003-05-31T11:32:55-07:00

Re: Native CLAHE support

Post by magick »

The problem you reported was fixed earlier today. A new Windows binary will be available sometime tomorrow.
User avatar
whugemann
Posts: 289
Joined: 2011-03-28T07:11:31-07:00
Authentication code: 8675308
Location: Münster, Germany 52°N,7.6°E

Re: Native CLAHE support

Post by whugemann »

OK, I have just verified that it is fixed in the current version 7.0.8-15. But I still cannot see any inluence of the clip-limit parameter. In Fiji/ImageJ its influence is quite drastic, the default value beeing 3.0. In ImageMagick, I cannot see any difference, regardless what value I supply for it. And https://www.imagemagick.org/script/comm ... .php#clahe gives no hint on what values IM expects for this parameter. Questions:
  • Is it a real or an integer value?
  • What is the range?
  • I am confused by the {+-} in front of the last two parameters. To my knowledge, most commands expect a plus a the default, as with lat, and a negative parameter tells the command something different. But how can you possibly have a negative count of histogram bins? Or what would a negative contrast threshold possibly mean?
BTW: Unless I missed something, the https://www.imagemagick.org/script/comm ... ptions.php page is hard to find via the web interface. (I landed on https://www.imagemagick.org/script/magick.php, where the option is not yet discribed.)
Wolfgang Hugemann
Post Reply