From 0db87a7d013ede56c0ebbc82e67cd051eb22a278 Mon Sep 17 00:00:00 2001 From: Doug Walker Date: Mon, 29 Sep 2025 23:47:51 -0400 Subject: [PATCH 1/5] Update documentation for 2.5 release Signed-off-by: Doug Walker --- docs/concepts/publications/publications.rst | 5 + docs/configurations/aces_cg.rst | 19 +- docs/configurations/aces_studio.rst | 11 +- docs/guides/authoring/colorspaces.rst | 84 +++++ docs/guides/authoring/displays_views.rst | 6 + docs/guides/authoring/looks.rst | 11 +- docs/guides/authoring/transforms.rst | 23 +- docs/guides/using_ocio/tool_overview.rst | 23 +- docs/index.rst | 8 +- docs/quick_start/downloads.rst | 1 - docs/releases/_index.rst | 1 + docs/releases/ocio_2_5.rst | 322 ++++++++++++++++++++ 12 files changed, 502 insertions(+), 12 deletions(-) create mode 100644 docs/releases/ocio_2_5.rst diff --git a/docs/concepts/publications/publications.rst b/docs/concepts/publications/publications.rst index 0a9152e5d3..467b7560aa 100644 --- a/docs/concepts/publications/publications.rst +++ b/docs/concepts/publications/publications.rst @@ -7,6 +7,11 @@ Presentations & Publications ============================ +* ASWF Open Source Days 2025 -- Project Update `video `_ + +* Color Interop Forum -- "Color Space Encodings for Texture Assets and CG Rendering" + `Recommendation `_ + * ASWF Open Source Days 2024 -- NanoColor `video `_ * ASWF Open Source Days 2024 -- Project Update `video `_ diff --git a/docs/configurations/aces_cg.rst b/docs/configurations/aces_cg.rst index 77c6cc73c4..3f69d3cd23 100644 --- a/docs/configurations/aces_cg.rst +++ b/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. `_ @@ -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`` + +``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: @@ -46,6 +50,15 @@ Where: * ACES: The aces-dev version being used * 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 diff --git a/docs/configurations/aces_studio.rst b/docs/configurations/aces_studio.rst index 6021d32a84..5e829a23a5 100644 --- a/docs/configurations/aces_studio.rst +++ b/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. `_ @@ -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 diff --git a/docs/guides/authoring/colorspaces.rst b/docs/guides/authoring/colorspaces.rst index b5cfce0239..1ddfeeec70 100644 --- a/docs/guides/authoring/colorspaces.rst +++ b/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 + + - ! + 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 + + - ! + 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 + + - ! + 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: diff --git a/docs/guides/authoring/displays_views.rst b/docs/guides/authoring/displays_views.rst index 581e272587..1cdc8c51bf 100644 --- a/docs/guides/authoring/displays_views.rst +++ b/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 diff --git a/docs/guides/authoring/looks.rst b/docs/guides/authoring/looks.rst index d3a35c873f..543dd1440c 100644 --- a/docs/guides/authoring/looks.rst +++ b/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: ! {src: 'neutral-${SHOT}-${SEQ}.csp', interpolation: linear } inverse_transform: ! {src: 'neutral-${SHOT}-${SEQ}-reverse.csp', interpolation: linear } + - ! + 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: ! {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 diff --git a/docs/guides/authoring/transforms.rst b/docs/guides/authoring/transforms.rst index 8a5a36db83..3313410050 100644 --- a/docs/guides/authoring/transforms.rst +++ b/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`` ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/guides/using_ocio/tool_overview.rst b/docs/guides/using_ocio/tool_overview.rst index 4de6c84ab0..02fa9a728f 100644 --- a/docs/guides/using_ocio/tool_overview.rst +++ b/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. + .. _overview-ociocheck: @@ -283,6 +287,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 diff --git a/docs/index.rst b/docs/index.rst index 1a8a4a9a61..90fb0592e5 100644 --- a/docs/index.rst +++ b/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 `_. Here is more information +about our :ref:`upgrading_to_v2`. About the Documentation diff --git a/docs/quick_start/downloads.rst b/docs/quick_start/downloads.rst index d39f449c57..c775101a2e 100644 --- a/docs/quick_start/downloads.rst +++ b/docs/quick_start/downloads.rst @@ -8,7 +8,6 @@ Downloads ========= * `OCIO v2 ACES Configurations `_ -* OCIO v1 Legacy Configurations -- `.zip `__ `.tar.gz `__ * Reference Images v1.0v4 -- `.tgz `__ * `OCIO Library source code `_ diff --git a/docs/releases/_index.rst b/docs/releases/_index.rst index ab62b6b987..20e5d707ff 100644 --- a/docs/releases/_index.rst +++ b/docs/releases/_index.rst @@ -10,6 +10,7 @@ Releases .. toctree:: :caption: Upgrading to v2 + ocio_2_5 ocio_2_4 ocio_2_3 ocio_2_2 diff --git a/docs/releases/ocio_2_5.rst b/docs/releases/ocio_2_5.rst new file mode 100644 index 0000000000..ffb56e82d7 --- /dev/null +++ b/docs/releases/ocio_2_5.rst @@ -0,0 +1,322 @@ +.. + SPDX-License-Identifier: CC-BY-4.0 + Copyright Contributors to the OpenColorIO Project. + + +OCIO 2.5 Release +================ + +Timeline +******** + +OpenColorIO 2.5 was delivered in September 2025 and is in the VFX Reference Platform for +calendar year 2026. + + +Breaking Changes +================ + +Please be aware of the following changes when upgrading to OCIO 2.5. + +For Users ++++++++++ + +* OCIOZ archive files created on Windows in prior releases are incompatible with OCIO 2.5 +due to an issue in a third-party library and will need to be regenerated. Please see below +for more details. + +* For applications that use the categories attribute of color spaces to filter the color +space menus shown to users, the filtering will now include color spaces that do not have +any category set. (Though applications may use a new API call to override this behavior.) + +For Developers +++++++++++++++ + +* Applications that use the OCIO GPU renderer may need to make small adjustments to their +code due to changes that were required in order to support the Khronos Vulkan graphics API. + +* The Python functions getActiveDisplays and getActiveViews now return iterators, please +see below for details. + +* Please see the section below about version updates to required third-party dependencies. + + +New Feature Guide +================= + +Config Merging (PREVIEW RELEASE) +******************************** + +Config files may now be merged. This was a long-standing feature request and it opens up +interesting new possibilities for how configs are created, managed, and deployed. Because +the workflow ramifications of this feature are far-reaching, this is being labelled a +Preview Release and therefore the API and behavior may change as a result of more feedback +and testing. + +Five different merge strategy options are provided, along with an extensive set of parameters +to customize the process. The new feature handles the complexities inherent in the very +flexible OCIO config format such as: + +* Handling name or alias conflicts. + +* Handling differences in reference connection spaces by adding compensating color space +conversions to transforms. + +* Avoiding adding duplicate color spaces (even if they are named are differently). This +allows applications to avoid adding color spaces that may already be present in the user's +config. + +* Providing a mechanism to group added color spaces under a separate menu hierarchy. + +For Users ++++++++++ + +End-users may use the new ``ociomergeconfigs`` command-line tool to merge configs. A new +OCIOM file format is provided to set the parameters that control how the merge is done. +For example, you may merge a specific set of color spaces or displays and views that are +needed for a given project into a general-purpose base config. + +For Developers +++++++++++++++ + +Developers may use the new API to merge a set of color spaces that an application requires +into the user's config. (This is typically done on the fly, in memory, to avoid modifying +any config files on disk.) Applications may then publish their required color spaces as a +config file which makes the process transparent to color scientists or pipeline experts at +a facility who may use ``ociomergeconfigs`` to merge the application color spaces into their +own configs and validate everything works as intended. + + +Built-in ACES 2.0 Configs +************************* + +The ACES 2.0 library support was finalized in the OCIO 2.4.2 release. In the 2.5.0 release, +built-in ACES 2.0 versions of the Studio and CG config are now provided. This allows use of +the ACES 2.0 Output Transforms as OCIO views. + +This `ASWF Open Source Days presentation `_ +from ILM's Alex Fry provides a great overview of the benefits of the new configs. + +In addition, the new configs make expanded use of OCIO v2 features such as File Rules and +Viewing Rules and add a virtual display to support use with ICC monitor profiles. + +Please take note that the display color spaces in the new configs pass through negative +values rather than clamping them (by mirroring the transfer function around the origin). +This provides better support for video workflows that require values below reference black +to be passed through. + +Finally, there are a few other color space additions including a Gamma 2.2 Rec.709 display +color space and a color space for DJI Log. + +For Users ++++++++++ + +The following URI strings may be provided anywhere you would normally provide a file path +to a config (e.g. as the OCIO environment variable): + +To use the updated :ref:`aces_cg`, use this string for the config path: + ocio://cg-config-v4.0.0_aces-v2.0_ocio-v2.5 + +To use the updated :ref:`aces_studio`, use this string for the config path: + ocio://studio-config-v4.0.0_aces-v2.0_ocio-v2.5 + +This string will give you the current default config, which is the latest ACES 2 CG Config: + ocio://default + +This string now points to this latest ACES 2 CG config: + ocio://cg-config-latest + +This string now points to this latest ACES 2 Studio config: + ocio://studio-config-latest + + +Hue Curve Transform +******************* + +A new ``GradingHueCurveTransform`` is added to allow a type of selective color correction +often available in grading tools. A set of eight spline-based curve adjustments are provided: + +* Hue-Hue: Map input hue to output hue (where a diagonal line is the identity). +* Hue-Sat: Adjust saturation as a function of hue (a value of 1.0 is the identity). +* Hue-Lum: Adjust luma as a function of hue (a value of 1.0 is the identity). +* Lum-Sat: Adjust saturation as a function of luma (a value of 1.0 is the identity). +* Sat-Sat: Adjust saturation as a function of saturation (a diagonal is the identity). +* Lum-Lum: Adjust luma as a function of luma, maintaining hue & sat (diagonal is identity). +* Sat-Lum: Adjust luma as a function of saturation (a value of 1.0 is the identity). +* Hue-FX : Map input hue to delta output hue (a value of 0.0 is the identity). + +Unlike the typical implementation of tools of this type, this transform is invertible and +has been developed to work well on video, log, and scene-linear color encodings. + +The parameters may be adjusted via OCIO's dynamic parameter mechanism which allows +adjustments to be made without having to recreate a Processor object. This facilitates +real-time adjustment in applications. + + +Vulkan Support +************** + +For Developers +++++++++++++++ + +Support has been added for the Khronos Vulkan graphics API standard. The OCIO GPU renderer may +now be used within applications that use Vulkan to get the most out of the latest GPUs. + +This has required a small modification to the existing GPU API. Developers that use the +GPU interface may need to modify their code when updating to OCIO 2.5. The API for the +following functions have been modified: ``addUniform``, ``addTexture``, ``add3DTexture``, +and ``createShaderText``. The ``addToDeclareShaderCode`` function has been replaced by the +more specific ``addToParameterDeclareShaderCode`` and ``addToTextureDeclareShaderCode``. +In addition new functions have been added to get the descriptor set and texture binding +indices. The ``GPU_LANGUAGE_GLSL_VK_4_6`` option is now available for the GpuLanguage enum. + + +New Color Space Attributes +************************** + +For Config Authors +++++++++++++++++++ + +New attributes are provided to allow OCIO to better interoperate with other color standards. +OCIO now 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. (Please note that the IDs are for use in +file formats but the color space's name attribute is still what should be used in a UI.) + +The new attributes are: + +* `interop_id`: Holds an ID string intended to be used across configs and file formats. + +* `icc_profile_name`: Holds the name of an associated ICC profile. + +* `amf_transform_ids`: Holds the ID strings associated with the ACES Metadata Format (AMF). + +Please note that the drafts of various Color Interop Forum recommendations on this topic are +currently being finalized and should be `published on GitHub `_ +over the next few months. + + +New "edr-video" Encoding +************************ + +For Config Authors +++++++++++++++++++ + +Color spaces currently have an encoding attribute that is used to give applications a general +sense of how colors are distributed within the numerical encoding. There are currently two +encodings that are recommended for use with video: `sdr-video` and `hdr-video`, where the +latter is intended for color spaces such as Rec.2100-PQ and Rec.2100-HLG. However, there are +increasingly a set of color spaces (such as "Display P3 HDR" in the built-in configs) that +use what is essentially an SDR encoding that is extended so that it may be used in cases +where there is a mix of both HDR and SDR content. For these color spaces, a new encoding is +being introduced: `edr-video`. + + +Version Updates +*************** + +The latest versions of all third-party dependencies have been reviewed for compatibility. +In some cases, support for older versions has been dropped. + +For Users ++++++++++ + +* Support for minizip-ng 3.x has been dropped. Due to a bug in previous versions of that +library, any OCIOZ files created on Windows would not have been cross-platform, are not +supported in OCIO 2.5, and will need to be regenerated. You may use standard Zip +decompressors to expand the .ocioz files on Windows and use the `ocioarchive` command-line +tool to recompress them. The new files will be cross-platform and will be compatible both +with OCIO 2.5 and previous releases. + +For Developers +++++++++++++++ + +* Support for CMake 4 has been added. +* Support for more recent versions of all dependences has been added. +* Support for C++ 11 and 14 has been dropped. OCIO now requires at least a C++ 17 compiler. +* Support for Python 3.8 has been dropped. +* Support for Expat prior to 2.6.0 has been dropped. +* Support for OpenEXR prior to 3.2.0 has been dropped. +* Support for Yaml-cpp prior to 0.8.0 has been dropped. +* Continuous Integration testing has added VFX Platform 2025 and dropped 2021. +* Miscellaneous other modifications and improvements have been made. + + +API Enhancements +**************** + +For Developers +++++++++++++++ + +The previous "frozen docs" system for generating Python API documentation for ReadTheDocs +has been replaced. This reduces the burden on developers when adding new API functions and +simplifies the maintenance of the project. + +The previous API for the active display and view lists returned one long string that +developers would need to manually parse into tokens, which could be error-prone (as commas +are both separators and may be used in display and view names). A new set of API calls has +been provided to get and set active displays and views individually. In the case of Python, +the ``getActiveDisplays`` and ``getActiveViews`` functions now return iterators, which is +the only change that requires a modification to existing code. + +In addition, here are some other new API functions: + +* The ``setDisplayTemporary`` function may be used to serialize displays created using an ICC +profile and a config's virtual display. This is helpful if a host application needs to serialize +a config that includes those displays for use by plug-ins such as OpenFX. + +* The ``setTreatNoCategoryAsAny`` function may be used on the ColorSpaceMenuParameters class +to control the menu filtering behavior for color spaces that do not have the categories +attribute set. The default is to include those color spaces when doing category filtering +since this is the least surprising behavior for end-users that are editing their own configs. + +* The following convenience methods have been added to the Config class for working with various +types of views: ``isViewShared``, ``clearSharedViews``, ``AreViewsEqual``, ``hasView``, +``hasVirtualView``, ``isVirtualViewShared``, ``AreVirtualViewsEqual``. + +* The ``setStringVar`` function is now available on the Context class in Python. + +* A ``removeNamedTransform`` function is now available. + + +New Fixed Function Transforms +***************************** + +For Config Authors +++++++++++++++++++ + +The following new styles are available for use with FixedFunctionTransforms in config files +with ``ocio_profile_version`` set to 2.5 or higher. They implement a conversion from an RGB +color space encoding to a hue, saturation, and luma space that is used by the new hue curve +transform. Three conversions are provided that are optimized for scene-linear, logarithmic, +and video color spaces: + +* ``FIXED_FUNCTION_RGB_TO_HSY_LIN`` +* ``FIXED_FUNCTION_RGB_TO_HSY_LOG`` +* ``FIXED_FUNCTION_RGB_TO_HSY_VID`` + + +New Built-in Transforms +*********************** + +For Config Authors +++++++++++++++++++ + +In config files with ``ocio_profile_version`` set to 2.5 or higher, config authors may take +advantage of the following new BuiltinTransform styles that mirror the transfer function +around the origin to pass negative values rather than clamp them: + +* ``DISPLAY - CIE-XYZ-D65_to_REC.1886-REC.709 - MIRROR NEGS`` +* ``DISPLAY - CIE-XYZ-D65_to_REC.1886-REC.2020 - MIRROR NEGS`` +* ``DISPLAY - CIE-XYZ-D65_to_G2.2-REC.709 - MIRROR NEGS`` +* ``DISPLAY - CIE-XYZ-D65_to_sRGB - MIRROR NEGS`` +* ``DISPLAY - CIE-XYZ-D65_to_G2.6-P3-D65 - MIRROR NEGS`` + + +Release Notes +============= + +For additional details, please see the GitHub release page: + +`OCIO 2.5.0 `_ From 849e9bda4bc0064e54032f9bdf5f1b37c79dabcc Mon Sep 17 00:00:00 2001 From: Doug Walker Date: Tue, 30 Sep 2025 00:08:45 -0400 Subject: [PATCH 2/5] Fix typos Signed-off-by: Doug Walker --- docs/configurations/aces_cg.rst | 4 ++-- docs/guides/authoring/colorspaces.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configurations/aces_cg.rst b/docs/configurations/aces_cg.rst index 3f69d3cd23..90a8611336 100644 --- a/docs/configurations/aces_cg.rst +++ b/docs/configurations/aces_cg.rst @@ -27,7 +27,7 @@ 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://cg-config-v4.0.0_aces-v2.0_ocio-v2.5`` +``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) @@ -47,7 +47,7 @@ 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: diff --git a/docs/guides/authoring/colorspaces.rst b/docs/guides/authoring/colorspaces.rst index 1ddfeeec70..7416763354 100644 --- a/docs/guides/authoring/colorspaces.rst +++ b/docs/guides/authoring/colorspaces.rst @@ -520,7 +520,7 @@ 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 +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 From e21f91875ed53fd5ac3809695aa31fb6e8a94767 Mon Sep 17 00:00:00 2001 From: Doug Walker Date: Tue, 30 Sep 2025 02:30:49 -0400 Subject: [PATCH 3/5] Address review comments Signed-off-by: Doug Walker --- docs/guides/using_ocio/tool_overview.rst | 5 ++++- docs/releases/ocio_2_5.rst | 11 +++++------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/guides/using_ocio/tool_overview.rst b/docs/guides/using_ocio/tool_overview.rst index 02fa9a728f..040d0b397d 100644 --- a/docs/guides/using_ocio/tool_overview.rst +++ b/docs/guides/using_ocio/tool_overview.rst @@ -45,7 +45,7 @@ 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. +being used, otherwise they may not open properly on Linux or macOS systems. .. _overview-ociocheck: @@ -96,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 @@ -188,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 diff --git a/docs/releases/ocio_2_5.rst b/docs/releases/ocio_2_5.rst index ffb56e82d7..99f290c757 100644 --- a/docs/releases/ocio_2_5.rst +++ b/docs/releases/ocio_2_5.rst @@ -21,9 +21,8 @@ Please be aware of the following changes when upgrading to OCIO 2.5. For Users +++++++++ -* OCIOZ archive files created on Windows in prior releases are incompatible with OCIO 2.5 -due to an issue in a third-party library and will need to be regenerated. Please see below -for more details. +* OCIOZ archive files created on Windows in prior releases should be regenerated due to an +issue in a third-party library. Please see below for more details. * For applications that use the categories attribute of color spaces to filter the color space menus shown to users, the filtering will now include color spaces that do not have @@ -224,10 +223,10 @@ For Users * Support for minizip-ng 3.x has been dropped. Due to a bug in previous versions of that library, any OCIOZ files created on Windows would not have been cross-platform, are not -supported in OCIO 2.5, and will need to be regenerated. You may use standard Zip +fully supported in OCIO 2.5, and should be regenerated. You may use standard Zip decompressors to expand the .ocioz files on Windows and use the `ocioarchive` command-line -tool to recompress them. The new files will be cross-platform and will be compatible both -with OCIO 2.5 and previous releases. +tool to recompress them. The new files will be cross-platform and will be compatible with +both OCIO 2.5 and previous releases. For Developers ++++++++++++++ From ecaabd92f8363325dd0add12d8589e5d785d8406 Mon Sep 17 00:00:00 2001 From: Doug Walker Date: Tue, 30 Sep 2025 14:41:56 -0400 Subject: [PATCH 4/5] Fix markdown Signed-off-by: Doug Walker --- docs/index.rst | 8 +------ docs/releases/ocio_2_5.rst | 48 +++++++++++++++++++------------------- 2 files changed, 25 insertions(+), 31 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 90fb0592e5..f87ffb2d79 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,7 +23,7 @@ films as SpiderMan 2 (2004), Surf's Up (2007), Cloudy with a Chance of Meatballs OpenColorIO v2 was in development from 2017 to 2020 and was feature complete as of 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 `_. Here is more information +`VFX Reference Platform `_. Here is more information about our :ref:`upgrading_to_v2`. @@ -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 `_. - Community ========= diff --git a/docs/releases/ocio_2_5.rst b/docs/releases/ocio_2_5.rst index 99f290c757..a6f9598dd6 100644 --- a/docs/releases/ocio_2_5.rst +++ b/docs/releases/ocio_2_5.rst @@ -14,7 +14,7 @@ calendar year 2026. Breaking Changes -================ +**************** Please be aware of the following changes when upgrading to OCIO 2.5. @@ -22,20 +22,20 @@ For Users +++++++++ * OCIOZ archive files created on Windows in prior releases should be regenerated due to an -issue in a third-party library. Please see below for more details. + issue in a third-party library. Please see below for more details. * For applications that use the categories attribute of color spaces to filter the color -space menus shown to users, the filtering will now include color spaces that do not have -any category set. (Though applications may use a new API call to override this behavior.) + space menus shown to users, the filtering will now include color spaces that do not have + any category set. (Though applications may use a new API call to override this behavior.) For Developers ++++++++++++++ * Applications that use the OCIO GPU renderer may need to make small adjustments to their -code due to changes that were required in order to support the Khronos Vulkan graphics API. + code due to changes that were required in order to support the Khronos Vulkan graphics API. * The Python functions getActiveDisplays and getActiveViews now return iterators, please -see below for details. + see below for details. * Please see the section below about version updates to required third-party dependencies. @@ -59,11 +59,11 @@ flexible OCIO config format such as: * Handling name or alias conflicts. * Handling differences in reference connection spaces by adding compensating color space -conversions to transforms. + conversions to transforms. * Avoiding adding duplicate color spaces (even if they are named are differently). This -allows applications to avoid adding color spaces that may already be present in the user's -config. + allows applications to avoid adding color spaces that may already be present in the user's + config. * Providing a mechanism to group added color spaces under a separate menu hierarchy. @@ -185,11 +185,11 @@ file formats but the color space's name attribute is still what should be used i The new attributes are: -* `interop_id`: Holds an ID string intended to be used across configs and file formats. +* ``interop_id``: Holds an ID string intended to be used across configs and file formats. -* `icc_profile_name`: Holds the name of an associated ICC profile. +* ``icc_profile_name``: Holds the name of an associated ICC profile. -* `amf_transform_ids`: Holds the ID strings associated with the ACES Metadata Format (AMF). +* ``amf_transform_ids``: Holds the ID strings associated with the ACES Metadata Format (AMF). Please note that the drafts of various Color Interop Forum recommendations on this topic are currently being finalized and should be `published on GitHub `_ @@ -222,11 +222,11 @@ For Users +++++++++ * Support for minizip-ng 3.x has been dropped. Due to a bug in previous versions of that -library, any OCIOZ files created on Windows would not have been cross-platform, are not -fully supported in OCIO 2.5, and should be regenerated. You may use standard Zip -decompressors to expand the .ocioz files on Windows and use the `ocioarchive` command-line -tool to recompress them. The new files will be cross-platform and will be compatible with -both OCIO 2.5 and previous releases. + library, any OCIOZ files created on Windows would not have been cross-platform, are not + fully supported in OCIO 2.5, and should be regenerated. You may use standard Zip + decompressors to expand the .ocioz files on Windows and use the `ocioarchive` command-line + tool to recompress them. The new files will be cross-platform and will be compatible with + both OCIO 2.5 and previous releases. For Developers ++++++++++++++ @@ -262,17 +262,17 @@ the only change that requires a modification to existing code. In addition, here are some other new API functions: * The ``setDisplayTemporary`` function may be used to serialize displays created using an ICC -profile and a config's virtual display. This is helpful if a host application needs to serialize -a config that includes those displays for use by plug-ins such as OpenFX. + profile and a config's virtual display. This is helpful if a host application needs to serialize + a config that includes those displays for use by plug-ins such as OpenFX. * The ``setTreatNoCategoryAsAny`` function may be used on the ColorSpaceMenuParameters class -to control the menu filtering behavior for color spaces that do not have the categories -attribute set. The default is to include those color spaces when doing category filtering -since this is the least surprising behavior for end-users that are editing their own configs. + to control the menu filtering behavior for color spaces that do not have the categories + attribute set. The default is to include those color spaces when doing category filtering + since this is the least surprising behavior for end-users that are editing their own configs. * The following convenience methods have been added to the Config class for working with various -types of views: ``isViewShared``, ``clearSharedViews``, ``AreViewsEqual``, ``hasView``, -``hasVirtualView``, ``isVirtualViewShared``, ``AreVirtualViewsEqual``. + types of views: ``isViewShared``, ``clearSharedViews``, ``AreViewsEqual``, ``hasView``, + ``hasVirtualView``, ``isVirtualViewShared``, ``AreVirtualViewsEqual``. * The ``setStringVar`` function is now available on the Context class in Python. From 4f22e5d7608598929a429b57e2eafc8f8098beaa Mon Sep 17 00:00:00 2001 From: Doug Walker Date: Wed, 1 Oct 2025 01:11:08 -0400 Subject: [PATCH 5/5] Minor updates Signed-off-by: Doug Walker --- docs/releases/ocio_2_5.rst | 3 +++ tests/gpu/FixedFunctionOp_test.cpp | 4 ++-- tests/gpu/GradingHueCurveOp_test.cpp | 1 + 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/releases/ocio_2_5.rst b/docs/releases/ocio_2_5.rst index a6f9598dd6..593076e3af 100644 --- a/docs/releases/ocio_2_5.rst +++ b/docs/releases/ocio_2_5.rst @@ -278,6 +278,9 @@ In addition, here are some other new API functions: * A ``removeNamedTransform`` function is now available. +* The previously deprecated function ``getDefaultBuiltinConfigName`` has now been removed. + Please use ``ResolveConfigPath("ocio://default")`` instead. + New Fixed Function Transforms ***************************** diff --git a/tests/gpu/FixedFunctionOp_test.cpp b/tests/gpu/FixedFunctionOp_test.cpp index b6a30c11ae..6c3879d858 100644 --- a/tests/gpu/FixedFunctionOp_test.cpp +++ b/tests/gpu/FixedFunctionOp_test.cpp @@ -1262,7 +1262,7 @@ OCIO_ADD_GPU_TEST(FixedFunction, style_RGB_TO_HSY_LIN_fwd) -0.055f, 0.01f, 0.05f, 0.f }; test.setCustomValues(values); - test.setErrorThreshold(1e-6f); + test.setErrorThreshold(5e-6f); } OCIO_ADD_GPU_TEST(FixedFunction, style_RGB_TO_HSY_LIN_inv) @@ -1285,7 +1285,7 @@ OCIO_ADD_GPU_TEST(FixedFunction, style_RGB_TO_HSY_LIN_inv) 0.730158730159f, 0.811517000f, -0.0009310f, 0.f }; test.setCustomValues(values); - test.setErrorThreshold(1e-6f); + test.setErrorThreshold(5e-6f); } OCIO_ADD_GPU_TEST(FixedFunction, style_RGB_TO_HSY_LOG_fwd) diff --git a/tests/gpu/GradingHueCurveOp_test.cpp b/tests/gpu/GradingHueCurveOp_test.cpp index 3eb31c0826..9a11626939 100644 --- a/tests/gpu/GradingHueCurveOp_test.cpp +++ b/tests/gpu/GradingHueCurveOp_test.cpp @@ -250,6 +250,7 @@ void BypassRGBtoHSY(OCIOGPUTest & test, OCIO::TransformDirection dir, bool dynam test.setProcessor(hc); test.setErrorThreshold(1e-5f); + test.setTestInfinity(false); } OCIO_ADD_GPU_TEST(GradingHueCurve, bypass_rgbtohsy_fwd)