The failures are interesting -- they pertain to a bit of code I need to refactor which will probably make them go away, but they point to unexpectedly different behavior either in Strutil::extract_from_list_string or, more likely, ImageSpec::metadata_val, only affecting the "CI / Windows" and "CI / (old)" runs.

The failures pertain to the ImageSpec::set_cicp() function that accepts a single string_view argument:

void
ImageSpec::set_cicp(string_view cicp)
{
    // If the string is empty, erase the attribute.
    if (cicp.empty()) {
        erase_attribute("oiio:CICP");
        return;
    }
    auto vals = Strutil::extract_from_list_string<int>("0,0,0,1", 4, 0);
    auto p    = find_attribute("oiio:CICP", TypeDesc(TypeDesc::UINT8, 4));
    if (p) {
        string_view existing_vals = metadata_val(*p);
        Strutil::extract_from_list_string<int>(vals, existing_vals);
    }
    Strutil::extract_from_list_string<int>(vals, cicp);
    set_cicp(vals[0], vals[1], vals[2], vals[3]);
}

What I'm doing here is a little silly -- if the "oiiio:CICP" attribute already exists in the spec, cast the values to a string, and then extract a vector of integers from said string; and then update that vector with values extracted from the user-provided string argument. I know, the casting-to-a-string bit seems unnecessary.

When I'd originally worked this out, I'd observed that libpng apparently incorrectly permits embedding string data to the cICP chunk; consequently, the Python library I was using to produce test PNGs also manages to incorrectly embed a comma-delimited string instead of the expected four uint8 values; and although image viewers can make neither heads nor tails of the metadata, OIIO would happily accept a string for the "oiio:CICP" value. At the time, I thought it was possible that "oiio:CICP" might be stored as a string value, or possibly some other flavor of integer vector; but I now realize that's pretty unlikely if ImageSpec::set_cicp is the means for setting the attribute in the first place.

Anyway, the actual failures we're seeing are due to the Windows and "(Old)" CI runners failing for some reason to extract integers from the string produced by metadata_val for the found "oiio:CICP" ParamValue.

So, in Python, on affected runners:

spec = oiio.ImageSpec()
spec.set_cicp("1,2,3,4")

# should set "oiio:CICP" to [1, 9, 3, 4], but instead sets to [0, 9, 0, 1]
spec.set_cicp(",9,,") 

Long story short, I'm gonna simplify this method, perhaps move some string parsing logic to png_pvt.h directly -- and it's likely gonna clear up these CI failures. But I still think this behavior is worth investigating further...

Just talking out loud here. These are discussion prompts, not necessarily prescriptive critiques.

I'm a little leery about making it directly a method of ImageSpec. We actually aimed to NOT have a proliferation of methods that set or retrieve each piece of metadata separately, instead just relying on attribute()/getattribute(). I'm not crazy about the precedent adding this would set.

There is a freestanding utility function set_colorspace(ImageSpec&, ...). Maybe this should be a similar function set_colorspace_cicp(...)?

Also, I'm wondering what the interaction between those calls and metadata should be. Should set_colorspace set the cicp flag also if the colorspace is one that is representable as a cicp code (and maybe clear the cicp if it is not)? And vice versa, should reading a cicp code in a file (or calling set_colorspace_cicp) not only set that attribute but also set "oiio:ColorSpace" to the right thing if there is an obvious correspondence?

Let me throw out an alternate design for discussion:

• There is only one attribute in an ImageSpec that contains the color space information: "ColorSpace". (Let's consider this a stand-in for whatever Color Interop Forum + OpenEXR picks as the official name, and we'll change from the unofficial "oiio:ColorSpace" to that when it happens.)

• There are a few different "formats" for the string content of the "ColorSpace" metadata. But the one that always gets priority if it can be deduced is the corresponding CIF token. When that is not known, it may fall back to one or more other standards.

• We never store "cicp" as a separate attribute in the ImageSpec, so that it can't conflict semantically with "ColorSpace".

• A file format reader that is capable of reading CICP data should set "ColorSpace" to a CIF standard token if the CICP data indicates one of those known color spaces. But if it's something not prescribed by CIF, it will set "ColorSpace" to a string "cicp:a,b,c,d".

• A file format writer (for a format capable of storing CICP data) should check the "ColorSpace" metadata and know to transform "ColorSpace" CIF tokens to CICP codes in the file where they correspond, or if it's handed one that looks like "cicp:a,b,c,d", then it also knows what to do in that case.

• Make OIIO scoped utility functions that can transform between CICP and CIF tokens when a correspondence is known, so this logic is centralized and not replicated for each format.

In other words, to apps and OIIO internals, there is only "ColorSpace", though what's stored there can take a few forms (always using a CIF token if we can figure out the right one). It's a detail of individual file format readers and writers to handle translating to and from CICF fields in those file that understand it.

Honestly, I'm not wild overloading the ColorSpace attribute like this. But let me propose a counter proposal:

• The "ColorSpace" attribute should remain an OCIO-specific thing -- it should always refer to a color space in the active default OCIO config.

• OCIO will provide the means for matching CIF standard tokens to color spaces that already exist in the config (with the option of generating an ad-hoc transform to the config's reference space if a matching color space cannot be found) (Or maybe it'll add the missing color space to the config in memory).

• We define a global setting that dictates three modes for handling the "ColorSpace" attribute:

  1. DO NOTHING -- i.e., don't do anything fancy or specific -- leave recognized aliases as-is.
  2. CONFORM CANONICAL -- coerce existing attribute to the OCIO config's "Canonical" name for the color space
  3. CONFORM INTEROP -- attempt to coerce to either the specified color space's "interop" name, if defined; or to the standard CIF token that represents the color space (if the token exists and can be ascertained automatically).

• The OCIO config author is responsible for defining the heuristics used for matching specific metadata key-value pairs to color spaces (i.e., with an API provided by OCIO) via an expanded set of OCIO File Rules, expanding on the existing mechanisms for matching filename string / regex patterns to color spaces.

• CICP should probably remain a separate attribute:

  • Though there's apparent overlap, CICP metadata and OCIO color space strings are used for different purposes, and aren't reliably fully interchangeable.
    • It's not a given that the CICP values we want to encode necessarily match a given OCIO Color Space, or vice versa.
    • Likewise, it's not clear that CICP metadata should take precedence over the filename when "autocc" does its thing -- that's a decision that should be made by the config author.
    • Very often, we can't represent a Color Space encoding with CICP (as is the case with Gamma 2.4 encodings!), or we want to use CICP to deliberately indicate an encoding other than the output color space's. There's such a practice as "implicit color management", where the output encoding and CICP tagging are intentionally "mismatched" as a means for compensating for differences in the intended viewing environment (e.g., stuff for video viewed in a dim environment, versus stuff for web viewed in a bright environment).
  • CICP shares much more in common with ICC than OCIO (and, in fact, has been incorporated into ICC v4 itself). Importantly, the presence of the metadata doesn't really imply that applications should necessarily use the metadata for so-called "linear workflows" (although that's not an entirely unreasonable assumption). It's more of a hint to imagers / browsers / operating systems informing how the encoded data is further transformed for rendering on a given display device.
    • For example, CICP might be able to indicate that an image is sRGB (~2.22) Rec.709 encoded; but CICP alone cannot indicate to OCIO (<=2.4) whether to treat the data as Color-Space-encoded or Display-View-encoded -- even in cases where the "Display" might be inferred from a CICP value, the "View" cannot.
    • OCIO-2.5 may offer config authors a way to specify how to treat combinations of specific CICP values and filename string patterns -- e.g., "for any .mov with a CICP 1-1-1-0 tag, identify as the 'rec709_legal' Color Space", etc.
    • OCIO-2.5 will offer config authors a way to specify CICP values to use for a given color space encoding.
    • Similarly, OCIO-2.5 will offer a way to associate ICC filenames (and likely actual ICC profile data) with Color Spaces (but it's not really clear to me how that'll work yet)
  • CICP metadata is part of a small constellation of static HDR metadata "schemes" ("chunks"?) supported by PNG, HEIF, AVIF, JXL, and various video codecs. Some of that metadata can be conveyed or hinted at by the OCIO config; and some of it requires image-sequence-wide analysis.

Given the complexity of all the moving pieces, I think it would be incredibly helpful to treat the CICP attribute as a first class citizen, for the sake of diagnostics, if nothing else:

• I want to be able to inspect the CICP values as they exist in an image header.
• I want to be able to set / modify / remove the CICP attribute before autocc identification
• I want autocc to feed both the original file name and any CICP / CIF metadata to OCIO
• I want to be able to inspect CICP values after autocc identification, or after any other IBA that mutates the state of the oiio:ColorSpace attribute.
• I want to be able to set / modify / remove the CICP attribute just before writing to a supported format
• It would be nice if, after writing to a supported format, I could continue using the oiio:ColorSpace attribute for subsequent operations

