feat(iba): add 'auto' value for all options of IBA::demosaic (AcademySoftwareFoundation#4786)

- The parameter 'pattern' now supports a special value 'auto', which is
also default.
- The parameter 'layout' now supports a special value 'auto', which is
also default.
- The parameter 'algorithm' now supports a special value 'auto', which
is also default.
- New parameter 'white_balance_mode.
- The raw input plugin now adds an attribute 'raw:WhiteBalance' in
addition to the libraw-specific 'raw:cam_mul', carrying the same values.

This changes the current behaviour, please read below.

Previously, the parameter 'pattern' defaulted to 'bayer'. The new default
value of 'auto' makes OIIO look for the input ImageBuf's attribute
'raw:FilterPattern', and deduct the pattern from its value. If the
attribute is missing, 'bayer' is assumed.

Previously, the parameter 'layout' defaulted to 'RGGB' for Bayer pattern,
or 'GRBGBR BGGRGG RGGBGG GBRGRB RGGBGG BGGRGG' for X-Trans. The new
default value of 'auto' makes OIIO look for the input ImageBuf's
attribute 'raw:FilterPattern', and deduct the layout from its value. If
the attribute is missing, the old default values are assumed.

Technically the 2 changes above the current behaviour may change, but
only in a very rare use case: when the user relies on the old default
values to decode the image, and there is metadata present in the
ImageBuf saying that the pattern and/or layout is different from the
default.

Previously, the parameter 'algorithm' defaulted to 'linear'. The new
default value 'auto' maps to 'MHC' for the Bayer pattern, and 'linear'
for the X-Trans.

The newly added parameter 'white_balance_mode' can have one of the
following three values:
- 'auto' (default) - the white-balancing weights are read from the input
ImageBuf's attribute 'raw:WhiteBalance', defaulting to (1, 1, 1, 1).
- 'manual' - the white-balancing weights are read from the parameter
'white_balance'.
- 'none' - same as 'manual' with the weights of (1, 1, 1, 1).

This changes the current behaviour where the white-balancing weights
from the parameter 'white_balance' get applied if present. Now, in
addition to providing them, you need to explicitly set
'white_balance_mode' to 'manual'.

I've updated the unit tests to cover the new 'auto' mode. 

---------

Signed-off-by: Anton Dukhovnikov <antond@wetafx.co.nz>

Author: antond-weta

src/doc/imagebufalgo.rst

@@ -1183,7 +1183,7 @@ Shuffling channels
 
        .. code-tab:: bash oiiotool
 
-          oiiotool -iconfig raw:Demosaic none -i test.cr3 --demosaic:layout=GRBG:white_balance=2.0,0.8,1.2,1.5 -o out.exr
+          oiiotool -iconfig raw:Demosaic none -i test.cr3 --demosaic:layout=GRBG:white_balance_mode=manual:white_balance=2.0,0.8,1.2,1.5 -o out.exr
 
 |
 

src/doc/oiiotool.rst

@@ -4281,20 +4281,41 @@ current top image.
     Optional appended modifiers include:
 
       `pattern=` *name*
-        sensor pattern. Currently supported patterns: "bayer", "xtrans".
+        sensor pattern. Currently supported patterns: "auto"(default), "bayer",
+        "xtrans". In the "auto" mode the pattern is deducted from the
+        "raw:FilterPattern" attribute of the source image buffer, defaulting to
+        "bayer" if absent.
       `layout=` *name*
-        photosite order of the specified pattern. The default value is "RGGB"
-        for Bayer, and "GRBGBR BGGRGG RGGBGG GBRGRB RGGBGG BGGRGG" for X-Trans.
+        The order the color filter array elements are arranged in,
+        pattern-specific. The Bayer pattern sensors usually have 4 values in the
+        layout string, describing the 2x2 pixels region. The X-Trans pattern
+        sensors have 36 values in the layout string, describing the 6x6 pixels
+        region (with optional whitespaces separating the rows). When set to
+        "auto", OIIO will try to fetch the layout from the "raw:FilterPattern"
+        attribute of the source image buffer, falling back to "RGGB" for Bayer,
+        "GRBGBR BGGRGG RGGBGG GBRGRB RGGBGG BGGRGG" for X-Trans if absent.
       `algorithm=` *name*
-        the name of the algorithm to use.
+        the name of the algorithm to use, defaults to "auto".
         The Bayer-pattern algorithms:
         - "linear"(simple bilinear demosaicing),
-        - "MHC"(Malvar-He-Cutler algorithm).
+        - "MHC"(Malvar-He-Cutler algorithm),
+        - "auto"(same as "MHC").
         The X-Trans-pattern algorithms:
-        - "linear"(simple bilinear demosaicing).
-      `white-balance=` *v1,v2,v3...*
+        - "linear"(simple bilinear demosaicing),
+        - "auto"(same as "linear").
+      `white_balance_mode=` *name*
+        white-balancing mode to use. The supported modes are:
+        - "auto"(OIIO will try to fetch the white balancing weights from the
+        "raw:WhiteBalance" attribute of the source image buffer, falling back to
+        {1.0, 1.0, 1.0, 1.0} if absent),
+        - "manual"(The white balancing weights will be taken from the attribute
+        "white-balance" (see below) if present, falling back to
+        {1.0, 1.0, 1.0, 1.0} if absent),
+        - "none"(no white balancing will be performed).
+      `white_balance=` *v1,v2,v3...*
         optional white balance weights, can contain either three (R,G,B) or four
-        (R,G1,B,G2) values. The order of the white balance multipliers is as
+        (R,G1,B,G2) values, only used when the white-balancing mode (see above)
+        is set to "manual". The order of the white balance multipliers is as
         specified, it does not depend on the matrix layout.
 
     Examples::
@@ -4303,7 +4324,7 @@ current top image.
             --output out.exr
 
          oiiotool --iconfig raw:Demosaic none --input test.cr3 \
-            --demosaic:pattern=bayer:layout=GRBG:algorithm=MHC:white_balance=2.0,0.8,1.2,1.5 \
+            --demosaic:pattern=bayer:layout=GRBG:algorithm=MHC:white_balance_mode=manual:white_balance=2.0,0.8,1.2,1.5 \
             --output out.exr
 
 

src/doc/pythonbindings.rst

@@ -3718,17 +3718,24 @@ Color manipulation
         ImageBufAlgo.unpremult (A, A)
 
 
-.. py:method:: ImageBuf ImageBufAlgo.demosaic (src, pattern="", algorithm="", layout="", white_balance=py::none(), roi=ROI.All, nthreads=0)
-                bool ImageBufAlgo.demosaic (dst, src, pattern="", algorithm="", layout="", white_balance=py::none(), roi=ROI.All, nthreads=0)
+.. py:method:: ImageBuf ImageBufAlgo.demosaic (src, pattern="", algorithm="", layout="", white_balance_mode="", white_balance=py::none(), roi=ROI.All, nthreads=0)
+                bool ImageBufAlgo.demosaic (dst, src, pattern="", algorithm="", layout="", white_balance_mode="", white_balance=py::none(), roi=ROI.All, nthreads=0)
     Demosaic a raw digital camera image.
 
     `demosaic` can currently process Bayer-pattern images (pattern="bayer")
     using two algorithms: "linear" (simple bilinear demosaicing), and "MHC"
     (Malvar-He-Cutler algorithm); or X-Trans-pattern images (pattern="xtrans")
-    using "linear" algorithm. The optional white_balance parameter can take
-    a tuple of three (R,G,B), or four (R,G1,B,G2) values. The order of the
-    white balance multipliers is as specified, it does not depend on the matrix
-    layout.
+    using "linear" algorithm. When "layout" or "pattern" are absent or set to
+    "auto" OIIO will attempt to deduct their value from the  "raw:FilterPattern"
+    attribute of the source image buffer. White-balancing mode can be se to
+    "auto" (OIIO will try to fetch the white balancing weights from the
+    "raw:WhiteBalance" attribute of the source image buffer, falling back to
+    {1.0, 1.0, 1.0, 1.0} if absent), "manual" (The white balancing weights will
+    be taken from the attribute "white_balance" (see below) if present, falling
+    back to {1.0, 1.0, 1.0, 1.0} if absent), "none" (no white balancing will be
+    performed). The optional "white_balance" parameter can take a tuple of three
+    (R,G,B), or four (R,G1,B,G2) values. The order of the white balance
+    multipliers is as specified, it does not depend on the matrix layout.
 
     Example:
 
@@ -3737,7 +3744,7 @@ Color manipulation
         Src = ImageBuf("test.cr3", 0, 0, hint)
         WB_RGBG = (2.0, 0.8, 1.5, 1.2)
         Dst = OpenImageIO.ImageBufAlgo.demosaic(Src, layout="GRBG",
-            white_balance = WB_RGBG)
+            white_balance_mode = "manual", "white_balance = WB_RGBG)
 
 
 

src/include/OpenImageIO/imagebufalgo.h

@@ -2162,28 +2162,45 @@ bool OIIO_API repremult (ImageBuf &dst, const ImageBuf &src,
 /// The `options` list contains optional ParamValue's that may control the reconstruction.
 /// The following options are recognized:
 ///
-///   - "pattern" : string (default: "bayer")
+///   - "pattern" : string (default: "auto")
 ///
 ///     The type of image sensor color filter array. Currently suported patterns:
 ///     - `bayer` - Bayer-pattern image.
 ///     - `xtrans` - X-Trans-pattern image.
+///     - `auto` - the pattern is deducted from the "raw:FilterPattern" attribute of the source image buffer.
 ///
-///   - "algorithm" : string (default: "linear")
+///   - "algorithm" : string (default: "auto")
 ///
 ///     The demosaicing algorithm, pattern-specific.
 ///     The following algorithms are supported for Bayer-pattern images:
 ///     - `linear` - simple bilinear demosaicing. Fast, but can produce artefacts along sharp edges.
 ///     - `MHC` - Malvar-He-Cutler linear demosaicing algorithm. Slower than `linear`, but produces 
 ///       significantly better results.
+///     - `auto` - same as "MHC"
 ///
 ///     The following algorithms are supported for X-Trans-pattern images:
 ///     - `linear` - simple linear demosaicing. Fast, but can produce artefacts along sharp edges.
+///     - `auto` - same as "linear"
 ///
-///   - "layout" : string (default: "RGGB" for Bayer, "GRBGBR BGGRGG RGGBGG GBRGRB RGGBGG BGGRGG" for X-Trans)
+///   - "layout" : string (default: "auto")
 ///
-///     The order the color filter array elements are arranged in, pattern-specific.
+///     The order the color filter array elements are arranged in, pattern-specific. The Bayer pattern sensors
+///     usually have 4 values in the layout string, describing the 2x2 pixels region. The X-Trans pattern
+///     sensors have 36 values in the layout string, describing the 6x6 pixels region (with optional
+///     whitespaces separating the rows). When set to "auto", OIIO will try to fetch the layout from the
+///     "raw:FilterPattern" attribute of the source image buffer, falling back to "RGGB" for Bayer,
+///     "GRBGBR BGGRGG RGGBGG GBRGRB RGGBGG BGGRGG" for X-Trans if absent.
 ///
-///   - "white-balance" : float[3] or float[4], (default: {1.0, 1.0, 1.0, 1.0})
+///   - "white_balance_mode" : string (default: "auto")
+///
+///     White-balancing mode. The following modes are supported:
+///     - `auto` - OIIO will try to fetch the white balancing weights from the "raw:WhiteBalance"
+///     attribute of the source image buffer, falling back to {1.0, 1.0, 1.0, 1.0} if absent.
+///     - `manual` - The white balancing weights will be taken from the attribute `white_balance` (see below)
+///     if present, falling back to {1.0, 1.0, 1.0, 1.0} if absent.
+///     - `none` - no white balancing will be performed.
+///
+///   - "white_balance" : float[3] or float[4]
 ///
 ///     Optional white-balancing weights. Can contain either three (R,G,B), or four (R,G1,B,G2) values.
 ///     The order of the white balance multipliers does not depend on the matrix layout.

src/libOpenImageIO/imagebufalgo_demosaic.cpp

@@ -19,6 +19,7 @@ namespace {
 static const ustring pattern_us("pattern");
 static const ustring algorithm_us("algorithm");
 static const ustring layout_us("layout");
+static const ustring white_balance_mode_us("white_balance_mode");
 static const ustring white_balance_us("white_balance");
 
 }  // namespace
@@ -970,7 +971,8 @@ demosaic(ImageBuf& dst, const ImageBuf& src, KWArgs options, ROI roi,
     std::string pattern;
     std::string algorithm;
     std::string layout;
-    float white_balance_RGBG[4] = { 1.0f, 1.0f, 1.0f, 1.0f };
+    std::string white_balance_mode;
+    float custom_white_balance_RGBG[4] = { 1.0f, 1.0f, 1.0f, 1.0f };
     std::string error;
 
     for (auto&& pv : options) {
@@ -992,22 +994,29 @@ demosaic(ImageBuf& dst, const ImageBuf& src, KWArgs options, ROI roi,
             } else {
                 dst.errorfmt("ImageBufAlgo::demosaic() invalid layout");
             }
+        } else if (pv.name() == white_balance_mode_us) {
+            if (pv.type() == TypeString) {
+                white_balance_mode = pv.get_string();
+            } else {
+                dst.errorfmt(
+                    "ImageBufAlgo::demosaic() invalid white_balance_mode");
+            }
         } else if (pv.name() == white_balance_us) {
             if (pv.type() == TypeFloat && pv.nvalues() == 4) {
                 // The order in the options is always (R,G1,B,G2)
-                white_balance_RGBG[0] = pv.get_float_indexed(0);
-                white_balance_RGBG[1] = pv.get_float_indexed(1);
-                white_balance_RGBG[2] = pv.get_float_indexed(2);
-                white_balance_RGBG[3] = pv.get_float_indexed(3);
+                custom_white_balance_RGBG[0] = pv.get_float_indexed(0);
+                custom_white_balance_RGBG[1] = pv.get_float_indexed(1);
+                custom_white_balance_RGBG[2] = pv.get_float_indexed(2);
+                custom_white_balance_RGBG[3] = pv.get_float_indexed(3);
 
-                if (white_balance_RGBG[3] == 0)
-                    white_balance_RGBG[3] = white_balance_RGBG[1];
+                if (custom_white_balance_RGBG[3] == 0)
+                    custom_white_balance_RGBG[3] = custom_white_balance_RGBG[1];
             } else if (pv.type() == TypeFloat && pv.nvalues() == 3) {
                 // The order in the options is always (R,G,B)
-                white_balance_RGBG[0] = pv.get_float_indexed(0);
-                white_balance_RGBG[1] = pv.get_float_indexed(1);
-                white_balance_RGBG[2] = pv.get_float_indexed(2);
-                white_balance_RGBG[3] = white_balance_RGBG[2];
+                custom_white_balance_RGBG[0] = pv.get_float_indexed(0);
+                custom_white_balance_RGBG[1] = pv.get_float_indexed(1);
+                custom_white_balance_RGBG[2] = pv.get_float_indexed(2);
+                custom_white_balance_RGBG[3] = custom_white_balance_RGBG[2];
             } else {
                 dst.errorfmt("ImageBufAlgo::demosaic() invalid white balance");
             }
@@ -1033,12 +1042,52 @@ demosaic(ImageBuf& dst, const ImageBuf& src, KWArgs options, ROI roi,
 
     IBAprep(dst_roi, &dst, &src, nullptr, &dst_spec);
 
-    if (pattern.length() == 0)
-        pattern = "bayer";
+    if (pattern.empty())
+        pattern = "auto";
+    if (layout.empty())
+        layout = "auto";
+    if (algorithm.empty())
+        algorithm = "auto";
+
+    if (layout == "auto") {
+        layout = src.spec().get_string_attribute("raw:FilterPattern");
+    }
+
+    if (pattern == "auto") {
+        size_t l = layout.length();
+        if ((l == 6 * 6 + 5) || (l == 6 * 6))
+            pattern = "xtrans";
+        else
+            pattern = "bayer";
+    }
+
+    if (white_balance_mode.length() == 0)
+        white_balance_mode = "auto";
+
+    float white_balance_RGBG[4] = { 1.0f, 1.0f, 1.0f, 1.0f };
+
+    if (white_balance_mode == "auto") {
+        auto pv = src.spec().find_attribute("raw:WhiteBalance");
+        if ((pv != nullptr) && (pv->type() == TypeDesc(TypeDesc::FLOAT, 4))) {
+            // The order in the options is always (R,G1,B,G2)
+            white_balance_RGBG[0] = pv->get_float_indexed(0);
+            white_balance_RGBG[1] = pv->get_float_indexed(1);
+            white_balance_RGBG[2] = pv->get_float_indexed(2);
+            white_balance_RGBG[3] = pv->get_float_indexed(3);
+        }
+    } else if (white_balance_mode == "manual") {
+        white_balance_RGBG[0] = custom_white_balance_RGBG[0];
+        white_balance_RGBG[1] = custom_white_balance_RGBG[1];
+        white_balance_RGBG[2] = custom_white_balance_RGBG[2];
+        white_balance_RGBG[3] = custom_white_balance_RGBG[3];
+    } else if (white_balance_mode != "none") {
+        dst.errorfmt("ImageBufAlgo::demosaic() unknown white balance mode {}",
+                     white_balance_mode);
+    }
 
     if (pattern == "bayer") {
-        if (algorithm.length() == 0) {
-            algorithm = "linear";
+        if (algorithm == "auto") {
+            algorithm = "MHC";
         }
 
         if (algorithm == "linear") {
@@ -1057,7 +1106,7 @@ demosaic(ImageBuf& dst, const ImageBuf& src, KWArgs options, ROI roi,
             dst.errorfmt("ImageBufAlgo::demosaic() invalid algorithm");
         }
     } else if (pattern == "xtrans") {
-        if (algorithm.length() == 0) {
+        if (algorithm == "auto") {
             algorithm = "linear";
         }