In the Colorize dialog (2.2 and 2.4), the Lightness slider runs from -100 to 100 but in HSV/HSL luminosity runs from 0 to 100. Is this a bug in the dialog or does Lightness not really mean Luminosity in this dialog (or do I misunderstand the range for Luminosity)? I didn't notice anything in the Bug db for it.

HSL is supposed to define a double hexcone where the vertical axis runs from black at one apex to white at the other, so maybe -100 to 100 makes sense, except I'm not sure what 0 lightness represents in that case.

Anyway, somebody asked me about this today and I didn't know the answer.

FYI, the online docs say the values run from 0-100 for this slider's range.

On Wed, 2007-02-07 at 08:57 +0100, Sven Neumann wrote:

As far as I understand the dialog doesn't show absolute values for Saturation and Lightness but relative ones. Perhaps the Saturation slider should also go from -100 to +100 then.

Saturation appears to be absolute. Lightness is relative. See below.

First of all someone should take a look at the code and find out what it really does. I very much doubt that anyone here can tell you this without looking at the code. So why don't you just have a look and tell us what you found?

Okay, here's how it looked to me. I had to trace through to figure out where the meat was being cooked, so this includes my tracing (in case I missed something):

Call sequence for changing the Lightness slider in the Colorize dialog:

* app/tools/gimpcolorizetool.c:colorize_lightness_adj_update() colorize_lightness_adj_update() is the callback in the Colorize dialog that handles Lightness slider changes.

* app/tools/gimpcolorizetool.c:colorize_lightness_adj_update() colorize_lightness_adj_update() calls colorize_update() after retrieving the L value from the dialog and saving it in a Colorize structure. The Colorize structure holds current HSL values as gdoubles
and two sets of 3 256-entry tables, one set of 3 for Luminance lookups and
one set of 3 for RGB lookups. Colorize is initialized (by colorize_init()) so that the Lum lookup table is non-zero.

* app/tools/gimpcolorizetool.c:colorize_update() colorize_update() calls colorize_calculate() before updating dialog
controls.

* app/base/colorize.c:colorize_calculate() Doesn't use the L component of Colorize structure. It simply computes
256 RGB lookup values (0-255) and sets L to i/255.0 for each component,
using the S and H components passed in the Colorize structure. The H
and S components are used as you would expect in HSV space: the value for H is divided by 360 and the value for S is divided by 100.

* app/tools/gimpimagemaptool.c:gimp_image_map_tool_preview() For the Colorize dialog, which has a preview, this function calls
gimp_image_map_tool_map().

colorize_lightness_adj_update() then calls gimp_image_map_tool_preview().

* app/tools/gimpimagemaptool.c:gimp_image_map_tool_preview() This call sequence eventually calls the gimp_colorize_tool_map() function to do the preview update.

* app/tools/gimpcolorizetool.c:gimp_colorize_tool_map() gimp_colorize_tool_map() calls gimp_image_map_apply(), which is passed
the colorize() function and a Colorize structure, along with the a structure containing a pointer to the drawable (re: preview) to update.

app/base/colorize.c:colorize() At each pixel across the width and height of the preview: Note: L = slider setting in the dialog, ie colorize->lightness "lum" inits to the combined luminance of the current pixel based on the luminance lookup table in the Colorize structure.

If L > 0, lum = (gdouble) lum * (100.0 - colorize->lightness) / 100.0; lum = += 255 - (100.0 - colorize->lightness) * 255.0 / 100.0;
else if L < 0
lum = (gdouble) lum * (colorize->lightness + 100.0) / 100.0; New pixel value is RGB = Colorize.RGBlookup[lum] (Alpha preserved)

This means:
If L = 0 then the pixel is always the luminance of the selected H/S combination.
If L < 0 then the pixel is the (absolute value of the lightness slider)%
of the current pixels luminance for the selected H/S combination.
If L > 0
Add the (lightness slider)% of 0-255 to (lightness slider)% of the
pixels current luminance and use that to compute the new color from
the RGB table based on the H/S combination.

It's unclear to me why the percent of 0-255 is added to a percent of the current luminance value instead of directly to the current luminance value though I can see why you might want to have -100 to 100 for the L slider: negative slider values reduce luminance of the current pixel while positive values increase it. You need to do this because your working relative to the current pixel and not on an absolute scale. In other words, the L slider is a percent increase or percent decrease in any given pixels luminance. Sort of.

On Wed, 2007-02-07 at 20:08 +0100, Michael Natterer wrote:

I don't remember the actual math involved and didn't try to follow your elaborate code path description. When I implemented this it was pretty clear from the beginning that -100% 'L' would have to make the image all black and +100% 'L' all white, and all values in between would be linear interpolations. That's how it was implemented in the end.

No voodoo involved :-)

The only point potentially open for discussion would be what the proper word for 'L' is.

I think Lightness is fine from an end user perspective.

The docs need to be updated to reflect the real meaning behind the slider (and it's name - the docs call it "Value" at the moment). The reason this came up at all was that someone asked what units were associated with those sliders, which led me to ask what the real meaning was for each slider. Now I know. :-)

I've got a minor patch for the english version of the online docs. I'll submit it to the gimp-docs mailing list.

Thanks.