About consistency in join point handling of various transfer functions and "Legality" versus "SDI Code Value" naming convention.

[KelSolaar]

I was looking at the join points of various definitions:

Canon Log

log_encoding_CanonLog(x, bit_depth=10, out_legal=True, in_reflection=True):

    with domain_range_scale('ignore'):
        clog = np.where(
            x < log_decoding_CanonLog(0.0730597, bit_depth, False),

Canon Log 2

log_encoding_CanonLog2(x, bit_depth=10, out_legal=True, in_reflection=True):

    with domain_range_scale('ignore'):
        clog2 = np.where(
            x < log_decoding_CanonLog2(0.035388128, bit_depth, False),

Canon Log 3

log_encoding_CanonLog3(x, bit_depth=10, out_legal=True, in_reflection=True):

    with domain_range_scale('ignore'):
        clog3 = np.select(
            (x < log_decoding_CanonLog3(0.04076162, bit_depth, False, False),
             x <= log_decoding_CanonLog3(0.105357102, bit_depth, False, False),
             x > log_decoding_CanonLog3(0.105357102, bit_depth, False, False)),

Panasonic V-Log

log_encoding_VLog(L_in, bit_depth=10, out_legal=True, in_reflection=True, constants=VLOG_CONSTANTS):

V_out = np.where(
        L_in < cut1,

Sony S-Log

log_decoding_SLog(y, bit_depth=10, in_legal=True, out_reflection=True)

    with domain_range_scale('ignore'):
        x = np.where(
            y >= log_encoding_SLog(0.0, bit_depth, in_legal),

Sony S-Log3

log_decoding_SLog3(y, bit_depth=10, in_legal=True, out_reflection=True)

    x = np.where(
        y >= 171.2102946929 / 1023,

Fuji F-Log

log_decoding_FLog(F_out, bit_depth=10, in_legal=False, constants=FLOG_CONSTANTS)

    L_in = np.where(
        F_out < cut2,

There is a mix of hardcoded constants and computed join points but with a mix of various inconsistent argument values across definitions. I think we should try to be more consistent in the way we tackle that and in cases we need to deviate, comment the code accordingly. We might have discussed about some above cases but I don't remember.

@nick-shaw what do you think?

[KelSolaar]

In relation to that, we were discussing the out_legal and in_legal argument names and @nick-shaw suggested changing from out_legal=True to out_ire=False.

I'm adding a few images to support the discussion:

Canon Log

>>> colour.models.log_encoding_CanonLog(0.18, 10, out_legal=False, in_reflection=True)
# 0.32795389693580906

Sony S-Log2

>>> colour.models.log_encoding_SLog2(0.18, 10, out_legal=True, in_reflection=True) * 1023
# 347.34177270035104

Sony S-Log3

>>> colour.models.log_encoding_SLog3(0.18, 10, out_legal=True, in_reflection=True) * 1023
# 420.0

Fuji F-Log

>>> colour.models.log_encoding_FLog(0.18, 10, out_legal=False)
# 0.46333651051465585

[nick-shaw]

Currently out_legal=False produces a normalised version of the "IRE" value in the table, i.e. IRE / 100, and out_legal=True produces a normalised version of the code value, i.e. CV / 1023 for 10-bit. This is based on the notion that CV = full_to_legal(IRE), so if code value is the one which is the result of a "full to legal scale", it is the one referred to as "legal". However, while this may make sense for a "video" signal, it is less clear cut for log, and conflicts with the description in the Fuji and Sony documentation of F-Log and S-Log3 being "full range".

Discussion with @KevinJW suggests that referring to "IRE" may not be desirable either, as it is a misuse of the term (and Sony also confusingly refer to "linear IRE" in their documentation, which is something else again). Also changing out_legal=True to out_ire=False would change behaviour in some people's existing code. Therefore it may be better to consider renaming out_legal to something less ambiguous.

out_normalised_cv was suggested as suitably descriptive option.

[nick-shaw]

Regarding cut points, it is a tricky question. We have always tried in general to follow the published literature, have we not? Modifying constants to produce a more accurate round-trip is deviating from that. In some cases we have to use a calculated cut point where the curve is published in only one direction (e.g. the Canon Log 3 IDT). For S-Log1 we follow the spirit rather than the letter of the published formula, since the threshold is given as the integer code value 90, which does not precisely code linear zero. Perhaps we need more comments or docstring detail to explain these choices.

Similarly maybe we should have more explanation of the way the three S-Log encodings have been modified for consistent behaviour, where the Sony documentation varies in terms of "linear IRE" vs reflection, and code value vs IRE.

[KelSolaar]

Perhaps we need more comments or docstring detail to explain these choices.

Yes, this is pretty much where I'm going to, maybe a line or two explaining why the code is this way.

[KelSolaar]

@nick-shaw : I changed the arguments as discussed and added a bit of documentation so that one can get the values of the various tables in the references. Feel free to add more details or expand the docstrings if you think it is worth it. I will close this one for now.