Discerning data ranges

I have trouble discerning when data should be [0,255], [0,1], etc. E.g., input should be [0,255] but sometimes I have to remember to normalize to [0,1] and maybe convert back afterward. It is not very intuitive for someone who is not proficient in math or programming.

The unwritten rule in many places of the GImp API is that if your channel value is an integer, then it’s range is 0-255 and if it’s a float then it’s 0.-1.

pdb.gimp_context_set_foreground((.5,.5,1.))
pdb.gimp_context_set_foreground((128,128,255))

You can even mix them:

pdb.gimp_context_set_foreground((255,.5,0))

The difference between int and float is that the int is just digits, when the float must have decimal dot (as the last character if there is no fractional part): 25 is an int, 25. is a float.

How do I know when to use what for any given command?

E.g., -i expects [0,255], so I would have to do -/ 257 to a 16-bit image, whereas -blend_fade expects one of its arguments to be [0,1] (Using -blend_fade - #3 by David_Tschumperle).

ATM, I am learning by trial and error and asking questions.

There are actually no hard constraints on the value range of input/output images. G’MIC reads/writes a file just as an array of values, so if your input is 8bits RGB, you’ll get values in range [0,255]. If your input is 16bits, value range will be [0,65535]. Float-valued images (as some .tiff or .exr files) are not constrained to be in a certain range, so you cannot expect values to be in [0,1] or whatsoever (e.g. having +inf value happens sometimes in certain .tiff files). We assume the user has to know what kind of images he is loading/saving.
For instance, if you want to save a .jpg file, you’ll have to ensure the data you want to save fits the range [0,255] before saving, otherwise you’ll get some glitches in your saved picture.

Having said that (there are no hard constraints on image data), there are anyway ‘conventions’ followed by most of the G’MIC commands. For instance, the convention for commands applying on RGB images is that the value range of the R,G,B values should be in [0,255] (this doesn’t mean 8bits, as values are expressed as floats). That’s the case for instance when you convert between colorspaces (-rgb2hsl,…). Another convention for defining ‘masks’ of any type (opacity masks, inpainting masks, etc…) is having values in range [0,1].

Most of the time, the commands try to follow all the same conventions for the same kind of data.

Thanks for the clarification :smiley:. Ideally, it would save beginners a lot of time if the documentation provided information on the assumed array and argument ranges for any given command. That said, GUI-enabled commands do do that to a certain extent,

#@gui Sharpen [unsharp mask] : fx_unsharp, fx_unsharp_preview(0)
#@gui : Sharpening type = choice(0,"Gaussian","Bilateral")
#@gui : Spatial radius = float(1.25,0,20)
[...]

so I should probably prefer using them over their CLI counterpart wherever possible.

There is a mode in the GUI that shows you the CLI command it is going to run. I generally fine tune my settings in the GUI and copy my commands over to my script.

The docs are also open; contributions are welcome :slight_smile:

That is what I tend to do as well. As for contributing to the docs (:wink:), I will refrain until I have a much better grasp of G’MIC. ATM, I suppose I could keep track of the commands that I happen to be using.


Out of curiosity, here are a few approaches to documentation that is more nuanced:

I don’t use or own these programs, and am not saying that we should follow their example :stuck_out_tongue:.

Perhaps these docs are not as through, but there is similar at http://gmic.eu/reference.shtml#subsection3