Fred's ImageMagick Scripts: KNEEMAP

Fred's ImageMagick Scripts

Licensing:

My scripts are available free of charge for non-commercial (non-profit) use, ONLY.

For use of my scripts in commercial (for-profit) environments or non-free applications, please contact me (Fred Weinhaus) for licensing arrangements. My email address is fmw at alink dot net.

If you: 1) redistribute, 2) incorporate any of these scripts into other free applications or 3) reprogram them in another scripting language, then you must contact me for permission, especially if the result might be used in a commercial or for-profit environment.

Usage, whether stated or not in the script, is restricted to the above licensing arrangements. It is also subject, in a subordinate manner, to the ImageMagick license, which can be found at: http://www.imagemagick.org/script/license.php

Please read the Pointers For Use on my home page to properly install and customize my scripts.

KNEEMAP

Creates a symmetric soft knee-shaped curved mapping look up table \ and applies it to an image

Download Script

last modified: December 15, 2018

USAGE: kneemap [-a amount] [-c channels] [-l lutlength] [-g] infile outfile
USAGE: kneemap [-h or -help]

-a .... amount ....... amount of curvature for knee curve mapping
...................... transformation; -1<float<1; positive values
...................... non-linearly brighten the image and negative values
...................... non-linearly darken the image; default=0 for no change
-c .... channels ..... any valid IM combination of channels corresponding to
...................... the image's colorspace to which to apply the
...................... transformation: r,g,b,a, or c,m,y,k,a;
...................... default=all non-alpha channels
-l .... lutlength .... length of 1D lut; integer>0; default=1000
-g ................... enables the creation of a graph of the knee curve
...................... mapping transformation, which is then displayed
...................... automatically. There is a default setting below that
...................... can be changed to enable this to be save to a file
...................... named outfile_kneegraph.gif rather than just viewed.

PURPOSE: To create a symmetric soft knee-shaped curved mapping look up table and applies it to an image.

DESCRIPTION: KNEEMAP creates a symmetric soft knee-shaped curved mapping transformation similar to -evaluate log or -evaluate pow (-gamma), but which is symmetric. This transformation is generated as 1D lut and applied to the image using -clut to affect the intensity/color transformation. The transformation is sensitive to the desired channels specified.

ARGUMENTS:

-a amount ... AMOUNT is the amount of curvature for knee curve mapping transformation. Values are in the range 1<float<1. Positive values non-linearly brighten the image and negative values non-linearly darken the image. The default=0 for no change.

-c channels ... CHANNELS are any valid IM combination of channels corresponding to the image's colorspace to which to apply the transformation. Combinations include: r,g,b,a, or c,m,y,k,a (with no commas). The

-l lutlength ... LUTLENGTH is the length of 1D lut. Values are integer>0. The default=1000

-g ... enables the creation of a graph of the knee curve mapping transformation, which is then displayed automatically. There is a default setting below that can be changed to enable this to be save to a file named outfile_kneegraph.gif. The graph will be scaled to size 100x100.

My thanks to Max Usatov for bringing the dynamic range compressor or soft knee compressor to my attention. See http://www.scribd.com/doc/14599153/Fast-Dynamic-Range-Compression-for-Grayscale-Images

REQUIREMENTS: IM 6.3.5-7 is required to support the use of -clut

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.

Thanks to Anthony Thyssen for the technique used to draw the points efficiently

EXAMPLES

Original Image - Brightenning	arguments: a 0.5	Transformation Graph

Original Image - Darkening	arguments: a -0.5	Transformation Graph

Original Image - Brighten Channels	arguments: a 0.5 -c r	arguments: a 0.5 -c g	arguments: a 0.5 -c b

Original Image - Darken Channels	arguments: a -0.5 -c r	arguments: a -0.5 -c g	arguments: a -0.5 -c b

Comparison: Knee Map, Exponential Map, Logarithmic Map Knee Map is symmetric and uses values between -1 and 1 with 0 as no change. Exponential Map is not symmetric and values range from 0 to 1 and 1 to infinity with 1 as no change. Scaled Logarithmic Map is not symmetric and one-sided with values ranging from 0 to infinity. A no change value does not exist.
Knee Map	Exponential Map -evaluate pow -gamma	Scaled Logarithmic Map -evaluate log

What the script does is as follows:

Uses -fx to apply the soft knee transformation equation to a 1D gradient
Applies the 1D lookup table to the image using -clut

This is equivalent to the following IM commands.

convert -quiet -regard-warnings "$infile" +repage "$tmpI1"
if [ "$channels" != "" ]; then
channelize="-channel $channels"
else
channelize=""
fi
test=`convert xc: -format "%[fx:sign($amount)]" info:`
if [ "$test" = "-1" ]; then
amount=`convert xc: -format "%[fx:$amount/(1+$amount)]" info:`
fi
convert -size 1x$lutlength gradient: -rotate 90 -fx "u/($amount*(u-1)+1)" $tmpL1
convert $tmpI1 $tmpL1 $channelize -clut $outfile