docs: clarify exr2aces output format

[patrickhulce]

Inspired by discussion in #1962. (many thanks to @peterhillman and @lgritz)

Adds additional background to the ACES Image Container format produced by exr2aces.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: patrickhulce / name: Patrick Hulce (54636f2, 22e80c2, 380f72f, f3fe3f9, e5a2f6b, 5320bc6, 9e3e64e)

[peterhillman]

I don't think the OpenEXR documentation should attempt to be the authority on what off-spec features are acceptable in ACES files. I believe that support for compression is the only way that the exr2aces output doesn't meet the strict definition of SMPTE ST 2065-4, so perhaps it would be better to be explicit about that. Then the user can make an informed decision about how to use the tool. Essentially exr2aces requires reading software to support the OpenEXR compression types which are not described in the ST 2065-4 standard.

Perhaps there should be a --strict flag that forces NO_COMPRESSION, to make it easier to guarantee compatibility.

All this does assume the user wants to generate a SMPTE ST 2065-4 ACES container file, not just an OpenEXR encoded with the ACES Chromaticities, which is the more usual approach and doesn't require use of exr2aces.

[patrickhulce]

Sure, is there specific language you had in mind that you feel would be more faithful to your comments?

I don't think the OpenEXR documentation should attempt to be the authority on what off-spec features are acceptable in ACES files.

I agree, and that's not my intent. My goal with this edit is to at least make it the authority on the behavior and rationale for its own tool's behavior (especially when deviating from any formally documented specification it may otherwise be confused with).

[peterhillman]

I wasn't involved with the creating the ACES standard. It would be helpful for somebody with more experience of that effort could suggest a solution to this.

I notice that the original version of exr2aces was committed in 2007 (4568596) many years before the ACES standards became official. That may explain the discrepancies between exr2aces and the final published standard.

[patrickhulce]

I still think some incremental improvement here would be valuable. Would you be more comfortable if this line were replaced by some caveat that this implementation predates the specification and may not have perfect alignment, citing compression as an example?

[JGoldstone]

The reason that compression isn't permitted in ST 2065-4 is that it is a nominative standard and as such can only specify what it precisely defines itself or by citing other nominative standards. Basically the transitive closure of the standard and the documents it references must define everything used in the standard. And there's no normative document for piz, dwa, etc. And no one on the 2054-4 committee wanted to either create individual new normative documents (at $5K administrative fees a pop, at least these days) or to add normative annexes to the already lengthy 2065-4 draft.

Here is a very relevant part of 2065-4:

In the theme of "show me on the doll where the bad person hurt you", can we see a sample of contract language that specifies the VFX vendor deliverable must comply to ST 2065-4? There's hairsplitting legal arguments that one can make, and then there's colloquial ACES where it's a file of RGB triplets of relative exposure values, the RGB definition being such that the triplets represent combinations of the ACES primaries and that they have the ACES neutral.

"Everyone knows" that an ACES file doesn't have to be uncompressed, the same way that "everyone knows" that a camera that claims to be putting out "Rec 709" may not be in strict compliance with ITU-R BT.709 -- in the latter case that camera may have a 'knee' circuit built in, so it is no longer possessed of a "Rec. 709" OETF.

If I were a really paranoid producer I might specify any built-in compression algorithm is acceptable for otherwise ST 2065-4 compliant OpenEXR files as long as they weren't being presented as final imagery that was going to be archived. That would let facilities exchange compressed files of radiometrically linear exposure values representing combinations of the specified ACES primaries, with the ACES white point, both inside the facility and between facilities; but when assets were archived, if their image data were compressed then that data needed to be uncompressed to produce a new uncompressed file and THAT would be archived.

OK, I guess I need to specify replacement text.

The ACES Image Container File Format specified in SMPTE ST 2065-4:2023 is a subset of the
OpenEXR file format defined by the implementation of the time (roughly OpenEXR 1.6). This imposes considerable restrictions on what image data and metadata can be transported from a modern
OpenEXR file into an ACES Image Container File, including (but not limited to) the following:
- The version field must be either be 2 or 1026; a value of 2 implies attribute names cannot be longer than 31 characters in length, as was the case prior to OpenEXR 1.7.
- Images must be stored as scanlines; tiles are not allowed.
- Images must contain RGB and possibly an A channel if they are monoscopic; images representing stereo pairs would add another three (or four if A is present) channels. Other channels are not permitted, including channels that otherwise might represent a combination of a luminance channel and chromaticity channels.
- The image must not be compressed.
- The `chromaticities` attribute must specify the ACES RGB primaries and the ACES neutral as specified in SMPTE ST 2065-1.
- the `acesImageContainerFlag` flat must be present and have the value 1

For the full set of restrictions, see SMTPE ST 2065-4:2023 (or any superseding later version of that standard).

In practice, facilities and productions often use the term "ACES file" to mean OpenEXR files containing linear scene data expressed as combinations of R, G and B whose chromaticities match those found in ST 2065-1, where equal amounts of those primaries produce a color the chromaticity of which matches that of the ACES neutral. The image data might be compressed using one of the OpenEXR's library's built-in compression functions, even though strict compliance with ST 2065-4 would forbid such compression; the `acesImageContainerFile` flag might be missing; and the `chromaticities` attribute might contain chromaticities that do not actually match those found in ST 2065-1.

I'm sure this is more than you bargained for, but you asked for someone with history to speak up, and I was on both the original and (to a lesser extent) the revision committees.

[patrickhulce]

Thank you @JGoldstone! Updated 👍

[cary-ilm]

Suggested change

	attribute names cannot be longer than 31 characters in length,
	attribute names cannot be longer than 31 characters in length,
	as was the case prior to OpenEXR 1.7.

[cary-ilm]

Need to indent the lines below the '-' so they're justified underneath the first character after the space after the '-'.

[patrickhulce]

sorry about that, fixed!

[cary-ilm]

same here

[cary-ilm]

same mere

[cary-ilm]

@patrickhulce, I'd like to go ahead and merge this but sphinx is failing because of the link. The suggestions I posted should fix it, can you look them over? Thanks!

[patrickhulce]

Apologies for the delay, updated @cary-ilm !

[cary-ilm]

Thanks all, we'll go with this update as is.