It's not completely impossible to do most of the above with a single overloaded oiio:ColorSpace attribute (if for no other reason than the fact that the formats that support CICP and CIF strings are mutually exclusive)... but, given that CICP may or may not inform the oiio:ColorSpace attribute, and vice versa, and given that we may have cause to treat CICP

The way I envisioned the CICP attribute working:

• With OCIO<=2.4:

  • The CICP attribute does not inform autocc, or vice versa
  • Whenever an IBA mutates oiio:ColorSpace, the CICP attribute is removed.
  • The CICP attribute can be set manually for writing to supported formats.

• With OCIO-2.5+:

  • Both the CICP attribute and the original file name inform autocc
  • If either autocc or an IBA updates oiio:ColorSpace, the CICP attribute is either updated or removed, depending on the OCIO config.
  • The CICP attribute can be set manually for writing to supported formats.

Does this seem reasonable?

n.b. these are about what came before the last three posts here

Mostly the variables you use for primaries, transfer function, matrix and video full range flag are pri, trc, mtx, and vfr; but I note that in imageio.h there's a place in the comments where you use tc for the transfer function. And in png_pvt.h you use cp, tf, mc and fr. If that's how the libpng headers read, fine, but if it's an arbitrary choice for you to make, consistency on names with other parts of OpenImageIO PNG support would be good.

Should we be allowing the caller to set CICP components to invalid values? In particular, 0 is an ITU-reserved value for color primaries and will probably never be valid; likewise 0 for transfer function. And non-zero values for a matrix enum are just plain wrong unless the essence is either YCbCr or ITcTp. Are there other places in OpenImageIO where a user passes in what is basically an enum value, but as an int instead of a type-checkable enum, and we look at that int's validity if interpreted as that enum?

Oh and there's one point in a comment where it's implied that both YCbCr and ITcTp are always "legal range" (or if you want to be more de jure in your terminology, "narrow range"). But this is not true for ITcTp; BT.2100 defines full-range ITcTp for both 10-bit and 12-bit integer encodings.

Now I'll go back and read the last three posts here; but not before thanking you both (Larry and Zach) for considering this stuff so carefully.

Oh, and one last thing: is the autocorrect I am now encountering as I type in my comments here an artifact of GitHub, or of my local browser? The only thing worse than trying to type in code in a text buffer that autocorrects, is trying to type German into such an autocorrecting text buffer when the local platform language is English. If it's my browser, I'll try and fix it; if it's GitHub I'll just do the "old man yells at cloud" thing.

I like Zach's counter proposal A LOT but have some questions:

• can you [Zach] give me some context so I can understand why you put both "active" and "default" in front of "OCIO config" in your first bullet point?

