From 213c6dd3d8428db2d28e68c0e257a28da0e01ec8 Mon Sep 17 00:00:00 2001 From: Doug Walker Date: Wed, 4 Jan 2023 16:44:23 -0500 Subject: [PATCH] Update documentation for 2.2 release (#1738) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update documentation for 2.2 release Signed-off-by: Doug Walker * Fix typos Signed-off-by: Doug Walker * Remove V2_DOC_README.md Signed-off-by: Doug Walker * Tweaks to 2.2 Signed-off-by: Doug Walker * Improve installation section Signed-off-by: Doug Walker * Add link to demo config Signed-off-by: Doug Walker * Fix typos Signed-off-by: Doug Walker * Improve file_rules section Signed-off-by: Doug Walker Signed-off-by: Doug Walker (cherry picked from commit 17f5c98f9b89e423f66d0cd07a2334467b1bdee0) Signed-off-by: Cédrik Fuoco --- COMMITTERS.md | 1 + CONTRIBUTING.md | 41 +- docs/V2_DOC_README.md | 106 ----- docs/concepts/publications/publications.rst | 27 +- docs/configurations/_index.rst | 6 +- docs/configurations/aces_1.0.3.rst | 8 +- docs/configurations/aces_cg.rst | 42 ++ docs/configurations/aces_studio.rst | 41 ++ docs/configurations/ocio_v2_demo.rst | 4 + docs/guides/authoring/colorspaces.rst | 18 +- docs/guides/authoring/overview.rst | 19 +- docs/guides/authoring/rules.rst | 57 ++- docs/guides/authoring/transforms.rst | 1 + .../contributing/documentation_guidelines.rst | 102 ++++- .../contributing/repository_structure.rst | 28 +- .../contributing/submitting_changes.rst | 10 +- docs/guides/using_ocio/tool_overview.rst | 48 ++- docs/index.rst | 25 +- docs/quick_start/downloads.rst | 39 +- docs/quick_start/for_artists.rst | 9 +- docs/quick_start/for_config_authors.rst | 9 +- docs/quick_start/for_contributors.rst | 5 +- docs/quick_start/for_devs.rst | 18 +- docs/quick_start/installation.rst | 374 +++++++++++------ docs/{upgrading_v2 => releases}/_index.rst | 8 +- .../how_to.rst => releases/ocio_2_0.rst} | 24 +- docs/releases/ocio_2_1.rst | 173 ++++++++ docs/releases/ocio_2_2.rst | 395 ++++++++++++++++++ docs/toc_redirect.rst | 2 +- include/OpenColorIO/OpenColorIO.h | 26 +- include/OpenColorIO/OpenColorTypes.h | 5 +- 31 files changed, 1259 insertions(+), 412 deletions(-) delete mode 100644 docs/V2_DOC_README.md create mode 100644 docs/configurations/aces_cg.rst create mode 100644 docs/configurations/aces_studio.rst rename docs/{upgrading_v2 => releases}/_index.rst (74%) rename docs/{upgrading_v2/how_to.rst => releases/ocio_2_0.rst} (97%) create mode 100644 docs/releases/ocio_2_1.rst create mode 100644 docs/releases/ocio_2_2.rst diff --git a/COMMITTERS.md b/COMMITTERS.md index e7da40cb39..23ed878e73 100644 --- a/COMMITTERS.md +++ b/COMMITTERS.md @@ -20,3 +20,4 @@ The current OpenColorIO Committers are: | Doug Walker | @doug-walker | | Kevin Wheatley | @KevinJW | | Rémi Achard | @remia | +| Cédrik Fuoco | @cedrik-fuoco-adsk | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 684e09a7a1..0d0a442c4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ explains our contribution process and procedures, so please review it first: For a description of the roles and responsibilities of the various members of the OpenColorIO community, see [GOVERNANCE](GOVERNANCE.md), and for further details, see the project's -[Technical Charter](docs/aswf/Charter.md). Briefly, Contributors are anyone +[Technical Charter](ASWF/Charter.md). Briefly, Contributors are anyone who submits content to the project, Committers review and approve such submissions, and the Technical Steering Committee provides general project oversight. @@ -214,18 +214,20 @@ the work. a Committer other than the PR contributor may squash and merge changes into the main branch. -See also (from the OCIO Developer Guide): -* [Getting started](http://opencolorio.org/developers/getting_started.html) -* [Submitting Changes](http://opencolorio.org/developers/submitting_changes.html) +For a more detailed description of the contribution process, please see the +Contributing Guide in the main OCIO documentation: + +* [Getting Started](https://opencolorio.readthedocs.io/en/latest/guides/contributing/contributing.html#getting-started) +* [Submitting Changes](https://opencolorio.readthedocs.io/en/latest/guides/contributing/contributing.html#submitting-changes) ## Coding Standards Please see the OpenColorIO -[Coding guidelines](http://opencolorio.org/developers/coding_guidelines.html) +[Coding guidelines](https://opencolorio.readthedocs.io/en/latest/guides/contributing/contributing.html#coding-style-guide) for a reference on project code style and best practices. For standards on contributing to documentation, see the -[Documentation guidelines](http://opencolorio.org/developers/documentation_guidelines.html). +[Documentation guidelines](https://opencolorio.readthedocs.io/en/latest/guides/contributing/contributing.html#documentation-guidelines). ## Test Policy @@ -245,27 +247,8 @@ The test should should be run, via ``ctest``, before submitting a pull request. ## Versioning Policy -OpenColorIO uses [semantic versioning](https://semver.org), which labels each -version with three numbers: Major.Minor.Patch, where: - -* **MAJOR** indicates incompatible API changes -* **MINOR** indicates functionality added in a backwards-compatible manner -* **PATCH** indicates backwards-compatible bug fixes - -## Creating a Release - -To create a new release from the main branch: - -1. Update the release notes in ``CHANGELOG.md`` with a high-level summary of - the features and improvements. Also include the summary in the Release - comments. - -2. Create a new release on the GitHub Releases page. - -3. Tag the release with name beginning with '``v``', e.g. '``v2.1.0``'. - -4. Download and sign the release tarball, as described - [here](https://wiki.debian.org/Creating%20signed%20GitHub%20releases), +OpenColorIO labels each version with three numbers: Major.Minor.Patch, where: -5. Attach the detached ``.asc`` signature file to the GitHub release as a - binary file. +* **MAJOR** indicates major architectural changes +* **MINOR** indicates an introduction of significant new features +* **PATCH** indicates ABI-compatible bug fixes and minor enhancements diff --git a/docs/V2_DOC_README.md b/docs/V2_DOC_README.md deleted file mode 100644 index 45bb946eeb..0000000000 --- a/docs/V2_DOC_README.md +++ /dev/null @@ -1,106 +0,0 @@ -# OCIO v2 Documentation Effort - -Since the API autodoc effort is happening simultaneously it will be easier for -a lot of contributors to do a light-weight build of the Sphinx docs, which -doesn't require building OCIO in its entirety. - -## How to Build HTML Docs - -In addition to the general OCIO v2 dependencies, install Doxygen, Sphinx, and -the Python packages listed in the `docs/requirements.txt` file. - -Doxygen can be installed with a package manager, or by downloading a binary -distribution from [Doxygen's website](https://www.doxygen.nl/download.html). -Use one of the following commands to install Doxygen with a platform-specific -package manager: - -Linux (Debian, etc.): - -``` -apt-get install doxygen -``` - -Linux (Fedora, etc.): - -``` -yum install doxygen -``` - -macOS ([Homebrew](https://brew.sh/)): - -``` -brew install doxygen -``` - -Windows ([Chocolatey](https://chocolatey.org/)): - -``` -choco install doxygen.install -``` - -Sphinx and the other Python dependencies can be installed with a single `pip` -command on all platforms: - -``` -pip install -r docs/requirements.txt -``` - -To build only the RST docs (excluding API) locally: - -``` -cd docs -mkdir _build -sphinx-build -b html . _build - _build/index.html -``` - -To build all HTML docs (including API) locally: - -``` -mkdir _build -cd _build -cmake ../. -DOCIO_BUILD_DOCS=ON -DCMAKE_INSTALL_PREFIX=../_install -make -j docs - docs/build-html/index.html -``` - -Python 3 is required to build the documentation. If you have multiple Python -installs you'll need to make sure pip and CMake find the correct version. You -can manually inform cmake of which to use by adding this option to the above -`cmake` command, which configures the documentation build: - -``` --DPython_ROOT= -``` - -To ease the documentation build and test on macOS one could also add these -three lines in the ~/.zshrc file: - -``` -alias python=/usr/local/bin/python3 -alias pip=/usr/local/bin/pip3 -alias =open -a "" -``` - -## Quirks - -The vuepress theme that we've migrated to has some quirks to its design. For -example it only allows two nested table of contents (TOC). So things have to be -organized in a slightly different way than other sphinx projects. - -The root-level `toc_redirect.rst` points to where to find the different section -TOCs. The name and contents of each sections TOC is defined in that -sub-directory's `_index.rst` file. - -In this TOC the `:caption:` directive determines what the name of the section -will be in the side-bar, and in the header of the website. The *H1* header -determines the name of the page in the right/left arrows navigation bar. In a -lot of cases this ends up doubling up the name on the page, but this seems -unavoidable at the present time. If additional explanatory text is put in the -`_index.rst` files then it shouldn't be as problematic. - -The site will show all *H1* headers in the side panel by default, these then -expand when selected to show all *H2* headers. - -Due to the limited TOC and side-bar depth, we shouldn't be afraid of looong -pages with many *H2* headings to break down the page into logical quadrants. diff --git a/docs/concepts/publications/publications.rst b/docs/concepts/publications/publications.rst index fe64c6f2f8..dfa8fcf778 100644 --- a/docs/concepts/publications/publications.rst +++ b/docs/concepts/publications/publications.rst @@ -4,11 +4,28 @@ .. _publications: -Publications -============ +Presentations & Publications +============================ -DigiPro 2020 **paper** `"The ASWF takes OpenColorIO to the Next Level" `_ +* OCIO wins the Pipeline Tool award at DigiPro 2022! `video `_ -DigiPro 2020 **video** `"The ASWF takes OpenColorIO to the Next Level" `_ +* ASWF Open Source Days 2022 `video `_ -`Cinematic Color `_ +* HPA Tech Retreat 2022 "Color Processing with OCIO v2 and the Academy/ASC Common LUT Format" + `Slides & Tutorial `_ + +* OCIO v2 wins an Engineering Excellence award from the Hollywood Post Alliance! + `article `_ + +* SIGGRAPH 2021 course "Color management with OpenColorIO V2" + `video `__ `PDF `__ `ACM `_ + +* ASWF Open Source Days 2021 `video `_ + +* DigiPro 2020 "The ASWF takes OpenColorIO to the Next Level" `video `__ `PDF `__ `ACM `_ + +* ASWF Open Source Days 2020 `video `_ + +* ASWF Open Source Days 2019 `video `_ + +* `Cinematic Color `_ diff --git a/docs/configurations/_index.rst b/docs/configurations/_index.rst index 2b7556688e..734cf350bd 100644 --- a/docs/configurations/_index.rst +++ b/docs/configurations/_index.rst @@ -10,8 +10,10 @@ Configurations .. toctree:: :caption: Configurations + aces_studio + aces_cg + ocio_v2_demo aces_1.0.3 - nuke_default spi_anim spi_vfx - ocio_v2_demo + nuke_default diff --git a/docs/configurations/aces_1.0.3.rst b/docs/configurations/aces_1.0.3.rst index b8ae17d946..ace8b95a0a 100644 --- a/docs/configurations/aces_1.0.3.rst +++ b/docs/configurations/aces_1.0.3.rst @@ -2,17 +2,21 @@ SPDX-License-Identifier: CC-BY-4.0 Copyright Contributors to the OpenColorIO Project. +.. _aces_1.0.3: + aces_1.0.3 ========== This section describes the ACES 1.0.3 OpenColorIO configuration. .. note:: - There is a more recent version of the ACES config for ACES 1.2 available here: + There is a more recent version of the ACES 1.0.3 config for ACES 1.2 available here: - https://github.com/colour-science/OpenColorIO-Configs/tree/feature/aces-1.2-config - An ACES config that takes advantage of the new OCIO v2 features is under development. +.. note:: + Please note that both of these configurations have been supplanted by the new + :ref:`aces_studio` for OCIO v2. Information about ACES diff --git a/docs/configurations/aces_cg.rst b/docs/configurations/aces_cg.rst new file mode 100644 index 0000000000..d134b62b44 --- /dev/null +++ b/docs/configurations/aces_cg.rst @@ -0,0 +1,42 @@ +.. + SPDX-License-Identifier: CC-BY-4.0 + Copyright Contributors to the OpenColorIO Project. + +.. _aces_cg: + +ACES CG Config +============== + +The ACES Computer Graphics (CG) config is a simple, lightweight config intended for use +in typical digital content creation (DCC) apps that need robust choices for texture and +rendering spaces and a basic selection of display and view transforms. + +Users who need a more extensive set of color spaces, including digital cinema camera +color spaces and a wider set of displays and view should look at the :ref:`aces_studio`. + +The latest version of this config may be downloaded from the Releases page of its GitHub +`repo. `_ + +The ACES CG Config leverages the high quality ACES implementation built into OCIO itself +and so requires no external LUT files. In fact, even the config file is built into OCIO +and users may access it from any application that uses OCIO 2.2 or higher by using the +following string in place of the config path:: + ocio://cg-config-v1.0.0_aces-v1.3_ocio-v2.1 + +The default built-in config is currently the ACES CG Config, so the even simpler: +``ocio://default`` may be used instead. Note however, that the value of the default +config may evolve over time. + +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 +space in the new config). + +Please note that with OCIO v2 we are trying to be more rigorous about what constitutes a +"color space". For this reason, the new configs do not bake view transforms or looks into +the display color spaces. Therefore, it is necessary to use a DisplayViewTransform rather +than a ColorSpaceTransform if you want to bake in an ACES Output Transform. This is not +only more rigorous from a color management point of view, it also helps clarify to end-users +the important role of a view transform in the process. Baking in a view transform is a +fundamentally different process than just converting between color space encodings, and it +should be perceived as such by users. diff --git a/docs/configurations/aces_studio.rst b/docs/configurations/aces_studio.rst new file mode 100644 index 0000000000..0f8132fc58 --- /dev/null +++ b/docs/configurations/aces_studio.rst @@ -0,0 +1,41 @@ +.. + SPDX-License-Identifier: CC-BY-4.0 + Copyright Contributors to the OpenColorIO Project. + +.. _aces_studio: + +ACES Studio Config +================== + +The ACES Studio Config is the successor to the widely used :ref:`ACES config ` +for OCIO v1. + +It contains the complete set of ACES color spaces, displays, and views. In addition, it +contains some extra color spaces that are widely used in the VFX 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 latest version of this config may be downloaded from the Releases page of its GitHub +`repo. `_ + +The ACES Studio Config leverages the high quality ACES implementation built into OCIO itself +and so requires no external LUT files. In fact, even the config file is built into OCIO +and users may access it from any application that uses OCIO 2.2 or higher by using the +following string in place of the config path:: + ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1 + +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 +space in the new config). + +Please note that with OCIO v2 we are trying to be more rigorous about what constitutes a +"color space". For this reason, the new configs do not bake view transforms or looks into +the display color spaces. Therefore, it is necessary to use a DisplayViewTransform rather +than a ColorSpaceTransform if you want to bake in an ACES Output Transform. This is not +only more rigorous from a color management point of view, it also helps clarify to end-users +the important role of a view transform in the process. Baking in a view transform is a +fundamentally different process than just converting between color space encodings, and it +should be perceived as such by users. diff --git a/docs/configurations/ocio_v2_demo.rst b/docs/configurations/ocio_v2_demo.rst index 22c072c078..52f098f19a 100644 --- a/docs/configurations/ocio_v2_demo.rst +++ b/docs/configurations/ocio_v2_demo.rst @@ -10,6 +10,10 @@ ocio-v2_demo Note: this is not intended to be a complete production-ready config, its purpose is to introduce many of the new features in OCIO v2. +Due to the limitations of the web template, it may be easier for you to read this +config in a text editor. The config file is located +`here. `_ + .. literalinclude:: ocio-v2_demo.ocio :language: yaml diff --git a/docs/guides/authoring/colorspaces.rst b/docs/guides/authoring/colorspaces.rst index 27684f1515..b5cfce0239 100644 --- a/docs/guides/authoring/colorspaces.rst +++ b/docs/guides/authoring/colorspaces.rst @@ -15,19 +15,19 @@ Colorspaces Required. -This section is a list of all the colorspaces known to OCIO. A -colorspace can be referred to elsewhere within the config (including +This section is a list of the scene-referred colorspaces in the config. +A colorspace may be referred to elsewhere within the config (including other colorspace definitions), and are used within OCIO-supporting applications. -A color space may use the following keys: +A colorspace may use the following keys: ``to_scene_reference`` and ``from_scene_reference`` --------------------------------------------------- These keys specify the transforms that define the relationship between -the color space and the scene-referred reference space. +the colorspace and the scene-referred reference space. Note: In OCIO v1, the keys ``to_reference`` and ``from_reference`` were used (since there was only one reference space). These are still supported @@ -404,10 +404,10 @@ compatibility. Optional. -These two options are used when OCIO transforms are applied on the -GPU. +These two options were used in OCIO v1 when transforms were applied on the +GPU. However, the new GPU renderer in OCIO v2 does not need these. -It is also used to automatically generate a "shaper LUT" when +However, they may still be used to automatically generate a "shaper LUT" when :ref:`baking LUT's ` unless one is explicitly specified (not all output formats utilise this) @@ -469,6 +469,8 @@ It's common to use literal ``|`` block syntax to preserve all newlines: This is the second. +.. _config-display-colorspaces: + Display Colorspaces ******************* @@ -477,7 +479,7 @@ Display Colorspaces Optional. -This section is a list of all the display colorspaces known to OCIO. +This section is a list of all the display-referred colorspaces in the config. A display colorspace is very similar to a colorspace except its transforms go from or to the display-referred reference space rather than the scene-referred reference space. diff --git a/docs/guides/authoring/overview.rst b/docs/guides/authoring/overview.rst index 7df06e669c..7d96a97508 100644 --- a/docs/guides/authoring/overview.rst +++ b/docs/guides/authoring/overview.rst @@ -18,6 +18,12 @@ This page alone will not help you to write a useful config file! See the :ref:`configurations` section for examples of complete, practical configs, and discussion of how they fit within a facilities workflow. +Please note that you should use the OCIO Python or C++ API to generate +the config.ocio file rather than writing the YAML by hand in a text editor. +However, if you do ever modify YAML by hand rather than via the API, you +should run :ref:`overview-ociocheck` on it to ensure that the syntax is +correct. + YAML basics *********** @@ -29,7 +35,7 @@ has a good overview. OCIO configs typically use a small subset of YAML, so looking at existing configs is probably the quickest way to familiarise yourself -(just remember the indentation is important!) +(just remember the indentation is important!). Checking for errors ******************* @@ -59,8 +65,12 @@ An OCIO config has the following sections: * :ref:`config-displays-views` -- This section defines how color spaces should be viewed. * :ref:`config-looks` -- Looks are transforms used to adjust colors, such as to apply a creative effect. -* :ref:`config-colorspaces` -- This section defines the universe of color space encodings +* :ref:`config-colorspaces` -- This section defines the scene-referred color space encodings available within the config. +* :ref:`config-display-colorspaces` -- This section defines the display-referred color space + encodings available within the config. +* :ref:`config-named-transforms` -- Named Transforms are a way to provide transforms that + do not have a fixed relationship to a specific reference space, such as a utility curve. A collection of :ref:`config-transforms` is provided for use in the various sections of the config file. @@ -99,11 +109,12 @@ Optional. A brief description of the configuration. ``name`` ^^^^^^^^ -Optional. A unique name for the config. +Optional. A unique name for the config. Future versions of OCIO might use this as a +sort of "namespace" for the color spaces defined in the rest of the config. .. code-block:: yaml - name: foo_2021-02-01 + name: studio-config-v1.0.0_aces-v1.3_ocio-v2.1 ``search_path`` diff --git a/docs/guides/authoring/rules.rst b/docs/guides/authoring/rules.rst index 3c557dbf4a..8fbc35775d 100644 --- a/docs/guides/authoring/rules.rst +++ b/docs/guides/authoring/rules.rst @@ -16,7 +16,9 @@ File & Viewing rules ``file_rules`` ^^^^^^^^^^^^^^ -Either file_rules or the default role are Required. +.. warning:: + Either the file_rules section or the default role are Required for configs of + version 2 or higher. Use the File Rules to assign a default color space to files based on their path. @@ -24,10 +26,10 @@ Here is example showing the various types of rules that may be defined: .. code-block:: yaml - files_rules: + file_rules: - ! {name: LogC, extension: "*", pattern: "*LogC*", colorspace: ARRI LogC} - ! {name: OpenEXR, extension: "exr", pattern: "*", colorspace: ACEScg} - - ! {name: TIFF, regex: ".*\.TIF?F$", colorspace: sRGB} + - ! {name: TIFF, regex: ".*\\.TIF?F", colorspace: sRGB} - ! {name: ColorSpaceNamePathSearch} - ! {name: Default, colorspace: default} @@ -42,36 +44,41 @@ other keys depend on the rule type. This is the basic rule type that uses Unix glob style pattern matching and is thus very easy to use. It contains the keys: -* ``name``: Name of the rule +* ``name``: Name of the rule. * ``pattern``: Glob pattern to be used for the main part of the name/path. - This is case-sensitive. + This is case-sensitive. It must be in double-quotes. Set it to "*" if you only + want the rule to consider the extension. * ``extension``: Glob pattern or string to be used for the file extension. Note that if glob tokens are not used, the extension will be used in a non-case-sensitive way by default. For example the simple string "exr" would match "exr" and "EXR". - If you only want to match "exr", use the glob pattern "[e][x][r]". + If you only want to match "exr", use the glob pattern "[e][x][r]". It must be + in double-quotes. Set it to "*" if you only want the rule to consider the pattern. * ``colorspace``: ColorSpace name to be returned. -2. Regex Rules -- +2. RegEx Rules -- This is similar to the basic rule but allows additional capabilities for power-users. It contains the keys: -* ``name``: Name of the rule -* ``regex``: Regular expression to be evaluated. +* ``name``: Name of the rule. +* ``regex``: Regular expression to be evaluated. It must be in double-quotes. * ``colorspace``: ColorSpace name to be returned. +Note that a backslash character in a RegEx expression needs to be doubled up as ``\\`` +(as shown in the example above for the TIFF rule) to make it through the Yaml parsing. + 3. OCIO v1 style Rule -- This rule allows the use of the OCIO v1 style, where the string is searched for ColorSpace names from the config. This rule may occur 0 or 1 times in the list. The position in the list prioritizes it with respect to the other rules. It has the key: -* ``name``: Must be "ColorSpaceNamePathSearch". +* ``name``: Must be ``ColorSpaceNamePathSearch``. 4. Default Rule -- -The file_rules must always end with this rule. If no prior rules match, this +The file_rules section must always end with this rule. If no prior rules match, this rule specifies the ColorSpace applications will use. It has the keys: -* ``name``: must be "Default". +* ``name``: must be ``Default``. * ``colorspace``: ColorSpace name to be returned. Note: OCIO v1 defined a ``default`` role intended to specify a default color space @@ -84,19 +91,24 @@ missing, an exception will be thrown when loading the config. Note that the strictparsing token does not affect the behavior of the File Rules API. In other words, evaluating the rules will always result in a ColorSpace being -available to an application. However, the API alsos allow the application to know +available to an application. However, the API also allows the application to know which rule was the matching one. So apps that want to work in "strict" mode should first check if strictparsing is true and if so check to see if the matching rule was the Default Rule. If so, it could then notify the user and take whatever action -is appropriate. +is appropriate. (As an alternative to checking which rule number was matched, the +API call ``filepathOnlyMatchesDefaultRule`` may be used instead.) Roles may be used rather than ColorSpace names in the rules. -It is also legal for rules to have additional key:value pairs where the value +It is also legal for rules to have additional key:value pairs where the value may be an arbitrary string. The API provides access to getting/setting these additional pairs and will preserve them on a Config read/write. These may be used to define application-specific behavior. +Note to developers: The older ``parseColorSpaceFromString`` API call is now deprecated +and should be replaced with ``getColorSpaceFromFilepath``. + + ``strictparsing`` ^^^^^^^^^^^^^^^^^ @@ -107,12 +119,21 @@ Optional. Valid values are ``true`` and ``false``. Default is ``true`` strictparsing: true -OCIO provides a mechanism for applications to extract the colorspace -from a filename (the ``parseColorSpaceFromString`` API method) +.. warning:: + This attribute is from OCIO v1. In OCIO v2, the FileRules system was + introduced and so the ``strictparsing`` attribute is less relevant now. + The ``parseColorSpaceFromString`` API call is now deprecated and the + proper way to obtain this information is ``getColorSpaceFromFilepath``. + The FileRules always return a default color space but the API + ``filepathOnlyMatchesDefaultRule`` may be used by applications that + want to take some special action if ``strictparsing`` is true. + +OCIO v1 provided a mechanism for applications to extract the colorspace +from a filename (the ``parseColorSpaceFromString`` API method). So for a file like ``example_render_v001_lnf.0001.exr`` it will determine the colorspace ``lnf`` (it being the right-most substring -containing a colorspace name) +containing a colorspace name). However, if the colorspace cannot be determined and ``strictparsing: true``, it will return an empty string. diff --git a/docs/guides/authoring/transforms.rst b/docs/guides/authoring/transforms.rst index 51dbbe904a..8a5a36db83 100644 --- a/docs/guides/authoring/transforms.rst +++ b/docs/guides/authoring/transforms.rst @@ -344,6 +344,7 @@ Keys: must also be present and the result is clamped at the high end. +.. _config-named-transforms: Named Transforms **************** diff --git a/docs/guides/contributing/documentation_guidelines.rst b/docs/guides/contributing/documentation_guidelines.rst index 6749cdc3bd..2cb6758b16 100644 --- a/docs/guides/contributing/documentation_guidelines.rst +++ b/docs/guides/contributing/documentation_guidelines.rst @@ -14,18 +14,39 @@ The documentation primarily lives in the ``docs/`` folder, within the main OpenColorIO repository. The rST source for the C++ API documentation is extracted from -comments in the public header files in ``export/`` +comments in the public header files in ``include/`` -The Python API documentation is extracted from dummy .py files within -the ``src/pyglue/DocStrings/`` folder +Installation of requirements +**************************** + +Scripts are available, for each platform, to install the documentation +requirements. + +The ``install_docs_env.sh`` script in the share/ci/scripts/ directory +will install the Python-related requirements for building the documentation +(Sphinx, six, testresources, recommonmark, sphinx-press-theme, sphinx-tabs, +and breathe) and Doxygen. + +Use GitBash (`provided with Git for Windows `_) to +execute the script on Windows. + +Python 3 is required to build the documentation. If you have multiple Python +installs you'll need to make sure pip and CMake find the correct version. You +can manually inform CMake of which to use by adding this option to the below +`cmake` command, which configures the documentation build: + + -DPython_ROOT= + +For the Python packages, ensure their locations are in your ``PYTHONPATH`` +environment variable prior to configuring the build. Building the docs ***************** -Just like a :ref:`regular build from source `, -but specify the ``-D OCIO_BUILD_DOCS=yes`` argument to CMake. +The build is just like a :ref:`regular build from source `, +but specify the ``-D OCIO_BUILD_DOCS=ON`` argument to CMake. -Then run the ``make doc`` target. The default HTML output will be +Then run the ``make docs`` target. The default HTML output will be created in ``build_dir/docs/build-html/`` Note that CMake must be run before each invocation of ``make`` to copy @@ -37,7 +58,50 @@ Initial run:: Then after each change you wish to preview:: - $ cmake -D OCIO_BUILD_DOCS=yes .. && make doc + $ cmake -D OCIO_BUILD_DOCS=ON .. && make docs + +Updating the Python docs +************************ + +If a contributor makes changes to any part of OCIO which affects the Python API docs +(so, public headers, Python bindings, any documentation process code, etc.) they should +do a local build with the new CMake option -DOCIO_BUILD_FROZEN_DOCS=ON, and add the +modified rST files under docs/api/python/frozen to their PR. + +Note: If you run the scripts on Linux, the freezing process should work well. On other +platforms, the process may sometimes make spurious deltas to rST files unrelated to your +changes. Please don't add these files to your PR. + +The OCIO conf.py module has a switch that detects when docs are being built on GH Actions +(CI env var == true) it will backup the frozen folder to a sibling backup folder on Sphinx +init, and following Sphinx build completion will do a file-by-file comparison of the new +frozen and the backup folders. If there are differences, the CI job may fail with an error +explaining where the differences were found and with instructions on how to fix them. + +The conf.py also has a switch that detects when it is being run on RTD, and in that case +will itself run Doxygen to generate the XML needed by breathe prior to building the docs, +and will also facilitate a CMake configure_file-like process (via Python) to handle +substitutions in headers and docs source files that CMake would usually handle, but can't +in this case. One potential plus to all of this is that if someone wants to just build +OCIO docs, they can technically do so by running sphinx-build in the docs directory, and +nothing more. Right now that only works when the READTHEDOCS env var == True, but it could +be easily exposed another way if needed. + +These features required several custom Sphinx extensions tuned for our project which are +located under share/docs. + +Building the docs -- Excluding the API docs +******************************************* + +If you don't need to build the API documentation, there is a quick and dirty way to +do a docs build. This approach does not need to compile the C++ code but is not ideal +since it modifies files in the source directory rather than the build directory: + + export READTHEDOCS=True + cd docs (in the source directory) + mkdir _build + sphinx-build -b html . _build + _build/index.html Basics ****** @@ -79,6 +143,30 @@ Basics In order to bake a LUT, ... +Quirks +****** + +The vuepress theme that we've migrated to has some quirks to its design. For +example, it only allows two nested table of contents (TOC). So things have to be +organized in a slightly different way than other sphinx projects. + +The root-level `toc_redirect.rst` points to where to find the different section +TOCs. The name and contents of each sections TOC is defined in that +sub-directory's `_index.rst` file. + +In this TOC the `:caption:` directive determines what the name of the section +will be in the sidebar, and in the header of the website. The *H1* header +determines the name of the page in the right/left arrows navigation bar. In a +lot of cases this ends up doubling up the name on the page, but this seems +unavoidable at the present time. If additional explanatory text is put in the +`_index.rst` files then it shouldn't be as problematic. + +The site will show all *H1* headers in the side panel by default, these then +expand when selected to show all *H2* headers. + +Due to the limited TOC and sidebar depth, we shouldn't be afraid of looong +pages with many *H2* headings to break down the page into logical quadrants. + Emacs rST mode ************** diff --git a/docs/guides/contributing/repository_structure.rst b/docs/guides/contributing/repository_structure.rst index 372dafe7ed..fb04e99543 100644 --- a/docs/guides/contributing/repository_structure.rst +++ b/docs/guides/contributing/repository_structure.rst @@ -45,32 +45,32 @@ continuous integration (CI) workflows for all supported platforms. Each .yml file defines one GHA workflow, which can contain one or more jobs and the repository events that trigger the workflow. +ASWF +**** + +This subdirectory contains important ASWF governance documents like the +OpenColorIO charter, CLAs and DCO reference. + +The ``meetings`` subdirectory contains historical meeting minutes for +TSC (Technical Steering Committee) and working group meetings. More +recent TSC and working group meeting notes are stored on the +`ASWF Wiki. `_ + docs **** This directory contains the OpenColorIO documentation source and build configuration. -The ``guides/contributing/tsc`` subdirectory contains meeting minutes for all -recorded TSC (Technical Steering Committee) and working group meetings. The -``guides/contributing/aswf`` subdirectory contains important ASWF governance -documents like the OpenColorIO charter, CLAs and DCO reference. - See :ref:`documentation-guidelines` for information on contributing to OCIO documentation. ext *** -This directory serves two purposes: - -1. House modified external dependencies which are permissible to store within - the OpenColorIO repository. Permissible dependencies have compatible FOSS - licenses which have documented approval by the ASWF governing board. - -2. Location for external dependencies temporarily installed and statically - linked by OpenColorIO when using the CMake ``OCIO_INSTALL_EXT_PACKAGES`` - option with the value ``MISSING`` or ``ALL``. +Houses modified external dependencies which are permissible to store within +the OpenColorIO repository. Permissible dependencies have compatible FOSS +licenses which have documented approval by the ASWF governing board. include ******* diff --git a/docs/guides/contributing/submitting_changes.rst b/docs/guides/contributing/submitting_changes.rst index 261b2409cf..a818742f1b 100644 --- a/docs/guides/contributing/submitting_changes.rst +++ b/docs/guides/contributing/submitting_changes.rst @@ -13,8 +13,8 @@ Code Review Ask early, and ask often! All new contributors are highly encouraged to post development ideas, questions, -or any other thoughts to the :ref:`mailing_lists` before starting to code. This -greatly improves the process and quality of the resulting library. Code +or any other thoughts to :ref:`slack` or the :ref:`mailing_lists` before starting to +code. This greatly improves the process and quality of the resulting library. Code reviews (particularly for non-trivial changes) are typically far simpler if the reviewers are aware of a development task beforehand. (And, who knows? Maybe they will have implementation suggestions as well!) @@ -73,6 +73,12 @@ assistance. git add . git commit -s -m 'Implement my feature' +* If your PR changes anything that appears in the public API documentation, + you should follow the directions below in "Updating the Python docs". + If this proves problematic for you, please reach out for help on Slack. + One of the other developers will probably be able to make the updates + for you in another PR. + * Push your changes back to origin (your fork):: git push -u origin myFeature diff --git a/docs/guides/using_ocio/tool_overview.rst b/docs/guides/using_ocio/tool_overview.rst index 87ad7d3974..6e5be4c81e 100644 --- a/docs/guides/using_ocio/tool_overview.rst +++ b/docs/guides/using_ocio/tool_overview.rst @@ -24,6 +24,26 @@ Note that some tools depend on OpenEXR or OpenImageIO and other libraries: .. TODO: check app lib dependencies .. TODO: make a pretty table in RST. +.. _overview-ocioarchive: + +ocioarchive +*********** + +This command-line tool allows you to convert a config and its external LUT files +into an OCIOZ archive file. A .ocioz file may be supplied to any command that +takes the path to a config or set as the OCIO environment variable. + +This example creates a file called myarchive.ocioz:: + + $ ocioarchive myarchive --iconfig myconfig/config.ocio + +This command will expand it back out:: + + $ ocioarchive --extract myarchive.ocioz + +The --list option may be used to see the contents of a .ocioz file. + + .. _overview-ociocheck: ociocheck @@ -33,7 +53,7 @@ This is a command-line tool which shows an overview of an OCIO config file, and checks for obvious errors. For example, the following shows the output of a config with a typo - -the colorspace used for ``compositing_log`` is not incorrect:: +the colorspace used for ``compositing_log`` is incorrect:: $ ociocheck --iconfig example.ocio @@ -189,6 +209,17 @@ not the case. Also, it does not leverage any of the new OCIO v2 features. .. TODO: Link to discussion of OpenImageIO source? +.. _overview-pyociodisplay: + +pyociodisplay +************* + +The pyociodisplay tool is a minimal image viewer implementation demonstrating use of +the OCIO GPU renderer in a Python application. It requires downloading a few dependencies +before use. For more information, please see the +`README. `_ + + .. _overview-ociolutimage: ociolutimage @@ -240,6 +271,7 @@ ACES2065-1:: The --list argument will print out all of the standard ACES color spaces that are supported as --csc arguments. + .. _overview-ocioperf: ocioperf @@ -272,6 +304,7 @@ Examples:: .. TODO: examples formatting + .. _overview-ociowrite: ociowrite @@ -298,3 +331,16 @@ Here is an example:: $ export OCIO=/path/to/the/config.ocio $ ociowrite --colorspaces acescct aces2065-1 --file mytransform.ctf + + +.. _overview-pyocioamf: + +pyocioamf +********* + +The pyocioamf tool is an initial attempt to support the ACES Metadata File (AMF) +`format. `_ +This Python script will take an AMF file and produce an OCIO CTF file that implements its color +pipeline. The CTF file may be applied to images using tools such as :ref:`overview-ocioconvert`. +For more information, please see the +`README. `_ diff --git a/docs/index.rst b/docs/index.rst index e620b9f37b..1241802ea1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,31 +20,30 @@ OCIO v1 represented the culmination of years of production experience earned on 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 has been in development since 2017 and was feature complete as of +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. OCIO v2 is in the VFX Reference Platform for -calendar year 2021. The OCIO v2 code is in the RB-2.0 branch on -`GitHub `_ -and we encourage developers to start integrating and providing feedback. -See :ref:`upgrading_to_v2` for more. +release was made in January 2021. Development has continued to be active since +then with the 2.1 release in 2021 and the 2.2 release in 2022 adding even more +capabilities. Here is more information about our :ref:`upgrading_to_v2`. About the Documentation ======================= +The documentation has been updated to include basic coverage of the new OCIO v2 features +but additional work is needed to provide more detail and tutorials about how to +best leverage them. We have an OCIO User Experience (UX) working group that is +gradually working on more coverage. + 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 channel on +improve it! An easy way to get involved is to join the #docs or #ux channel on :ref:`slack`. -The documentation has been updated to include most of the new OCIO v2 features -but additional work is needed to provide more detail and tutorials about how to -best leverage them. We will be working on that over the coming weeks. - Accessing Other Versions ************************ -You are reading the documentation for OCIO v2. The documentation for the the previous -stable release (1.1.1) is available `here `_. +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/quick_start/downloads.rst b/docs/quick_start/downloads.rst index a2b71cf601..d39f449c57 100644 --- a/docs/quick_start/downloads.rst +++ b/docs/quick_start/downloads.rst @@ -7,44 +7,13 @@ Downloads ========= -* Sample OCIO Configurations -- `.zip `__ `.tar.gz `__ +* `OCIO v2 ACES Configurations `_ +* OCIO v1 Legacy Configurations -- `.zip `__ `.tar.gz `__ * Reference Images v1.0v4 -- `.tgz `__ -* Core Library v2.0.0 -- `.zip `__ `.tar.gz `__ -* Core Library dev -- `.zip `__ `.tar.gz `__ - -Per-version updates: :ref:`changelog-main`. - -Build instructions: :ref:`building-from-source`. +* `OCIO Library source code `_ .. _contributor-license-agreements: Contributor License Agreements ****************************** -Please see the `OCIO GitHub repository `__ - -Deprecated Downloads -******************** -* Reference Images v1.0v3 `tgz `__ -* Reference Images v1.0v2 `tgz `__ -* Reference Images v1.0v1 `tgz `__ - -* Core Library v1.1.1 -- `.zip `__ `.tar.gz `__ -* Core Library v1.1.0 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.9 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.8 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.7 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.6 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.5 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.4 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.3 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.2 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.1 -- `.zip `__ `.tar.gz `__ -* Core Library v1.0.0 -- `.zip `__ `.tar.gz `__ - -* Color Config v0.7v4 `tgz `__ (OCIO v0.7.6+) -* Core Library v0.8.7 -- `.zip `__ `.tar.gz `__ -* Core Library v0.7.9 -- `.zip `__ `.tar.gz `__ -* Core Library v0.6.1 -- `.zip `__ `.tar.gz `__ -* Core Library v0.5.16 -- `.zip `__ `.tar.gz `__ -* Core Library v0.5.8 -- `.zip `__ `.tar.gz `__ - +Please see the `OCIO GitHub repository `__ diff --git a/docs/quick_start/for_artists.rst b/docs/quick_start/for_artists.rst index 7716e4eb63..d3ee1613aa 100644 --- a/docs/quick_start/for_artists.rst +++ b/docs/quick_start/for_artists.rst @@ -14,7 +14,12 @@ each application. Note that OCIO configurations are required to do any 'real' work, and are available separately on the :ref:`downloads` section of this site. Example images are also available. For assistance customizing .ocio configurations, -contact `ocio-user `__\. +contact `ocio-user `_ or the #configs +channel on :ref:`slack` + +If your application supports OCIO 2.2 or later, you may take advantage of the +configurations built into OCIO itself. For example, by setting the config path to: +``ocio://default``. - Step 1: set the ``$OCIO`` environment-variable to ``/path/to/your/config.ocio`` - Step 2: Launch supported application. @@ -23,6 +28,6 @@ If you are on a platform that is not envvar friendly, most applications also provide a menu option to select a different OCIO configuration after launch. Please be sure to select a configuration that matches your color workflow (VFX -work typically requires a different profile than animated features). If you need +work sometimes requires a different profile than animated features). If you need assistance picking a profile, email `ocio-user `__\. diff --git a/docs/quick_start/for_config_authors.rst b/docs/quick_start/for_config_authors.rst index 87348ac2bb..45fa3cc722 100644 --- a/docs/quick_start/for_config_authors.rst +++ b/docs/quick_start/for_config_authors.rst @@ -7,11 +7,10 @@ Quick Start for Config Authors ============================== -Get started by following the :ref:`installation` instructions. Note that if -you want to try out the new OpenColorIO v2 features, you'll need to build -from source. You will want to make sure to build the command-line tools as -well as the library itself, so you should install OpenImageIO or OpenEXR before -building (OCIO is now able to build the latter itself). +As a config author, you'll want access to the OCIO command-line tools such as +``ociocheck``. Please see the :ref:`installation` instructions for the various +options, for example Homebrew on macOS and Vcpkg on Windows. On Linux you may +need to build from source. Grab the available configuration files (and the sample images, if you want) from :ref:`downloads` so you'll have some examples to study. diff --git a/docs/quick_start/for_contributors.rst b/docs/quick_start/for_contributors.rst index d123150228..3b33442d1c 100644 --- a/docs/quick_start/for_contributors.rst +++ b/docs/quick_start/for_contributors.rst @@ -15,9 +15,10 @@ testing, example configs, and documentation as well as actual coding. issues with the ``good first issue`` label. * If you want to help develop config files, start by looking at :ref:`quick_start_config_authors` - and join the #configs channel on :ref:`slack`. + and join the #configs channel on :ref:`slack`. From there, you may want to join the + OCIO Configs working group. -* If you want to help with documentation, join the #docs channel on :ref:`slack`. +* If you want to help with documentation, join the #docs and #ux channel on :ref:`slack`. * If you want to help test, join the #general channel on :ref:`slack` and let us know you want to help test. diff --git a/docs/quick_start/for_devs.rst b/docs/quick_start/for_devs.rst index fb98472ed2..358a5ac2d5 100644 --- a/docs/quick_start/for_devs.rst +++ b/docs/quick_start/for_devs.rst @@ -8,10 +8,12 @@ Quick Start for Developers ========================== Get started by following the :ref:`installation` instructions to build OCIO from -source. You will want to make sure to build the command-line tools as well as the -library itself, so you should install OpenImageIO or OpenEXR before building -(OCIO is now able to build the latter itself). Note that active development of -OCIO v2 is happening in the main branch. +source. In addition to the library itself, you will want to make sure to build the +command-line tools, including ``ocioconvert``. + +Note that active development of OCIO v2 is happening in the main branch. + +Watch the OCIO SIGGRAPH course listed in :ref:`publications`. Grab the available configuration files (and the sample images, if you want) from :ref:`downloads`. @@ -22,12 +24,16 @@ the :ref:`overview-ocioconvert` tool to process an image from one color space to Try using :ref:`overview-ociodisplay` to view an image through a color space conversion. Take a look at the example code in the :ref:`developers-usageexamples` and then study -the code for the command-line tools, which is under src/apps. +the code for the command-line tools, which is under ``src/apps``. -There are helper classes under src/libutils/apphelpers for common application tasks +There are helper classes under ``src/libutils/apphelpers`` for common application tasks such as generating color space menus, building a viewing pipeline for a viewport, and writing a color picker for scene-linear color spaces. Look through the :ref:`concepts_overview` to get a sense of the big picture. Check out :ref:`upgrading_to_v2` for an overview of the new features in OCIO v2. + +Join the #dev and #ux channel on :ref:`slack`. From the #ux channel, you may want to +get involved with the OCIO User Experience (UX) working group which discusses best +practices for implementing OCIO support in applications. diff --git a/docs/quick_start/installation.rst b/docs/quick_start/installation.rst index d265f5f0e3..600fa89e12 100644 --- a/docs/quick_start/installation.rst +++ b/docs/quick_start/installation.rst @@ -5,30 +5,45 @@ .. _installation: Installation -************ +============ + +Installation may be done either by installing pre-built binaries from various package +managers or by building from source. (The OCIO project currently does not provide +pre-built libraries as downloadable artifacts other than through package managers.) + +Please note that the version available through a given package manager may be significantly +outdated when compared to the current official OCIO release, so please verify the version +you install is current. (Unfortunately, even two years after the introduction of +OpenColorIO v2, several package managers continue to install OCIO 1.1.1.) -Although OpenColorIO is available through a variety of package managers, please note that the -version available through a given package manager may be significantly outdated when compared to -the current official OCIO release. Even two years after the introduction of OpenColorIO v2, several -package managers continue to install OCIO 1.1.1. +Alternatives +************ .. _Python: Python -^^^^^^ +++++++ + +If you only need the Python binding, the simplest solution is to take advantage of the pre-built +wheels in the Python Package Index (PyPI) `here `_. It +can be installed as follows, once you have Python installed. -If you only need the Python bindings, the simplest solution is to take advantage of the pre-built -wheels in the Python Package Installer (PyPi) `here `__. It -can be installed by using this command:: +**PyPI**:: pip install opencolorio +The pre-built wheels are listed `here `_. Note that +source code is provided, so it may be possible for ``pip`` to compile the binding on your machine if +the matrix of Python version and platform version does not have the combination you need. More +detailed instructions are available for how to use +`pip. `_ + OpenImageIO -^^^^^^^^^^^ ++++++++++++ -If you only need to apply color conversions to images, please note that OpenImageIO's oiiotool has -most of the functionality of the ocioconvert command-line tool (although not everything, such as -GPU processing). OpenImageIO is available via several package managers (including brew and vcpkg). +If you only need to apply color conversions to images, please note that OpenImageIO's ``oiiotool`` has +most of the functionality of the ``ocioconvert`` command-line tool (although not everything, such as +GPU processing). OpenImageIO is available via several package managers (including Homebrew and Vcpkg). **Homebrew**:: @@ -38,16 +53,17 @@ GPU processing). OpenImageIO is available via several package managers (includin vcpkg install openimageio[opencolorio,tools]:x64-windows --recurse -Installing OpenColorIO using existing packages -********************************************** + +Installing OpenColorIO using Package Managers +============================================= Linux -^^^^^ +***** -When it comes to Linux distributions, relatively few of the Linux distribution repositories have been -updated to OCIO v2. The **latest Fedora** is one good option as it offers the most -recent release of OpenColorIO v2. Information about the package can be found on -`fedoraproject website `__. +When it comes to Linux distributions, relatively few of the Linux distribution repositories +have been updated to OCIO v2. The **latest Fedora** is one good option as it offers a +recent release of OpenColorIO v2. Information about the package can be found on the +`Fedora project website `__. For the other distributions, information about which release of OpenColorIO is available can be verified on `pkgs.org `__. @@ -55,72 +71,88 @@ verified on `pkgs.org `__. **The recommendation is to build OpenColorIO from source**. You may build from source using the instructions below. See :ref:`building-from-source`. -Windows 7 or newer using vcpkg -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Windows using Vcpkg +******************* -Vcpkg can be used to install OpenColorIO on Windows. In order to do that, Vcpkg must be installed +Vcpkg can be used to install OpenColorIO on Windows 7 or higher. To do that, Vcpkg must be installed by following the `official instructions `__. Once Vcpkg is installed, OpenColorIO and some of the tools can be installed with the following command:: vcpkg install opencolorio[tools]:x64-windows -Note that this package **does not** install ocioconvert, ociodisplay, ociolutimage and the Python -bindings. +Note that this package **does not** install ``ocioconvert``, ``ociodisplay``, ``ociolutimage``, +and the Python binding. -The three missing tools can be built from source by following the steps in the :ref:`Windows 7 or newer` -section while the Python bindings can be install using the pip command in the :ref:`Python` section. +If you need the extra command-line tools, you'll need to install :ref:`from source. ` +However, the Python binding can be installed as described in the :ref:`Python` section. -OS X using Homebrew -^^^^^^^^^^^^^^^^^^^ +MacOS using Homebrew +******************* -You can use the Homebrew package manager to install OpenColorIO on OS X. +You can use the Homebrew package manager to install OpenColorIO on macOS. First install Homebrew as per the instructions on the `Homebrew -homepage `__ (or see the `Homebrew wiki -`__ for more -detailed instructions) +homepage `__ (or see the `Homebrew documentation +`__ for more detailed instructions). Then simply run the following command to install:: brew install opencolorio -Homebrew does not install the Python binding or the command-line tools that depend on OpenImageIO -such as ocioconvert, ociodisplay and ociolutimage. +Homebrew does not install the Python binding or the command-line tools that depend on either +OpenImageIO or OpenEXR such as ``ocioconvert``, ``ociodisplay``, and ``ociolutimage``. .. _building-from-source: -Building from source -******************** +Building from Source +==================== + +The basic requirements to build OCIO from source on Linux, macOS, and Windows are a +supported C++ compiler, CMake, and an internet connection. The OCIO Cmake scripts are +able to download, build, and install all other required components. However, more +advanced users are also able to have the build use their own version of dependencies. Dependencies -^^^^^^^^^^^^ +************ -The basic requirements for building OCIO are the following. Note that, by -default, cmake will try to install all of the items labelled with * and so -it is not necessary to install those items manually: +OCIO depends on the following components. By default, the OCIO CMake scripts will +download and build the items labelled with a \*, so it is not necessary to install those +items manually: -- cmake >= 3.12 +Required components: + +- C++ 11-17 compiler (gcc, clang, msvc) +- CMake >= 3.13 - \*Expat >= 2.4.1 (XML parser for CDL/CLF/CTF) - \*yaml-cpp >= 0.7.0 (YAML parser for Configs) - \*Imath >= 3.0 (for half domain LUTs) - \*pystring >= 1.1.3 +- \*minizip-ng >= 3.0.7 (for config archiving) +- \*ZLIB >= 1.2.13 (for config archiving) -Some optional components also depend on: +Optional OCIO functionality also depends on: - \*Little CMS >= 2.2 (for ociobakelut ICC profile baking) -- \*pybind11 >= 2.9.2 (for the Python bindings) -- Python >= 2.7 (for the Python bindings) -- Python 3.7 or 3.8 (for the docs, with the following PyPi packages) - - Sphinx - - six - - testresources - - recommonmark - - sphinx-press-theme - - sphinx-tabs - - breathe -- NumPy (for complete Python test suite) +- \*OpenGL GLUT & GLEW (for ociodisplay) +- \*OpenEXR >= 3.0 (for apps including ocioconvert) +- OpenImageIO >= 2.1.9 (for apps including ocioconvert) +- \*OpenFX >= 1.4 (for the OpenFX plug-ins) +- OpenShadingLanguage >= 1.11 (for the OSL unit tests) - Doxygen (for the docs) -- OpenImageIO >= 2.1.9 or OpenEXR >= 3.0 (for apps including ocioconvert) +- NumPy (optionally used in the Python test suite) +- \*pybind11 >= 2.9.2 (for the Python binding) +- Python >= 2.7 (for the Python binding only) +- Python 3.7 - 3.9 (for building the documentation) + +Building the documentation requires the following packages, available via PyPI: + +- Sphinx +- six +- testresources +- recommonmark +- sphinx-press-theme +- sphinx-tabs +- breathe Example bash scripts are provided in `share/ci/scripts `_ @@ -132,14 +164,14 @@ available for all supported platforms. Use GitBash this script on Windows. Automated Installation ----------------------- +++++++++++++++++++++++ -Listed dependencies with a preceeding * can be automatically installed at -build time using the ``OCIO_INSTALL_EXT_PACKAGES`` option in your cmake -command (requires an internet connection). This is the default. C/C++ -libraries are pulled from external repositories, built, and statically-linked -into libOpenColorIO. Python packages are installed with ``pip``. All installs -of these components are fully contained within your build directory. +Dependencies listed above with a preceeding * can be automatically installed at +build time using the ``OCIO_INSTALL_EXT_PACKAGES`` option in your ``cmake`` +command (requires an internet connection). The C/C++ libraries are pulled from +external repositories, built, and are (typically) statically-linked into an OCIO +dynamic library. All installs of these components are fully contained within your +build directory. Three ``OCIO_INSTALL_EXT_PACKAGES`` options are available:: @@ -153,37 +185,130 @@ Three ``OCIO_INSTALL_EXT_PACKAGES`` options are available:: current system. Existing Install Hints ----------------------- - -When using existing system libraries, the following CMake variables can be -defined to hint at non-standard install locations and preference of shared -or static linking: - -- ``-Dexpat_ROOT=`` (include and/or library root dir) -- ``-Dexpat_STATIC_LIBRARY=ON`` (prefer static lib) -- ``-Dyaml-cpp_ROOT=`` (include and/or library root dir) -- ``-Dyaml-cpp_STATIC_LIBRARY=ON`` (prefer static lib) -- ``-DImath_ROOT=`` (include and/or library root dir) -- ``-DImath_STATIC_LIBRARY=ON`` (prefer static lib) -- ``-DHalf_ROOT=`` (include and/or library root dir) -- ``-DHalf_STATIC_LIBRARY=ON`` (prefer static lib) -- ``-Dpystring_ROOT=`` (include and/or library root dir) -- ``-Dpystring_STATIC_LIBRARY=ON`` (prefer static lib) -- ``-Dlcms2_ROOT=`` (include and/or library root dir) -- ``-Dlcms2_STATIC_LIBRARY=ON`` (prefer static lib) -- ``-Dpybind11_ROOT=`` (include and/or library root dir) -- ``-DPython_EXECUTABLE=`` (Python executable) - -To hint at Python package locations, add paths to the ``PYTHONPATH`` -environment variable prior to configuring the build. +++++++++++++++++++++++ + +When using libraries already on your system, the CMake variable +``-D _ROOT=`` may be used to specify the path to the include and +library root directory rather than have CMake try to find it. The package names used +by OCIO are as follows (note that these are case-sensitive): + +Required: + +- ``expat`` +- ``yaml-cpp`` +- ``Imath`` +- ``pystring`` +- ``ZLIB`` +- ``minizip-ng`` + +Optional: + +- ``OpenEXR`` +- ``OpenImageIO`` +- ``lcms2`` +- ``pybind11`` +- ``openfx`` +- ``OSL`` +- ``Sphinx`` +- ``GLEW`` +- ``GLUT`` +- ``Python`` + +There are scenarios in which some of the dependencies may not be compiled into an +OCIO dynamic library. This is more likely when OCIO does not download the packages +itself. In these cases, it may be helpful to additionally specify the CMake variable +``-D _STATIC_LIBRARY=ON``. The following package names support this hint: +``expat``, ``yaml-cpp``, ``Imath``, ``lcms2``, ``ZLIB``, and ``minizip-ng``. + +Rather than using ``_ROOT``, and possibly ``_STATIC_LIBRARY``, you may instead use +``-D _LIBRARY=`` and ``-D _INCLUDE_DIR=``. +In this case, the library path will control whether a static or dynamic library is used. +It may also be used to handle situations where the library and/or include files are not +in the typical location relative to the root directory. + +The OCIO `CMake find modules `_ +may be consulted for more detail on the handling of a given package and the CMake +variables it uses. + +Please note that if you provide your own ``minizip-ng``, rather than having OCIO's CMake +download and build it, you will likely need to set its CMake variables the same way +that OCIO does (e.g., enable ZLib and turn off most other options). Using a ``minizip-ng`` +from various package managers (e.g., Homebrew) probably won't work. Please see the +settings that begin with ``-DMZ_`` that are used in the OCIO +`minizip-ng find module. `_ + +Please note that if you build a static OCIO library, it will not contain the libraries +for the external packages and so you will need to list those separately when linking your +client application. If you had OCIO download and build these packages, you will +find them under your build directory in ``ext/dist/lib``. The libraries that are +needed are: ``expat``, ``yaml-cpp``, ``Imath``, ``pystring``, ``ZLIB``, and ``minizip-ng``. + +The OCIO ``make install`` step will install CMake configuration files that may be used +by applications that consume OCIO to find and utilize OCIO during their own build process. + +For the Python packages required for the documentation, ensure that their locations +are in your ``PYTHONPATH`` environment variable prior to configuring the build. + +This custom variable is also available: + +- ``-DPython_EXECUTABLE=`` (Python executable for pybind11) + + +.. _enabling-optional-components: + +Enabling optional components +**************************** + +CMake Options ++++++++++++++ + +There are many options available in `CMake. +`_ + +Several of the most common ones are: + +- ``-DCMAKE_BUILD_TYPE=Release`` (Set to Debug, if necessary) +- ``-DBUILD_SHARED_LIBS=ON`` (Set to OFF to build OCIO as a static library) + +Here are the most common OCIO-specific CMake options (the default values are shown): + +- ``-DOCIO_BUILD_APPS=ON`` (Set to OFF to not build command-line tools) +- ``-DOCIO_USE_OIIO_FOR_APPS=OFF`` (Set ON to build tools with OpenImageIO rather than OpenEXR) +- ``-DOCIO_BUILD_PYTHON=ON`` (Set to OFF to not build the Python binding) +- ``-DOCIO_BUILD_OPENFX=OFF`` (Set to ON to build the OpenFX plug-ins) +- ``-DOCIO_USE_SSE=ON`` (Set to OFF to turn off SSE CPU performance optimizations) +- ``-DOCIO_BUILD_TESTS=ON`` (Set to OFF to not build the unit tests) +- ``-DOCIO_BUILD_GPU_TESTS=ON`` (Set to OFF to not build the GPU unit tests) +- ``-DOCIO_USE_HEADLESS=OFF`` (Set to ON to do headless GPU reendering) +- ``-DOCIO_WARNING_AS_ERROR=ON`` (Set to OFF to turn off warnings as errors) +- ``-DOCIO_BUILD_DOCS=OFF`` (Set to ON to build the documentation) +- ``-DOCIO_BUILD_FROZEN_DOCS=OFF`` (Set to ON to update the Python documentation) + +Several command-line tools (such as ``ocioconvert``) require reading or writing image files. +If ``OCIO_USE_OIIO_FOR_APPS=OFF``, these will be built using OpenEXR rather than OpenImageIO +and therefore you will be limited to using OpenEXR files with these tools rather than the +wider range of image file formats supported by OIIO. (Using OpenEXR for these tools works +around the issue of a circular dependency between OCIO and OIIO that can complicate some +build chains.) + +The CMake output prints information regarding which image library will be used for the +command-line tools (as well as a lot of other info about the build configuration). + + +Documentation ++++++++++++++ + +Instructions for installing the documentation pre-requisites and building the docs +are in the section on :ref:`contributing documentation. ` + .. _osx-and-linux: -OS X and Linux -^^^^^^^^^^^^^^ +MacOS and Linux +*************** While there is a huge range of possible setups, the following steps -should work on OS X and most Linux distros. To keep things simple, this guide +should work on macOS and most Linux distros. To keep things simple, this guide will use the following example paths - these will almost definitely be different for you: @@ -196,12 +321,12 @@ First make the build directory and cd to it:: $ mkdir /tmp/ociobuild $ cd /tmp/ociobuild -Next step is to run cmake, which looks for things such as the +Next step is to run ``cmake``, which looks for things such as the compiler's required arguments, optional requirements like Python, OpenImageIO etc For this example we will show how to install OCIO to a custom location -(instead of the default ``/usr/local``), we will thus run cmake with +(instead of the default ``/usr/local``), we will thus run ``cmake`` with ``CMAKE_INSTALL_PREFIX``. Still in ``/tmp/ociobuild``, run:: @@ -209,8 +334,8 @@ Still in ``/tmp/ociobuild``, run:: $ cmake -DCMAKE_INSTALL_PREFIX=/software/ocio /source/ocio The last argument is the location of the OCIO source code (containing -the main CMakeLists.txt file). You should see something along the -lines of:: +the main CMakeLists.txt file). You should see it conclude with something +along the lines of:: -- Configuring done -- Generating done @@ -231,25 +356,33 @@ the specified location:: $ make install If nothing went wrong, ``/software/ocio`` should look something like -this:: +this (on Linux or macOS):: $ cd /software/ocio $ ls - bin/ include/ lib/ + bin/ include/ lib/ share/ $ ls bin/ ociobakelut ociocheck (and others ...) $ ls include/ - OpenColorIO/ PyOpenColorIO/ pkgconfig/ + OpenColorIO/ $ ls lib/ - libOpenColorIO.a libOpenColorIO.dylib + cmake/ libOpenColorIO.dylib (and some more specific versions ...) + libOpenColorIOimageioapphelpers.a libOpenColorIOoglapphelpers.a + pkgconfig/ python/ + $ ls lib/pkgconfig + OpenColorIO.pc + $ ls lib/python/site-packages + PyOpenColorIO.so + $ ls share/ocio + setup_ocio.sh -.. _Windows 7 or newer: +.. _Windows: -Windows 7 or newer -^^^^^^^^^^^^^^^^^^ +Windows +******* While build environments may vary between users, the recommended way to build OCIO from source on -Windows is to use the scripts provided in the Windows +Windows 7 or newer is to use the scripts provided in the Windows `share `_ section of the OCIO repository. There are two scripts currently available. @@ -270,7 +403,7 @@ Run this command to execute the ocio_deps.bat script:: The second script is called `ocio.bat `_ and it provide a way to configure and build OCIO from source. Moreover, this script executes the -install step of cmake as well as the unit tests. The main use case is the following:: +install step of ``cmake`` as well as the unit tests. The main use case is the following:: ocio.bat --b --i --vcpkg --ocio --type Release @@ -282,39 +415,14 @@ For more information, please look at each script's documentation:: ocio_deps.bat --help -.. _enabling-optional-components: - -Enabling optional components -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The OpenColorIO library is probably not all you want - the Python -libraries bindings, the Nuke nodes and several applications are only -built if their dependencies are found. - -In the case of the Python bindings, the dependencies are the Python -headers for the version you wish to use. These may be picked up by -default - if so, when you run cmake you would see:: - - -- Python 2.6 okay, will build the Python bindings against .../include/python2.6 - -If not, you can point cmake to correct Python executable using the -``-D PYTHON=...`` cmake flag:: - - $ cmake -D PYTHON=/my/custom/python2.6 /source/ocio - -The applications included with OCIO have various dependencies - to -determine these, look at the CMake output when first run:: - - -- Not building ocioconvert. Requirement(s) found: OIIO:FALSE - - .. _quick-env-config: Quick environment configuration -******************************* +=============================== The quickest way to set the required :ref:`environment-setup` is to source the ``share/ocio/setup_ocio.sh`` script installed with OCIO. +On Windows, use the corresponding setup_ocio.bat file. For a simple single-user setup, add the following to ``~/.bashrc`` (assuming you are using bash, and the example install directory of @@ -336,7 +444,7 @@ configuration script etc), for example:: .. _environment-setup: Environment variables -********************* +===================== Note: For other user facing environment variables, see :ref:`using_env_vars`. @@ -345,7 +453,7 @@ Note: For other user facing environment variables, see :ref:`using_env_vars`. This variable needs to point to the global OCIO config file, e.g ``config.ocio`` -.. envvar:: DYLD_LIBRARY_PATH +.. envvar:: DYLD_LIBRARY_PATH (macOS) The ``lib/`` folder (containing ``libOpenColorIO.dylib``) must be on the ``DYLD_LIBRARY_PATH`` search path, or you will get an error @@ -356,11 +464,11 @@ Note: For other user facing environment variables, see :ref:`using_env_vars`. Reason: image not found This applies to anything that links against OCIO, including the - ``PyOpenColorIO`` Python bindings. + ``PyOpenColorIO`` Python binding. -.. envvar:: LD_LIBRARY_PATH +.. envvar:: LD_LIBRARY_PATH (Linux) - Equivalent to the ``DYLD_LIBRARY_PATH`` on Linux + The Linux equivalent of the macOS ``DYLD_LIBRARY_PATH``. .. envvar:: PYTHONPATH diff --git a/docs/upgrading_v2/_index.rst b/docs/releases/_index.rst similarity index 74% rename from docs/upgrading_v2/_index.rst rename to docs/releases/_index.rst index cc45f6ef7a..9d61474e7f 100644 --- a/docs/upgrading_v2/_index.rst +++ b/docs/releases/_index.rst @@ -4,10 +4,12 @@ .. _upgrading_to_v2: -Upgrading to v2 -=============== +Releases +======== .. toctree:: :caption: Upgrading to v2 - how_to \ No newline at end of file + ocio_2_2 + ocio_2_1 + ocio_2_0 diff --git a/docs/upgrading_v2/how_to.rst b/docs/releases/ocio_2_0.rst similarity index 97% rename from docs/upgrading_v2/how_to.rst rename to docs/releases/ocio_2_0.rst index 0a2ba7f6a0..2892605d03 100644 --- a/docs/upgrading_v2/how_to.rst +++ b/docs/releases/ocio_2_0.rst @@ -3,15 +3,15 @@ Copyright Contributors to the OpenColorIO Project. -Introduction -============ +OCIO 2.0 Release +================ OpenColorIO v2 is a major update, three years in development, and contains a large number of new features. This section describes the new features and their relevance for both config authors and application developers. Timeline -======== +******** OpenColorIO v2 was proposed to the community at SIGGRAPH 2017 and reached "feature complete" at SIGGRAPH 2020. The official 2.0.0 release was made in @@ -19,7 +19,7 @@ January 2021 after a period of stabilization and refinement. OCIO v2 is in the VFX Reference Platform for calendar year 2021. Demo Config -=========== +*********** There is a config file that illustrates many of the new OCIO v2 features described below. This is available in the configs section of the documentation as :ref:`ocio-v2_demo`. @@ -641,3 +641,19 @@ processed. **Developers**: This may be useful, for example, when displaying data color spaces on an HDR monitor. + + +Release Notes +============= + +For more detail, please see the GitHub release pages: + +`OCIO 2.0.0 `_ + +`OCIO 2.0.1 `_ + +`OCIO 2.0.2 `_ + +`OCIO 2.0.3 `_ + +`OCIO 2.0.4 `_ diff --git a/docs/releases/ocio_2_1.rst b/docs/releases/ocio_2_1.rst new file mode 100644 index 0000000000..5fcf6b4924 --- /dev/null +++ b/docs/releases/ocio_2_1.rst @@ -0,0 +1,173 @@ +.. + SPDX-License-Identifier: CC-BY-4.0 + Copyright Contributors to the OpenColorIO Project. + + +OCIO 2.1 Release +================ + +Timeline +******** + +OpenColorIO 2.1 was delivered in August 2021 and is in the VFX Reference Platform for +calendar year 2022. + +New Features +============ + +ACES 1.3 Gamut Compression +************************** + +ACES 1.3 introduced a scene-referred gamut compression algorithm that compresses +colors captured by a camera into the AP1 gamut. This avoids artifacts that may +occur downstream (such as in the ACES Output Transforms) for scene elements such +as colored lights. This supersedes the earlier "Blue Light Artifact Fix" LMT. + +`ACES RGC User Guide +`_ + +`ACES RGC Implementation Guide +`_ + +The implementation includes a BuiltinTransform for the ACES Reference Gamut Compression. +Here's what that looks like in Config YAML:: + + ! {style: ACES-LMT - ACES 1.3 Reference Gamut Compression} + +There is also a FixedFunctionTransform for the underlying gamut compression algorithm. +As described in the links above, it takes seven parameter values:: + + [ Limit_Cyan, Limit_Magenta, Limit_Yellow, Threshold_Cyan, Threshold_Magenta, Threshold_Yellow, Roll-off ]. + +Here is how that looks in Config YAML with the parameters set for the ACES 1.3 Reference Gamut +Compression:: + + ! {style: ACES_GamutComp13, params: [1.147, 1.264, 1.312, 0.815, 0.803, 0.88, 1.2]} + +And here's how it looks in a CTF file:: + + + +**Config authors**: These new transforms may be used in configs with version 2.1 or higher +and CTF files with version 2.1 or higher. + + +OpenFX OCIO plug-ins +******************** + +A framework to support OpenFX plug-ins has been added and example source code may be found +in the vendor/openfx directory. The initial set consists of two plug-ins, one for applying +a ColorSpaceTransform and another for applying a DisplayViewTransform. + +Some screenshots of the UI may be found in `PR #1371. +`_ + +**End users**: There are currently no pre-built executables available, so you will need to +compile these yourself. + +**Developers**: Set the CMake variable ``-D OCIO_BUILD_OPENFX=ON`` to build the plug-ins. + + +Support for PyPI (pip install) +****************************** + +Python wheel generation has been added and support for the `Python Package Index (PyPI). +`_ +This allows you to easily install the OCIO Python bindings without needing to build from +source or use one of the OS-specific package managers. The command is simply:: + + pip install opencolorio + + +Support for emitting Open Shading Language (OSL) +************************************************ + +The OCIO GPU Renderer may now emit shaders in `Open Shading Language +`_ format. There is a +new GpuLanguage enum: ``LANGUAGE_OSL_1``. + +Note that the OCIO library does not need to be compiled against the OSL library but running +the OSL unit tests does require OSL and OIIO. These will be built automatically if CMake is +able to find them or you set ``-D OSL_ROOT`` to indicate the installed location. + +Currently, Lut1D and Lut3D Transforms are not supported and will throw an exception if used. +All other transforms are supported. However, dynamic properties are currently locked to +their initial values and may not be adjusted. + + +Support for Apple Metal Shading Language and OpenGL ES +****************************************************** + +The OCIO GPU Renderer may now emit shaders in these other new languages. The new +GpuLanguage enums are: + +* ``GPU_LANGUAGE_MSL_2_0`` +* ``GPU_LANGUAGE_GLSL_ES_3_0`` +* ``GPU_LANGUAGE_GLSL_ES_1_0`` + + +Test suite for the Academy/ASC Common LUT Format (CLF) +****************************************************** + +The set of CLF test files was expanded and a set of Python scripts was added under +``share/clf`` which were developed by the ACES Common LUT Format Implementation Working Group. +The scripts allow use of the OpenColorIO renderers to process a sample image through each +CLF file in the test suite and then compare the reference images to a set of corresponding +images from another CLF implementation to see if the differences are within the tolerance +allowed by the `CLF Implementation Guide. `_ + + +Imath 3 support +*************** + +OCIO and its CI system now support Imath 3 for the Half data type dependency. + + +Noteworthy API updates +********************** + +getColorSpaceFromFilePath ++++++++++++++++++++++++++ + +``Config::getColorSpaceFromFilepath()`` is now the proper way to extract a color space from +a file path, regardless of whether the config is version 1, or version 2 or higher. It +works regardless of whether the config has FileRules defined. Therefore, the older +``Config::parseColorSpaceFromString()`` method (which does not work with FileRules) is +officially deprecated. + +Note that ``Config::getColorSpaceFromFilepath()`` always returns a color space, regardless +of whether the config's ``strictparsing`` attribute is true or false. This was a request from +app developers that always need a default (which is a common scenario). Please see +`Issue #1398 `_ +for more details on how to take special action if ``strictparsing`` is true. + + +getDefaultView +++++++++++++++ +There is a new ``Config::getDefaultView(display, colorspaceName)`` method that takes +advantage of the ViewingRules feature that was introduced in OCIO 2.0. It returns the +default view that is most appropriate for a given color space. If the color space is +known, developers should call this rather than ``Config::getDefaultView(display)``. + +The motivation is that the best view transform to use varies with the color space. For +example, a scene-referred color space typically wants some kind of tone-map such as an +ACES Output Transform. However, a display-referred color space will look wrong with such +a view transform since it has already been tone-mapped. + +One scenario where this new method is ideal is when an application needs to generate +thumbnails for a large number of images that are in a variety of color spaces. Note that +the config must have the Viewing Rules set in order to return different views, but if the +rules are not set, it will still return the same result as ``Config::getDefaultView(display)``, +so it may be used with either v1 or v2 configs. + + +Release Notes +============= + +For more detail, please see the GitHub release pages: + +`OCIO 2.1.0 `_ + +`OCIO 2.1.1 `_ + +`OCIO 2.1.2 `_ diff --git a/docs/releases/ocio_2_2.rst b/docs/releases/ocio_2_2.rst new file mode 100644 index 0000000000..beb5624017 --- /dev/null +++ b/docs/releases/ocio_2_2.rst @@ -0,0 +1,395 @@ +.. + SPDX-License-Identifier: CC-BY-4.0 + Copyright Contributors to the OpenColorIO Project. + + +OCIO 2.2 Release +================ + +Timeline +******** + +OpenColorIO 2.2 was delivered in October 2022 and is in the VFX Reference Platform for +calendar year 2023. + + +New Features +============ + +Built-in Configs +**************** + +The OCIO Configs Working Group has put a lot of effort into building new ACES configs that +take advantage of the features of OCIO v2 and that are informed by the learnings from the +previous ACES configs. The new configs are available from the project's GitHub repo: +`OpenColorIO-Config-ACES +`_ + +To make them easily accessible, they are built in to the library itself and may be +accessed directly from within applications that incorporate the OCIO 2.2 library. + +For Users ++++++++++ + +Wherever you are able to provide a file path to a config, you may now provide a URI-type +string to instead use one of the built-in configs. For example, you may use these strings +for the OCIO environment variable. + +To use the :ref:`aces_cg`, use this string for the config path:: + ocio://cg-config-v1.0.0_aces-v1.3_ocio-v2.1 + +To use the :ref:`aces_studio`, use this string for the config path:: + ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1 + +This string will give you the current default config, which is currently the ACES CG Config:: + ocio://default + +In future releases, it is expected that updated versions of these configs will be added, +each with a unique name string. However, the previous strings will continue to be +supported for backwards compatibility. + +For Developers +++++++++++++++ + +The new URI-type strings may be passed into the existing APIs such as ``CreateFromEnv`` +and ``CreateFromFile``. There is also a new ``CreateFromBuiltinConfig``. No changes +should be needed, but please test that users of your application may use a path containing +a URI-type string rather than a path to a config.ocio file. + +If you'd like to offer the built-in configs from your user interface, there is an API to +access them through the new ``BuiltinConfigRegistry``. Here is basic Python code to +access the registry and print the strings to present in a UI:: + + registry = ocio.BuiltinConfigRegistry().getBuiltinConfigs() + for item in registry: + # The short_name is the URI-style name. + # The ui_name is the name to use in a user interface. + short_name, ui_name, isRecommended, isDefault = item + + # Don't present built-in configs to users if they are no longer recommended. + if isRecommended: + print(ui_name) + +Prints: + + Academy Color Encoding System - CG Config [COLORSPACES v1.0.0] [ACES v1.3] [OCIO v2.1] + + Academy Color Encoding System - Studio Config [COLORSPACES v1.0.0] [ACES v1.3] [OCIO v2.1] + +If your application saves the path to a config and the user enters ``ocio://default``, it +is recommended that you don't save that as is. Instead, call +``getDefaultBuiltinConfigName`` to get the name of the current default. This is +guaranteed to give the same results, whereas the default config could change somewhat +between releases. Prepend ``ocio://`` in order to save it as a valid config path. Here's +the Python code:: + + "ocio://" + ocio.BuiltinConfigRegistry().getDefaultBuiltinConfigName() + + +Config Archiving +**************** + +An OCIO config, including its external LUT files, may now be packaged into a single file. +This makes it easier to distribute configs and may slightly discourage tampering with the +contents. An archived config may be created with the new ``ocioarchive`` command-line +tool and is stored in a file with the extension ``.ocioz``. It is basically a compressed +ZIP archive of the config and its LUTs. + +To be archivable, the external LUT files must be contained within (or below) the config's +working directory. (In OCIO terminology, the "working directory" is the directory that +contains the config.ocio file.) + +A config is not archivable if any of the following are true: + +* It contains FileTransforms with a src outside the working directory +* The search path contains paths outside the working directory +* The search path contains paths that start with a context variable +* The working directory is not set (if archiving a Config object) + +Context variables are allowed but the intent is that they may only resolve to paths that +are within or below the working directory. This is because the archiving function will +only archive files that are within the working directory in order to ensure that if it is +later expanded, that it will not create any files outside this directory. + +For example, a context variable on the search path intended to contain the name of a +sub-directory under the working directory must have the form ``./$DIR_NAME`` rather than +just ``$DIR_NAME`` to be considered archivable. This is imperfect since there is no way to +prevent the context variable from creating a path outside the working dir, but it should +at least draw attention to the fact that the archive would fail if used with context vars +that try to abuse the intended functionality. + +All files within or below the working directory that end with an extension corresponding +to a LUT type supported by OCIO are added to the archive. This approach was taken since +the goal was for the archive to work with any combination of context variables that the +original config works with. Files with other extensions or no extension are not archived. + + +For Users ++++++++++ + +Wherever you are able to provide a file path to a config, you may now provide a path to a +.ocioz file. For example, you may use this for the OCIO environment variable. + +The ``ocioarchive`` command-line tool will allow you to archive a config or to expand an +existing archive. It will also allow you to list the contents of an archived config. Run +``ocioarchive --help`` to get a print-out of the various options. + +The print out from the ``ociocheck`` command-line tool now includes a new line-item +indicating whether the config is archivable. + +For Developers +++++++++++++++ + +The new .ocioz files may be passed into the existing APIs such as ``CreateFromEnv`` and +``CreateFromFile``. No changes should be needed, but please test that users of your +application may use a path containing a .ocioz file rather than a path to a config.ocio +file. + +The Config class has new ``isArchivable`` and ``archive`` methods. There is also an +``ExtractOCIOZArchive`` function. + + +Abstracting the Source of External LUT Files +******************************************** + +The new ConfigIOProxy class allows the calling program to supply the config and any +associated LUT files directly, without relying on the standard file system. This opens +the door to expanded ways in which OCIO may be used. + +The new config archiving feature was implemented using this mechanism. + +For Developers +++++++++++++++ + +Please refer to the ``ConfigIOProxy`` class. By implementing the ``getLutData``, +``getConfigData``, and ``getFastLutFileHash`` methods, you have control over how the +config is provided to OCIO. No file system access to a config is required. + +The ``CreateFromConfigIOProxy`` factory allows for the creation of a Config object from a +ConfigIOProxy object. + + +Converting To or From a Known Color Space +***************************************** + +An OCIO config defines its own self-contained universe of color spaces. But there are not +any requirements for color spaces which must always be included or how they must be named. +This poses difficulties for many applications which need to convert to or from certain +known standard color spaces. For example, a renderer might have a physical sun and sky +model which produces colors in a CIE space and it needs to convert those into the +rendering space defined by a user's custom OCIO config. Or an application may use an SDK +to debayer images from a digital cinema camera. The SDK produces images in a specific +color space which then needs to be processed into something viewable through a user's +custom OCIO config. + +For Developers +++++++++++++++ + +OCIO v2 introduced the Interchange Roles to help address this problem but these had +previously been optional and are unlikely to be included in OCIO v1 configs (although it +would be perfectly legal to add them). + +OCIO 2.2 introduces the new functions ``GetProcessorToBuiltinColorSpace`` and +``GetProcessorFromBuiltinColorSpace`` that will allow you to convert to or from any of the +color spaces in the built-in Default config (this is currently the ACES CG config +described above). This built-in config includes common spaces such as "Linear Rec.709 +(sRGB)", "sRGB - Texture", "ACEScg", and "ACES2065-1". + +If the source config defines the necessary Interchange Role (typically +``aces_interchange``), then the conversion will be well-defined and equivalent to calling +``GetProcessorFromConfigs`` with the source config and the Built-in config + +However, if the Interchange Roles are not present, heuristics will be used to try and +identify a common color space in the source config that may be used to allow the +conversion to proceed. If the heuristics fail to find a suitable space, an exception is +thrown. The heuristics may evolve, so the results returned by this function for a given +source config and color space may change in future releases of the library. However, the +Interchange Roles are required in config versions 2.2 and higher, so it is hoped that the +need for the heuristics will decrease over time. + +The current heuristics should work on any config (including an OCIO v1 config) that was +generated by editing one of the ACES configs or any config that uses one of the following +as its reference space: + +* ACES2065-1 +* ACEScg +* Scene-linear Rec.709 (sRGB) +* Scene-linear Rec.2020 +* Scene-linear P3-D65 + +And that has a color space either for any of the above spaces or for an sRGB texture space +that has "sRGB" (case-insensitive) in its color space name or one of its aliases. + +Note that the heuristics create a Processor and evaluate color values that must match +within a certain tolerance. No color space is selected purely based on its name alone. +If the heuristics fail to find a recognized color space, an exception is thrown. + + +Making the interchange roles required for config versions 2.2 or higher +*********************************************************************** + +For Users ++++++++++ + +Users were surveyed during the OCIO 2.2 development process as to whether the Interchange +Roles should become mandatory. The response was overwhelmingly in favor of doing this, +largely because it allows robust interchange of color spaces between configs or to +external known standard color spaces. + +Therefore, as described in the previous section, for config files of version 2.2 or +higher, it is mandatory to define the ``aces_interchange`` role. If the config includes +display color spaces, the ``cie_xyz_d65_interchange`` role is also required. + +Note that the ``cie_xyz_d65_interchange`` is only used in connection with display color +spaces (that is, with the display-referred connection space). It is not used for +scene-referred color spaces, and indeed it is an error if a scene-referred space is +assigned to that role. + +The ``ociocheck`` command-line tool has been updated to make these checks. In addition, +its reporting on other roles has been modified to be more lenient regarding roles which +are no longer considered essential. + +For Developers +++++++++++++++ + +The Config::validate method will log an error if the Config object does not meet these +requirements. Note that an exception is not thrown since it was felt that the Config's +``upgradeToLatestVersion`` method must always produce a valid config. + + +Determining if a Color Space is Linear +************************************** + +There have been many requests from developers that would like a standard way to determine +if a color space is linear, since this impacts what sort of processing is suitable. OCIO +v2 introduced a new ``encoding`` attribute for color spaces which contains this +information. However, this is optional and may not be set by all config authors. And it +won't be present in OCIO v1 configs, which are still widely used. + +For Developers +++++++++++++++ + +OCIO 2.2 adds a new ``isColorSpaceLinear`` method to the Config class which may be used +for this purpose. + +Note that since OCIO has both a scene-referred and a display-referred reference space, the +method also takes a ReferenceSpaceType enum to indicate which reference space the +linearity determination is with respect to. Typically developers will set this to +``REFERENCE_SPACE_SCENE``. + +The following algorithm is used to make the determination: + +* If the color space ``isdata`` attribute is true, return false. +* If the reference space type of the color space differs from the requested reference +space type, return false. +* If the color space's encoding attribute is present, return true if it matches the +expected reference space type (i.e., "scene-linear" for ``REFERENCE_SPACE_SCENE`` or +"display-linear" for ``REFERENCE_SPACE_DISPLAY``) and false otherwise. +* If the color space has no ``to_reference`` or ``from_reference`` transform, return true. +* Evaluate several points through the color space's transform and check if the output only +differs by a scale factor (which may be different per channel, e.g. allowing an arbitrary +matrix transform, with no offset). + +Note that the last step is a heuristic that may or may not be accurate. However, note +that the ``encoding`` attribute takes precedence and so config authors have the ultimate +control over the linearity determination. + + +Getting a Processor for a NamedTransform +**************************************** + +For Developers +++++++++++++++ + +A new config object was introduced in OCIO v2 called Named Transforms. These are used +when there is a need to apply a mathematical function which is not a conversion between +two specific color spaces. The most common example is applying a transfer function curve +to convert linear data to non-linear, or vice-versa. + +The new ACES configs include Named Transforms, so it is important for application +developers to start supporting this type of config object. The preferred method for doing +so is to add a new tool, similar to FileTransform that applies a Named Transform. + +What is new in OCIO 2.2 is that the code for applying these is now simpler with the +introduction of several new getProcessor methods on the Config class that will return a +Processor directly from a NamedTransform object. + +In addition, the NamedTransform class has a GetTransform method that returns a (regular) +Transform object for a given direction. It will create the transform from the inverse +direction if the transform for the requested direction is missing. + + +Circular OCIO / OIIO Build Dependency Solution +********************************************** + +A long-standing complaint has been regarding the circular build dependency between OCIO +and OpenImageIO. This is due to the fact that OIIO wants to use OCIO for color management +and OCIO wants to use OIIO in its command-line tools ``ocioconvert``, ``ociolutimage``, +and ``ociodisplay`` for reading and writing image files. These tools will not be built if +OIIO is not available when configuring the build. + +Furthermore, some package installers will not install these command-line tools due to the +dependency on OIIO. + +By default, OCIO will now build these tools with OpenEXR rather than relying on OIIO. + +For Users ++++++++++ + +If you have a version of OCIO that was not compiled with tools such as ``ocioconvert`` and +you want to use OCIO to process images, you could try using OpenImageIO's ``oiiotool``. +(Although note that ``ocioconvert`` has a few features that are not in ``oiiotool``, such +as GPU processing support.) Similarly if you have ``ocioconvert``, but it is compiled +with OpenEXR rather than OpenImageIO, you may use ``oiiotool`` to convert other image file +formats to/from OpenEXR. + +If you want to use ``oiiotool`` but it does not support a particular type of conversion, +you may be able to use ``ociowrite`` to export a CTF file and then use that with the +``--ociofiletransform`` option in ``oiiotool``. + +For Developers +++++++++++++++ + +In OCIO 2.2, by default, the build will now use OpenEXR rather than OpenImageIO for the +command-line tools that read or write images. This will limit the functionality of the +aforementioned command-line tools to only working with OpenEXR files. If you want support +for more file formats in these tools, you will still need to have OIIO available when +building OCIO and set the CMake variable ``-D OCIO_USE_OIIO_FOR_APPS=ON``. + + +Miscellaneous Improvements +************************** + +Here are some other improvements in OCIO 2.2: + +* Support for more types of ICC Monitor Profiles -- All of the parametric curve types are +now supported. + +* New hash function for calculating cache IDs -- The md5 algorithm has been replaced with +xxhash, which provides a considerable speed-up for various operations. The APIs that +return cache ID strings will obviously return different strings now, but please note that +these are not guaranteed to be unchanged across releases. (The 128-bit version of xxhash +was used, which is the same length as for md5.) + +* The command-line tools ``ocioconvert``, ``ociowrite``, and ``ocioperf`` now support +using an inverse DisplayViewTransform. + +* Add DisplayViewTransform and NamedTransform support to Baker. + +* Several new Built-in Transforms are available for version 2.2 config files, including +ARRI LogC4. + +* Preliminary support for ACES Metadata File (AMF) -- A prototype Python tool has been +added named ``pyocioamf`` that converts an AMF file into the OCIO native transform format +CTF. It uses a prototype ACES Reference config file that is serving as a database of ACES +Transform IDs for interpreting the AMF file. + +* Support for PyPI installation from source rather than pre-built binaries. + + +Release Notes +============= + +For more detail, please see the GitHub release pages: + +`OCIO 2.2.0 `_ diff --git a/docs/toc_redirect.rst b/docs/toc_redirect.rst index 3785c12f92..2dd5537956 100644 --- a/docs/toc_redirect.rst +++ b/docs/toc_redirect.rst @@ -30,7 +30,7 @@ .. toctree:: :hidden: - upgrading_v2/_index + releases/_index .. toctree:: :hidden: diff --git a/include/OpenColorIO/OpenColorIO.h b/include/OpenColorIO/OpenColorIO.h index 514fcc3db0..a7d073f788 100644 --- a/include/OpenColorIO/OpenColorIO.h +++ b/include/OpenColorIO/OpenColorIO.h @@ -459,14 +459,25 @@ class OCIOEXPORT Config const char * getEnvironmentVarDefault(const char * name) const; void clearEnvironmentVars(); + /** + * \brief The EnvironmentMode controls the behavior of loadEnvironment. + * * ENV_ENVIRONMENT_LOAD_PREDEFINED - Only update vars already added to the Context. + * * ENV_ENVIRONMENT_LOAD_ALL - Load all env. vars into the Context. + * + * \note Loading ALL the env. vars may reduce performance and reduce cache efficiency. + * + * Client programs generally will not use these methods because the EnvironmentMode is + * set automatically when a Config is loaded. If the Config has an "environment" + * section, the mode is set to LOAD_PREDEFINED, and otherwise set to LOAD_ALL. + */ void setEnvironmentMode(EnvironmentMode mode) noexcept; EnvironmentMode getEnvironmentMode() const noexcept; + /// Initialize the environment/context variables in the Config's Context. void loadEnvironment() noexcept; const char * getSearchPath() const; /** - * \brief Set all search paths as a concatenated string, ':' to separate the - * paths. + * \brief Set all search paths as a concatenated string, use ':' to separate the paths. * * See \ref addSearchPath for a more robust and platform-agnostic method of * setting the search paths. @@ -3442,8 +3453,9 @@ class OCIOEXPORT Context void setWorkingDir(const char * dirname); const char * getWorkingDir() const; - /// Add (or update) a context variable. But it removes it if the value argument - /// is null. + /// Add (or update) a context variable. But it removes it if the value argument is null. + /// Note that a Context StringVar is the same thing as a Config EnvironmentVar and these + /// are both often referred to as a "context var". void setStringVar(const char * name, const char * value) noexcept; /// Get the context variable value. It returns an empty string if the context /// variable is null or does not exist. @@ -3459,13 +3471,11 @@ class OCIOEXPORT Context /// Add to the instance all the context variables from ctx. void addStringVars(const ConstContextRcPtr & ctx) noexcept; - + /// See \ref Config::setEnvironmentMode. void setEnvironmentMode(EnvironmentMode mode) noexcept; - - EnvironmentMode getEnvironmentMode() const noexcept; - /// Seed all string vars with the current environment. + /// Seed string vars with the current environment, based on the EnvironmentMode setting. void loadEnvironment() noexcept; /// Resolve all the context variables from the string. It could be color space diff --git a/include/OpenColorIO/OpenColorTypes.h b/include/OpenColorIO/OpenColorTypes.h index 9976ac821d..c400568eaa 100644 --- a/include/OpenColorIO/OpenColorTypes.h +++ b/include/OpenColorIO/OpenColorTypes.h @@ -456,11 +456,12 @@ enum GpuLanguage GPU_LANGUAGE_MSL_2_0 ///< Metal Shading Language }; +/// Controls which environment variables are loaded into a Context object. enum EnvironmentMode { ENV_ENVIRONMENT_UNKNOWN = 0, - ENV_ENVIRONMENT_LOAD_PREDEFINED, - ENV_ENVIRONMENT_LOAD_ALL + ENV_ENVIRONMENT_LOAD_PREDEFINED, ///< Only load vars in the config's environment section + ENV_ENVIRONMENT_LOAD_ALL ///< Load all env. vars (note: may reduce performance) }; /// A RangeTransform may be set to clamp the values, or not.