feat: Support display color space interop IDs in I/O

[brechtvl]

Description

• Display referred interop IDs are now chosen over scene referred ones by
  default on file read. This more closely matches the standards for CICP, ICC
  and other color metadata. Most images will now have oiio:ColorSpace set to
  srgb_rec709_display rather than srgb_rec709_scene on file read.

  There is a new global attribute color:prefer_image_state that when changed
  from the default "display" to "scene" will prefer scene referred color spaces
  as before.

• Both srgb_rec709_scene and srgb_rec709_display are now (distinct) built-in
  color spaces. The built-in sRGB color space name remains an alias of
  srgb_rec709_scene.

  Documentation was updated to discourage the use of sRGB in favor of
  the more specific interop IDs.

• Previously only srgb_rec709_scene was recognized as sRGB for file metadata
  and display, now srgb_rec709_display and g22_rec709_display are treated as
  sRGB as well.

  The reason for g22_rec709_display behavior is that this type of display is
  often used to correct for the discrepancy where images are encoded as sRGB but
  usually decoded as gamma 2.2 by the physical display. By encoding it as gamma
  2.2 and claiming it's sRGB the transfer functions cancel out exactly.

• g24_rec709_display is now recognized as having gamma 2.4, and the name
  g24_rec709_scene was replaced with ocio:g24_rec709_scene since the
  former is not an official interop ID.

• This change also fixes an issue where tga and rla were incorrectly using
  g22_rec709 and g18_rec709 without _scene suffix, and not handling
  g24_rec709.

• cio:itu709_rec709_scene and ocio:lin_ciexyzd65_display were added to complete
  the list of interop IDs in OCIO configs that match a CICP.

• ColorConfig now includes inactive colorspaces. In older ACES configs (like
  v2.1.0 bundled with OpenColorIO 2.3), the display color spaces are inactive.
  But we now heavily rely on them.

Tests

• Many test outputs were changed due to the new display referred default.
• Added test for g22_rec709_display behavior.
• Added test for color:prefer_image_state.

Checklist:

