anthony wrote:
I have always struggled with exactly what -contrast-stretch and -linear-stretch actually does, and how best to example the command. Because of this I have only even provided minimal examples for these command.
I believe that my tests (see above) have clearly demonstrated how -contrast-stretch works. It uses histogram bins and clips by either count or percent count using the bins.
But to function properly the white-point value must be expressed as either:
total-pixels minus desired clip count
or
100% minus desired percent clip count
This requires that the user determine the total number of pixels if using count and not percent count. Unfortunately, such value may easily exceed the quantumrange (255 for Q8 and 65535 for Q16) and thus be an unallowed value. For example for a 20x20 pixel image and a desired count of 10, one needs to specify white-point=390 which is larger than 255. Similarly for a 300x300 image and a count of 10, one needs to specify 89990 which is greater than 65535. Thus in both situations the parameter value needs to be larger than what can be used for that Q level IM.
This implies that the way the white-point currently needs to be specified for non-percent count is actually unusable in most cases.
In fact, I tried to script it and found that out. So I tried to convert counts to percent, but that was limited by precision, so that a 1 or 10 pixel count converted to percent for a large image was equivalent to 100% for the white-point. Thus scripting the conversion of counts to white-point causes errors when trying to use counts directly and complete loss of precision when trying to convert counts to percent.
I don't really understand why one would actually want the precision of counts rather than just using percent. I don't expect to do such and can understand why Anthony has not made any examples that way. In fact, the use of counts is not practical at all, since for certain count values, one would have to specify non-allowed values for your IM Q level unless you are using Q32 or HDRI. Right now, low counts cause a problem as one needs total pixels minus count. But if changed to simply count, then large counts for clip values would be larger than allowed values. Thus counts are not really usable in general as not every possible count can be specified without a problem.
Thus I see only 4 meaningful choices:
1) Change the count mode so that low counts are usable (but high counts will not be usable) as it is more likely that one desires a moderately small clip on either end. But leave the percent count alone. This has inconsistent behavior.
2) Change both modes to use counts (so low counts can be used for the white-point value). This suffers backward compatibility, especially for the percent mode, but makes both modes consistent.
3) Eliminate the count mode altogether (as it is not totally practical for all count values) and leave the percent mode alone for backward compatibility
4) Eliminate the count mode altogether (as it is not totally practical for all count values) and change the percent mode to use white-point=percent count rather than 100% - percent count. This is more logical and conforms to Photoshop and GIMP. But loses backward compatibility
anthony wrote:
I am willing to see what others (including Fred) thinks should be done to fix these operators and bring them into a fully-defined useful state. I am even willing to do the work if we reach consensus. As such define EXACTLY what it should be, and we will get both documentation and the operator to agree.
My recommendation would be in order of my highest preference first 4) then 2), then 3) then 1), namely, to change modes even at the expense of backward compatibility.
But I am open to any other user's opinions about the loss of backward compatibility for the percent count mode. Does anyone else have existing scripts that would suffer if the white-point value for percent was changed?
anthony wrote:
... and of course other 'auto-level' type operations that has been missing from IM for a long time.
I do have a script that does auto-level type operations, now. I believe I wrote you about it. It finds the min and max values for stretch and an automatic determination of gamma. It applies both using the existing -level. Thus a new front end that simply computes the gamma and feeds to the core levels routine could make for a new IM auto-level function. The gamma formula is very simple.