• when you say "handling" the "ColorSpace" attribute, what operations are covered by these modes?

  • the user tries to manually set the oiio:ColorSpace attribute
  • the user reads in a file (and either the oiio:ColorSpace attribute is set then and there, or it's set lazily when requested)
  • something else?

• would "CONFORM CANONICAL" be more precisely named something like "CONFORM CONFIG"?

• the PNG 3e spec has this hierarchy of metadata, with earlier ones overriding later ones:

  • cICP info
  • cICC info (does their ICC support just mean reading the ICC 4.4 tag for CICP info, or are they actually saying the colorimetry in the file is presumed to have been chromatically adapted to D50 and rendered on the graphic arts-centric reference medium?)
  • sRCB marker
  • explicit chromaticies (cHRM) and gamma (gAMA)

Would you see OCIO then enhanced to let you supply potentially all of the above to it, and it would apply any config-specified resolution protocol or a default resolution protocol if none were explicitly provided?

I still want somehow to be able to detect when an image has other metadata that conflicts with its CICP value. That feels like something where one should be able to ask a file format's plugin "what are all the ways you can identify your colorspace" and then pass those to OCIO for sanity checking.

Though I hope for a period where we see better support from CICP for certain combinations of primaries and transfer function — say someday support for 16-bit LogC4 in PNG — my feeling is that the amount of time it takes for that to go through ITU standardization will be long compared to OpenColorIO release cycles, and anyway in the meantime people can fall back on filename patterns. Personally I find that sort of thing cringe, but I've been too long out of the production trenches to suggest to others how they should work.

Fantastic feedback, Joe. Thank you.

Mostly the variables you use for primaries, transfer function, matrix and video full range flag are pri, trc, mtx, and vfr; but I note that in imageio.h there's a place in the comments where you use tc for the transfer function. And in png_pvt.h you use cp, tf, mc and fr. If that's how the libpng headers read, fine, but if it's an arbitrary choice for you to make, consistency on names with other parts of OpenImageIO PNG support would be good.

Good catch -- will fix!

Should we be allowing the caller to set CICP components to invalid values? In particular, 0 is an ITU-reserved value for color primaries and will probably never be valid; likewise 0 for transfer function. And non-zero values for a matrix enum are just plain wrong unless the essence is either YCbCr or ITcTp. Are there other places in OpenImageIO where a user passes in what is basically an enum value, but as an int instead of a type-checkable enum, and we look at that int's validity if interpreted as that enum?

Very good points.
OCIO made the decision to explicitly allow any integer, and defer the interpretation and validation of the CICP tuple to downstream consumers (potentially allowing for internal "house rules"* for communicating a non-standard enum. I think it would certainly be easiest to let the format writer dictate the validity of the CICP tuple, but I also don't think it's a bad idea for OIIO to help things along in whatever way makes sense.

Like you say, the mtx business is tricky, especially as it pertains to the various non-RGB encodings. I don't necessarily think OIIO should correct for impossible values if it somehow receives 'em -- that means, either a format implicitly allows it (or there's an upstream decoder-library bug!), or a user / OCIO-config-author has intervened, and will duly benefit / suffer. I do think it's important for OIIO to be able to passively report the contents of an apparently-valid header. And I also think it's important for OIIO to be able to transform into R'G'B' with the least amount of effort possible. And I also also think that conversions from R'G'B' should ideally take place as a function of selecting format-specific output options (like, encode my RGB buffer as YCbCr just before writing, and CICP-tag as such).

So... my possibly-misguided thinking is... we should probably include a means for converting to / from YCbCr / ICtCp, independently of color space conversions. There are a handful of ways we could approach this with OCIO. In a best-case scenario, this is somehow controlled for by the OCIO API itself -- that's something we'll have to discuss further with the OCIO folks. Another solution -- we could add in-memory to the OCIO Config used by ColorConfig a series of NamedTransforms for the relevant conversions (Rec.709-to-YCbCr, Rec.2020-to-YCbCr, Rec.601-to-YCbCr, XYZ-to-ICtCp...), and invoke their inverses either on autocc, or whenever an ImageBufAlgo that cares about oiio:ColorSpace encounters a non-zero oiio:CICP mtx value, ultimately flipping oiio:CICP's last two bytes to ,,0,1 before proceeding with subsequent ColorProcessors. Or, instead, we could add equivalent (clipped, scaled) color spaces to OIIO's built-in OCIO config? I need to let this marinate some more...

In practice, there are four image formats that I know of that support CICP:

1. PNG:

• Only intends to hold RGB(A) values; as such, libpng only allows a mtx value of 0, and so OIIO always writes 0, ignoring whatever third value is stored in the oiio:CICP attribute.

2. JXL:

• I need to look closer at libjxl, but it's not immediately clear to me that the library even accepts mtx or vfr values. CICP is a means for converting to and from JXL's internal YXB color space.
• When trc=65535, use a pure power function with the embedded custom "gamma" value

3. HEIF

• I haven't investigated too closely, but libheif's API expects CICP values to match libheif int enums, and seems to genuinely do stuff for non-RGB encodings.

4. AVIF

• Everything that applies to HEIF seems to apply to AVIF, but I could be mistaken.

Oh and there's one point in a comment where it's implied that both YCbCr and ITcTp are always "legal range" (or if you want to be more de jure in your terminology, "narrow range"). But this is not true for ITcTp; BT.2100 defines full-range ITcTp for both 10-bit and 12-bit integer encodings.

Great point -- I'll update the comment to better clarify.

Oh, and one last thing: is the autocorrect I am now encountering as I type in my comments here an artifact of GitHub, or of my local browser? The only thing worse than trying to type in code in a text buffer that autocorrects, is trying to type German into such an autocorrecting text buffer when the local platform language is English. If it's my browser, I'll try and fix it; if it's GitHub I'll just do the "old man yells at cloud" thing.

It's your browser. If you highlight the offender and right-click, you should see some sort of "Add to dictionary" option.

can you [Zach] give me some context so I can understand why you put both "active" and "default" in front of "OCIO config" in your first bullet point?

Sure. There should have been a slash between "active" and "default".
By "default config", I mean the OCIO config provided if not otherwise specified.
By "active config", I'm referring to an OCIO API concept that might not have an equivalent in OIIO? But it's an idiom I'd like to see in OIIO.

The Python OCIO API offers PyOpenColorIO.GetDefaultConfig() and PyOpenColorIO.SetDefaultConfig(cfg: ocio.Config) for mutating a global pointer to a PyOpenColorIO.Config instance. If GetDefaultConfig() is called before SetDefaultConfig(...), OCIO attempts to load a config from the $OCIO environment variable, if set, and fails over to a barebones default Config otherwise.

when you say "handling" the "ColorSpace" attribute, what operations are covered by these modes?
I'm specifically referring to how the attribute is written out / persisted downstream (e.g., in EXR attributes).

The OCIO API currently offers a PyOpenColorIO.Config.getCanonicalName(cs: str) function; and will soon offer a PyOpenColorIO.Config.getInteropName(cs: str) function. The Canonical name is the name of a color space in a config (as opposed to an alias or a role). The Interop name is either explicitly specified in the color space definition (via a new OCIO-2.5 attribute); or it fails over to the "CIF name" that matches the color space (if possible); or passes the Canonical name through.

So, the three uses would be:

• Don't change the color space name. (Very often, we want to use a "dynamic" color space whose value is determined by the OCIO Context; as such, we wouldn't necessarily want these color space names resolved to absolutely-defined spaces).
• Conform all color space names to the convention used primarily by the OCIO config
• Conform all color space names to the standard "Color Interop Forum" convention, except for those color spaces the config author elects to treat differently.

Would you see OCIO then enhanced to let you supply potentially all of the above to it, and it would apply any config-specified resolution protocol or a default resolution protocol if none were explicitly provided?

Maybe. It's all up for discussion.

• The gAMA chunk has been mentioned a few times specifically, in OCIO discussions; and OIIO has a few simple heuristics for ascertaining a value from a color space name (which I think we could improve upon).
• I think there's room for attaching mDCV metadata to OCIO color spaces and view transforms.
• sRGB is a little unclear to me, since it pertains to rendering intent, which is inherently both content-dependent and device ICC profile dependent. The presence of the flag also implies a very specific gAMA value and set of cHRM values. However, I think the cICP attribute takes precedence over this.
• cHRM is interesting. OCIO should be able to derive chromaticities for all display color spaces in the default configs pretty effortlessly. In previous discussions re: the EXR chromaticities attribute, I think we decided against providing a way to match / divine ad-hoc color spaces given a set of chromaticities, mainly because we want to put the practice to bed, in favor of the CIF convention.
• For PNG, cICC is ignored when cICP is present. It's not clear to me what happens when CICP values are provided in a ICC profile that also contains additional data. It's also not totally clear to me what OCIO's plans are for relating ICC profiles to color spaces, other than that there are indeed plans.

Now... it should be possible to match / derive ad-hoc color spaces given gAMA + cHRM, sRGB, cICC, or cICP data. But whether we should do so, I think, should be dictated by the OCIO config, in some fashion.
(And then we can come to a consensus re: sensible defaults for OIIO).

I still want somehow to be able to detect when an image has other metadata that conflicts with its CICP value. That feels like something where one should be able to ask a file format's plugin "what are all the ways you can identify your colorspace" and then pass those to OCIO for sanity checking.

That would be interesting. It would be nice if OIIO could optionally reconcile the other attributes with a given CICP attribute on write.

Though I hope for a period where we see better support from CICP for certain combinations of primaries and transfer function — say someday support for 16-bit LogC4 in PNG — my feeling is that the amount of time it takes for that to go through ITU standardization will be long compared to OpenColorIO release cycles, and anyway in the meantime people can fall back on filename patterns. Personally I find that sort of thing cringe, but I've been too long out of the production trenches to suggest to others how they should work.

Well, as far as OCIO release cycles go, OCIO doesn't intend to validate CICP data (beyond any heuristics provided by the config author). So, any new additions to H.273 et al. shouldn't break OCIO ABI compatibility.

And there's really nothing stopping us from defining an OIIO-flavored-CICP spec for primaries and transfer functions, as long as there are formats that allow it. Although so much of CICP is redundant, confusing, or irrelevant, it almost warrants a new spec... insert xkcd comic here (you know exactly which one)

Re: filename patterns -- they can be extremely useful in a lot of situations -- particularly where the person setting the filename doesn't have control over the metadata or the means to interpret it. Right now, it's also the only way we have to indicate whether to apply an inverse display-view transform or a colorimetric color space transform when "linearizing" output-referred encodings.

I just want to refocus the discussion here so we can move things forward...

@lgritz -- given that...

1. There will almost definitely not be a 1:1 relationship between CICP metadata and OCIO color space in a given config.
2. OCIO will offer a means for config authors to govern the heuristics of relating filenames, CICP, other metadata <--> OCIO Color Spaces.
3. It would be extremely helpful to be able to use OIIO to reliably diagnose + inspect + validate container metadata <--> OCIO config <--> CICP behavior (i.e., to provide insight into how I/O functions of OCIO-supporting applications should ostensibly behave)
4. CICP and OCIO metadata are intended for different purposes -- OCIO metadata informs downstream (internal and external) OCIO processes, while CICP informs downstream (external) encoding and decoding.
5. CICP is only one "chunk" of HDR metadata informing downstream viewer decoding that we mean for OIIO to handle; nor is it the only form of non-string metadata that OCIO intends to handle.

...are you any more comfortable with the idea of tracking a separate oiio:CICP attribute?

I feel the benefits of creating the scaffolding for robustly wrangling CICP, among other types of downstream-decoding metadata, outweigh the costs of managing the when, where, and how of OCIO interaction; and I fear that overloading the oiio:ColorSpace attribute prevents OIIO from serving as a diagnostic utility, where diagnostics would be particularly helpful, and for which OIIO is uniquely equipped.

That said, I definitely understand the allure of using a single attribute to track the internal "image state" of the buffer while it's in motion, and if that's the way you feel we should go for now, I'd be more than happy to oblige.

I don't mind there being a separate "oiio:CICP" attribute. (Aside: if this is a well established standard, we can just call it "CICP". Usually the "oiio:" prefix is for things that only OIIO is expected to understand, and/or internal signalling/hinting of some sort.)

I'm less sure whether it's so foundational that we should have a separate ImageSpec::set_CICP() method just for that, versus calling ImageSpec::attribute like we would for anything else. We wanted as much as possible to just use the generalized token/value metadata store, and only have special fields or single-metadata API functions growing with each new item that comes along.

and only have special fields or single-metadata API functions growing with each new item that comes along.

I meant "only have special... when really necessary" or "NOT have special calls for each new item that comes along". But somehow I combined the two phrasings and managed to completely garble the message.

Ha! I understood your meaning.

The main reason why I implemented an ImageSpec::set_cicp() method is, the attribute is a series of four integers, but I wanted to expose a way to selectively mutate only some values and not others; and Strutil::extract_from_list_string couldn't be more perfect for that; and so, I ended up with an overloaded method that accepts a series of integers or a comma-delimited string, both of which cast to a uint8[4] array. It's important that we're able to modify the values independently -- the data that a given OCIO config provides will most likely only be valid for the first two CICP bytes (the primaries and transfer function), because the last two bytes describe non-RGB luma-chroma encodings and video range scaling, which are transforms that are more likely to take place outside of the OCIO color space graph.

Another reason why I implemented an ImageSpec::set_cicp() method is, I was thinking ahead to how we might want to deal with the other HDR metadata chunks, and was kind of using CICP as an opportunity as a "trial run" for how we might want to handle some of the more complex schemes -- in particular, "Mastering Display Color Volume" (mDCV), which is a series of ten values, representing a set of chromaticities, a max luminance (nits) value, and a min luminance (nits) value; but it's usually coded and represented in string form (i.e., when passed to ffmpeg) as a series of scaled integers, even though it's only human-friendly to reason about in terms of floats. So, I was thinking, we'd want either an overloaded set_mdcv() function for converting either a series of floats or ints to a single internal representation, as well as a means for converting from a string representation ("P3D65x1000n005"); or we'd want to defer that normalization to get_mdcv_int() and get_mdcv_float() methods invoked by format writers. Or both. We could probably get away with not attaching a get_mdcv() function to ImageSpec (or even exposing such a function to the public API).

Originally, I was thinking, it would make sense to attach set_cicp(), set_mdcv(), set_clli() and set_rwtm() methods for setting the four horsemen of ISO/TS 22028-5 HDR/WCG metadata (if there are, indeed, only four horsemen -- I don't have access to the spec! -- but these are the schemes that are currently support (or whose support is planned for the future) for the handful of image formats that can convey static HDR metadata (other than the gainmap stuff, which is a whole other beast).

(I was also thinking, it wouldn't hurt to have an overloaded set_chromaticities() method that could take a string, a float[8], a vector of 4x float[2], or nothing at all, which would derive approximated values for oiio:ColorSpace from the ColorConfig)

Anyway, we can discuss what to do with the other metadata schemes elsewhere -- I just wanted to give you an idea of where my head was at.

All this said, as far as this PR is concerned, I'll happily do whatever you'd prefer. If you'd like to get rid of the ImageSpec::set_cicp() method, I can move the string parsing stuff to the oiiotool --cicp implementation, and handle all the uint8 casting (if necessary) in the format writers. That doesn't really leave us with an out-of-the-box solution for only partially modifying the "state" of an existing CICP attribute with the API, but that's not difficult to handle in a programmatic context with the standard methods of getting and setting attributes.

Should I proceed with getting rid of set_cicp?

How about this compromise: instead of making set_cicp a method of ImageSpec, let's make it a free-standing function (somewhat like the existing set_colorspace())? Somehow it seems less intrusive to me than making it an IS method.

I'm on the fence about whether the string-based API call is necessary, or if it's sufficient to just make that functionality live in oiiotool. Maybe start with that part just in oiiotool, but if we decide later that we really want it directly, it's easy enough to add? But I'm happy to go with your recommendation if you want it in the API now.

I don't have a good feel for how often it will come up that people will want to manipulate just one field independently and can't just "get" all 4, modify what they want, and then send the whole package back. Will that idiom of 4 or 5 lines be so commonly repeated in people's code that it's worth having a new API call for us to test and maintain?

Just so you know what's currently swirling in my brain for a place to work toward eventually:

You have convinced me that separately maintaining "OCIOColorSpace", "CICP", "Chromaticities", and possibly other attributes is the right approach, if for no other reason, then simply for the sake of being able to accurately report what was really in a file that we read.

However, I still feel like it would be a mistake to make everyplace in the code base that needs to check or set or propagate color space information, and every piece of USER code that needs to do so, to have to check a growing list of possible attribute names and different standards for what color space the pixels are, understand them all (plus, the list may grow), and also to know which one to set in order to be supported by the output file type they are using (which is antithetical to OIIO's original core purpose of allowing near total format-agnosticism on the app side).

So what I'm thinking is that there is still a use for a get_colorspace() method/function, centrally implemented, that surveys the various attributes and synthesizes a single string descriptor for the color space to put in "internal" attribute "oiio:ColorSpace", and a corresponding set_colorspace() that takes such a token and sets any or all of the individual attributes (and clearing any that contradict, can't be known, or have no corresponding version). This centralizes the logic for translating between the different standards and lets most apps, and most parts of OIIO internals, operate as if it was a single simple attribute, even though there are actually several attributes and standards that get elaborated depending on the file type.

So, for example, if you read an openexr file that has a "OCIOColorSpace" attribute, that will be set in the ImageSpec and also "oiio:ColorSpace" will be set to, say, "lin_rec709". If it reads a PNG file with CICF info, the "CICF" attribute will be set, but also "oiio:ColorSpace" will end up with an OCIO name if it corresponds to one, but if not, then "cicf:1,2,3,4". Or if all that's known is chromaticities and they don't seem to correspond to any known CIF space, maybe it will just get "chromaticities:....".

Is something like that going to make all the color scientists hate me?

Roger that -- I will...

• Change the attribute name to "CICP", dropping the internal prefix
• Remove the set_cicp function entirely from the API
• Move the string parsing stuff to oiiotool
• Handle the casting to and from uint8 in the PNG reader / writer
• Update the tests
• Update the language in the comments re: how the third CICP byte sometimes informs the fourth (re: Joseph's feedback)

Let me know if I've forgotten anything.

Will that idiom of 4 or 5 lines be so commonly repeated in people's code that it's worth having a new API call for us to test and maintain?

No, I wouldn't imagine so -- really, the kind of wrangling we're talking about would only happen under pretty unique and specific circumstances. We can make things simpler for user code by treating the CICP attribute as an int[4] instead of a uint8[4] attribute, and we can ascertain a likely fourth CICP byte for format writers if users treat the attribute as a uint8[3] (which they very well might). Beyond that, I think developers will manage.

if for no other reason, then simply for the sake of being able to accurately report what was really in a file that we read.

Thank you! This is crucial.

However, I still feel like it would be a mistake to make everyplace in the code base that needs to check or set or propagate color space information, and every piece of USER code that needs to do so, to have to check a growing list of possible attribute names and different standards for what color space the pixels are, understand them all (plus, the list may grow), and also to know which one to set in order to be supported by the output file type they are using (which is antithetical to OIIO's original core purpose of allowing near total format-agnosticism on the app side).

Oh, couldn't agree more - ideally, the vast majority of user code should be able to drive everything that needs driving with only the oiio:ColorSpace attribute and OCIO-2.5 config heuristics, with each OCIO-using-IBA updating the state of a couple of attributes; and power users would have the opportunity to manually inspect / set / modify / clear certain attributes before writing. Format writers should be able to ascertain what to do from the OCIO config + oiio:ColorSpace + the state of the relevant values.

(Do format writers have easy access to the ColorConfig?)
((Which ColorConfig? The one used by the most recently applied IBA?))

So what I'm thinking is that there is still a use for a get_colorspace() method/function, centrally implemented, that surveys the various attributes and synthesizes a single string descriptor for the color space to put in "internal" attribute "oiio:ColorSpace", and a corresponding set_colorspace() that takes such a token and sets any or all of the individual attributes (and clearing any that contradict, can't be known, or have no corresponding version). This centralizes the logic for translating between the different standards and lets most apps, and most parts of OIIO internals, operate as if it was a single simple attribute, even though there are actually several attributes and standards that get elaborated depending on the file type.

I'm not sure about the particular method details themselves, but I think this is 100% the right idea, and aligns with the approach I imagine OCIO's API will very likely take!

Sidebar: It might be useful to contrive an internal oiio:FrozenAttributes string attribute for storing the names of other attributes that we do not want downstream operations modifying automatically. Likewise, maybe a oiio:DoNotWriteAttributes attribute for explicitly disabling a downstream format writer from writing certain metadata?

If it reads a PNG file with CICF info, the "CICF" attribute will be set, but also "oiio:ColorSpace" will end up with an OCIO name if it corresponds to one, but if not, then "cicf:1,2,3,4". Or if all that's known is chromaticities and they don't seem to correspond to any known CIF space, maybe it will just get "chromaticities:....".

Mmmm. I don't know... maybe I'm misunderstanding, but with a get_colorspace() function described as above, this seems redundant. It seems to me that an oiio:ColorSpace attribute set to anything another than an OCIO color space is probably less helpful than just leaving the attribute unset. What's a downstream IBA to do when attribute oiio:ColorSpace == "cicp:1,2,3,4" contradicts attribute CICP == (4,5,6,7)?

That said, I don't at all mind the idea of string-based shorthand for setting set non-oiio:ColorSpace attributes with set_colorspace(); which, in turn, could reconcile a value for oiio:ColorSpace with get_colorspace(). I also wouldn't mind a way of using set_colorspace as a means for adding ad-hoc color spaces to ColorConfig if they don't already exist (or aliasing them if they do). I think that would be very useful.

I want to highlight two things:

1. Believe me, I understand how overwhelming the idea providing meaningful support for all these different color metadata paradigms can be. As it is, juggling "gamma", "chromaticities", "sRGB", "ICC", and "oiio:ColorSpace"... it's a lot to tie together, and adding even more to the mix must seem kind of nightmarish. Just know, it's really appreciated; and I'll do my best to help you make sense of it, when and where I can.

2. I think it would be a good idea for OIIO to ship with its own built-in OCIO config, so we can migrate the various hard-coded aliases and heuristics and preferences scattered throughout the codebase to more idiomatic use of OCIO. It's a larger discussion, of course, but I wanted to put the bug in your ear.

Let me know if I've forgotten anything.

I think we're on the same page about pretty much all of this.

Oh, couldn't agree more - ideally, the vast majority of user code should be able to drive everything that needs driving with only the oiio:ColorSpace attribute

Cool. Needless to say, the specifics I outlined were just off the top of my head and speculative, all depends on how the OCIO stuff shakes out, input from others, etc.

(Do format writers have easy access to the ColorConfig?) ((Which ColorConfig? The one used by the most recently applied IBA?))

There is one default color config, set by $OCIO or attribute, or if no config is found, the built-in OCIO CC.

Sidebar: It might be useful to contrive an internal oiio:FrozenAttributes string attribute for storing the names of other attributes that we do not want downstream operations modifying automatically. Likewise, maybe a oiio:DoNotWriteAttributes attribute for explicitly disabling a downstream format writer from writing certain metadata?

I think there's an overall question we've always had about which metadata being set should invalidate which other metadata, and what to do about things that seem to contradict. The metadata needs metadata!

Mmmm. I don't know... maybe I'm misunderstanding, but with a get_colorspace() function described as above, this seems redundant. It seems to me that an oiio:ColorSpace attribute set to anything another than an OCIO color space is probably less helpful than just leaving the attribute unset. What's a downstream IBA to do when attribute oiio:ColorSpace == "cicp:1,2,3,4" contradicts attribute CICP == (4,5,6,7)?

It won't. If you call set_colorspace("cicp:x,y,z,w"), the logic would be:

spec.attribute("cicp", {x,y,z,w});   // definitely sets CICP -- we were given it directly
if (cicp x,y,z,w corresponds to a known CIF color space token or a color space in
    the active OCIO config) {
    spec.attribute("OCIOColorSpace", foo);  // we know what OCIO space corresponds
    spec.attribute("oiio:ColorSpace", foo); // oiio prefers the OCIO token when available
} else {
    spec.erase_attribute("OCIOColorSpace"); // no known OCIO space, so clear it
    spec.attribute("oiio:ColorSpace", "cicp:x,y,z,w");  // best identifying token we know
}

Conversely, if the thing passed to set_colorspace appears to be an OCIO or CIF name 'foo', the logic would be:

spec.attribute("OCIOColorSpace", foo);  // we know it's an OCIO color space
spec.attribute("oiio:ColorSpace", foo);  // we prefer OCIO as short name
if (OCIO space foo is known to map to a CICF quad code xyzw) {
    spec.attribute("CICF", {x,y,z,w});  // it's a known one
} else {
    spec.erase_attribute("CICF");  // no idea what CICF we are, so get rid of it
}

or something like that.

Oh, and if it gets as far as an IBA that needs to know something about color space and it's anything other than an OCIO token, it just will treat it as an unknown color space. In effect, the "CICF" values that don't correspond to a known OCIO color space are really only being carried around for the sake of the eventual ImageOutput that writes the file.

2. I think it would be a good idea for OIIO to ship with its own built-in OCIO config, so we can migrate the various hard-coded aliases and heuristics and preferences scattered throughout the codebase to more idiomatic use of OCIO. It's a larger discussion, of course, but I wanted to put the bug in your ear.

We do require OCIO as a dependency now, at a minimum of 2.2, so there is always at least that built-in color config available. I'm sure there are lots of places in the OIIO code that haven't yet caught up to the best logic to apply given that as a minimum set of capabilities, and could thus be improved to give more consistency and better sensible default behavior.

Elaborating a little more...

There are a few possible attributes that could be set:

• "OCIOColorSpace" (string) -- explicit OCIO/CIF color space name, only if present in the read file
• "CICF" (int[4]): CICF quad, only if present in the read file
• "Chromaticities" (float[8]) : chromaticities & whitepoint, only if present in the read file
• ... possibly others in the future TBD, same deal ...
• "oiio:ColorSpace" (string) : OIIO's internal single-token color space descriptor, never read from or written to any file

And there are a few operations of note:

set_colorspace

• sets the attribute corresponding to the specific scheme
• clears all other possibly contradictory attributes
• sets "oiio:ColorSpace" to the most sensible thing we can, with preference for OCIO if we know it

set_colorspace(ImageSpec& spec, string token) :
    if (token is an OCIO/CIF name):
        spec.attribute("oiio:ColorSpace", token);
        spec.attribute("OCIOColorSpace", token);  // we know it for sure
        erase "CICF", "chromaticities", and anything else that might conflict
    else if (token is a CICF quad) :
        spec.attribute("CICF", quad);  // we know it for sure
        erase "OCIOColorSpace", "chromaticities", and anything else that might conflict
        if (we know the CICF quad corresponds to an OCIO space, 'foo'):
            spec.attribute("oiio:ColorSpace", "foo");  // because we know the OCIO equiv.
        else:
            spec.attribute("oiio:ColorSpace", "cicf:x,y,z,w");
    ..etc...

ImageInputs:

• are expected to call set_colorspace based on what they find in the file
• e.g. some files will have an OCIO color space name, some will have a CICF, etc.
• the result of the set_colorspace call is that oiio:ColorSpace is set, and so is the attribute for the actual thing that was found.

ImageBufAlgo functions():

• IBAs that need to know color space go 100% on "oiio:ColorSpace"
• They definitely understand if the contents of "oiio:ColorSpace" is an OCIO token in either the current externally-found config, or in the built-in configs, or in the CIF list (which presumably will always be present in future OCIO built-in configs)
• They probably don't understand anything else and are allowed to error in that case if asked to do a color space transformation
• IBA functions that change an image's color space tag it with set_colorspace, thus leaving only "oiio:ColorSpace" and "OCIOColorSpace" set, and getting rid of all contradictory/conflicting attributes.

ImageOutput:

• mainly cares only about "oiio:ColorSpace" in the image it's being asked to output
• if writing to a file that accepts OCIO names (like OpenEXR), writes that
• or if writing to a file that accepts CICF:
  • writes the CICF found in the attribs, if it's there
  • else tries to convert the OCIO name into CICF if there's a corresponding one
  • else punts, it doesn't know how to express the color space in that type of file
• so we'll probably need a couple of utility functions that do things like given a CICF, finds a matching OCIO name if there is a corresponding one, and vice versa

So the upshot is that most of the OIIO code base and most apps can just deal with oiio:ColorSpace and treat nothing else as special; ImageInputs just call set_colorspace; ImageOutputs need a little format-specific logic to see if the spec has the right kind of color information (or it can be deduced by what's there); ImageBufAlgo lives in an OCIO world. But all along, things like iinfo will correctly print what's really in the file; and things like reading a file and writing to a different file format will do the best pipe fitting it can, including propagating either OCIO or CICF exactly if it is supported by both input and output file types.

Ah, I see -- I thought OCIOColorSpace would replace the internal oiio:ColorSpace for some reason.

Either way, I still don't understand why we'd want oiio:ColorSpace to be anything other than a resolved OCIO color space, or why we'd want to persist as string metadata anything that we're already storing in attributes elsewhere?

In effect, the "CICF" values that don't correspond to a known OCIO color space are really only being carried around for the sake of the eventual ImageOutput that writes the file.

But why overload oiio:ColorSpace in the first place, if we already have "proper" attributes for storing CICP and Chromaticities and "Gamma" metadata? When would an oiio:ColorSpace value of something other than an OCIO Color Space be useful internally? An input filename string, I might understand, if there's nowhere else to keep it, as a means to a "deferred autocc".

In my view:

• set_colorspace() should always resolve an OCIO color space name for oiio:ColorSpace.

  • This might include an ad-hoc color space added to the ColorConfig in-memory -- e.g., for recognized CIF tokens that don't otherwise match a color space in the current config, or for linear color spaces derived from chromaticities metadata that arent otherwise recognized.
  • If the OCIO config cannot ascertain a color space or appropriate transform for the given metadata, oiio:ColorSpace will be set to the config author's intended default color space.
  • If we want OIIO to fail over to "lin_rec709" instead of ACES2065-1, like ocio://default specifies, OIIO should ship with a custom OCIO config as its built-in default. (It can easily be a modified version of one of the builtin OCIO configs).
    • Likewise, an OIIO-OCIO config would be a good place for OIIO's "Linear" + "sRGB" aliases, etc.

• ImageInput should always run set_colorspace(), as you suggest. Upshot is, oiio:ColorSpace gets set to an actual OCIO color space as early as possible.

• IBAs that need to know something about oiio:ColorSpace always have the information they need, and duly modify the output buffer ImageSpec upon success.

• ImageOutput cares about format-specific attributes as previously set or populated by IBAs. oiio:ColorSpace is ignored -- nothing is automatically derived at this point, giving users the opportunity to remove attributes they don't want written.

Does that make sense?

It would mean IBAs that alter the output spec's oiio:ColorSpace would simultaneously attempt to derive chromaticities and gamma values, and possibly CICP and MDCV metadata as well with OCIO-2.5 configs.

It may be the case that only approximate chromaticities can be derived, or that a "gamma" cannot be ascertained, which is fine. The approximated chromaticities will be good enough for government work, and the "gamma" either won't apply for the color space (cuz it's a log-encoded space, etc.), or, if an output format absolutely requires a "gamma" metadata, we can attempt to derive a value from the output filename, vis-a-vis the OCIO config's FileRules; and failing that, we can require user intervention to override OIIO's existing format-specific defaults.

(It would also mean that we'd probably want to start adding an "opt-in" feature to the EXR writer for embedding chromaticity metadata; because, as nice as it may be that we can derive values, CIF et al would like to deprecate the attribute entirely, in favor of OCIOColorSpace / OCIOConfigName).

Ah, I see -- I thought OCIOColorSpace would replace the internal oiio:ColorSpace for some reason.

At one point, so did I. I'm basically just talking out loud here, trying to grope my way to a set of rules that makes for consistent behavior while minimizing what apps using OIIO need to do. The only reason I have them separate now is to disginguish the OIIO operative color space of the image ("oiio:ColorSpace") from "the explicit OCIO name we found in the file, for those formats that support it."

Either way, I still don't understand why we'd want oiio:ColorSpace to be anything other than a resolved OCIO color space, or why we'd want to persist as string metadata anything that we're already storing in attributes elsewhere?

I believe I was thinking that this just gives us a single item to pass all the way through the chain? But maybe I'm wrong and it's not necessary?

But why overload oiio:ColorSpace in the first place, if we already have "proper" attributes for storing CICP and Chromaticities and "Gamma" metadata? When would an oiio:ColorSpace value of something other than an OCIO Color Space be useful internally?

Maybe? But like I said, if as we are implementing this, we see that there are some redundancies or inconsistencies, we should definitely eliminate them.

* `set_colorspace()` should _always_ resolve an OCIO color space name for `oiio:ColorSpace`.
  
  * This might include an _ad-hoc color space_ added to the ColorConfig in-memory -- e.g., for recognized CIF tokens that don't otherwise match a color space in the current config, or for linear color spaces derived from chromaticities metadata that arent otherwise recognized.

Oh, I didn't know this would be possible except for a very few special cases. An area of OCIO's APIs I have never really dealt with is building configs or augmenting a loaded config with addition CS's. Do all the CIF quads map to something we could in principle add on the fly to the OCIO config, so we really can just concern ourselves with OCIO tokens?

* ImageOutput cares about format-specific attributes as previously set or populated by IBAs. `oiio:ColorSpace` is ignored -- nothing is automatically derived at this point, giving users the opportunity to remove attributes they don't want written.

This is the only part you wrote that I disagree with (or maybe just don't understand exactly what you mean). I wouldn't say "oiio:ColorSpace" is ignored by ImageOutput; I would say it's the single source of truth if present, but it's up to the ImageOutput for each format to know which fields and standards are supported by that format and express it the right way in the file.

It would mean IBAs that alter the output spec's oiio:ColorSpace would simultaneously attempt to derive chromaticities and gamma values, and possibly CICP and MDCV metadata as well with OCIO-2.5 configs.

I think it's simpler than that. I'm suggesting that "CICP", "gamma", "OCIOColorSpace", etc. only express input file metadata. ImageInputs also set "oiio:ColorSpace". IBA functions that don't do color space transformations just pass all metadata through untouched. IBA functions that change color space erase all of them and just set a single "oiio:ColorSpace" to carry all information forward (e.g. the only thing we know coming out of an IBA color transforming function is what we think the new OCIO color space is). ImageOutput set whatever fields they support based on oiio:ColorSpace if it is present, but otherwise may fall back on a format-specific item like "CICP" if present.

(It would also mean that we'd probably want to start adding an "opt-in" feature to the EXR writer for embedding chromaticity metadata; because, as nice as it may be that we can derive values, CIF et al would like to deprecate the attribute entirely, in favor of OCIOColorSpace / OCIOConfigName).

I'm in the camp of people who think "Chromaticies" should be considered deprecated for exr files. I have never considered it trustworthy, and I don't think OIIO even reads it from the file.

Should we be moving this wonderful (I mean it) discussion to design the future of passing color space info around within OIIO to a GitHub Discussion rather than on this one PR which presumably will be merged and closed soon?

Small note for @zachlewis : please refer to me in these discussions as "Joseph" rather than "Joe". It's not that I take offense at the diminutive form, but it's that everyone knows me as Joseph, and so if you attribute something to "Joe" they will miss the association, at least without tracing back to my comment and extracting the last name from my GitHub name. Again, no offense taken, I'm just saying this for clarity if anyone comes digging in this PR later.

Catching up (my you've both been energetic in the last 72 hours or so)

• @lgritz you're going to drive me crazy with CICF; you mean CICP, right?

• In re: (YCbCr or ITcTp) conversion to and from RGB, perhaps that's a case where responsibilities are split between OCIO and OIIO. If we want to evangelize ASWF libraries to people outside the usual mid-to-high-end production pipleine software creators, we're going to have to deal with things like 4:2:2 or 4:2:0 YCbCr and that can be tricky to put it mildly. For that I think we really want to lean on components that have already been debugged and tested and our source should be ffmpeg.

• In re: the four horsemen of ISO 22028-5, actually I did buy a copy, and here's what's there:

  • CICP from H.273
    • primaries
      • the sometimes-included, sometimes-not-included conveyance of a white point in a primaries specification drives me nuts by the way
    • OETF (explicitly "the reference opto-electronic transfer characteristic")
      • this is a bit worrisome if CICP is used for display-referred imagery as it implies (for, e.g, a camera with an SLog3 or LogC3 OETF) that one would take log images and put them out directly for dislplay. Or am I missingn something?
    • matrix coefficients
    • video full range indicator
  • viewing environment
    • ISO 22028-5 is super vague about this saying that if your viewing environment doesn't match the following default, then somehow you should carry it along:
      • no specular from display, D65-colored, 5 nit surround with darker periphery
  • if image is "created for display-viewing", then
    • MDCV (mastering display color volume) from SMPTE ST 2086 defines mastering display primaries, white, min and max displayable luminance
      • note that white is exxplicitly considered distinct from primaries here
      • also note that the max lum is probably the brightest you could get for a (say) 100 x 100 white square on an otherwise black field, i.e. this is not the lum you get if you go full-frame white and the power supply forces peak lum down after a second or two (and on a Sony display a little red light goes on)
    • optionally CCV (content color volume) from ISO/IEC 23008-2 defines content primaries, white [explicit again!], and luminance range including an average luminance. So I guess this could change from frame to frame?
    • optionally CLL (content light level) from ISO/IEC 23008-2
      • but ISO 22028-5 doesn't break it apart other than saying it's "information about the light level"
    • HDR diffuse white luminance in nits. I think this means the nits of a reproduction of the capture of a perfect reflecting diffuser. Scene-referre imagery is not at all diffused (sorry) through the minds of people in ISO TC 42 ... yet.

• In re: Zach's comment about having an OpenImageIO custom OCIO config, can't we construct this dynamically, i.e. read in the OCIO default config, dupe it under an OIIO-specific name and modify it? That would keep divergence to a minimum if OCIO's default config changes over the years.

* @lgritz you're going to drive me crazy with **CICF**; you mean **CICP**, right?

Sorry, yeah. The right combo of font and eyes and you can see how I keep making that mistake, right?

• In re: (YCbCr or ITcTp) conversion to and from RGB, perhaps that's a case where responsibilities are split between OCIO and OIIO. If we want to evangelize ASWF libraries to people outside the usual mid-to-high-end production pipleine software creators, we're going to have to deal with things like 4:2:2 or 4:2:0 YCbCr and that can be tricky to put it mildly.

I'm not sure what you mean by "deal with", but so far, a core assumption of OIIO is that these are encoding details that live entirely internal to the ImageInput/ImageOutput implementation of a format. The "app side" of the OIIO APIs does not have the concepts of subsampling nor non-RGB data encodings (just like it doesn't know about compressed data streams, or bit depths that aren't 8/16/32). Ideally and whenever possible, those encoding details aren't even handled in the ImageInput/ImageOutput, but are handled completely in the underlying per-format library if at all possible.

For that I think we really want to lean on components that have already been debugged and tested and our source should be ffmpeg.

100%, that's always been our policy -- ffmpeg for video, libraw for camera raw, libtiff for YCbCr-encoded tiff files, etc.

• In re: Zach's comment about having an OpenImageIO custom OCIO config, can't we construct this dynamically, i.e. read in the OCIO default config, dupe it under an OIIO-specific name and modify it? That would keep divergence to a minimum if OCIO's default config changes over the years.

I have an admittedly sketchy grasp of this part, even the terminology. We want to honor whatever external OCIO config is found at runtime, and in the absence of one, default to modern OCIO's "built-in" config. If there's a way to dynamically augment that at runtime in order to outsource even more of the color handling code to OCIO rather than do any of it on the OIIO side, that's great. But when you call it an "OpenImageIO custom OCIO config" I start to get confused, because that sounds (to me, and I bet to OIIO's downstream users who aren't super OCIO gurus) like it's something we're doing instead of their studio config or OCIO's built-in config.

In re: having ffmpeg do the work, on write at least, don't we have to pass down new metadata to it to indicate which subsampling we want it to use? And wouldn't that involve creating a new attribute to hold that info? I take your point that the heaviest lifting we outsource, but I would think we'll still have to do some work to pass along instructions to the outsourced worker.

@zachlewis's comment was "If we want OIIO to fail over to "lin_rec709" instead of ACES2065-1, like ocio://default specifies, OIIO should ship with a custom OCIO config as its built-in default. (It can easily be a modified version of one of the builtin OCIO configs)." and I created the phrase "OpenImageIO custom OCIO config" to describe that. Sorry if that made things unclear.

In re: having ffmpeg do the work, on write at least, don't we have to pass down new metadata to it to indicate which subsampling we want it to use? And wouldn't that involve creating a new attribute to hold that info? I take your point that the heaviest lifting we outsource, but I would think we'll still have to do some work to pass along instructions to the outsourced worker.

Oh yes, we already do that. They all have namespaced attributes "formatname:attributename". The ImageInput sometimes sets them to reveal certain settings of the file that was read from, but these do not necessarily describe the data read (for example, maybe "blorgformat:encoding" might be "YCbCr" to indicate that was what was stored in the file, but all the data returned from the ImageInput::read_image is RGB as OIIO requires). An ffmpeg example is here. And ImageOutput format implementations often will recognize several items in this form that aren't metadata of the image per se, but are interpreted as hints to control the writer (tiff example to control 'rowsperstrip' here).

Generally, writers are expected to ignore any hints of the form "format:attributename" where the namespace 'format' is the name of a different image format. For examples, the EXR writer will ignore things like "tiff:rowsperstrip" because it knows "tiff" is the name of another format, so it correctly understands this to be a hint for the TIFF writer, and NOT a piece of metadata to add to the OpenEXR file's attributes. EXR's logic for that is here

I believe I was thinking that this just gives us a single item to pass all the way through the chain? But maybe I'm wrong and it's not necessary?

Ah, I'm picking up what you're putting down. I was thinking, it would be useful to be able to inspect the various attributes after OCIO-concerned-IBAs -- but if it makes things easier, we can do without.

IBA functions that change color space erase all of them and just set a single "oiio:ColorSpace" to carry all information forward (e.g. the only thing we know coming out of an IBA color transforming function is what we think the new OCIO color space is). ImageOutput set whatever fields they support based on oiio:ColorSpace if it is present, but otherwise may fall back on a format-specific item like "CICP" if present.

We won't be able to use "oiio:ColorSpace" to carry all information forward -- "MDCV" metadata will likely only be set by forwards ociodisplayview IBAs, and should probably only be erased by inverse ociodisplayview IBAs. But for stuff like Chromaticities, Gamma, CICP, ICC -- sure, we can erase those attributes after each color-space-changing IBA. So, if a user wants to manually adjust a CICP value, they'll have to do so after all IBAs are applied. I can live with that.

Still, I would imagine that any existing attribute-specific values would take precedence over the "oiio:ColorSpace" value, cuz if those values exist by the time we're writing to disk, it means those values are either correctly being carried forward from the input, or they've been manually set by the user.
(Right? I think that follows.)

optionally CCV (content color volume) from ISO/IEC 23008-2 defines content primaries, white [explicit again!], and luminance range including an average luminance. So I guess this could change from frame to frame?
optionally CLL (content light level) from ISO/IEC 23008-2 but ISO 22028-5 doesn't break it apart other than saying it's "information about the light level"

That's interesting that CCV also defines the content primaries + white; that seems redundant, if CICP is meant to convey that information.

I do know that MaxFALL (Frame Average Light Level) and MaxCLL (Content Light Level) metadata are static -- the values are supposed to be constant throughout all frames of the program. I found this excellent article from the SMPTE Motion Imaging Journal on how to compute the values while rejecting outliers: https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9508136
Here's a gist implementing the paper.

this is a bit worrisome if CICP is used for display-referred imagery as it implies (for, e.g, a camera with an SLog3 or LogC3 OETF) that one would take log images and put them out directly for dislplay. Or am I missingn something?

I assume you mean scene-referred imagery (unless I'm misunderstanding?), but you're not wrong -- CICP is explicitly a convention for display-referred imagery -- isn't equipped to provide downstream imagers or processes with any information regarding how to transform a scene-referred image state for viewing. On the other hand, typically for log-encoded data, I don't think we'd want CICP interfering with how the values are consumed or displayed downstream. (That said, I love that ARRI's log-encoded ProRes videos can contain extractable LUTs in the metadata. I don't know of anyone else who does that, but I wish it were common practice). That's part of the reason why an OCIO config author needs to be able to selectively prioritize when / how / whether to use CICP for identifying an input file's color space (relative to the other means of doing so -- like using a filename!)

In practice (at Company 3 / Method, anyway), I think the only part of NCLX metadata considered meaningful for ingesting / converting log-encoded videos is the full range flag (if that).

But I'm still with you, Joseph -- it would be helpful if CICP additionally codified the various scene-referred gamuts and transfer functions. In theory, one could define an "in-house" convention with OCIO-2.5 (which is part of the reason why OCIO-2.5 will not validate CICP tuples)

HDR diffuse white luminance in nits. I think this means the nits of a reproduction of the capture of a perfect reflecting diffuser. Scene-referre imagery is not at all diffused (sorry) through the minds of people in ISO TC 42 ... yet.

I believe Chris (@digitaltvguy) can clarify. I've been referring to this as rWtm (Reference White metadata), per Chris's proposal for PNG 4th edition, although I think heif may refer to it as "Nominal Diffuse White metadata" or something. I've not seen this explained anywhere, but I think it's meant to serve as a pivot-point for scaling graphics, UI widgets, titles, and other extremely-not-scene-referred elements relative to the scene-referred stuff over which the graphic elements are composited (e.g. for display-to-display conversion). I think this is only set if conveying a value other than the default 203 nits.

In re: Zach's comment about having an OpenImageIO custom OCIO config, can't we construct this dynamically, i.e. read in the OCIO default config, dupe it under an OIIO-specific name and modify it? That would keep divergence to a minimum if OCIO's default config changes over the years.

Yes, that's exactly what I had in mind -- in fact, I started putting together a proof of concept doing exactly that. Alternatively, we could define an extremely minimal OCIO config, and just use OCIO-2.5's config merging abilities to merge with one of OCIO's builtin configs, but we'll probably have to hold off on that approach until OIIO raises the minimum OCIO version to 2.5 in three years or whenever.

That sounds (to me, and I bet to OIIO's downstream users who aren't super OCIO gurus) like it's something we're doing instead of their studio config or OCIO's built-in config.

To be clear, we'll be doing something on top of one of OCIO's built-in configs as a default; and we'll leave user-set OCIO configs alone.

I'm gonna bring this up in another issue / discussion, and better explain why I think this is a good idea. The idea is to fail over to something useful that ships with OCIO, but with inoffensive OIIO-specific tweaks to serve OIIO-specific needs (as "ocio://default" doesn't really provide a helpful out-of-the-box experience for a lot of very common use cases -- e.g., "camera log" --> "scene linear" conversions)

• Building off one of the ACES Studio configs (e.g., "ocio://studio-config-latest") that ship with OCIO instead of one of the ACES CG configs (e.g., "ocio://default") (i.e., to expose the various camera-log color spaces known by ACES)
• Setting the default color space to "lin_rec709" instead of "ACES2065-1", cuz that's the default Larry seems to prefer (and frankly, it's just as good as any other default).
• Adding the "ColorSpaceNamePathSearch" File Rule, which enables the OCIO-1-style color-space-name-string-matching behavior (that OIIO is currently manually implementing -- OIIO shouldn't automatically attempt to match a color space name (or alias) in the file name string like it currently does -- the OCIO config author should dictate when and whether that heuristic is applied, relative to the other File Rules)
• Adding extension-specific File Rules that match the assumptions OIIO is already making elsewhere in the codebase
• (Possibly) adding regex-based File Rules for matching camera-vendor-specific filename patterns to specific camera log flavors.
• Adding OIIO-specific backward-compatible aliases like "Linear" and "sRGB" (that also exist in the codebase), that might otherwise be frowned upon when authoring an OCIO config for public consumption
• Adding View Rules for scene-referred and display-referred encodings, and updating the existing Views to use 'em -- i.e., so if an empty string is passed to an ociodisplay IBA's "view" argument, the value of the "fromspace" argument (if provided; otherwise, the value of "oiio:ColorSpace") informs the selection of an appropriate default View for the given input color space. In other words, if viewing a display-referred color space, use a colorimeteric View by default; else, use whatever the ACES configs currently use (i.e., an ACES-1.x Output Transform). This would allow, for example, an ImageBuf viewed in a Jupyter notebook (feat(python): _repr_png_ implementation for ImageBuf #4753) to always display the contents in an output-referred state (rather than trying to dump radiometrically linear relative exposure values to a temporary PNG file as-is for viewing).

In other words, we'd be moving OIIO's hardcoded conventions (like the "Linear" and "sRGB" color space aliases) and preferences (like failing over to "lin_rec709" as a default color space) to OIIO's built-in OCIO config, thereby making OIIO itself behave more reliably, as intended, with user-provided OCIO configs.

I'm not sure what you mean by "deal with", but so far, a core assumption of OIIO is that these are encoding details that live entirely internal to the ImageInput/ImageOutput implementation of a format. The "app side" of the OIIO APIs does not have the concepts of subsampling nor non-RGB data encodings (just like it doesn't know about compressed data streams, or bit depths that aren't 8/16/32). Ideally and whenever possible, those encoding details aren't even handled in the ImageInput/ImageOutput, but are handled completely in the underlying per-format library if at all possible.

This does get to the core of the matter. The third CICP component, the "color matrix", specifically concerns the various non-RGB encodings. If OIIO always converts to and from RGB whenever reading / writing, that make life a lot simpler for us. That means any explicit scaling for luma-chroma encodings will be handled by the plugin at conversion time.

Should we be moving this wonderful (I mean it) discussion to design the future of passing color space info around within OIIO to a GitHub Discussion rather than on this one PR which presumably will be merged and closed soon?

Probably. I don't suppose GitHub provides a way to convert this Issue into a Discussion? I can't reenact these jams.

Probably. I don't suppose GitHub provides a way to convert this Issue into a Discussion? I can't reenact these jams.

Not that I can find. I think we will have to just open a new issue and then cut/paste the important parts of this discussion into it to capture what we have so far and then pick up the discussion at that point.

Ah, I'm picking up what you're putting down. I was thinking, it would be useful to be able to inspect the various attributes after OCIO-concerned-IBAs -- but if it makes things easier, we can do without.

My assumption was just that post OCIO-concerned-IBA execution, most of those attribs would be invalidated anyway, but I am happy to be corrected. I'm hoping to avoid a situation where any function that receives an IB (that may have gone though unknown steps to get there) doesn't need to recreate the full logic of "if this thing is set, it means this, but if not then look for this other thing, and it means that...". My dream was that it could all be one attribute used through the whole chain for the real decisions, with everything else merely being documentation of what was found in the original file (and quickly invalidated any time the meaning of the pixel values could break what the file documented).

"MDCV" metadata

You're easily showing just by using terminology that I don't know that I'm way out of my depth here on the color pipeline issues. Take my rambling as only somebody with an eye on whether the APIs and conventions will be easy to document, use, and maintain, but I am relying on others to make the real decisions about a sensible color management workflow for OIIO and you should not hesitate to override me if I'm not accounting for what we need to have a correct and complete solution.

In other words, we'd be moving OIIO's hardcoded conventions (like the "Linear" and "sRGB" color space aliases) and preferences (like failing over to "lin_rec709" as a default color space) to OIIO's built-in OCIO config, thereby making OIIO itself behave more reliably, as intended, with user-provided OCIO configs.

A lot of this dates back to before OCIO was required and before it had built-in configs or any kind of name standardization, just me (not a color scientist) trying to grope for behavior that's likely to be right a lot of the time and notation that's easy for lay users to remember. I recognize that both "Linear" and "sRGB" are imprecise and ambiguous, and am happy for us to change the set of aliases, defaults, and behaviors. Don't consider any of that to be set in stone (though it's a bonus if the things naive users "try" are likely to do more or less what they expect).

This does get to the core of the matter. The third CICP component, the "color matrix", specifically concerns the various non-RGB encodings. If OIIO always converts to and from RGB whenever reading / writing, that make life a lot simpler for us. That means any explicit scaling for luma-chroma encodings will be handled by the plugin at conversion time.

So far, our convention has been that the default behavior is always to convert to some RGB-based system upon read, but often there is a back door (using open-with-configuration-hint "oiio:RawColor") to mean "don't do any conversion to RGB, just give me whatever channel encoding was in the file, and I (the caller of OIIO) will be responsible for sorting it out." That is not to say we are averse to providing some freestanding utility functions (or IBA?) that will convert among common choices or understand how they map to CICP (not CICF! I have the contact lenses in today) values.

I will start a discussion thread. Stay tuned for that and we'll pick up the discussion there. Let's keep the rest of the comments here firmly on what it takes to complete this PR's task.

Where are we on this one, @zachlewis ?

Is this PR still an ongoing concern (if so, I think there are some changes we agreed upon), or has it be superseded by the separate discussion of a larger reorganization of how color management information flows through OIIO?

Nope, not superseded at all -- I hope to implement the changes as discussed some time this week. Thanks for your patience!

Alright. Almost there.

I need help with the CI / Windows failures.

Upshot: $ oiiotool -i foo.png --cicp '' should erase the CICP attribute; but on Windows, it sets CICP to 0, 0, 0, 0.

I flagged similar behavior above, before I got rid of the "set_cicp" method:

Anyway, the actual failures we're seeing are due to the Windows and "(Old)" CI runners failing for some reason to extract integers from the string produced by metadata_val for the found "oiio:CICP" ParamValue.

So, in Python, on affected runners:

spec = oiio.ImageSpec()
spec.set_cicp("1,2,3,4")

# should set "oiio:CICP" to [1, 9, 3, 4], but instead sets to [0, 9, 0, 1]
spec.set_cicp(",9,,")

I suspect the problem has something to do with Strutil::extract_from_list_string, but I'm really not familiar enough with C++ to know where to look for potential platform-dependent differences in string parsing code...

Here's the relevant bit (moved from set_cicp to oiiotool.cpp's --cicp):

class OpSetCICP final : public OiiotoolOp {
public:
    OpSetCICP(Oiiotool& ot, string_view opname, cspan<const char*> argv)
        : OiiotoolOp(ot, opname, argv, 1)
    {
        inplace(true);  // This action operates in-place
        cicp = args(1);
    }
    OpSetCICP(Oiiotool& ot, string_view opname, int argc, const char* argv[])
        : OpSetCICP(ot, opname, { argv, span_size_t(argc) })
    {
    }
    bool setup() override
    {
        ir(0)->metadata_modified(true);
        return true;
    }
    bool impl(span<ImageBuf*> img) override
    {
        // Because this is an in-place operation, img[0] is the same as
        // img[1].
        if (cicp.empty()) {
            img[0]->specmod().erase_attribute("CICP");
            return true;
        }
        std::vector<int> vals { 0, 0, 0, 1 };
        auto p = img[0]->spec().find_attribute("CICP",
                                               TypeDesc(TypeDesc::INT, 4));
        if (p) {
            const int* existing = static_cast<const int*>(p->data());
            for (int i = 0; i < 4; ++i)
                vals[i] = existing[i];
        }
        Strutil::extract_from_list_string<int>(vals, cicp);
        img[0]->specmod().attribute("CICP", TypeDesc(TypeDesc::INT, 4),
                                    vals.data());
        return true;
    }

private:
    string_view cicp;
};

I'll see if I can put together some more informative tests... I may even resurrect set_cicp just for the sake of testing, if it helps remove confounding variables...

Hey @lgritz -- I think this is ready for review.

If it's cool with you, I'd like to spin off a new issue to address the failing CI / Windows check. The failing test case shouldn't block this PR; and it'll be a lot easier to explain / troubleshoot the issue with a tangible feature to test with.

This PR introduces a mechanism for manually tweaking CICP metadata with oiiotool:

# Example A: Convert a Rec.2100-PQ full-range 12-bit DPX to a properly-tagged 16-bit PNG
$ oiiotool  -i in.dpx --cicp 9,16 -d uint16 -o out.png

# Example B: Unset the CICP attribute entirely
$ oiiotool -i a.png --cicp "" -o b.png

# Example C: Set the "narrow range" part of the CICP attribute (without affecting other existing parts of the CICP attribute)
$ oiiotool -i a.png --cicp ,,,0 -o legal.png

Apparently, Example C (partial modification of an existing CICP attribute) doesn't behave as expected on Windows.

(The immediate workaround for Windows would be to always set all four CICP values when using --cicp)