• I have read the contribution guidelines.
• I have updated the documentation, if applicable. (Check if there is no
  need to update the documentation, for example if this is a bug fix that
  doesn't change the API.)
• I have ensured that the change is tested somewhere in the testsuite
  (adding new test cases if necessary).
• If I added or modified a C++ API call, I have also amended the
  corresponding Python bindings (and if altering ImageBufAlgo functions, also
  exposed the new functionality as oiiotool options).
• My code follows the prevailing code style of this project. If I haven't
  already run clang-format before submitting, I definitely will look at the CI
  test that runs clang-format and fix anything that it highlights as being
  nonconforming.

[brechtvl]

Draft because:

• This depends on and includes the changes from feat: Auto convert between oiio:ColorSpace and CICP attributes in I/O #4964.

[zachlewis]

Would you mind changing this to ocio:g24_rec709_scene? This matches the interop_id used by the "Gamma 2.4 Encoded Rec.709" scene color space or whatever it's called in the latest studio config.

[lgritz]

Is g24_rec709_scene not a real interop tag?

[lgritz]

So here I am torn about this prefixing. Does OCIO recognize "ocio:g24_rec709_scene", or does this mean that something elsewhere in OIIO we need to look for, and strip out, the prefixes any time it needs to actually call OCIO? That seems pretty ugly, too.

Convince me otherwise, but I'm inclined to think that the "oiio:ColorSpace" attrib can have any unadorned OCIO color space name, as long as it's either in the current config or the built-in studio config. Or am I thinking of it wrong?

[doug-walker]

The interop ID description is here. The "g24_rec709_scene" name is not on the CIF texture ID list. Therefore it needs a namespace prefix. The prefix we use in the OCIO configs for ACES is "ocio". You would never strip that out, it's part of the interop ID. Zach is trying to keep OIIO in sync with the usage in the released OCIO configs.

[zachlewis]

ocio:g24_rec709_scene matches an alias for, and the interop_id of, a color space that exists in the latest (v4.0) OCIO Studio config.

Let me back up --

The "Studio Config" contains a superset of the color spaces contained by the "CG Config"; and the "CG Config" is what we're using as OIIO's default ("ocio://default").

Each of the 65ish color spaces in OCIO-2.5's ocio://studio-config-latest defines a unique interop_id whose value matches an alias for that color space. If the color space definition matches the identity of one of the standard CIF tokens, the interop_id value will match the corresponding CIF string. All other Color Spaces use a similar convention, but are prefixed with an ocio "namespace". In turn, these "ocio:"-prefixed interop_id values are reserved values for referencing color spaces defined in the builtin OCIO configs (or color spaces in other OCIO configs that are definitionally equivalent to those in the builtin configs.

Two examples snipped from studio-config-v4.0.0_aces-v2.0_ocio-v2.5:

 - !<ColorSpace> name: Gamma 2.2 Encoded Rec.709 aliases: [g22_encoded_rec709, g22_rec709, Utility - Gamma 2.2 - Rec.709 - Texture, Gamma 2.2 Rec.709 - Texture, g22_rec709_tx, g22_rec709_scene] interop_id: g22_rec709_scene family: Utility equalitygroup: "" bitdepth: 32f description: Convert ACES2065-1 to 2.2 gamma-corrected Rec.709 primaries, D65 white point isdata: false categories: [file-io, texture] encoding: sdr-video allocation: uniform from_scene_reference: !<GroupTransform> name: AP0 to Gamma 2.2 Encoded Rec.709 children: - !<MatrixTransform> {matrix: [2.52168618674388, -1.13413098823972, -0.387555198504164, 0, -0.276479914229922, 1.37271908766826, -0.096239173438334, 0, -0.0153780649660342, -0.152975335867399, 1.16835340083343, 0, 0, 0, 0, 1]} - !<ExponentTransform> {value: 2.2, style: pass_thru, direction: inverse} - !<ColorSpace> name: Gamma 2.4 Encoded Rec.709 aliases: [g24_encoded_rec709, g24_rec709, rec709_display, Utility - Rec.709 - Display, Gamma 2.4 Rec.709 - Texture, g24_rec709_tx, ocio:g24_rec709_scene] interop_id: ocio:g24_rec709_scene family: Utility equalitygroup: "" bitdepth: 32f description: Convert ACES2065-1 to 2.4 gamma-corrected Rec.709 primaries, D65 white point isdata: false categories: [file-io, texture] encoding: sdr-video allocation: uniform from_scene_reference: !<GroupTransform> name: AP0 to Gamma 2.4 Encoded Rec.709 children: - !<MatrixTransform> {matrix: [2.52168618674388, -1.13413098823972, -0.387555198504164, 0, -0.276479914229922, 1.37271908766826, -0.096239173438334, 0, -0.0153780649660342, -0.152975335867399, 1.16835340083343, 0, 0, 0, 0, 1]} - !<ExponentTransform> {value: 2.4, style: pass_thru, direction: inverse} 

So, the "Gamma 2.2 Encoded Rec.709" color space can be referenced by its alias, "g22_rec709_scene", which matches both, the color space's "interop_id" value, as well as the name of the CIF token that describes this color space's mathematical "identity" and image state.

Meanwhile, "Gamma 2.4 Encoded Rec.709" has the interop_id (and a matching alias) "ocio:g24_rec709_scene", because there is no CIF token that matches both the color space's identity and image state.

Elsewhere in the config, under the display_colorspaces section, there's this:

 - !<ColorSpace> name: Rec.1886 Rec.709 - Display aliases: [rec1886_rec709_display, g24_rec709_display] interop_id: g24_rec709_display family: Display equalitygroup: "" bitdepth: 32f description: Convert CIE XYZ (D65 white) to Rec.1886/Rec.709, mirror neg. values isdata: false categories: [file-io] encoding: sdr-video interchange: amf_transform_ids: | urn:ampas:aces:transformId:v2.0:InvOutput.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1 urn:ampas:aces:transformId:v2.0:Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1 allocation: uniform from_display_reference: !<BuiltinTransform> {style: DISPLAY - CIE-XYZ-D65_to_REC.1886-REC.709 - MIRROR NEGS} 

The Display ColorSpace named "Rec.1886 Rec.709 - Display" matches both the mathematical identity and image state described by the "g24_rec709_display" CIF token, and uses that value accordingly for its interop_id; and, like all the other color spaces in the config, each color space's interop_id value is also an alias of the color space itself.

---

There are certain rules by which valid colorInteropId attributes / OCIO interop_id values must abide:

• All interop_ids other than the standard CIF tokens must be prefixed with a namespace.
• Namespaced interop_ids are formatted: "ns:interop_id_name" (the namespace is separated from the rest of the interop_id by a single colon).
• Interop ids can only contain certain characters (regex: [a-zA-Z-_~/*#%^+()[\]{}|:]+)
• interop ids can only contain, at most, a single ":" value.

---

So here I am torn about this prefixing. Does OCIO recognize "oiio:g24_rec709_scene", or does this mean that something elsewhere in OIIO we need to look for, and strip out, the prefixes any time it needs to actually call OCIO? That seems pretty ugly, too.

We've briefly outlined guidelines in one of the CIF specs. I'll have to check the wording, but I believe the current heuristic is essentially:

1. First check to see if the full string matches a name or alias of a color space in the current config.
2. Else, if the full string matches the name or alias of a color space in "ocio://studio-config-latest", try to find and use a definitionally equivalent color space in the current config; and if no equivalent color space exists, either merge the color space from the builtin config into the current config, or use Config::getProcessor to transform from the specified color space in the bulitin config to a color space in the current config, depending on what you're trying to do

And then, in the future, there will be more complex mechanisms for searching for color spaces in external configs, given a namespaced interop_id (which is all stuff I'm hoping and assuming OpenColorIO itself will manage one day...)

Convince me othearwise, but I'm inclined to think that the "oiio:ColorSpace" attrib can have any unadorned OCIO color space name, as long as it's either in the current config or the built-in studio config. Or am I thinking of it wrong?

I think it's probably okay if we incorporate functionality to allow users to assign builtin config names and aliases to "oiio:ColorSpace"; but I think the OIIO codebase should endeavor to avoid naively assigning hardcoded color space names to "oiio:ColorSpace" directly (although roles are okay). Partly because this is generally just a bad practice when developing with OCIO that provides opportunities for fail conditions, and partly because we want to make it explicit that our use of these hardcoded values assumes (or requires) downstream handling to ensure that IBAs are equipped to make sense of the value, given the ColorConfig the IBA is expected to use.

I recommend that, in the codebase, we instead use the "colorInteropId" attribute to hold such "untranslated" / "config-aganostic" interop_id strings; and we use our TBD interpret_metadata_as_color_space() function as needed either to turn the "colorInteropId" value into an "oiio:ColorSpace" value valid for the ColorConfig that the IBA is using (i.e., by finding a matching color space for the string, as described above, making ad-hoc edits to the ColorConfigs to merge missing color spaces from a builtin config into the config used by the IBA); or, alternatively, instead of any merging of color spaces into configs, we simply create a cross-config transform from the builtin color space indicated by the "colorInteropId" value to the appropriate reference space in the IBA's active ColorConfig (using OCIO's uber-overloaded Config::getProcessor(...)), and then concatenate that cross-config transform to the transform that the IBA would normally create when using the reference space as the IBA's "src" color space.

Man, I hope what I just typed made sense.

Upshot is, whether using "colorInteropId" to store interop_id values that need special handling, or implementing logic to handle cases where the value of "oiio:ColorSpace" might not refer to a color space that actually exists in a given ColorConfig, we pretty much have to apply the same handling heuristics; and I just think it's cleaner and more explicit if we use the "colorInteropId" attribute internally the same way we would use it when reading EXRs.

[lgritz]

Is the built-in studio config a strict superset of the default OCIO cg config these days? Should we make the studio config be the one that OIIO uses as a default / backstop? I'm not sure if there are performance implications to that.

But the reason why the studio config is not the default is only because a couple years ago when I was looking at it, the main thing the studio config added was cameras that I thought "naive" users (those not working in a production environment with its own config) would not need. But if it has evolved to the point where a bunch of color spaces that people might encounter in files found in the wild, but that are are not pro-camera-specific (i.e. stuff that any old CICP tags might implicate) are in the studio config but not on the default cg config, maybe we should re-evaluate the choice?

[doug-walker]

Yes, the Studio is a strict superset of the CG config. But I think all the color spaces we've been discussing are already in the CG config? Your original thinking on which config to use still seems correct to me, though as I think Zach mentioned somewhere it might be useful to customize the CG config for OIIO specific needs.

[zachlewis]

Welp, I'd like to imbue the ColorConvert IBA with the ability to "do the right thing" given a known "builtin interop_id" (i.e., the set of interop_id values associated with each Studio config color space), regardless of whether the current ColorConfig actually contains a color space matching that name or associated definition.

In other words, the entire set of Studio config color spaces will always be accessible to ColorConvert (except in rare cases where OCIO's heuristics cannot ascertain a way to bridge the active ColorConfig and the builtin Studio config). This means there's a reserved set of ColorConfig-agnostic strings that will reliably work with ColorConvert:

import PyOpenColorIO as ocio def get_builtin_interop_ids() -> list[str]: return [i.getInteropID() for i in ocio.Config.CreateFromFile("ocio://studio-config-latest").getColorSpaces()]

print(sorted(get_builtin_interop_ids(), key = lambda s: s.startswith("ocio:")))

['srgb_rec709_display', 'g22_rec709_display', 'srgb_p3d65_display', 'srgbe_p3d65_display', 'g26_p3d65_display', 'g24_rec709_display', 'hlg_rec2020_display', 'pq_rec2020_display', 'pq_p3d65_display', 'lin_ap0_scene', 'lin_ap1_scene', 'srgb_rec709_scene', 'g18_rec709_scene', 'g22_rec709_scene', 'srgb_p3d65_scene', 'g22_adobergb_scene', 'srgb_ap1_scene', 'g22_ap1_scene', 'lin_adobergb_scene', 'lin_p3d65_scene', 'lin_rec2020_scene', 'lin_rec709_scene', 'data', 'ocio:acescc_ap1_scene', 'ocio:acescct_ap1_scene', 'ocio:adx10_apd_scene', 'ocio:adx16_apd_scene', 'ocio:applelog_rec2020_scene', 'ocio:arrilogc3_awg3_scene', 'ocio:lin_awg3_scene', 'ocio:arrilogc4_awg4_scene', 'ocio:lin_awg4_scene', 'ocio:bmdfilm5_wg5_scene', 'ocio:lin_bmdwg5_scene', 'ocio:davinci_dwg_scene', 'ocio:lin_dwg_scene', 'ocio:canonlog2_cgamutd55_scene', 'ocio:lin_cgamutd55_scene', 'ocio:canonlog3_cgamutd55_scene', 'ocio:djilog_dgamut_scene', 'ocio:lin_dgamut_scene', 'ocio:vlog_vgamut_scene', 'ocio:lin_vgamut_scene', 'ocio:redlog3g10_rwg_scene', 'ocio:lin_rwg_scene', 'ocio:slog3_sgamut3_scene', 'ocio:slog3_sgamut3cine_scene', 'ocio:slog3_sgamut3venice_scene', 'ocio:slog3_sgamut3cinevenice_scene', 'ocio:lin_sgamut3_scene', 'ocio:lin_sgamut3cine_scene', 'ocio:lin_sgamut3venice_scene', 'ocio:lin_sgamut3cinevenice_scene', 'ocio:g24_rec709_scene', 'ocio:itu709_rec709_scene'] 

[lgritz]

Indeed, I'm in favor of a general heuristic of "if it's not in the active config, try the broadest built-in config we have, and it's only an error if it still can't figure it out at that point."

[brechtvl]

I have changed it to ocio:g24_rec709_scene. But also made further changes to prefer display colorspaces, which means it will be g24_rec709_display by default.

[doug-walker]

I did a quick pass through this one. I'm still an OIIO novice, but it seems like there are a lot of nice improvements in here.

[doug-walker]

Is moving "sRGB" to srgb_rec709_display going to be disruptive? Just wondering if it should stay as srgb_rec709_scene, or be based on prefer_image_state, as it does not seem directly related to CICP.

[lgritz]

I guess the question is: when a naive user asks to convert something to or from "sRGB", do they mean srgb_rec709_display or srgb_rec709_scene?

(I still struggle to understand under which practical, in-the-wild situations those would yield different pixel values, except for expert users who have defined an OCIO config that has an srgb color space with tone mapping, right?)

[brechtvl]

I think in general using sRGB should not be recommended anymore, and I could update the documentation for that. With that in mind, keeping it as srgb_rec709_scene would give better backwards compatibility for something that we are phasing out. The reason I set it to srgb_rec709_display was to match the default interpretation of sRGB image files. I'm happy to change it if backwards compatibility is preferred for this case.

---

My understanding is that with the ACES and other well designed configs, there is no difference for direct conversions between color spaces for srgb_rec709_display and srgb_rec709_scene.

The difference between these spaces is the default view transform for commands like --ociodisplay. For scene referred it will apply e.g. the ACES view transform, while for display referred it will effectively skip it and do a direct conversion to the chosen display color space.

These assumptions break with configs that:

• Incorrectly set an interop ID as an alias on a color space that does not match the CIF recommendation.
• Set default_view_transform (the connection between scene and display spaces, not the default view transform mentioned above) to something that's arguably invalid.

[doug-walker]

Larry, the concern applies even when using the current built-in ACES configs. Brecht, I mostly agree with what you wrote but will add the caveat that I think it's perfectly reasonable for a config to use something other than Un-tone-mapped as the default_view_transform (I think it would still be considered well-designed). And I would add a third bullet point to your list:

The current built-in ACES configs contain the viewing_rules, which are intended to modify the default way images are displayed on a monitor, based on their color space. So for example, if an app wants to generate a thumbnail or preview for an image in a given color space, they would call:
getDefaultView(const char * display, const char * colorspaceName). The view that is returned will differ between a color space of srgb_rec709_scene and srgb_rec709_display. The former will get an ACES Output Transform (because it is scene-referred) whereas the latter will get the equivalent of Un-tone-mapped (which would better match what someone would see in Photoshop).

[doug-walker]

But just to be clear, I have no objection to Brecht's updates to "sRGB" in the latest commit. I don't have a strong opinion on what is the preferred interpretation for that legacy name. I just wanted to provide some more context about what the practical difference is between the options.

[brechtvl]

Brecht, I mostly agree with what you wrote but will add the caveat that I think it's perfectly reasonable for a config to use something other than Un-tone-mapped as the default_view_transform (I think it would still be considered well-designed).

Ah, from discussion in #4787 (reply in thread) I assumed such a config is considered invalid. I guess if you modify default_view_transform then using oiiotool and maketx correctly gets harder, but there's not much we can do about that.

[lgritz]

I think in general using sRGB should not be recommended anymore,

Oh yes, 100% agreed. The only thing we should "recommend" are the official CIF names, or to use something they know is in their facility's OCIO config.

The sole concern here is what legacy aliases we accept and what they mean. Lots of scripts probably exist that use "sRGB", and it's really difficult to track down all the places anybody in a facility may have used it. In particular, there are probably many instances of things like

oiiotool production.exr --tocolorspace sRGB -o web.jpg 

and we would like that to continue working. I don't really care which CIF tag we decide that means, as long as web.jpg keeps making the same pixels.

[brechtvl]

The most backwards compatible is sRGB = srgb_rec709_scene, so I'll change it back to that. (Even if in your example it would be wrong, but wrong the same way as before, and only for certain OCIO configs that are probably uncommon.)

I'll write some example commands in the comments for posteriority.

[zachlewis]

I think this is the right approach, aligning "sRGB" to "srgb_rec709_scene". We'd probably want to discourage use of "sRGB".

Ah, from discussion in #4787 (reply in thread) I assumed such a config is considered invalid. I guess if you modify default_view_transform then using oiiotool and maketx correctly gets harder, but there's not much we can do about that.

I apologize for the confusion... at some point, I deleted a few hundred words going into detail about default_view_transform, because I thought it would be most straightforward to frame default_view_transform as an immutable implementation detail determined by the color specialist responsible for defining the color spaces for the config.

In any case, if an OCIO config author is setting default_view_transform incorrectly, it'll likely be obvious in that the config will either be invalid (i.e., if a view name is specified instead of a view_transform name), or display-views would (very likely) look very obviously incorrect. oiiotool and maketx would suffer the same problems other applications would suffer with that OCIO config.

There's rarely a reason for users, and never a reason for applications, to modify the value of default_view_transform, once set by the color specialist responsible for the config. @doug-walker , is that fair?

[doug-walker]

Here is more detail about the default_view_transform. OCIO has two primary methods of converting between color spaces: ColorSpaceTransform (which is for converting between color spaces of the same image state) and DisplayViewTransform (which is for converting between color spaces of different image states). However, those transforms try to be forgiving and not throw an exception if someone tries to use, e.g. a ColorSpaceTransform to convert from a scene-referred to a display-referred color space. In those scenarios, a View Transform must be inserted to allow the processing. That's the purpose of the default_view_transform. (It is not the default view, for which it is sometimes mistaken due to the similarity in the naming.)

It could plausibly be any View Transform in the config. For example, someone could make it the same as the default view (i.e., the first entry in the active_views) and that would be a perfectly fine choice. That would likely even be a better choice in some industries, but Un-tone-mapped makes the most sense for CG since it makes srgb_rec709_scene and srgb_rec709_display behave the same in most, though not all, circumstances.

I agree that this is something that is best decided by the config author and should not be modified by applications or end-users.

But I will stress that if the color space tag is correctly assigned, and the application is using the appropriate type of transform for the task at hand (ColorSpace vs. DisplayView), then the default_view_transform is never used. It is a fallback.

[brechtvl]

Regarding the current status for this PR. I'm not currently planning further changes. There's more refactoring that could done, for deferred color space determination and more unified code. But that's probably best left for another PR?

I think the main decisions to be taken are:

• Defaut to scene or display referred? (Consensus seems to be display.)
• Should sRGB be srgb_rec709_scene (backwards compatibility) or srgb_rec709_display (consistency with default image load) or even be controlled by color:prefer_image_state? (Consensus is srgb_rec709_scene)
• Write CICP and ICC even for scene referred color spaces? (In my opinion, yes)
• Is the special g22_rec709_display handling a good thing? Or too confusing or undesirable for users with a Gamma 2.2 workflow? Or we won't have a good answer soon, so remove the exception and defer the decision? (Unsure)