Expose white level metadata

[kmilos]

Example:

import rawpy
import numpy as np

with rawpy.imread('Canon - EOS 1100D - RAW (3_2).CR2') as raw:
    print(f'Scaling ratio: {65535/(raw.white_level - np.array(raw.black_level_per_channel).max())}')

Scaling ratio: 5.6804195198058425

[letmaik]

Is this equivalent to raw.raw_image.max()?

[kmilos]

Nope, if you're underexposed your raw data doesn't reach the saturation value, which is the one used for scaling.

[letmaik]

Got it, stupid question. How come black level is per channel but white level is not?

[kmilos]

Not sure, probably because it's not so critical for the color shift as if when you get the black level wrong... It's not per channel in the TIFF/EP or DNG spec either, only per plane.

Speaking of which, the only doubt I have is how to name this property: I went for ISO (TIFF/EP & DNG) tag terminology, but we could also go for e.g. sat_level to align w/ dcraw/LibRaw terminology and existing user_sat

[letmaik]

Let's keep white_level, it seems more consistent. But yes, the docstring for user_sat should be updated to clarify this. Currently it's :param int user_sat: saturation adjustment. How about :param int user_sat: custom white level (saturation adjustment). This would make it more aligned with :param int user_black: custom black level. I really wonder why libraw/dcraw calls it saturation and not white level. Are you absolutely sure these are the same concepts?

[kmilos]

Yes.

For background see definition of "WhiteLevel" tag on p.30 of the DNG spec, and then the procedure in Chapter 5, compared to LibRaw's scale_colors() from around here

Also matches section 4.2 of this guide.

[letmaik]

Thanks for digging this out! Really appreciate it.