levels "clamp input/ output" question

[nodal]

Afternoon,

Newbie here, what do the clamp input/ output tick boxes do in levels? I cannot see a difference on a 16 bit raw to tiff image that I play around with from time to time, ticking and unticking the input checkbox and looking at the preview histogram.

https://docs.gimp.org/2.10/en/gimp-tool-levels.html has no information and 

clamp input has the mouseover text "Clamp input values before applying output mapping" and Clamp output has "Clamp final output  values", both message seem to suggest that I am missing some critical piece of knowledge. I am aware the histogram is a representation on the tones or colours in an image and that levels alter the relative values on a mathematical way to alter the proportion of said tones to the human eye (as the computer does not care if big chunks and posterised splits appear in the histogram), but what is being clamped to what?

Philip.

[rich2005]

I will bump this post.

I do not know the answer except from a search.

https://gitlab.gnome.org/GNOME/gimp/commit/dce93c7d7e012ba9b85766e13d4f6dd62e21ec8d
Bug 762443 - Levels tool Output Level sliders works incorrectly
Add "clamp-input" (which clamps the input values to [0..1])
and "clamp-output" (which clips the final result to [0..1]),

Which reverts to Gimp 2.8 usage

.... and from this old post: https://www.gimpusers.com/forums/gimp-de...-light-rgb

Will the user see out of gamut (that is, out of the sRGB color space's gamut) RGB values expressed as RGB values that are less than 0.0 and/or greater than 1.0?

Yes. There is one complication: Users have the ability to choose to edit in different bitdepths, so the integer bitdepths will be clipped.

Quote:...I cannot see a difference on a 16 bit raw to tiff image that I play around with from time to time, ticking and unticking the input checkbox and looking at the preview histogram.

Maybe your image does not have any out-of-gamut colours.

You can try https://discuss.pixls.us/ for an answer

[nodal]

I do have a semi-answer on clamp input from an experiment, which I will post when I can work out the words as I can see what it's doing and the result but explanations are a little more difficult (and no idea on clamp output).

[nodal]

(10-02-2020, 04:07 PM)nodal Wrote: I do have a semi-answer on clamp input from an experiment, which I will post when I can work out the words as I can see what it's doing and the result but explanations are a little more difficult (and no idea on clamp output).

Nope, I am flummoxed. Attached is an image of three rectangles and a gaussian blur to spread out the tones on the histogram. Even if the 8 bit jpg is converted to 16 bit float using the mode menu, I still have issues understanding whether "levels" is actually broken.

Here's the theory as I understand it, if the output levels were really output levels then setting the black to 50, white to 205 (using 8 bit) then that should knock off all the deep blacks and whites producing a histogram that was blocky in the middle and no tones at either end. This does work as long as input levels is not touched. 

If the input levels are set to the same as the output ( 50,205 ) the ends of the histogram appear which I believe is intuitively wrong. This looks like is "scaling" where the maths goes, "what's the difference between the input and output", nothing, so multiply by 1 and you end up with the tones everywhere. In the paragraph above you state "output levels, knock off the black and white ends".

Setting 30, 225 to the input and 50, 205 output does give a cut off histogram as it's scaled down but not as dramatically as only altering the output levels. 

However if we go back to the initial example where input and output are set (50,205) the same and tick "clamp input", the ends of the histogram are cut off like you would expect, and if you alter the input values then it appears that the maths goes something like "clamp the input to remain inside the output histogram" whereas by default the maths appears to go scale the proportion of input to output. 

I cannot find an example that gets clamp output to work so don't know the logic behind it.

[BrianLink]

I think clamping is hardcoded to TRUE when invoked via colors-levels gui.  
That explains why attempting to see what it does is fraught.

Noted is that clamping is not provided in the color-levels gui interface in earlier gimp versions.
Also in other areas within the gimp source code are comments about using CLAMP to avoid error conditions created by other buggy parts of the code.   I suspect it was an overzealous coder.

Analysis of the code shows that clamping must be hardcoded to TRUE.

Code:

static inline gdouble
gimp_operation_levels_map (gdouble  value,
                          gdouble  low_input,
                          gdouble  high_input,
                          gboolean clamp_input,
                          gdouble  inv_gamma,
                          gdouble  low_output,
                          gdouble  high_output,
                          gboolean clamp_output)
{
 /*  determine input intensity  */
 if (high_input != low_input)
   value = (value - low_input) / (high_input - low_input);
 else
   value = (value - low_input);

 if (clamp_input)
   value = CLAMP (value, 0.0, 1.0);

 if (inv_gamma != 1.0 && value > 0)
   value =  pow (value, inv_gamma);

 /*  determine the output intensity  */
 if (high_output >= low_output)
   value = value * (high_output - low_output) + low_output;
 else if (high_output < low_output)
   value = low_output - value * (low_output - high_output);

 if (clamp_output)
   value = CLAMP (value, 0.0, 1.0);

 return value;
}

What is the intent of the code?
A)  The code is allowing a user to limit  the range of intensities from INPUT low to INPUT high.
B) Gamma is then applied to that range: new=old ^ (1/gamma). This entails the INPUT range to be normalized onto the unit interval 0 to 1 where INPUT low maps to 0 and INPUT high maps to 1.  Intensities below INPUT low are clamped to low and intensities greater than INPUT high are clamped to  high.
C) Then the gamma adjusted intensities now represented as a number between 0 to 1 are made to represent intensities from OUTPUT low to OUTPUT high.

The first clamping (line 109) implies that clamp input is hardcoded to TRUE.  Otherwise, by picking INPUT high very close to INPUT low, the computations (item B above) can be made arbitrary large.  0 is darkest and 1 is brightest.  Greater than 1 has no interpretation in this context.   Also, values below INPUT low become negative in the computation although there is some defensive code to avoid gamma adjusting a negative number.  The only way the code makes sense is if clamp_input is TRUE.  Lets put it this way........IF clamp_input is not hardcoded, there is some code somewhere else handling absurb conditions.

Having established that clamp_input hardcoded to TRUE,  the second clamping (line 121 output_clamped) has no effect.  The numbers already range 0 to 1.