[Proposed docs for "-intensity" now in thread for approval.] When converting a grayscale image to color...

[Dabrosny]

Originally, I just wanted grayscale images (linear and nonlinear) to work the same as RGB and sRGB, but I discovered that grayscale images are now far more complex than color images, in the way that their linearity is not determined by their colorspace, and the -intensity affects not only how a grayscale image is calculated from a color image, but also labels the grayscale image itself as to whether it will be treated as nonlinear or linear by further processing. This raised a lot of questions that didn't arise when there were simply some (even if too many) separate linear and nonlinear gray colorspaces, before these were combined into the single "Gray".

Here are some questions that the documentation of "-intensity" (or elsewhere?) needs to cover in my opinion:

1. Does -intensity change a particular image's attributes or a global setting?
2. What does it do?
3. What is its default value?
4. Does this intensity attribute have a different effect when it is on a Gray image vs on a color image?
5. What effect does a Gray image's intensity attribute have when I write it to a JPEG or other file formats?
6. How is it affected by other image attributes such as gamma?
7. What attributes of a Gray image does IM use in order to interpret its numeric values as linear vs nonlinear (like it uses colorspace RGB vs sRGB for color images)?
8. What sets these attributes initially on a Gray image?
9. What happens if I assign or change these attributes on an existing Gray image?
10. Is the intensity attribute of a Gray image related to the familiar sRGB vs RGB distinction of a color image, and how do they differ?
11. Why does it matter whether IM treats an image as linear or nonlinear - how does this affect my results?
12. I understand the distinction between -colorspace (RGB/sRGB) vs. -set colorspace (RGB/sRGB) operations as they relate to linear/nonlinear color images (one also converts the data values and the other doesn't); is there a similar distinction with intensity on Gray images?
13. How do I convert a linear Gray image to or from a nonlinear one, and will this change the numeric pixel values in my image, or only how these values are used?
14. What happens when I convert a Gray image to color using -colorspace sRGB or -colorspace RGB and how does the intensity attribute of the Gray image affect this?

[fmw42]

Most of these question I cannot answer as they pertain to the coding.

[Dabrosny]

In order to understand what -intensity does and how it replaces the old nonlinear and linear grayscale colorspaces, I did some experimentation and this "-intensity" documentation entry is based on what I believe is the actual behavior of IM 7 (at least in 7.0.6 x64 q16 HDRI).

See my preceding post on this thread for a list of questions that I felt this needed to answer.

I included a form of Snibgo's idea related to the possible use of sRGB and RGB colorspaces even for single-channel grayscale images.

I don't know whether perhaps some of what I'm documenting here is unintended behavior.

(I haven't yet tried to change the documentation for the -grayscale operation because its behavior has an inconsistency that I'll probably submit as a bug report later, rather than merely documenting its current behavior.)

This isn't formatted like the actual documentation, but you get the idea.

------------------------------------------------------------------------------
-intensity method

set image attribute specifying the method to generate intensity values from a non-Gray image or pixel, and that identifies a Gray image as linear or nonlinear

This sets the intensity attribute of the current image(s), and also sets a global default for any further images lacking this attribute themselves. The form +intensity unassigns the intensity.

On a color image (non-Gray colorspace), this attribute determines the formula that will be used by -colorspace Gray to convert to grayscale, and in other situations where an operator needs to calculate a single grayscale value for some purpose, from the image's red, green, and blue pixel components.

The following methods are available (R,G,B indicate linear channels while R',G',B' indicate nonlinear):

Rec709Luminance converts to RGB and then uses 0.212656R + 0.715158G + 0.072186B to get a linear grayscale (equal to luminance Y as in XYZ colorspace)

Rec601Luminance converts to RGB and then uses 0.298839R + 0.586811G + 0.114350B to get a linear grayscale

Rec709Luma converts to sRGB and then uses 0.212656R' + 0.715158G' + 0.072186B' to get a nonlinear grayscale

Rec601Luma converts to sRGB and then uses 0.298839R' + 0.586811G'+ 0.114350B' to get a nonlinear grayscale

If the image has no intensity attribute, the global intensity set by the most recent -intensity is used. If there is no global intensity assigned, then the Rec709Luma nonlinear grayscale formula is currently used by default.

The -colorspace Gray conversion on an existing non-Gray image will set an appropriate gamma of 1 (linear) or 0.454545 (nonlinear) as well as retaining the intensity attribute on the resulting Gray image, so that further operations on this Gray image will know whether to treat it as linear or nonlinear. (Note: if a nonlinear image were ever treated as linear or vice-versa, then conversion back to a non-Gray colorspace would be incorrect, and conversion to an external file format (such as JPEG) would create an image file that would be too dark or too light when viewed.)

Whereas a non-Gray image is treated by IM as having nonlinear or linear values based solely on its colorspace irrespective of gamma (or of intensity), a Gray image will be treated as having linear values only if its intensity attribute is Rec709Luminance (or Rec601Luminance) and its Gamma attribute is exactly 1. For all other combinations of intensity and gamma value (or lacking one or both), the Gray image will be treated as nonlinear (like sRGB).

Using -intensity (or +intensity) on an existing Gray image can change the interpretation of the image's values (as linear vs. nonlinear) without a corresponding change in those values themselves, much like -set colorspace changes the interpretation of a non-Gray image's values without changing those values. You should also -set gamma (1 for linear or 0.454545 for nonlinear) to be consistent with the new intensity, because, unlike -set colorspace, setting the intensity does not change gamma. If you set a linear intensity on a Gray image but don't also set the gamma to precisely 1, then IM will continue to treat the image as nonlinear. But if you set a nonlinear intensity (or remove the intensity) for a Gray image, it will be treated as nonlinear (like sRGB) irrespective of gamma.

While there is no operator that will convert between linear and nonlinear Gray images, an alternative is to use -colorspace RGB or -colorspace sRGB, which will keep the image as a single channel initially (and replicate it into three channels when needed by a further operation), although no longer identified as Gray colorspace. For many output file formats such as JPEG and PNG, the image will (for default settings) automatically be saved as a single-channel grayscale image if all three color channels are equal throughout the image, and if read back into IM this will become Gray colorspace and threfore subject to the behavior documented here for Gray rather than that of sRGB or RGB.

The following intensity methods are mathematical in nature and will use the current value in the image's respective r,g,b channel regardless of its colorspace or whether these channels are linear or nonlinear.

Brightness max(r, g, b )

Lightness (min(r, g, b) + max(r, g, b)) / 2.0

Average (r + g + b) / 3.0

MS (r^2 + g^2 + b^2) / 3.0

RMS sqrt( (r^2 + g^2 + g^2) / 3.0 )

These methods are often used for other purposes, such as generating a grayscale difference image between two color images (using -compose 'Difference' composition.

For example The 'MS' (Mean Squared) setting is good for minimizing color error comparisions. While... The method 'RMS' (Root Mean Squared) for example is appropriate for calculating color vector distance, from a color difference image. This is equivalent to the color only component of the -fuzz factor color compare setting.

See also -grayscale which applies one of the above formulas directly to convert an image to Gray without setting the global default intensity.

To print a complete list of possible pixel intensity setting methods, use -list intensity.

Operators affected by the -intensity setting of a non-Gray image include:

-adaptive-blur
-adaptive-sharpen
-black-threshold
-clut (when mapping grayscale CLUT image to alpha channel if set by -channels)
-colors for gray colorspace
-compose {LightenIntensity, DarkenIntensity, CopyOpacity, CopyBlack}
-contrast-stretch
-distort {ErodeIntensity, DilateIntensity}
-normalize
-random-threshold
-selective-blur
-shade
-threshold
-tint
-white-threshold

[fmw42]

Whereas a non-Gray image is treated by IM as having nonlinear or linear values based solely on its colorspace irrespective of gamma

I am not sure this is true. I think IM will make sure a linear image has gamma=1. Most external color formats do not have a linear RGB option and only treat the image as linear if gamma=1.

But I will defer to the IM developers to correct my statements.

Also I hope other read and comment on your documentation as well as the IM developers.

But I will wait until you resolve any potential bugs in -grayscale or -intensity.

[Dabrosny]

Whereas a non-Gray image is treated by IM as having nonlinear or linear values based solely on its colorspace irrespective of gamma

I am not sure this is true. I think IM will make sure a linear image has gamma=1.
...
But I will defer to the IM developers to correct my statements.

A -colorspace RGB or -set colorspace RGB will set gamma=1, but when it comes time for IM to convert to another colorspace (for example in order to write to a file format that only supports a particular colorspace) it produces the same result regardless of what you might have set gamma to. It will do the transformations of the data as if RGB is linear and sRGB is the usual variant of 0.454545 and the gamma won't affect this. I don't think we need developers in order to test this. For example, here we convert back and forth between sRGB and RGB:

Code: Select all

$ magick -verbose rose: -identify -colorspace RGB -identify -colorspace sRGB -identify null: | myformatting
Colorspace: sRGB; mean: 105.147 (0.412341); Gamma: 0.454545;
Colorspace: RGB;  mean: 56.0028 (0.219619); Gamma: 1;       
Colorspace: sRGB; mean: 105.147 (0.412341); Gamma: 0.454545;

Now here we set gamma before each colorspace transformation to see whether it affects the result:

Code: Select all

$ magick -verbose rose: -identify -set gamma 1 -colorspace RGB -identify -set gamma 0.1 -colorspace sRGB -identify null: | myformatting
Colorspace: sRGB; mean: 105.147 (0.412341); Gamma: 0.454545;
Colorspace: RGB;  mean: 56.0028 (0.219619); Gamma: 1;       
Colorspace: sRGB; mean: 105.147 (0.412341); Gamma: 0.454545;

Gamma doesn't affect the way IM treats the image and it doesn't affect the result, and IM overwrites the gamma anyway so it doesn't even get propagated to an external file unless you set it after the last colorspace conversion.
It doesn't treat the sRGB image as linear even when gamma=1.
Or was there some other situation that you were thinking of where gamma might affect how IM treats a (non-Gray) image with respect to its colorspace?

Also I hope other read and comment on your documentation as well as the IM developers.

Thanks. Me too.

But I will wait until you resolve any potential bugs in -grayscale or -intensity.

I don't think I said there were bugs in -intensity, so please don't wait for that.
I don't plan on doing anything with -grayscale in the near future, so please don't wait for that either.
Let's get "-intensity" documented first.

[fmw42]

(I haven't yet tried to change the documentation for the -grayscale operation because its behavior has an inconsistency that I'll probably submit as a bug report later, rather than merely documenting its current behavior.)

Your issue was with -grayscale. But they both are intertwined internal to IM. So I do not want to change any documentation until we see if any bug fix related to -grayscale affects -intensity.

Also as I said, I want to hear back from other users and the IM development team before I make any documentation changes and also get approval especially since your documentation is rather long. The team may prefer to have a shorter version in the options page and a link to your longer version.

[Dabrosny]

(I haven't yet tried to change the documentation for the -grayscale operation because its behavior has an inconsistency that I'll probably submit as a bug report later, rather than merely documenting its current behavior.)

Your issue was with -grayscale. But they both are intertwined internal to IM. So I do not want to change any documentation until we see if any bug fix related to -grayscale affects -intensity.

The behavior of -grayscale has no effect on the behavior of -intensity, and the potential bug in -grayscale I mentioned won't even make sense until the intensity image attribute itself (irrespective of the operations that set it) is documented, which is part of what I'm trying to do here. I regret that I ever mentioned -grayscale if this is going to be a reason not to change the documentation for -intensity.

...especially since your documentation is rather long...

Yes, it got long because the behavior of IM got very complicated with the intensity acting as a partial substitute for simply having both a linear and a nonlinear grayscale colorspace

[fmw42]

Why would documentation change anything related to some potential bug report?

[Dabrosny]

Why would documentation change anything related to some potential bug report?

Because a bug is when the software does not behave as intended, and without documentation we don't know what is intended.
Until there is agreement on what the intensity image attribute (on a Gray image) does at all, I can't show that the behavior of -grayscale is sometimes inconsistent with it.

[fmw42]

But you said -intensity is unrelated to -grayscale. So your comment is a bit confusing to me. Nevertheless, not to argue, I will make any documentation changes that are approved by the IM developer. But I need him to confirm you statements. I rarely have used -intensity, so I am not that familiar enough to comment on its behavior. My limited use of linear grayscale images was via -grayscale. Perhaps snibgo or one of the other users might also comment. I think others understand -intensity better than I do.

[Dabrosny]

But you said -intensity is unrelated to -grayscale.

I didn't say they were unrelated, but I merely said "The behavior of -grayscale has no effect on the behavior of -intensity". In other words "-intensity" does what it does, whether or not "-grayscale" even exists or works correctly.

Nevertheless, not to argue, I will make any documentation changes that are approved by the IM developer.

Much appreciated.

[snibgo]

I welcome Dabrosny's work on this. I can't check the proposed documentation as I don't have a recent version of IM (and won't in the near future).

I don't know the answers to Dabrosny's questions (a) to (n).

Personally, I hardly use "-intensity". (Just one script, histoPeaks.bat.) I use "-grayscale" in 17 scripts, mostly "-grayscale RMS".

For my work in linear (as opposed to sRGB etc), the processing is the same whether the image happens to have colour. As I said upthread, IM's metadata about linearity is confusing, partly because it accommodates many file formats. This creates difficulty when creating linear workflows. I take a pragmatic (or cowardly) route: convert the image to linear, then "-set colorspace sRGB" to pretend it is in sRGB so IM won't convert it to sRGB when writing to files or doing floodfills or whatever.

[Dabrosny]

I welcome Dabrosny's work on this. I can't check the proposed documentation as I don't have a recent version of IM (and won't in the near future). I don't know the answers to Dabrosny's questions (a) to (n).

Thanks. Those q's were just meant to describe the motivation for my proposed documentation, which is a bit long because it attempts to answer many of them.

As I said upthread, IM's metadata about linearity is confusing, partly because it accommodates many file formats. This creates difficulty when creating linear workflows.

Exactly! I've spent countless hours just trying to figure out how the gray linearity works, since it works completely differently from color image linearity (which is based on colorspaces).
(Things were much simpler back when there were both linear and nonlinear grayscale colorspaces, although there really didn't need to be more than one of each as -intensity could still choose the particular nonlinear or linear formula you want to use.)

I take a pragmatic (or cowardly) route: convert the image to linear, then "-set colorspace sRGB" to pretend it is in sRGB so IM won't convert it to sRGB when writing to files or doing floodfills or whatever.

I can't say I blame you. Perhaps there should be some additional principles for IM operations like "don't change the colorspace" (or, rather, change it for the operation if necessary but then change it back to what it was). Of course when writing to a file there are always going to be limitations imposed by the file format. As we discussed earlier, "-set colorspace Undefined" might be more elegant than "falsely" setting sRGB, but I'm not sure if it would do what you need.

[Dabrosny]

I'm thinking maybe i should post the docu proposal as a new topic rather than it being buried here in the middle of page 3. If so, should it be here in bugs or perhaps in Developers?

[fmw42]

Developers