Increasing Contrast

[tielur]

I've been looking but haven't been able to find a function that would increase the contract of an Image, is that possible?

[kipcole9]

@tielur I'm just about to release 0.34 that includes Image.brightness/2 and Image.saturation/2. Image.contrast/2 is targeted for the next release (currently on about a bi-weekly release schedule). Hope that's ok for you? I'll update here with I pushed a commit with an implementation.

[tielur]

Perfect, can't wait to use it!

[kipcole9]

Actually I had a few minutes and committed an initial implementation so you are welcome to try it out if you configure image from Github.

[tielur]

I definitely will! I'll give it a go this weekend

[kipcole9]

You might find Image.autolevels/1 of some utility as well. It is pretty much the same as the photoshop version - it spreads the histogram from dark to light. Depending on the image that also increases apparent contrast.

[tielur]

@kipcole9 thanks for the mention of autolevel/1, I'll have to give that a try. I did test out Image.contrast. It seems similar to what brightness does at least with my white background with black text. I'm not sure how other tools work but I think they may be using the hisogram when considering what the "max" contrast is?

For example if you open up an image in macos preview and grab the constrat to max it doesn't turn the whole image white

[tielur]

I'm also not entirely sure what may be happening but I noticed if I increase the contrast or brightness too high normalize/1 will fail.

For example:

image |> Image.brightness!(1.0) |> Image.normalize!()
%Vix.Vips.Image{ref: #Reference<0.3064193128.2407923736.253143>}

image |> Image.brightness!(2.0) |> Image.normalize!()
%Vix.Vips.Image{ref: #Reference<0.3064193128.2407923736.253124>}

image |> Image.brightness!(3.0) |> Image.normalize!()
** (CaseClauseError) no case clause matching: %Vix.Vips.Image{ref: #Reference<0.3064193128.2407923736.253146>}
    (image 0.35.0-dev) lib/image.ex:4283: Image.normalize!/1

image |> Image.contrast!(1.0) |> Image.normalize!()
%Vix.Vips.Image{ref: #Reference<0.3064193128.2407923736.253166>}

image |> Image.contrast!(3.0) |> Image.normalize!()
%Vix.Vips.Image{ref: #Reference<0.3064193128.2407923736.253174>}

image |> Image.contrast!(5.0) |> Image.normalize!()
** (CaseClauseError) no case clause matching: %Vix.Vips.Image{ref: #Reference<0.3064193128.2407923736.253176>}
    (image 0.35.0-dev) lib/image.ex:4283: Image.normalize!/1

[kipcole9]

I've fixed the return type that was causing that exception so a refresh of the dependency should at least get you past that point.

[kipcole9]

The implementation is based upon the "standard" contrast calculation which is to multiply the pixels by a contrast factor and then clamp them to the range of the original image format (8 bits per channel for sRGB). This is documented, for example, at https://docs.opencv.org/2.4/doc/tutorials/core/basic_linear_transform/basic_linear_transform.html

Given the naive implementation, large contrast factors will definitely push everything to white.

A better solution will be to use vips_tonelut which is a curves-based contrast adjustment and much more useful.

I'm thinking that:

• Image.autolevel/1 should be a reasonable default since it spreads the histogram over the range
• Image.contrast/2 is a brute force and needs careful selection of the contrast factor and therefore not very helpful on its own without examining the histogram (which isn't implemented)
• Image.tone_curve/2 (which doesn't exist yet) that uses vips_tonelut would be a reasonable general purpose solution.

[kipcole9]

I could implement a very RGB specific contrast function but I'm wary of ending up with too much implementation tied to that colourspace. On the other hand, if the naive contrast function isn't useful that's no good either.

I'll be curious how Image.autolevel/1 works out for you. It's similar to Image.normalize/1 but normalise just expands the luminance band (in lab colourspace) whereas auto level expands all levels. Therefore you would typically use auto level or normalise. I'm not sure what the results would be if you used both.

[kipcole9]

I will implement Contrast Limited Adaptive Histogram Equalization on the train to work this morning. That might be a good solution for "auto" contrast too.

[kipcole9]

After some more review I'm thinking of the following family of functions:

1. Image.autolevel/1 normalises an image band-by-band (already exists). This also has the byproduct of improving color casts in some circumstances.
2. Image.normalize/1 normalizes only the luminance of an image.
3. Image.equalise/1 normalizes all three bands of an image (whereas autolevel/1 does it band by band)
4. Image.local_contrast/2 uses a local histogram to perform local equalisation which has the effect of local contrast enhancements. I've implemented this function on my local machine but I'm seeing unexpected results and have opened an issue.

My main concern is that these functions are hard to comprehend unless the user has some knowledge of image processing. I'd welcome any suggestions on how to improve cognition and maybe refactor the functions to be more approachable.

[kipcole9]

Maybe they could be called:

• Image.equalize_all does histogram equalisation (contrast enhancement) across all bands together (Vix.Vips.Operation.hist_equal)
• Image.equalize_each does histogram equalisation band-by-band (today's autolevel/2)
• Image.equalize_luminance does luminance equalisation (today's normalize/1)
• Image.equalize_local does local contrast enhancement (Vix.Vips.Operation.hist_local)

That seems more digestible to me. Thoughts? (sorry for lots of commentary on my Monday morning).

[kipcole9]

How about:
Image.equalize/2 with the option:

• bands: :all
• bands: :each
• bands: :luminance

[kipcole9]

I have pushed a commit which implements the function above and removes Image.autolevel/1, Image.normalize/1.

[kipcole9]

As of now on main branch is:

• Image.contrast/2 as you've already tried. Probably too brutal.
• Image.autolevel/1 which normalises each band separately
• Image.normalize/1 which normalises only the luminance band
• Image.equalize/1 which normalises all bands by the same factor
• Image.local_contrast/2 which performs local contrast. Try with params window_size: 50, max_slope: 50 as a starting point.

Unless you have a better alternative I will go ahead and refactor these functions into a single Image.equalize/2 function per the previous comment.

Feedback and suggestions most welcome.

[kipcole9]

I have added one more function and I think it's the one you'll find most useful: Image.apply_tone_curve/2. Since it's a tone mapping function you won't blow out the highlights or crush the shadows so much. There are options to set black point, white point, shadow point, mid point and highlight point so it's quite flexible.

I don't plan any more contrast related functions for now unless you see a particular requirement. I'm going to work on creating histogram images now and then release - hopefully by the end of week. I suspect you'll find the histogram imaging useful in your work.

Example

iex> i = Image.open! "./test/support/images/Singapore-2016-09-5887.jpg"
%Vix.Vips.Image{ref: #Reference<0.3121742381.1532100637.44636>}

iex> {:ok, i2} = Image.apply_tone_curve i, shadows: -10, highlights: 10
{:ok, %Vix.Vips.Image{ref: #Reference<0.3121742381.1532100637.44650>}}

[tielur]

Thanks for all your hard work @kipcole9, I'm going to be getting back into updating our image processing pipeline soon so I'll let you know! Looks like a lot of new functions to play with though!

[kipcole9]

All good. I've also improved the Image.contrast/2 function so that its behaviour mirrors the CSS contrast function (as near as possible). I think you'll find its behaviour now more consistent and predictable. I would still tend to use Image.apply_tone_curve/2 for most cases with a default of shadows: -5, highlights: 5 but your needs may vary.

[kipcole9]

Since you are a print shop I will also add, for the release next week:

• Image.sharpen/2 although I would recommend Image.local_contrast/2 since it's the closest thing to an unsharp mask. Similar but not the same.

[kipcole9]

Hmm, seems Image.sharpen/2 will be able to perform unsharp masking.

[kipcole9]

I've added Image.sharpen/2 to the main branch. This is, depending on your requirements and testing, the last addition before the next release.

[kipcole9]

In summary, all the new "toys" you can play with. They aree primarily contrast, or contrast-related (from the changelog):

Enhancements

• Adds Image.equalize/2 which expands an image to fill the tone range. Equalization can be performed on all bands, on each band or only on the luminance band. This function replaces Image.normalize/1 and Image.autolevel/1.

• Adds Image.apply_tone_curve/2 which applies a tone curve to an image. This is typically used to affect overall image contrast.

• Adds Image.contrast/2 to apply simple contrast adjustments to an image. The contrast parameter is provided as a float > 0.0 with contrast less than 1.0 meaning reduce contrast and greater than 1.0 meaning increase contrast.

• Adds Image.local_contrast/2 which applies a Constrast Limited Adaptive histogram equalization (CLAHE) to improve local contrast in images.

• Adds Image.sharpen/2 to apply sharpening to an image.

• Adds Image.band_format/1 to return the band format of an image in Nx notation.

• Adds Image.with_band_format/3 to cast an image to a new band format, execute a function on the cast image and then re-cast the image back to its original band format if the function returns successfully.

• Adds Image.range/1 that returns the possible range of values for a pixel as a tuple in the form {min_value, max_value}.

• Adds Image.reduce_noise/2 and Image.reduce_noise!/2 that applies a median filter to reduce salt and pepper noise in an image.