feat(IBA): IBA::scale() (#4541)

Implements IBA::scale, an algo which takes two images, one of which is
required to be a single channel image, each channel of the other image
gets multiplied by that single channel, per pixel.

Note that this is subtly different from IBA::mul(), which is a
channel-by-channel multiplication, and so doesn't have a provision for
allowing you to scale all channels of one image by the single channel of
a second image.

I have added tests for the C++ code, python code, oiiotool, and the
documentation examples


Signed-off-by: Anton Dukhovnikov <[email protected]>

Author: antond-weta

src/doc/figures/scale.jpg

@@ -1329,6 +1329,38 @@ Image arithmetic
 
 |
 
+.. doxygenfunction:: scale(const ImageBuf &A, const ImageBuf &B, KWArgs options = {}, ROI roi = {}, int nthreads = 0)
+..
+
+  Result-as-parameter version:
+
+    .. doxygenfunction:: scale(ImageBuf &dst, const ImageBuf &A, const ImageBuf &B, KWArgs options = {}, ROI roi = {}, int nthreads = 0)
+
+  Examples:
+
+    .. tabs::
+
+       .. tab:: C++
+             .. literalinclude:: ../../testsuite/docs-examples-cpp/src/docs-examples-imagebufalgo.cpp
+              :language: c++
+              :start-after: BEGIN-imagebufalgo-scale
+              :end-before: END-imagebufalgo-scale
+              :dedent: 4
+
+       .. tab:: Python
+          .. literalinclude:: ../../testsuite/docs-examples-python/src/docs-examples-imagebufalgo.py
+              :language: py
+              :start-after: BEGIN-imagebufalgo-scale
+              :end-before: END-imagebufalgo-scale
+              :dedent: 4
+
+       .. code-tab:: bash oiiotool
+
+          # Pixel-by-pixel multiplication of all channels of one image by the only channel of another image
+          oiiotool a.exr mono.exr --scale -o scale.exr
+
+|
+
 .. doxygenfunction:: mul(Image_or_Const A, Image_or_Const B, ROI roi = {}, int nthreads = 0)
 ..
 

src/doc/imagebufalgo.rst

@@ -2507,6 +2507,27 @@ current top image.
         Include/exclude subimages (see :ref:`sec-oiiotool-subimage-modifier`).
 
 
+.. option:: --scale
+
+    Replace the *two* top images with a new image that is the pixel-by-pixel
+    multiplicative product of those images. One of the images must have a single
+    channel, that channel's pixel value is used to scale all channels of the
+    other image by.
+
+
+    Example::
+
+        # Apply vertical gradient
+        oiiotool tahoe.jpg --pattern fill:top=0.5:bottom=1 512x384 1 --scale -o scale.jpg
+    ..
+
+        .. image:: figures/tahoe-small.jpg
+            :width: 2.0 in
+        .. image:: figures/scale.jpg
+            :width: 2.0 in
+        |
+
+
 .. option:: --mul
             --mulc <value>
             --mulc <value0,value1,value2...>

src/doc/oiiotool.rst

@@ -2833,6 +2833,23 @@ Image arithmetic
 
 
 
+.. py:method:: ImageBuf ImageBufAlgo.scale (A, B, roi=ROI.All, nthreads=0)
+               bool ImageBufAlgo.scale (dst, A, B, roi=ROI.All, nthreads=0)
+
+    Per-pixel multiply all channels of one image by the single channle of the
+    other image. One of the input images must have only one channel.
+
+    Example:
+
+    .. code-block:: python
+
+        # Scale one image by the other
+        buf = ImageBufAlgo.scale (ImageBuf("a.exr"), ImageBuf("mono.exr"))
+
+        # Scale one image by the other, in place
+        ImageBufAlgo.scale (buf, buf, ImageBuf("mono.exr"))
+
+
 .. py:method:: ImageBuf ImageBufAlgo.mul (A, B, roi=ROI.All, nthreads=0)
                bool ImageBufAlgo.mul (dst, A, B, roi=ROI.All, nthreads=0)
 

src/doc/pythonbindings.rst

@@ -953,6 +953,21 @@ ImageBuf OIIO_API abs (const ImageBuf &A, ROI roi={}, int nthreads=0);
 bool OIIO_API abs (ImageBuf &dst, const ImageBuf &A, ROI roi={}, int nthreads=0);
 
 
+/// Compute per-pixel product `A * B`, returning the result image. At least
+/// one of `A` and `B` must be a single channel image, whose value is used to
+/// scale all channels of the other image.
+///
+/// @param  options
+///         Optional ParamValue's that may control the reconstruction.
+///         (Reserved for future expansion.)
+///
+ImageBuf OIIO_API scale (const ImageBuf &A, const ImageBuf &B,
+                         KWArgs options = {}, ROI roi={}, int nthreads=0);
+/// Write to an existing image `dst` (allocating if it is uninitialized).
+bool OIIO_API scale (ImageBuf &dst, const ImageBuf &A, const ImageBuf &B,
+                     KWArgs options = {}, ROI roi={}, int nthreads=0);
+
+
 /// Compute per-pixel product `A * B`, returning the result image.
 ///
 /// Either both `A` and `B` are images, or one is an image and the other is

src/include/OpenImageIO/imagebufalgo.h

@@ -25,6 +25,65 @@
 OIIO_NAMESPACE_BEGIN
 
 
+template<class Rtype, class Atype, class Btype>
+static bool
+scale_impl(ImageBuf& R, const ImageBuf& A, const ImageBuf& B, ROI roi,
+           int nthreads)
+{
+    ImageBufAlgo::parallel_image(roi, nthreads, [&](ROI roi) {
+        ImageBuf::Iterator<Rtype> r(R, roi);
+        ImageBuf::ConstIterator<Atype> a(A, roi);
+        ImageBuf::ConstIterator<Btype> b(B, roi);
+        for (; !r.done(); ++r, ++a, ++b)
+            for (int c = roi.chbegin; c < roi.chend; ++c)
+                r[c] = a[c] * b[0];
+    });
+    return true;
+}
+
+
+
+bool
+ImageBufAlgo::scale(ImageBuf& dst, const ImageBuf& A, const ImageBuf& B,
+                    KWArgs options, ROI roi, int nthreads)
+{
+    pvt::LoggedTimer logtime("IBA::scale");
+    bool ok = false;
+    if (B.nchannels() == 1) {
+        if (IBAprep(roi, &dst, &A, &B))
+            OIIO_DISPATCH_COMMON_TYPES3(ok, "scale", scale_impl,
+                                        dst.spec().format, A.spec().format,
+                                        B.spec().format, dst, A, B, roi,
+                                        nthreads);
+    } else if (A.nchannels() == 1) {
+        if (IBAprep(roi, &dst, &A, &B))
+            OIIO_DISPATCH_COMMON_TYPES3(ok, "scale", scale_impl,
+                                        dst.spec().format, B.spec().format,
+                                        A.spec().format, dst, B, A, roi,
+                                        nthreads);
+    } else {
+        dst.errorfmt(
+            "ImageBufAlgo::scale(): one of the arguments must be a single channel image.");
+    }
+
+    return ok;
+}
+
+
+
+ImageBuf
+ImageBufAlgo::scale(const ImageBuf& A, const ImageBuf& B, KWArgs options,
+                    ROI roi, int nthreads)
+{
+    ImageBuf result;
+    bool ok = scale(result, A, B, options, roi, nthreads);
+    if (!ok && !result.has_error())
+        result.errorfmt("ImageBufAlgo::scale() error");
+    return result;
+}
+
+
+
 template<class Rtype, class Atype, class Btype>
 static bool
 mul_impl(ImageBuf& R, const ImageBuf& A, const ImageBuf& B, ROI roi,

src/libOpenImageIO/imagebufalgo_muldiv.cpp

@@ -3090,6 +3090,7 @@ BINARY_IMAGE_OP(add, ImageBufAlgo::add);          // --add
 BINARY_IMAGE_OP(sub, ImageBufAlgo::sub);          // --sub
 BINARY_IMAGE_OP(mul, ImageBufAlgo::mul);          // --mul
 BINARY_IMAGE_OP(div, ImageBufAlgo::div);          // --div
+BINARY_IMAGE_OP(scale, ImageBufAlgo::scale);      // --scale
 BINARY_IMAGE_OP(absdiff, ImageBufAlgo::absdiff);  // --absdiff
 
 BINARY_IMAGE_COLOR_OP(addc, ImageBufAlgo::add, 0);          // --addc
@@ -6644,6 +6645,9 @@ Oiiotool::getargs(int argc, char* argv[])
     ap.arg("--csub %s:VAL")
       .hidden() // Deprecated synonym
       .OTACTION(action_subc);
+    ap.arg("--scale")
+      .help("Scale all channels of one image by the single channel of another image")
+      .OTACTION(action_scale);
     ap.arg("--mul")
       .help("Multiply two images")
       .OTACTION(action_mul);

src/oiiotool/oiiotool.cpp

@@ -652,6 +652,22 @@ IBA_abs_ret(const ImageBuf& A, ROI roi = ROI::All(), int nthreads = 0)
 
 
 
+bool
+IBA_scale_images(ImageBuf& dst, const ImageBuf& A, const ImageBuf& B,
+                 ROI roi = ROI::All(), int nthreads = 0)
+{
+    py::gil_scoped_release gil;
+    return ImageBufAlgo::scale(dst, A, B, {}, roi, nthreads);
+}
+
+ImageBuf
+IBA_scale_images_ret(const ImageBuf& A, const ImageBuf& B, ROI roi = ROI::All(),
+                     int nthreads = 0)
+{
+    py::gil_scoped_release gil;
+    return ImageBufAlgo::scale(A, B, {}, roi, nthreads);
+}
+
 bool
 IBA_mul_color(ImageBuf& dst, const ImageBuf& A, py::object values_tuple,
               ROI roi = ROI::All(), int nthreads = 0)
@@ -2625,6 +2641,11 @@ declare_imagebufalgo(py::module& m)
         .def_static("abs", &IBA_abs_ret, "A"_a, "roi"_a = ROI::All(),
                     "nthreads"_a = 0)
 
+        .def_static("scale", &IBA_scale_images, "dst"_a, "A"_a, "B"_a,
+                    "roi"_a = ROI::All(), "nthreads"_a = 0)
+        .def_static("scale", &IBA_scale_images_ret, "A"_a, "B"_a,
+                    "roi"_a = ROI::All(), "nthreads"_a = 0)
+
         .def_static("mul", &IBA_mul_images, "dst"_a, "A"_a, "B"_a,
                     "roi"_a = ROI::All(), "nthreads"_a = 0)
         .def_static("mul", &IBA_mul_color, "dst"_a, "A"_a, "B"_a,

src/python/py_imagebufalgo.cpp

@@ -33,6 +33,7 @@ example_add
 example_sub
 example_absdiff
 example_abs
+example_scale
 example_mul
 example_div
 example_fixNonFinite

testsuite/docs-examples-cpp/ref/out-arm.txt

@@ -33,6 +33,7 @@ example_add
 example_sub
 example_absdiff
 example_abs
+example_scale
 example_mul
 example_div
 example_fixNonFinite