feat: color space renaming to adhere to CIF conventions (#4860)

This doesn't really change any of the color management algorithms per
se, or change how we use OCIO. That will come later.

But this tries as best as we can to shift to CIF recommended interop
names for color spaces.

* "srgb_rec709_scene" as the canonical name for what we used to refer to
as "sRGB".
* "lin_rec709_scene" as the canonical name for what we used to refer to
as "lin_rec709" and several other names.
* "lin_ap1_scene" as the canonical name for ACEScg.
* Stop setting "oiio:Gamma" metadata (though we still accept it for back
compatibility), instead using space names like "g22_rec709_scene" and so
on. We never came across files with truly arbitrary gamma.

If I've done it right, the old names will continue to be accepted as
aliases.

I recognize that changing the output (when printing metadata) to the
canonical names might be an inconvenience at first, but in the long run,
I think it's better to comply with the conventions that will be used for
USD, MaterialX, and OpenEXR.

I'm fine with the new wordy and pedantic names as what is stored
underneath as the "oiio:ColorSpace" alias or stored in an OpenEXR file
in the colorInteropID metadata. But I gotta say, from a UI/UX
perspective, I do not feel good about replacing "srgb" and "acescg" as
things that are easy to type and are known/understood by the vast
majority of OIIO users with a change to these wonky, error-prone,
hard-to-type names. So I'm very uncertain about changing oiiotool
documentation, say, away from the short and widely understood aliases.
Seeking feedback on what to do here!

---------

Signed-off-by: Larry Gritz <[email protected]>
Co-authored-by: Doug Walker <[email protected]>

Author: lgritz

src/bmp.imageio/bmpinput.cpp

@@ -262,7 +262,7 @@ BmpInput::open(const std::string& name, ImageSpec& newspec,
     // Default presumption is that a BMP file is meant to look reasonable on a
     // display, so assume it's sRGB. This is not really correct -- see the
     // comments below.
-    m_spec.attribute("oiio:ColorSpace", "sRGB");
+    m_spec.attribute("oiio:ColorSpace", "srgb_rec709_scene");
 #if 0
     if (m_dib_header.size >= WINDOWS_V4
         && m_dib_header.cs_type == CSType::CalibratedRGB) {

src/build-scripts/build_opencolorio.bash

@@ -11,7 +11,7 @@ set -ex
 
 # Which OCIO to retrieve, how to build it
 OPENCOLORIO_REPO=${OPENCOLORIO_REPO:=https://github.com/AcademySoftwareFoundation/OpenColorIO.git}
-OPENCOLORIO_VERSION=${OPENCOLORIO_VERSION:=v2.3.2}
+OPENCOLORIO_VERSION=${OPENCOLORIO_VERSION:=v2.4.2}
 
 # Where to install the final results
 LOCAL_DEPS_DIR=${LOCAL_DEPS_DIR:=${PWD}/ext}

src/cmake/build_OpenColorIO.cmake

@@ -6,7 +6,7 @@
 # OpenColorIO by hand!
 ######################################################################
 
-set_cache (OpenColorIO_BUILD_VERSION 2.4.1 "OpenColorIO version for local builds")
+set_cache (OpenColorIO_BUILD_VERSION 2.4.2 "OpenColorIO version for local builds")
 set (OpenColorIO_GIT_REPOSITORY "https://github.com/AcademySoftwareFoundation/OpenColorIO")
 set (OpenColorIO_GIT_TAG "v${OpenColorIO_BUILD_VERSION}")
 set_cache (OpenColorIO_BUILD_SHARED_LIBS  OFF #ON

src/dds.imageio/ddsinput.cpp

@@ -838,14 +838,16 @@ DDSInput::seek_subimage(int subimage, int miplevel)
         case DDS_FORMAT_BC7_UNORM_SRGB:
         case DDS_FORMAT_R8G8B8A8_UNORM_SRGB:
         case DDS_FORMAT_B8G8R8A8_UNORM_SRGB:
-        case DDS_FORMAT_B8G8R8X8_UNORM_SRGB: colorspace = "sRGB"; break;
+        case DDS_FORMAT_B8G8R8X8_UNORM_SRGB:
+            colorspace = "srgb_rec709_scene";
+            break;
         }
     }
 
     // linear color space for HDR-ish images
     if (colorspace == nullptr
         && (basetype == TypeDesc::HALF || basetype == TypeDesc::FLOAT))
-        colorspace = "lin_rec709";
+        colorspace = "lin_rec709_scene";
 
     m_spec.set_colorspace(colorspace);
 

src/doc/builtinplugins.rst

@@ -688,9 +688,6 @@ preferred except when legacy file access is required.
      - string
      - Color space (see Section :ref:`sec-metadata-color`). We currently
        assume that any RGBE files encountered are linear with sRGB primaries.
-   * - ``oiio:Gamma``
-     - float
-     - the gamma correction specified in the RGBE header (if it's gamma corrected).
    * - ``heif:Orientation``
      - int
      - If the configuration option ``heif:reorient`` is nonzero and
@@ -1771,9 +1768,6 @@ files use the file extension :file:`.png`.
    * - ``oiio:ColorSpace``
      - string
      - Color space (see Section :ref:`sec-metadata-color`).
-   * - ``oiio:Gamma``
-     - float
-     - the gamma correction value (if specified).
    * - ``ICCProfile``
      - uint8[]
      - The ICC color profile. A variety of other ``ICCProfile:*`` attributes
@@ -2370,9 +2364,6 @@ software developed at Wavefront.  RLA files commonly use the file extension
    * - ``oiio:ColorSpace``
      - string
      - Color space (see Section :ref:`sec-metadata-color`).
-   * - ``oiio:Gamma``
-     - float
-     - the gamma correction value (if specified).
 
 **Configuration settings for RLA input**
 
@@ -2611,9 +2602,6 @@ http://www.dca.fee.unicamp.br/~martino/disciplinas/ea978/tgaffs.pdf
    * - ``oiio:ColorSpace``
      - string
      - Color space (see Section :ref:`sec-metadata-color`).
-   * - ``oiio:Gamma``
-     - float
-     - the gamma correction value (if specified).
 
 If the TGA file contains a thumbnail, its dimensions will be stored in the
 attributes ``"thumbnail_width"``, ``"thumbnail_height"``, and

src/doc/oiiotool.rst

@@ -709,13 +709,19 @@ Color convert an image
 ----------------------
 
 This command linearizes a JPEG assumed to be in sRGB, saving as an HDRI
-OpenEXR file::
+OpenEXR file in ACEScg color space::
 
-    oiiotool photo.jpg --colorconvert sRGB linear -o output.exr
+    oiiotool photo.jpg --colorconvert srgb acescg -o output.exr
 
 And the other direction::
 
-    oiiotool render.exr --colorconvert linear sRGB -o fortheweb.png
+    oiiotool render.exr --colorconvert acescg srgb -o fortheweb.png
+
+Above, we're using the short aliases "srgb" and "acescg", but it's also fine
+to use the canonical Color Interop Forum names::
+
+    oiiotool photo.jpg --colorconvert srgb_rec709_scene lin_ap1_scene -o output.exr
+    oiiotool render.exr --colorconvert lin_ap1_scene srgb_rec709_scene -o fortheweb.png
 
 This converts between two named color spaces (presumably defined by your
 facility's OpenColorIO configuration)::
@@ -1608,7 +1614,7 @@ Writing images
 
         oiiotool in.tif -otex out.tx
     
-        oiiotool in.jpg --colorconvert sRGB linear -d uint16 -otex out.tx
+        oiiotool in.jpg --colorconvert srgb_rec709_scene lin_rec709_scene -d uint16 -otex out.tx
     
         oiiotool --pattern:checker 512x512 3 -d uint8 -otex:wrap=periodic checker.tx
     
@@ -4352,15 +4358,12 @@ current top image.
 Many of the color management commands depend on an installation of
 OpenColorIO (http://opencolorio.org).
 
-If OIIO has been compiled with OpenColorIO support and the environment
-variable `$OCIO` is set to point to a valid OpenColorIO configuration file,
-you will have access to all the color spaces that are known by that OCIO
-configuration.  Alternately, you can use the `--colorconfig` option to
-explicitly point to a configuration file. If no  valid configuration file is
-found (either in `$OCIO` or specified by `--colorconfig}` or OIIO was not
-compiled with OCIO support, then the only color space transformats available
-are `linear` to `Rec709` (and vice versa) and `linear` to `sRGB` (and vice
-versa).
+If the environment variable `$OCIO` is set to point to a valid OpenColorIO
+configuration file, you will have access to all the color spaces that are
+known by that OCIO configuration.  Alternately, you can use the
+`--colorconfig` option to explicitly point to a configuration file. If no
+valid configuration file is found (either in `$OCIO` or specified by
+`--colorconfig`), then the built-in OCIO "default" config will be used.
 
 If you ask for :program:`oiiotool` help (`oiiotool --help`), at the very
 bottom you will see the list of all color spaces, looks, and displays that

src/doc/pythonbindings.rst

@@ -729,7 +729,7 @@ Section :ref:`sec-ImageSpec`, is replicated for Python.
     .. code-block:: python
 
         spec = ImageSpec(...)
-        spec.set_colorspace ("sRGB")
+        spec.set_colorspace ("srgb_rec709_scene")
 
 
 .. py:method:: ImageSpec.undefined ()
@@ -3961,12 +3961,12 @@ details.
     .. code-block:: python
 
         spec = oiio.ImageSpec()
-        oiio.set_colorspace (spec, "lin_rec709")
+        oiio.set_colorspace (spec, "lin_rec709_scene")
 
     This function was added in OpenImageIO 3.0.
 
 
-.. py:method:: set_colorspace_rec709_gamma (spec, name)
+.. py:method:: set_colorspace_rec709_gamma (spec, gamma)
 
     Set the metadata of the `spec` to reflect Rec709 color primaries and the
     given gamma.
@@ -3992,7 +3992,7 @@ details.
 
         # ib is an ImageBuf
         cs = ib.spec().get_string_attribute("oiio:ColorSpace")
-        if oiio.equivalent_colorspace(cs, "sRGB") :
+        if oiio.equivalent_colorspace(cs, "srgb_rec709_scene") :
             print ("The image is sRGB")
 
     This function was added in OpenImageIO 3.0.

src/doc/stdmetadata.rst

@@ -139,34 +139,24 @@ Color information
 
 .. option:: "oiio:ColorSpace" : string
 
-    The name of the color space of the color channels.  Values include:
+    The name of the color space of the color channels. This can be the name of
+    any documented Color Interop Forum standard token, or any color space,
+    alias, or role known to OpenColorIO. Common values include:
 
-    - `"scene_linear"` :  Color pixel values are known to be scene-linear and
-      using facility-default color primaries as defined by the OpenColorIO
-      configuration.
-    - `"lin_srgb"`, `"lin_rec709"` :  Color pixel values are known to be
-      linear and using sRGB/Rec709 color primaries. Note that `"linear"` is
-      treated as a synonym.
-    - `"sRGB"` :  Using standard sRGB response and primaries.
-    - `"Rec709"` :  Using standard Rec709 response and primaries.
-    - `"ACEScg"` :  ACEScg color space encoding.
-    - `"AdobeRGB"` :  Adobe RGB color space.
-    - `"KodakLog"` :  Kodak logarithmic color space.
-    - `"g22_rec709"` : Rec709/sRGB primaries, but using a response curve
+    - `"lin_rec709_scene"`,  :  Color pixel values are known to be linear
+      scene-referred and using sRGB/Rec709 color primaries. Note that
+      `"lin_rec709"` is treated as a synonym.
+    - `"lin_ap1_scene"`, `"ACEScg"` :  ACEScg color space encoding.
+    - `"lin_ap0_scene"` :  ACES2065-1, the recommended ACES space for
+      interchange and archiving.
+    - `"srgb_rec709_scene"` : Using standard (piecewise) sRGB response and
+      primaries. The token `"sRGB"` is treated as a synonym.
+    - `"g22_rec709_scene"` : Rec709/sRGB primaries, but using a response curve
       corresponding to gamma 2.2.
-    - `"g18_rec709"` : Rec709/sRGB primaries, but using a response curve
-      corresponding to gamma 1.8.
-    - `"GammaX.Y"` :  Color values have been gamma corrected
-      (raised to the power :math:`1/\gamma`). The `X.Y` is the numeric value
-      of the gamma exponent.
-    - *arbitrary* :  The name of any color space known to OpenColorIO (if
-      OCIO support is present).
-
-.. option:: "oiio:Gamma" : float
-
-    If the color space is "GammaX.Y", this value is the gamma exponent.
-    (Optional/deprecated; if present, it should match the suffix of the color
-    space.)
+
+    Additionally, `"scene_linear"` is a role that is appropriate for color
+    pixel values are known to be scene-linear and using facility-default color
+    primaries as defined by the OpenColorIO configuration.
 
 .. option:: "oiio:BorderColor" : float[nchannels]
 

src/gif.imageio/gifinput.cpp

@@ -259,7 +259,7 @@ GIFInput::read_subimage_metadata(ImageSpec& newspec)
     newspec.nchannels = 4;
     newspec.default_channel_names();
     newspec.alpha_channel = 4;
-    newspec.set_colorspace("sRGB");
+    newspec.set_colorspace("srgb_rec709_scene");
 
     m_previous_disposal_method = m_disposal_method;
     m_disposal_method          = DISPOSAL_UNSPECIFIED;

src/hdr.imageio/hdrinput.cpp

@@ -291,7 +291,7 @@ HdrInput::RGBE_ReadHeader()
     if (!line.size())
         return false;
 
-    m_spec.set_colorspace("lin_rec709");
+    m_spec.set_colorspace("lin_rec709_scene");
     // presume linear w/ srgb primaries -- seems like the safest assumption
     // for this old file format.