Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify exr2aces output format #1963

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify exr2aces output format #1963

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions website/bin/exr2aces.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,10 @@ Description
Read an OpenEXR file from infile and save the contents
in ACES image file outfile.

The ACES image file format is a subset of the OpenEXR file
format. ACES image files are restricted as follows:
The ACES image file format defined by `SMPTE ST 2065-4`_
is a subset of the OpenEXR file format.

ACES image container files generally follow these restrictions:

- Images are stored as scanlines; tiles are not allowed.

Expand All @@ -36,6 +38,12 @@ format. ACES image files are restricted as follows:
- The "chromaticities" header attribute must specify
the ACES RGB primaries and white point.

Note that perfect adherence to the specification is not strictly
necessary for many use cases and often diverges in minor ways
(e.g. the use of PIZ compression in exr2aces is technically off-spec),
but the file generated here is generally suitable for broadly
compatible archival.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Options:
--------

Expand All @@ -52,3 +60,4 @@ Options:
print version information


.. _SMPTE ST 2065-4: https://doi.org/10.5594/SMPTE.ST2065-4.2013
Loading