feat(IBA): Add FLIP perceptual image difference metric (#5154)

Implements the FLIP algorithm from Andersson et al. 2020, rewritten with
OIIO idioms (no source code from the BSD-licensed reference FLIP.h is
directly incorporated). Included are C++ and Python API for
ImageBufAlgo::FLIP_diff(), and `oiiotool --flipdiff` command. The basic
operation is to compare two images and produce a per-pixel error map
that conveys perceptual difference to human observers.

I won't explain it all here; see the extensive comments in
imagebufalgo.h, imagebufalgo_flip.cpp, oiiotool.cpp, imagebufalgo.rst,
oiiotool.rst.

There are some important changes (especially for how we expose this via
oiiotool) versus the way the original NVIDIA reference implementation's
command line tool worked. Please read the extensive comments at the top
of imagebufalgo_flip.cpp for details.

This is a preliminary, experimental implementation. It's hidden behind
an `experimental` namespace (and the oiiotool command requires use of
the `--experimental` argument) to emphasize that it may change and is
not yet considered part of OIIO's public API, and thus is exempt from
our usual strict rules about breaking backward compatibility. Try it out
and give feedback, but do not rely on this yet!

Assisted-by: Claude Code / sonnet-4.6 + opus-4.6

I used Claude Code for the inital stab at transforming the NVIDIA
reference implementation into OIIO idiomatic equivalents. But to be
honest, that got me over the hump of the blank page, but I rewrote most
of it bit by bit as I continued to refine my design ideas for how it
should work and be exposed to users.

Signed-off-by: Larry Gritz <lg@larrygritz.com>

Author: lgritz

.github/workflows/ci.yml

@@ -225,7 +225,7 @@ jobs:
             container: aswf/ci-oiio:2025.5
             cxx_std: 17
             build_type: Debug
-            ctest_test_timeout: "240"
+            ctest_test_timeout: "300"
             python_ver: "3.11"
             simd: "avx2,f16c"
             fmt_ver: 11.2.0

CHANGES.md

@@ -8,9 +8,21 @@ Release 3.2 (target: Sept 2026?) -- compared to 3.1
 ### ⛰️  New features and public API changes:
 * *New image file format support:*
 * *oiiotool new features and major improvements*:
+  - `oiiotool --flipdiff` computes the FLIP perceptual difference between two
+    images, prints statistics, and leaves the error map on the image stack for
+    further processing or saving. Options: `hdr=1` for HDR-FLIP, `colormap=NAME`
+    to apply a false-color map (e.g. "magma"), `ppd=N` to override pixels-per-
+    degree, `tonemapper=NAME` for HDR tonemapper ("aces", "reinhard", "hable").
 * *Command line utilities*:
   - *iv*: Flip, rotate and save image [#5003](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5003) (by Valery Angelique) (3.2.0.0, 3.1.11.0)
 * *ImageBuf/ImageBufAlgo*:
+  - `ImageBufAlgo::FLIP()` computes the FLIP (eLearning perceptual Image
+    difference Predictor) metric between two LDR or HDR images. The result is
+    a single-channel float image with per-pixel FLIP error in [0,1]. A
+    `FLIPResults` struct returns mean error, max error, and location. The
+    optional `colormap` kwarg applies a false-color map to the result.
+    `FLIP_ppd()` helper computes pixels-per-degree for a given display setup.
+    Python bindings and `oiiotool --flipdiff` are also provided.
   - *ImageBuf*: `IB::localpixels_as_[writable_]byte_image_span` [#5011](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5011) (3.2.0.0, 3.1.10.0)
 * *ImageCache/TextureSystem*:
   - *api/TS*: `IBA::make_texture()` now honors "maketx:threads" hint [#5014](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5014) (3.2.0.0, 3.1.10.0)

src/cmake/testing.cmake

@@ -168,6 +168,7 @@ macro (oiio_add_all_tests)
                     oiiotool-text
                     oiiotool-xform
                     diff
+                    flip
                     dither dup-channels
                     jpeg jpeg-corrupt jpeg-metadata
                     maketx oiiotool-maketx

src/doc/imagebufalgo.rst

@@ -2190,6 +2190,66 @@ Image comparison and statistics
 ..
 
 
+|
+
+.. _sec-iba-flip:
+
+FLIP perceptual difference
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygengroup:: FLIP_diff
+   :content-only:
+..
+
+  Examples:
+
+  .. tabs::
+
+     .. code-tab:: c++
+
+        ImageBuf ref ("ref.exr");
+        ImageBuf test ("test.exr");
+
+        // Basic use: returns 1-channel float error map in [0,1].
+        ImageBuf flipmap = ImageBufAlgo::FLIP_diff(ref, test);
+        OIIO::print("Mean FLIP error: {}\n",
+                    flipmap.spec().get_float_attribute("FLIP:meanerror"));
+        OIIO::print("Max  FLIP error: {} at ({}, {})\n",
+                    flipmap.spec().get_float_attribute("FLIP:maxerror"),
+                    flipmap.spec().get_int_attribute("FLIP:maxx"),
+                    flipmap.spec().get_int_attribute("FLIP:maxy"));
+
+        // LDR mode (display-referred images only):
+        ImageBufAlgo::FLIP_diff(flipmap, ref, test, { {"hdr", 0} });
+
+        // For a false-color visualization, pass the result to color_map():
+        ImageBuf colored = ImageBufAlgo::color_map(flipmap, 0, "magma");
+
+     .. code-tab:: py
+
+        ref = ImageBuf("ref.exr")
+        test = ImageBuf("test.exr")
+
+        # Basic use: returns 1-channel float error map in [0,1].
+        flipmap = ImageBufAlgo.FLIP_diff(ref, test)
+        print("Mean FLIP error:", flipmap.spec().get_float_attribute("FLIP:meanerror"))
+        print("Max  FLIP error:", flipmap.spec().get_float_attribute("FLIP:maxerror"),
+              "at", flipmap.spec().get_int_attribute("FLIP:maxx"),
+              flipmap.spec().get_int_attribute("FLIP:maxy"))
+
+        # For a false-color visualization, pass the result to color_map():
+        colored = ImageBufAlgo.color_map(flipmap, 0, "magma")
+
+        # LDR mode:
+        flipmap = ImageBufAlgo.FLIP_diff(ref, test, hdr=0)
+
+     .. code-tab:: bash oiiotool
+
+        # Default HDR mode, outputting per-pixel error map
+        oiiotool ref.exr test.exr --flipdiff -o errormap.exr
+        # Output the false color visualization)
+        oiiotool ref.exr test.exr --flipdiff:colormap=magma -o errorvis.exr
+
 |
 
 .. doxygenfunction:: isConstantColor

src/doc/oiiotool.rst

@@ -1901,6 +1901,10 @@ Writing images
           221  > 1,1,1
         65315  within range
 
+
+:program:`oiiotool` commands that compare images
+================================================
+
 .. option:: --diff
             --fail <A> --failpercent <B> --hardfail <C>
             --warn <A> --warnpercent <B> --hardwarn <C>
@@ -1925,10 +1929,90 @@ Writing images
 .. option:: --pdiff
 
     This command computes the difference of the current image and the next
-    image on the stack using a perceptual metric, and prints whether or not
-    they match according to that metric.  This command does not alter the
+    image on the stack using the Yee perceptual metric, and prints whether or
+    not they match according to that metric.  This command does not alter the
     image stack.
 
+.. option:: --flipdiff
+
+    Compute the FLIP perceptual difference of the top two images on the stack
+    (removing them), optionally print error metrics, and leave the per-pixel
+    error map on the stack.
+
+    Limitations: Currently, this only operates on the first subimage,
+    and the first three (RGB) channels, and does not work on volumetric
+    or "deep" images.
+
+    Optional appended modifiers include:
+
+      `:hdr=` *int* (default: 1)
+        If nonzero, computes the HDR FLIP comparison. If zero, computes
+        the LDR FLIP comparision. The default is 1, for HDR mode.
+      `:maxluminance=` *float* (default: 2.0)
+        The top of the expected luminance range, used to compute exposure
+        settings. If set to 0.0, the "startExposure" and "stopExposure"
+        will be used instead. The default is 2.0, which should be adequate
+        for most production scenarios.
+      `:medianluminance=` *float* (default: 0.18)
+        The assumed median luminance (used if "maxluminance" is not 0, so
+        we are using these estimates instead of measuring from the image).
+        The default 0.18 assumes that "middle grey" is a good guess for
+        a typical median luminance of the image.
+      `:ppd=` *float* (default:67.02)
+        Specifies the horizontal pixels per degree of viewing. The default
+        value of 67.02 is computed as the value for a 3840 pixel (2xHD) image
+        filling a display that is 0.7m wide, 0.7m in front of the viewer.
+      `:tonemapper=` *name* (default: "aces")
+        Specifies the HDR tonemapper: one of "aces" (default), "reinhard", or
+        "hable".
+      `:startExposure=` *float* `:stopExposure=` *float*
+        If supplied, and if "maxluminance" is set to 0, specify start and stop
+        exposures for the HDR FLIP method. If not supplied, they will be
+        automatically computed from the contents of the image.
+      `:numExposures=` *int* (default: 0)
+        The number of exposures for HDR FLIP computation (default: 0, which
+        means to automatically compute it).
+      `:colormap=` *name*
+        If absent or empty, the output error image will be a single channel
+        grey value. If present and the name of a color map (the same set
+        accepted by the oiiotool `--colormap` action), the output error
+        image will be a 3-channel RGB false-color visualization of the
+        perceptual error for each pixel.
+      `:print=` *int* (default: 1)
+        If nonzero, will print information such as the average and maximum
+        error of the pixels. The default is 1, meaning that the report will
+        print to stdout. Set to 0 to suppress the printing.
+      `:fail=` *float*
+        If set, a PASS/FAIL message will be printed to the console, with
+        "failing" meaning that any pixel's error metric exceeded the threshold
+        specified as the value for this parameter. In the case of a failure,
+        the oiiotool run itself will have a shell error code.
+
+    The command also sets metadata on the result image based on the FLIP
+    computation:
+
+      `"FLIP:meanerror"`
+        Mean of error map in [0,1].
+      `"FLIP:maxerror"`
+        Maximum perceptual pixel error.
+      `"FLIP:maxx"`
+        x coordinate of the pixel with the highest error.
+      `"FLIP:maxy"`
+        y coordinate of the pixel with the highest error.
+      `"FLIP:startExposure"`, `"FLIP:stopExposure"`
+        (HDR mode only) The start and stop exposure stops used.
+      `"FLIP:numExposures"`
+        (HDR mode only) Number of exposure steps used.
+
+    Examples::
+
+        # Default HDR mode, with false-color visualization
+        oiiotool reference.exr test.exr --flipdiff:colormap=magma -o error.exr
+
+        # LDR mode (for display-referred images), 1-channel error map
+        oiiotool reference.jpg test.jpg --flipdiff:hdr=0 -o error.exr
+
+    This command was added in OIIO 3.2.
 
 
 :program:`oiiotool` commands that change the current image metadata

src/doc/pythonbindings.rst

@@ -3287,6 +3287,98 @@ Image comparison and statistics
 
 
 
+.. py:method:: ImageBuf ImageBufAlgo.FLIP_diff (ref, test, hdr=1, maxluminance=2.0, medianluminance=0.18, ppd=0.0, tonemapper="aces", roi=ROI.All, nthreads=0)
+               bool ImageBufAlgo.FLIP_diff (dst, ref, test, hdr=1, maxluminance=2.0, medianluminance=0.18, ppd=0.0, tonemapper="aces", roi=ROI.All, nthreads=0)
+
+    WARNING: This is EXPERIMENTAL and may change at any time. Do not rely
+    on it prior to the release of OIIO 3.2.
+
+    Compute the `FLIP <https://research.nvidia.com/publication/2020-07_flip-difference-evaluator-alternating-images>`_
+    perceptual difference between images `ref` and `test`, returning a
+    single-channel float error map whose pixel values lie in [0,1].  Higher
+    values indicate larger perceived differences.
+
+    If the image's ``oiio:ColorSpace`` metadata does not clearly define a
+    color space, it will be assumed to be ``lin_rec709_scene`` before
+    processing. Three channels starting at ``roi.chbegin`` are used.
+
+    Summary statistics are stored as metadata attributes on the result
+    ``ImageBuf``:
+
+    .. code-block:: python
+
+        errmap = ImageBufAlgo.FLIP_diff (ref_image, test_image)
+        errmap.spec().get_float_attribute("FLIP:meanerror")   # mean perceptual error
+        errmap.spec().get_float_attribute("FLIP:maxerror")    # maximum per-pixel error
+        errmap.spec().get_int_attribute("FLIP:maxx")          # x coordinate of max-error pixel
+        errmap.spec().get_int_attribute("FLIP:maxy")          # y coordinate of max-error pixel
+        errmap.spec().get_float_attribute("FLIP:startExposure") # HDR: first exposure stop used
+        errmap.spec().get_float_attribute("FLIP:stopExposure")  # HDR: last exposure stop used
+        errmap.spec().get_int_attribute("FLIP:numExposures")  # HDR: number of exposure steps used
+
+    Options:
+
+    * `hdr` (int, default 1) — set to 0 to force use of LDR-FLIP mode (should
+      only be used for images in a LDR display-referred color space).
+    * `maxluminance` (float, default 2.0) — estimated maximum luminance
+    * `medianluminance` (float, default 0.18) — estimated median luminance
+    * `ppd` (float, default 67.02) — pixels per degree of visual angle
+    * `tonemapper` (str, default ``"aces"``) — HDR tonemapper:
+      ``"aces"``, ``"reinhard"``, or ``"hable"``
+    * `startExposure`, `stopExposure` (float) - The start and end exposures
+      for HDR FLIP. If not supplied, they will be computed automatically based
+      on the `maxluminance`, which if it is 0, will be computed based on the
+      value range in the reference image.
+    * `numExposures` (int) - The number of exposures used for HDR FLIP. If
+      not supplied, it will be computed automatically.
+
+    Tip: For a false-color visualization pass the result to
+    :py:meth:`ImageBufAlgo.color_map`.
+
+    See also :py:meth:`ImageBufAlgo.FLIP_ppd` for computing `ppd` from
+    display geometry.
+
+    This was added in OpenImageIO 3.2.
+
+    Example:
+
+    .. code-block:: python
+
+        ref  = ImageBuf("ref.exr")
+        test = ImageBuf("test.exr")
+
+        # Basic use: 1-channel float error map in [0,1].
+        errmap = ImageBufAlgo.FLIP_diff(ref, test)
+        print("Mean FLIP error:", errmap.spec().get_float_attribute("FLIP:meanerror"))
+        print("Max  FLIP error:", errmap.spec().get_float_attribute("FLIP:maxerror"),
+              "at", errmap.spec().get_int_attribute("FLIP:maxx"),
+              errmap.spec().get_int_attribute("FLIP:maxy"))
+
+        # LDR mode (display-referred images only):
+        errmap = ImageBufAlgo.FLIP_diff(ref, test, hdr=0)
+
+        # False-color visualization:
+        colored = ImageBufAlgo.color_map(errmap, 0, "magma")
+
+
+
+.. py:method:: float ImageBufAlgo.FLIP_ppd (monitor_distance_m=0.7, screen_width_px=3840, screen_width_m=0.7)
+
+    Compute the pixels-per-degree value for use as the `ppd` argument to
+    :py:meth:`ImageBufAlgo.FLIP_diff`, given the viewing distance in meters,
+    the screen width in pixels, and the screen width in meters.  The default
+    values correspond to ~67 ppd (a common desktop monitor at typical viewing
+    distance).
+
+    Example:
+
+    .. code-block:: python
+
+        ppd = ImageBufAlgo.FLIP_ppd(0.5, 2560, 0.6)
+        errmap = ImageBufAlgo.FLIP_diff(ref, test, ppd=ppd)
+
+
+
 .. py:method:: tuple ImageBufAlgo.isConstantColor (src, threshold=0.0, roi=ROI.All, nthreads=0)
 
     If all pixels of `src` within the ROI have the same values (for the