Update documentation for 2.5 release (#2202)

* Update documentation for 2.5 release

Signed-off-by: Doug Walker <[email protected]>

* Fix typos

Signed-off-by: Doug Walker <[email protected]>

* Address review comments

Signed-off-by: Doug Walker <[email protected]>

* Fix markdown

Signed-off-by: Doug Walker <[email protected]>

* Minor updates

Signed-off-by: Doug Walker <[email protected]>

---------

Signed-off-by: Doug Walker <[email protected]>

Author: doug-walker

docs/concepts/publications/publications.rst

@@ -7,6 +7,11 @@
 Presentations & Publications
 ============================
 
+* ASWF Open Source Days 2025 -- Project Update `video <https://youtu.be/w-T64bqFh5E?feature=shared>`_
+
+* Color Interop Forum -- "Color Space Encodings for Texture Assets and CG Rendering" 
+  `Recommendation <https://github.com/AcademySoftwareFoundation/ColorInterop/blob/main/Recommendations/01_TextureAssetColorSpaces/TextureAssetColorSpaces.md>`_
+
 * ASWF Open Source Days 2024 -- NanoColor `video <https://youtu.be/ym1kfYmGz-M?feature=shared>`_
 
 * ASWF Open Source Days 2024 -- Project Update `video <https://youtu.be/zizC0ORvwnc?feature=shared>`_

docs/configurations/aces_cg.rst

@@ -17,6 +17,8 @@ color spaces and a wider set of displays and view should look at the :ref:`aces_
 Please note that some of the color spaces (e.g. for texturing) are not officially part of the 
 ACES specifications but are included because they are widely used in VFX, animation, and games.
 
+The most recent version of the CG config is based on ACES 2.0.
+
 The latest version of this config may be downloaded from the Releases page of its GitHub
 `repo. <https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES/releases>`_
 
@@ -25,11 +27,13 @@ and so requires no external LUT files.  In fact, even the config file is built i
 and users may access it from any application that uses OCIO 2.2 or higher by using one of the
 following strings in place of the config path:
 
-``ocio://studio-config-v2.2.0_aces-v1.3_ocio-v2.4``   (for OCIO 2.4 or higher)
+``ocio://cg-config-v4.0.0_aces-v2.0_ocio-v2.5``   (for OCIO 2.5 or higher)
+
+``ocio://cg-config-v2.2.0_aces-v1.3_ocio-v2.4``   (for OCIO 2.4 or higher)
 
-``ocio://studio-config-v2.1.0_aces-v1.3_ocio-v2.3``   (for OCIO 2.3 or higher)
+``ocio://cg-config-v2.1.0_aces-v1.3_ocio-v2.3``   (for OCIO 2.3 or higher)
 
-``ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1``   (for OCIO 2.2 or higher)
+``ocio://cg-config-v1.0.0_aces-v1.3_ocio-v2.1``   (for OCIO 2.2 or higher)
 
 These new configs adopt an advanced naming convention so that they can be uniquely identified:
 
@@ -43,9 +47,18 @@ Where:
 
 * Type: The type of the config, e.g., CG or Studio
 * Colorspaces: The version for the color spaces and other config features
-* ACES: The aces-dev version being used
+* ACES: The aces-dev version being used (currently supports ACES 1.3 and 2.0)
 * Profile: Minimum required OCIO version
 
+In addition, the latest version of the CG config may be accessed simply using:
+
+``ocio://cg-config-latest``
+
+and this is the default built-in config for the library:
+
+``ocio://default``
+
+
 The OCIO Configs Working Group collected input from the community and simplified the
 naming scheme relative to the earlier OCIO v1 ACES configs.  However, aliases have been 
 added so that the original color space names continue to work (if there is an equivalent

docs/configurations/aces_studio.rst

@@ -17,6 +17,8 @@ used in the VFX, animation, games, and post-production industries.
 Users who need a simpler config that contains just the basics needed to use ACES color
 management in common DCC tools are encouraged to check out the :ref:`aces_cg`.
 
+The most recent version of the Studio config is based on ACES 2.0.
+
 The latest version of this config may be downloaded from the Releases page of its GitHub
 `repo. <https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES/releases>`_
 
@@ -25,6 +27,8 @@ and so requires no external LUT files.  In fact, even the config file is built i
 and users may access it from any application that uses OCIO 2.2 or higher by using one of the
 following strings in place of the config path:
 
+``ocio://studio-config-v4.0.0_aces-v2.0_ocio-v2.5``   (for OCIO 2.5 or higher)
+
 ``ocio://studio-config-v2.2.0_aces-v1.3_ocio-v2.4``   (for OCIO 2.4 or higher)
 
 ``ocio://studio-config-v2.1.0_aces-v1.3_ocio-v2.3``   (for OCIO 2.3 or higher)
@@ -43,9 +47,14 @@ Where:
 
 * Type: The type of the config, e.g., CG or Studio
 * Colorspaces: The version for the color spaces and other config features
-* ACES: The aces-dev version being used
+* ACES: The aces-dev version being used (currently supports ACES 1.3 and 2.0)
 * Profile: Minimum required OCIO version
 
+In addition, the latest version of the Studio config may be accessed simply using:
+
+``ocio://studio-config-latest``
+
+
 The OCIO Configs Working Group collected input from the community and simplified the
 naming scheme relative to the earlier OCIO v1 ACES configs.  However, aliases have been 
 added so that the original color space names continue to work (if there is an equivalent

docs/guides/authoring/colorspaces.rst

@@ -241,6 +241,10 @@ proportional to an SDR video signal. Examples: Rec.709/Rec.1886 video, sRGB.
 ``hdr-video`` -- A display-referred encoding where the numeric representation is 
 proportional to an HDR video signal. Examples: Rec.2100/PQ or Rec.2100/HLG.
 
+``edr-video`` -- A display-referred encoding where the numeric representation is 
+proportional to an SDR video signal but allows extended range values intended
+for use on extended or high-dynamic range displays. Example: Display P3 HDR.
+
 ``data`` -- A non-color channel. Note that typically such a color space would 
 also have the isdata attribute set to true. Examples: alpha, normals, Z-depth.
 
@@ -398,6 +402,46 @@ compatibility.
 
     aliases: [shortName, obsoleteName]
 
+``interop_id``
+--------------
+
+Optional.
+
+OCIO supports the Color Interop ID developed by the Color Interop Forum. This allows
+config authors to set an ID on the color spaces in a config to unambiguously identify them
+as conforming to the recommendations of the ASWF Color Interop Forum. These IDs may then be
+used in file formats including OpenEXR and OpenUSD. 
+
+Note that if a color space has an ``interop_id``, that same string must appear as an alias or
+as the name of a color space in the config. Unlike color space names or aliases, more than 
+one color space may use the same interop ID string. This is because sometimes a config may 
+have multiple color spaces that correspond to a given external standard. In this situation,
+only one of those color spaces will have the alias and that will be the one that is used by
+default, for example when an application loads an OpenEXR file that uses that interop ID.
+
+The interop ID is not an arbitrary string, it must adhere to the rules and structure 
+defined by the Color Interop Forum. For example, only certain characters are allowed, and
+color spaces not published in a Color Interop Forum recommendation must include a namespace
+prefix.
+
+Although config authors may use a variety of names for a given color space, based on the
+needs and conventions of their studio, the intent is that everyone will use the same interop
+IDs and that this will allow better tagging in file formats than the local color space names
+that are only meaningful within the context of a specific config.
+
+Developers should note that these IDs are for use internally in file formats but the color 
+space's name attribute is still what should be used in a UI.
+
+The interop ID may be used in configs of version 2.0 or higher.
+
+.. code-block:: yaml
+
+    - !<ColorSpace>
+      name: ACEScg
+      aliases: [ACES - ACEScg, lin_ap1, lin_ap1_scene]
+      interop_id: lin_ap1_scene
+      [...]
+
 
 ``allocation`` and ``allocationvars``
 -------------------------------------
@@ -468,6 +512,46 @@ It's common to use literal ``|`` block syntax to preserve all newlines:
         This is one line.
         This is the second.
 
+``interchange``
+---------------
+
+Optional.
+
+The interchange attributes are provided to allow better interop between OCIO and other
+color management standards.
+
+The ``amf_transform_ids`` is a newline-separated list of transform IDs intended for use
+with the ACES Metadata File (AMF). Please note that this should include both the forward
+and inverse IDs (if available). For display color spaces, this should include the ACES
+Output Transform IDs used with that display. Note that the same attribute for the 
+View Transforms and Looks sections of the config should be populated as well.
+
+.. code-block:: yaml
+
+    - !<ColorSpace>
+      name: ACEScct
+      [...]
+      interchange:
+        amf_transform_ids: |
+          urn:ampas:aces:transformId:v2.0:CSC.Academy.ACES_to_ACEScct.a2.v1
+          urn:ampas:aces:transformId:v2.0:CSC.Academy.ACEScct_to_ACES.a2.v1
+
+The ``icc_profile_name`` is intended to identify an ICC profile to be used in connection
+with a given color space in the config. For example, some applications may want to embed
+an ICC profile when writing image files to indicate the color space. The profile should
+be located somewhere on the config's search path. Developers may use the resolveFileLocation
+function on the Context class to resolve the full path to the file.
+
+.. code-block:: yaml
+
+    - !<ColorSpace>
+      name: sRGB - Display
+      [...]
+      interchange:
+        icc_profile_name: srgb_profile.icc
+
+The interchange attributes may be used in configs of version 2.5 or higher.
+
 
 .. _config-display-colorspaces:
 

docs/guides/authoring/displays_views.rst

@@ -120,6 +120,8 @@ A View Transform may use the following keys:
 * ``description``: A description of the ViewTransform.
 * ``family``: A family string (similar to ColorSpace).
 * ``categories``: The categories used for menu filtering (similar to ColorSpace).
+* ``amf_transform_ids``: The ACES transform IDs to be used with AMF files. Note this 
+  is a sub-key under the ``interchange`` key.
 * ``from_scene_reference``: The transform from the scene-referred reference space
   to the display-referred reference space.
 * ``to_scene_reference``: The transform from the display-referred reference space
@@ -139,6 +141,10 @@ The default view transform is the view transform that is used if a ColorSpaceTra
 needs to convert between a scene-referred and display-referred colorspace.  If this
 key is missing, the first view transform in the config is used.
 
+Please note that this is *not* the default view for the config. The default view is the 
+first view in the ``active_views`` list and should be obtained using the ``getDefaultView``
+API function.
+
 .. code-block:: yaml
 
   default_view_transform: un-tone-mapped

docs/guides/authoring/looks.rst

@@ -33,7 +33,7 @@ in the correct colorspace (by converting from the input colorspace to
 the process space, applies the look's transform, and converts the
 image to the output colorspace)
 
-Here is a simple ``looks:`` section, which defines two looks:
+Here is a simple ``looks:`` section, which defines three looks:
 
 .. code-block:: yaml
 
@@ -49,6 +49,15 @@ Here is a simple ``looks:`` section, which defines two looks:
         transform: !<FileTransform> {src: 'neutral-${SHOT}-${SEQ}.csp', interpolation: linear }
         inverse_transform: !<FileTransform> {src: 'neutral-${SHOT}-${SEQ}-reverse.csp', interpolation: linear }
 
+      - !<Look>
+        name: ACES 1.3 Reference Gamut Compression
+        process_space: ACES2065-1
+        description: LMT (applied in ACES2065-1) to compress scene-referred values from common cameras into the AP1 gamut
+        interchange:
+          amf_transform_ids: |
+            urn:ampas:aces:transformId:v2.0:InvLook.Academy.ReferenceGamutCompress.a2.v1
+            urn:ampas:aces:transformId:v2.0:Look.Academy.ReferenceGamutCompress.a2.v1
+        transform: !<BuiltinTransform> {style: ACES-LMT - ACES 1.3 Reference Gamut Compression
 
 Here, the "beauty" look applies a simple, static ASC CDL grade, making
 the image very green (for some artistic reason!). The beauty look is

docs/guides/authoring/transforms.rst

@@ -186,7 +186,7 @@ Keys:
 ``GradingRGBCurveTransform``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Applies a spline-based curve.
+Applies a spline-based curve on the red, green, and blue channels.
 
 Keys:
 
@@ -200,6 +200,27 @@ Keys:
 * ``direction``
 
 
+``GradingHueCurveTransform``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Applies a spline-based curve controlling hue, saturation, and luma.
+
+Keys:
+
+* ``style``
+* ``hue_hue``
+* ``hue_sat``
+* ``hue_lum``
+* ``lum_sat``
+* ``sat_sat``
+* ``lum_lum``
+* ``sat_lum``
+* ``hue_fx``
+* ``rgb2hsy_bypass``
+* ``name``
+* ``direction``
+
+
 ``GradingToneTransform``
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/guides/using_ocio/tool_overview.rst

@@ -18,7 +18,7 @@ point to the config file you want to use.
 Note that some tools depend on OpenEXR or OpenImageIO and other libraries:
  * ociolutimage: (OpenEXR or OpenImageIO)
  * ociodisplay: (OpenEXR or OpenImageIO), OpenGL, GLEW, GLUT
- * ocioconvert: (OpenEXR or OpenImageIO)
+ * ocioconvert: (OpenEXR or OpenImageIO), OpenGL, GLEW, GLUT
 
 .. TODO: link to build instructions
 .. TODO: check app lib dependencies
@@ -43,6 +43,10 @@ This command will expand it back out::
 
 The --list option may be used to see the contents of a .ocioz file.
 
+Note: Archive files generated on Windows machines in OCIO 2.4 or earlier should
+be regenerated in OCIO 2.5 or higher due to a bug in the third-party library
+being used, otherwise they may not open properly on Linux or macOS systems.
+
 
 .. _overview-ociocheck:
 
@@ -92,6 +96,7 @@ problems it will detect are:
 * Required roles being undefined
 * At least one display device is defined
 * No v2 features are used in a v1 config
+* Validates the structure and usage of interop IDs 
 
 
 As with all the OCIO command-line tools, you can use the `--help` argument to
@@ -184,6 +189,8 @@ may be used to output the shader program used by the GPU renderer.
 
 Uses OpenImageIO or OpenEXR for opening and saving files and modifying
 metadata. Supported formats will vary depending on the use of OpenImageIO.
+The interop ID, if available, is written to the header of OpenEXR files.
+
 Use the --help argument for more information on to the available options.
 
 .. TODO: Examples
@@ -283,6 +290,23 @@ The --list argument will print out all of the standard ACES color spaces that ar
 supported as --csc arguments.
 
 
+.. _overview-ociomergeconfigs:
+
+ociomergeconfigs
+****************
+
+The ociomergeconfigs tool processes an OCIOM file to merge one or more config files::
+
+    $ ociomergeconfigs mergeFile.ociom --out mergedConfig.ocio
+
+The OCIOM file identifies the source configs and controls the merge process. 
+Please refer to the API documentation for the ConfigMergingParameters class for an
+explanation of the OCIOM file format, the available merge strategies and the parameters
+available to control the merge process.
+
+Additional documentation on this feature will be forthcoming.
+
+
 .. _overview-ocioperf:
 
 ocioperf

docs/index.rst

@@ -21,10 +21,10 @@ films as SpiderMan 2 (2004), Surf's Up (2007), Cloudy with a Chance of Meatballs
 (2009), Alice in Wonderland (2010), and many more.  
 
 OpenColorIO v2 was in development from 2017 to 2020 and was feature complete as of
-SIGGRAPH 2020.  After a stabilization and bug-fixing period, an official 2.0.0 
-release was made in January 2021.  Development has continued to be active since
-then with the 2.1 release in 2021, the 2.2 release in 2022, and the 2.3 release
-in 2023 adding even more capabilities.  Here is more information about our :ref:`upgrading_to_v2`.
+SIGGRAPH 2020 and was released in January of 2021. Development has continued to be
+active since then with annual releases around September, timed in relation to the
+`VFX Reference Platform <https://vfxplatform.com/>`_.  Here is more information 
+about our :ref:`upgrading_to_v2`.
 
 
 About the Documentation
@@ -39,12 +39,6 @@ The documentation is a work-in-progress and we would love to have your help to
 improve it!  An easy way to get involved is to join the #docs or #ux channel on 
 :ref:`slack`.
 
-Accessing Other Versions
-************************
-
-You are reading the documentation for OCIO v2.  The documentation for the earlier
-1.x series of releases is available `here <https://opencolorio.org/old/index.html>`_.
-
 
 Community
 =========

docs/quick_start/downloads.rst

@@ -8,7 +8,6 @@ Downloads
 =========
 
 * `OCIO v2 ACES Configurations <https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES/releases>`_
-* OCIO v1 Legacy Configurations -- `.zip <https://github.com/imageworks/OpenColorIO-Configs/zipball/master>`__ `.tar.gz <https://github.com/imageworks/OpenColorIO-Configs/tarball/master>`__
 * Reference Images v1.0v4 -- `.tgz <https://code.google.com/p/opencolorio/downloads/detail?name=ocio-images.1.0v4.tgz>`__
 * `OCIO Library source code <https://github.com/AcademySoftwareFoundation/OpenColorIO/releases>`_