[FEATURE REQUEST] Add an inverse modifier to oiiotool's --ociodisplay option

[doug-walker]

Problem Description

The oiiotool --ociodisplay option is very useful for applying an OCIO DisplayViewTransform. This takes an image in a "src" color space and then applies a "view" transform for a specific "display". For example, one might take a source image in ACEScg space and apply the "ACES 1.0 - SDR Video" view for the "sRGB - Display", using either of the following:

% oiiotool acescg.exr --ociodisplay:from="ACEScg" "sRGB - Display" "ACES 1.0 - SDR Video" -o srgb.jpg
% oiiotool acescg.exr --iscolorspace "ACEScg" --ociodisplay "sRGB - Display" "ACES 1.0 - SDR Video" -o srgb.jpg

However, it is often useful to be able to apply the DisplayViewTransform in the inverse direction. For example, to convert sRGB back to ACEScg, inverting a specific view transform. The ocioconvert tool (one of the OCIO command-line tools) is already able to do this, as follows:

% ocioconvert --invertview srgb.exr "sRGB - Display" "ACES 1.0 - SDR Video" acescg.exr "ACEScg"

Inverting a DisplayViewTransform is easily possible via the OCIO v2 API. Simply set the direction of the DisplayViewTransform to TRANSFORM_DIR_INVERSE.

Proposed solution

The --ociofiletransform option in oiiotool already has an "inverse" modifier. So the proposed solution is to add an "inverse" modifier to --ociodisplay.

[lgritz]

Proposed fix in #3650

I'm hoping that maybe somebody could apply this patch on their end and test it by hand, verifying that it appears to work to make the inverse display transform (and also doesn't break the forward transform in any way).

To be honest, I don't really have a test for this in this PR. I noticed recently (to my embarrassment) that the current OIIO testsuite does not contain a test that directly exercises --ociodisplay (though it does for --ociolook and --colorconvert). I haven't had a chance to fix that yet, so of course it also doesn't test the inverse. At my facility, oiiotool --ociodisplay is used in production, so I am not actually worried that it's horribly broken. But I would prefer to have it tested directly in the OIIO testsuite and include in the CI, rather than just assume that it's used enough that I'd get yelled at if it stopped working.

The main impediment to my adding these tests is that the OCIO config that I ship in the testsuite itself, which is the nuke-default, doesn't actually contain any "displays." I think that the solution is going to be to shift the tests to using the new OCIO 2.2 "built-in" configs, which do contain displays. That gives me more testing fodder, as well as knowing that the testsuite doesn't need to come with its own sample config (and, for that matter, allowing oiiotool to rely on the built-in configs in cases where the user doesn't have their own full config). But that's a separate task.

[lgritz]

To that end, @doug-walker, I was just poking around the ocio docs and... is there anyplace that directly addresses how to use the built-in configs? Are there any new API calls? Or do you just ask for a config as always, and use the name of the built-ins? I had trouble finding anyplace that really spelled it out in the docs, but it's possible I just wasn't looking in the right place.

[doug-walker]

@lgritz , I have some documentation in progress for the new features in OCIO 2.2. I'm still writing it, but here is what I have for the built-in configs section so far:

Built-in Configs

For users

The OCIO Configs Working Group has put a lot of effort building new ACES configs that take advantage of the features of OCIO v2. These configs are available separately from the project's GitHub repo:
https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES/releases

To make them more accessible, they are built in to the library itself and may be accessed directly from within applications that incorporate the OCIO 2.2 library. Wherever you are able to provide a file path to a config, you may now provide a URI-type string to instead use one of the built-in configs. For example you may use these strings for the OCIO environment variable.

To use the ACES CG config, use this string for the config path:
ocio://cg-config-v1.0.0_aces-v1.3_ocio-v2.1

To use the ACES Studio config, use this string for the config path:
ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1

This string will give you the current default config, which is currently the CG config:
ocio://default

In future releases, it is expected that updated versions of these configs will be added, each with a unique name string. However, the previous strings will continue to be supported for backwards compatibility.

For developers

The new URI-type strings may be passed into the existing APIs such as CreateFromEnv and CreateFromFile. This is also a new CreateFromBuiltinConfig.

If you'd like to offer the built-in configs from your user interface, there is an API to access them through the new BuiltinConfigRegistry. Here is basic Python code to access the registry and print the strings to present in a UI:

    registry = ocio.BuiltinConfigRegistry().getBuiltinConfigs()
    for item in registry:
        # The short_name is the URI-style name.
        # The ui_name is the name to use in a user interface.
        short_name, ui_name, isRecommended, isDefault = item

        # Don't present built-in configs to users if they are no longer recommended.
        if isRecommended:
            print(ui_name)

Prints:
Academy Color Encoding System - CG Config [COLORSPACES v1.0.0] [ACES v1.3] [OCIO v2.1]
Academy Color Encoding System - Studio Config [COLORSPACES v1.0.0] [ACES v1.3] [OCIO v2.1]

If your application saves the path to a config and the user enters "ocio://default", it is recommended that you don't save that. Instead, call getDefaultBuiltinConfigName to get the name of the current default. This is guaranteed to give the same results, whereas the default config could change somewhat between releases. Prepend "ocio://" in order to save it as a valid config path. Here's the Python code:

    "ocio://" + ocio.BuiltinConfigRegistry().getDefaultBuiltinConfigName()

[lgritz]

Oh, thanks, this is very helpful.