feat: Add ImageSpec::set_cicp functions and oiiotool --cicp option

The ImageSpec::set_cicp functions are convenience functions for setting the uint8[4] oiio:CICP attribute.

The oiiotool `action_cicp` function works similarly to `action_iscolorspace`, in that it uses a custom OiiotoolOp to modify the top image's spec with the aforementioned set_cicp function.

Upshot: oiiotool now has a `--cicp` option, which makes it easy to add, modify, or remove CICP metadata.
Signed-off-by: Zach Lewis <zachcanbereached@gmail.com>

Author: zachlewis

src/doc/pythonbindings.rst

@@ -717,6 +717,43 @@ Section :ref:`sec-ImageSpec`, is replicated for Python.
     data types, but not the arbitrary named metadata or channel names.
 
 
+.. py:method:: ImageSpec.set_cicp (pri: int, trc: int, mtx: int = 0, vfr: int = 1)
+               ImageSpec.set_cicp (cicp: str)
+
+    Set CICP metadata for image formats that support it. The overloaded
+    function accepts either a series of integers corresponding to the
+    H.273 enumerations for primaries, transfer characteristic, color
+    matrix, and video full range flag; or it'll accept a single string
+    argument of up to 4 comma-separated values. 
+
+    The third and fourth CICP values are optional, and are typically
+    more pertinant to video formats. The default values assume OIIO 
+    buffers hold unscaled (i.e., full-range) RGB-encoded data (as 
+    opposed to Y'CbCr or ICtCp).
+
+    Examples:
+
+    .. code-block:: python
+        
+        spec = ImageSpec(...)
+        spec.set_cicp(1, 13, 1)        # [1, 13, 1, 1]
+
+        # If only provided primaries and transfer characteristics,
+        # the color matrix is "identity" (0)
+        spec.set_cicp(1, 13)           # [1, 13, 0, 1]
+
+        # Passing an empty string will erase the attribute.
+        spec.set_cicp("") 
+        
+        # By default, OIIO assumes "full-range" scaling
+        spec.set_cicp("9,16,9")       # [9, 16, 9, 1]
+
+        # Use the following syntax to modify only certain values:
+        spec.set_cicp(",,,0")         # [9, 16, 9, 0] 
+
+    This function was added in version 3.0.7.
+
+
 .. py:method:: bool ImageSpec.set_colorspace (name)
 
     Set metadata to indicate the presumed color space `name`, or clear all

src/include/OpenImageIO/imageio.h

@@ -811,6 +811,40 @@ class OIIO_API ImageSpec {
         deep = other.deep;
     }
 
+    /// Set the "oiio:CICP" attribute to the given values. The `pri`, `tc`, `mtx`,
+    /// and `vfr` values are the CICP parameters, which are used to describe
+    /// aspects of the color encoding of the image, as defined in ITU-T H.273.
+    /// 
+    /// @param pri
+    ///     An integer representing the color primaries.
+    /// @param tc
+    ///     An integer representing the transfer characteristics.
+    /// @param mtx 
+    ///     An integer representing the matrix coefficients. RGB encodings
+    ///     typically use 0 (identity matrix).
+    /// @param vfr 
+    ///     An integer indicating whether the image is "full range" (Typically
+    ///     true of RGB encodings)
+    ///
+    /// @version 3.0
+    void set_cicp(int pri, int trc, int mtx=0, int vfr=1);
+    /// Set the "oiio:CICP" attribute to the given values. The `cicp` string
+    /// is a comma-delimeted list of integers representing the CICP parameters.
+    /// The `cicp` string should be in the format "pri,tc,mtx,vfr", where
+    /// `pri`, `trc`, `mtx`, and `vfr` are integers representing the color
+    /// primaries, transfer characteristics, matrix coefficients, and
+    /// video full range flag, respectively. If the `cicp` string is empty,
+    /// the "oiio:CICP" attribute will be removed from the `ImageSpec`.
+    /// The `cicp` string may also contain commas (",") without any 
+    /// integer value specified beforehand, in which case the 
+    /// corresponding CICP parameter will fall back to its current value,
+    /// or to the default value (of {0, 0, 0, 1}) if there is no current value.
+    /// For example, `",,,0"` would set the "video full range flag" to 0 to
+    /// indicate a "narrow range" encoding, while keeping the other three
+    /// parameters unchanged. 
+    /// @param cicp 
+    void set_cicp(string_view cicp);
+
     /// Set the metadata to presume that color space is `name` (or to assume
     /// nothing about the color space if `name` is empty). The core operation
     /// is to set the "oiio:ColorSpace" attribute, but it also removes or
@@ -2157,6 +2191,9 @@ class OIIO_API ImageOutput {
     ///        Does this format allow 0x0 sized images, i.e. an image file
     ///        with metadata only and no pixels?
     ///
+    ///  - `"cicp"` :
+    ///        Does this format support embedding CICP metadata?
+    ///
     /// This list of queries may be extended in future releases. Since this
     /// can be done simply by recognizing new query strings, and does not
     /// require any new API entry points, addition of support for new
@@ -3366,6 +3403,22 @@ OIIO_API void set_colorspace(ImageSpec& spec, string_view name);
 OIIO_API void set_colorspace_rec709_gamma(ImageSpec& spec, float gamma);
 
 
+
+// /// Set the spec's metadata to reflect a custom set of CICP values.
+// /// The core operation is to set the "oiio:CICP" attribute to an
+// /// uint8[4] array. Currently, the CICP attribute must be 
+// /// manually maintained by the user; but OCIO-2.5 will offer
+// /// a way for config authors to specify CICP values for a
+// /// color space, and it will be possible to use this function
+// /// in ImageBufAlgos that mutate "oiio:ColorSpace".
+// ///
+// /// @version 3.0
+// OIIO_API void set_cicp(ImageSpec& spec, int transfer_characteristic,
+//                        int color_primaries, int matrix_coefficients,
+//                        int video_full_range_flag);
+
+
+
 /// Are the two named color spaces equivalent, based on the default color
 /// config in effect?
 ///

src/libOpenImageIO/formatspec.cpp

@@ -470,7 +470,7 @@ ImageSpec::find_attribute(string_view name, ParamValue& tmpparam,
     auto iter = extra_attribs.find(name, searchtype, casesensitive);
     if (iter != extra_attribs.end())
         return &(*iter);
-        // Check named items in the ImageSpec structs, not in extra_attrubs
+    // Check named items in the ImageSpec structs, not in extra_attrubs
 #define MATCH(n, t)                                 \
     (((!casesensitive && Strutil::iequals(name, n)) \
       || (casesensitive && name == n))              \
@@ -1268,6 +1268,38 @@ ImageSpec::set_colorspace(string_view colorspace)
 
 
 
+void
+ImageSpec::set_cicp(int pri, int trc, int mtx, int vfr)
+{
+    uint8_t vals[4] = { uint8_t(std::clamp(pri, 0, 255)),
+                        uint8_t(std::clamp(trc, 0, 255)),
+                        uint8_t(std::clamp(mtx, 0, 255)),
+                        uint8_t(std::clamp(vfr, 0, 255)) };
+    attribute("oiio:CICP", TypeDesc(TypeDesc::UINT8, 4), vals);
+}
+
+
+
+void
+ImageSpec::set_cicp(string_view cicp)
+{
+    // If the string is empty, erase the attribute.
+    if (cicp.empty()) {
+        erase_attribute("oiio:CICP");
+        return;
+    }
+    auto vals = Strutil::extract_from_list_string<int>("0,0,0,1", 4, 0);
+    auto p = find_attribute("oiio:CICP", TypeDesc(TypeDesc::UINT8, 4));
+    if (p) {
+        string_view existing_vals = metadata_val(*p);
+        Strutil::extract_from_list_string<int>(vals, existing_vals);
+    }
+    Strutil::extract_from_list_string<int>(vals, cicp);
+    set_cicp(vals[0], vals[1], vals[2], vals[3]);
+}
+
+
+
 template<>
 size_t
 pvt::heapsize<ImageSpec>(const ImageSpec& is)

src/oiiotool/oiiotool.cpp

@@ -2219,6 +2219,47 @@ icc_read(Oiiotool& ot, cspan<const char*> argv)
 }
 
 
+// Special OiiotoolOp whose purpose is to set attributes on the top image.
+class OpSetCICP final : public OiiotoolOp {
+public:
+    OpSetCICP(Oiiotool& ot, string_view opname, cspan<const char*> argv)
+        : OiiotoolOp(ot, opname, argv, 1)
+    {
+        inplace(true);  // This action operates in-place
+        cicp = args(1);
+    }
+    OpSetCICP(Oiiotool& ot, string_view opname, int argc,
+                    const char* argv[])
+        : OpSetCICP(ot, opname, { argv, span_size_t(argc) })
+    {
+    }
+    bool setup() override
+    {
+        ir(0)->metadata_modified(true);
+        return true;
+    }
+    bool impl(span<ImageBuf*> img) override
+    {
+        // Because this is an in-place operation, img[0] is the same as
+        // img[1].
+        img[0]->specmod().set_cicp(cicp);
+        return true;
+    }
+
+private:
+    string_view cicp;
+};
+
+
+// --cicp
+static void
+action_cicp(Oiiotool& ot, cspan<const char*> argv)
+{
+    OpSetCICP op(ot, "cicp", argv);
+    op();
+}
+
+
 
 // --colorconfig
 static void
@@ -7081,6 +7122,9 @@ Oiiotool::getargs(int argc, char* argv[])
     ap.arg("--iccread %s:FILENAME")
       .help("Add the contents of the file to the top image as its ICC profile")
       .OTACTION(icc_read);
+    ap.arg("--cicp %s:CICP")
+       .help("Set CICP metadata for supporting output formats (e.g., '12,16,0,1')")
+       .OTACTION(action_cicp);
     // clang-format on
 
     if (ap.parse_args(argc, (const char**)argv) < 0) {

src/png.imageio/png_pvt.h

@@ -328,9 +328,9 @@ read_info(png_structp& sp, png_infop& ip, int& bit_depth, int& color_type,
 
 #ifdef PNG_cICP_SUPPORTED
     {
-        png_byte cp = 0, tf = 0, mc = 0, fr = 0;
-        if (png_get_cICP(sp, ip, &cp, &tf, &mc, &fr)) {
-            uint8_t cicp[4] = { cp, tf, mc, fr };
+        png_byte pri = 0, trc = 0, mtx = 0, vfr = 0;
+        if (png_get_cICP(sp, ip, &pri, &trc, &mtx, &vfr)) {
+            uint8_t cicp[4] = { pri, trc, mtx, vfr };
             spec.attribute(CICP_ATTR, TypeDesc(TypeDesc::UINT8, 4), cicp);
         }
     }
@@ -715,7 +715,8 @@ write_info(png_structp& sp, png_infop& ip, int& color_type, ImageSpec& spec,
         const png_byte* vals = static_cast<const png_byte*>(p->data());
         if (setjmp(png_jmpbuf(sp)))  // NOLINT(cert-err52-cpp)
             return "Could not set PNG cICP chunk";
-        png_set_cICP(sp, ip, vals[0], vals[1], vals[2], vals[3]);
+        // libpng will only write the chunk if the third byte is 0
+        png_set_cICP(sp, ip, vals[0], vals[1], (png_byte) 0, vals[3]);
     }
 #endif
 

src/python/py_imagespec.cpp

@@ -278,6 +278,16 @@ declare_imagespec(py::module& m)
                 self.set_colorspace(cs);
             },
             "name"_a)
+        .def(
+            "set_cicp", [](ImageSpec& self, int pri, int trc,
+                int mtx, int vfr) {
+                self.set_cicp(pri, trc, mtx, vfr);
+            },
+            "pri"_a, "trc"_a, "mtx"_a = 0, "vfr"_a = 1)
+        .def(
+            "set_cicp",
+            [](ImageSpec& self, const std::string& cicp) { self.set_cicp(cicp); },
+            "cicp"_a)
         // __getitem__ is the dict-like `ImageSpec[key]` lookup
         .def("__getitem__",
              [](const ImageSpec& self, const std::string& key) {