oiiotool: allow all filtered ops to take highlightcomp= modifier (#3239)

When doing operations with filters that have negative lobes, you can
sometimes get visible ringing artifacts in very high contrast regions
of HDR images (you tend not to see these artifacts in images that have
range [0,1] because the ringing is very low amplitude unless the input
is very large).

You can do "highlight compensation" to reduce the artifacts when they
occur by doing --rangecompress, which does a log transform on the
input, then the filtered op, then --rangeexpand to transform back to a
linear space. But that makes for kind of verbose and clumsy command
lines, and makes it easy to err by doing the transforms in the wrong
sequence or omitting one.

The -otex command takes a highlightcomp=1 modifier, which does this
bracketing automatically, foolproof, with a compact notation.

This patch adds support for optional highlightcomp=1 modifier for all
of the oiiotool commands that let you specify a filter= option:
--rotate, --warp, --resize, --fit, and --pixelaspect.

Author: lgritz

src/doc/oiiotool.rst

@@ -2910,10 +2910,16 @@ current top image.
 
     Optional appended modifiers include:
 
-      `filter=` *name*
+      `:filter=` *name*
         Filter name. The default is `blackman-harris` when increasing
         resolution, `lanczos3` when decreasing resolution.
 
+      `:highlightcomp=` *val*
+        If nonzero, does highlight compensation by surrounding the filtered
+        operation with the equivalent of `--rangecompress` and
+        `--rangeexpand`, which can reduce visible ringing artifacts when a
+        filter with negative lobes is used on a very high-contrast HDR image.
+
       `:subimages=` *indices-or-names*
         Include/exclude subimages (see :ref:`sec-oiiotool-subimage-modifier`).
 
@@ -2940,6 +2946,11 @@ current top image.
 
     - `filter=` *name* : Filter name. The default is `blackman-harris` when
       increasing resolution, `lanczos3` when decreasing resolution.
+    - `highlightcomp=` *val* : If nonzero, does highlight compensation by
+      surrounding the filtered operation with the equivalent of
+      `--rangecompress` and `--rangeexpand`, which can reduce visible ringing
+      artifacts when a filter with negative lobes is used on a very
+      high-contrast HDR image.
     - `fillmode=` *mode* : determines which of several methods will be used
       to determine how the image will fill the new frame, if its aspect
       ratio does not precisely match the original source aspect ratio:
@@ -3013,7 +3024,13 @@ current top image.
 
     Optional appended modifiers include:
 
-      - `filter=` *name* : Filter name. The default is `lanczos3`.
+      - `:filter=` *name* : Filter name. The default is `lanczos3`.
+
+      - `:highlightcomp=` *val* : If nonzero, does highlight compensation by
+        surrounding the filtered operation with the equivalent of
+        `--rangecompress` and `--rangeexpand`, which can reduce visible
+        ringing artifacts when a filter with negative lobes is used on a very
+        high-contrast HDR image.
 
     Examples::
 
@@ -3030,13 +3047,19 @@ current top image.
 
     Optional appended modifiers include:
 
-      `center=` *x,y*
+      `:center=` *x,y*
         Alternate center of rotation.
 
-      `filter=` *name*
+      `:filter=` *name*
         Filter name. The default is `lanczos3`.
 
-      `recompute_roi=` *val*
+      `:highlightcomp=` *val*
+        If nonzero, does highlight compensation by surrounding the filtered
+        operation with the equivalent of `--rangecompress` and
+        `--rangeexpand`, which can reduce visible ringing artifacts when a
+        filter with negative lobes is used on a very high-contrast HDR image.
+
+      `:recompute_roi=` *val*
         If nonzero, recompute the pixel data window to exactly hold the
         transformed image (default=0).
 
@@ -3063,10 +3086,16 @@ current top image.
 
     Optional appended modifiers include:
 
-      `filter=` *name*
+      `:filter=` *name*
         Filter name. The default is `lanczos3`.
 
-      `recompute_roi=` *val*
+      `:highlightcomp=` *val*
+        If nonzero, does highlight compensation by surrounding the filtered
+        operation with the equivalent of `--rangecompress` and
+        `--rangeexpand`, which can reduce visible ringing artifacts when a
+        filter with negative lobes is used on a very high-contrast HDR image.
+
+      `:recompute_roi=` *val*
         If nonzero, recompute the pixel data window to exactly hold the
         transformed image (default=0).
 

src/oiiotool/oiiotool.cpp

@@ -3208,6 +3208,7 @@ action_reorient(int argc, const char* argv[])
 OIIOTOOL_OP(rotate, 1, [](OiiotoolOp& op, span<ImageBuf*> img) {
     float angle            = Strutil::from_string<float>(op.args(1));
     std::string filtername = op.options()["filter"];
+    bool highlightcomp     = op.options().get_int("highlightcomp");
     bool recompute_roi     = op.options().get_int("recompute_roi");
     std::string cent       = op.options()["center"];
     string_view center(cent);
@@ -3222,25 +3223,55 @@ OIIOTOOL_OP(rotate, 1, [](OiiotoolOp& op, span<ImageBuf*> img) {
         cx               = 0.5f * (src_roi_full.xbegin + src_roi_full.xend);
         cy               = 0.5f * (src_roi_full.ybegin + src_roi_full.yend);
     }
-    return ImageBufAlgo::rotate(*img[0], *img[1], angle * float(M_PI / 180.0),
-                                cx, cy, filtername, 0.0f, recompute_roi);
+    bool ok = true;
+    ImageBuf tmpimg;
+    ImageBuf* src = img[1];
+    if (highlightcomp) {
+        // If the caller requested highlight compensation for an HDR image to
+        // prevent ringing artifacts, we make a temporary image with the
+        // reduced-contrast data.
+        ok &= ImageBufAlgo::rangecompress(tmpimg, *src);
+        src = &tmpimg;
+    }
+    ok &= ImageBufAlgo::rotate(*img[0], *src, angle * float(M_PI / 180.0), cx,
+                               cy, filtername, 0.0f, recompute_roi);
+    if (highlightcomp && ok) {
+        // re-expand the range in place
+        ok &= ImageBufAlgo::rangeexpand(*img[0], *img[0]);
+    }
+    return ok;
 });
 
 
 
 // --warp
 OIIOTOOL_OP(warp, 1, [](OiiotoolOp& op, span<ImageBuf*> img) {
     std::string filtername = op.options()["filter"];
+    bool highlightcomp     = op.options().get_int("highlightcomp");
     bool recompute_roi     = op.options().get_int("recompute_roi");
     std::vector<float> M(9);
     if (Strutil::extract_from_list_string(M, op.args(1)) != 9) {
         ot.error(op.opname(),
                  "expected 9 comma-separatd floats to form a 3x3 matrix");
         return false;
     }
-    return ImageBufAlgo::warp(*img[0], *img[1], *(Imath::M33f*)&M[0],
-                              filtername, 0.0f, recompute_roi,
-                              ImageBuf::WrapDefault);
+    bool ok = true;
+    ImageBuf tmpimg;
+    ImageBuf* src = img[1];
+    if (highlightcomp) {
+        // If the caller requested highlight compensation for an HDR image to
+        // prevent ringing artifacts, we make a temporary image with the
+        // reduced-contrast data.
+        ok &= ImageBufAlgo::rangecompress(tmpimg, *src);
+        src = &tmpimg;
+    }
+    ok &= ImageBufAlgo::warp(*img[0], *src, *(Imath::M33f*)&M[0], filtername,
+                             0.0f, recompute_roi, ImageBuf::WrapDefault);
+    if (highlightcomp && ok) {
+        // re-expand the range in place
+        ok &= ImageBufAlgo::rangeexpand(*img[0], *img[0]);
+    }
+    return ok;
 });
 
 
@@ -3802,6 +3833,7 @@ class OpResize final : public OiiotoolOp {
     virtual bool impl(span<ImageBuf*> img) override
     {
         std::string filtername = options()["filter"];
+        bool highlightcomp     = options().get_int("highlightcomp");
         if (ot.debug) {
             const ImageSpec& newspec(img[0]->spec());
             const ImageSpec& Aspec(img[1]->spec());
@@ -3811,8 +3843,23 @@ class OpResize final : public OiiotoolOp {
                       << (filtername.size() ? filtername.c_str() : "default")
                       << " filter\n";
         }
-        return ImageBufAlgo::resize(*img[0], *img[1], filtername, 0.0f,
-                                    img[0]->roi());
+        bool ok = true;
+        ImageBuf tmpimg;
+        ImageBuf* src = img[1];
+        if (highlightcomp) {
+            // If the caller requested highlight compensation for an HDR image
+            // to prevent ringing artifacts, we make a temporary image with
+            // the reduced-contrast data.
+            ok &= ImageBufAlgo::rangecompress(tmpimg, *src);
+            src = &tmpimg;
+        }
+        ok &= ImageBufAlgo::resize(*img[0], *src, filtername, 0.0f,
+                                   img[0]->roi());
+        if (highlightcomp && ok) {
+            // re-expand the range in place
+            ok &= ImageBufAlgo::rangeexpand(*img[0], *img[0]);
+        }
+        return ok;
     }
 };
 
@@ -3851,18 +3898,31 @@ action_fit(cspan<const char*> argv)
     std::string filtername = options["filter"];
     std::string fillmode   = options["fillmode"];
     bool exact             = options.get_int("exact");
+    bool highlightcomp     = options.get_int("highlightcomp");
 
     int subimages = allsubimages ? A->subimages() : 1;
     ImageRecRef R(new ImageRec(A->name(), subimages));
     for (int s = 0; s < subimages; ++s) {
         ImageSpec newspec = (*A)(s, 0).spec();
+        ImageBuf tmpimg;
+        ImageBuf* src = &((*A)(s, 0));
+        if (highlightcomp) {
+            // If the caller requested highlight compensation for an HDR image
+            // to prevent ringing artifacts, we make a temporary image with
+            // the reduced-contrast data.
+            ImageBufAlgo::rangecompress(tmpimg, *src);
+            src = &tmpimg;
+        }
         newspec.width = newspec.full_width = fit_full_width;
         newspec.height = newspec.full_height = fit_full_height;
         newspec.x = newspec.full_x = fit_full_x;
         newspec.y = newspec.full_y = fit_full_y;
         (*R)(s, 0).reset(newspec);
-        ImageBufAlgo::fit((*R)(s, 0), (*A)(s, 0), filtername, 0.0f, fillmode,
-                          exact);
+        ImageBufAlgo::fit((*R)(s, 0), *src, filtername, 0.0f, fillmode, exact);
+        if (highlightcomp) {
+            // re-expand the range in place
+            ImageBufAlgo::rangeexpand((*R)(s, 0), (*R)(s, 0));
+        }
         R->update_spec_from_imagebuf(s, 0);
     }
     ot.pop();
@@ -3938,6 +3998,7 @@ action_pixelaspect(int argc, const char* argv[])
 
     auto options           = ot.extract_options(command);
     std::string filtername = options["filter"];
+    bool highlightcomp     = options.get_int("highlightcomp");
 
     if (ot.debug) {
         std::cout << "  Scaling "
@@ -3955,6 +4016,8 @@ action_pixelaspect(int argc, const char* argv[])
         std::string command = "resize";
         if (filtername.size())
             command += Strutil::sprintf(":filter=%s", filtername);
+        if (highlightcomp)
+            command += ":highlightcomp=1";
         const char* newargv[2] = { command.c_str(), resize.c_str() };
         action_resize(2, newargv);
         A                         = ot.top();
@@ -4816,7 +4879,7 @@ prep_texture_config(ImageSpec& configspec, ParamValueList& fileoptions)
     configspec.attribute(
         "maketx:highlightcomp",
         fileoptions.get_int("highlightcomp",
-                            fileoptions.get_int("hilightcomp",
+                            fileoptions.get_int("highlightcomp",
                                                 fileoptions.get_int("hicomp"))));
     configspec.attribute("maketx:sharpen", fileoptions.get_float("sharpen"));
     if (fileoptions.contains("filter") || fileoptions.contains("filtername"))
@@ -6042,19 +6105,19 @@ getargs(int argc, char* argv[])
       .help("Resample (640x480, 50%) (options: interp=0)")
       .action(action_resample);
     ap.arg("--resize %s:GEOM")
-      .help("Resize (640x480, 50%) (options: filter=%s)")
+      .help("Resize (640x480, 50%) (options: filter=%s, highlightcomp=%d)")
       .action(action_resize);
     ap.arg("--fit %s:GEOM")
-      .help("Resize to fit within a window size (options: filter=%s, pad=%d, exact=%d)")
+      .help("Resize to fit within a window size (options: filter=%s, pad=%d, fillmode=%s, exact=%d, highlightcomp=%d)")
       .action(action_fit);
     ap.arg("--pixelaspect %g:ASPECT")
-      .help("Scale up the image's width or height to match the given pixel aspect ratio (options: filter=%s)")
+      .help("Scale up the image's width or height to match the given pixel aspect ratio (options: filter=%s, highlightcomp=%d)")
       .action(action_pixelaspect);
     ap.arg("--rotate %g:DEGREES")
-      .help("Rotate pixels (degrees clockwise) around the center of the display window (options: filter=%s, center=%f,%f, recompute_roi=%d")
+      .help("Rotate pixels (degrees clockwise) around the center of the display window (options: filter=%s, center=%f,%f, recompute_roi=%d, highlightcomp=%d")
       .action(action_rotate);
     ap.arg("--warp %s:MATRIX")
-      .help("Warp pixels (argument is a 3x3 matrix, separated by commas) (options: filter=%s, recompute_roi=%d)")
+      .help("Warp pixels (argument is a 3x3 matrix, separated by commas) (options: filter=%s, recompute_roi=%d, highlightcomp=%d)")
       .action(action_warp);
     ap.arg("--convolve")
       .help("Convolve with a kernel")