Improvements related to image dithering and low-bit-depth output (#3141)

We have options that allow adding random dither to images before
output, which when converting float images to 8 bit or less, can
greatly reduce the appearance of banding artifacts. This PR makes a
number of improvements:

* When the option is used, it should apply dither any time you are
  reducing an image with > 8 bits/channel to an output with <= 8
  bits/channel. Not just from float/half, but also from uint16, for
  example. (When outputting > 8 bits per channel, there are enough
  gradations that you tend not to see banding artifacts, so dithering
  is not necessary for 16 bit output, even if coming from a float data
  source.)

* Change the actual dither we use to blue noise. The old dither just
  used a hash to add uniformly distributed random numbers to each
  pixel value before quantization, completely uncorrelated from pixel
  to pixel. Blue noise is specially constructed to still have a
  uniform distribution of the output range, but it ensures that
  spatially, similar values are distributed as far away from each
  other as possible, rather than having similar values sometimes
  clumped together.  The result is a MUCH NICER appearance.

* Of course, this means the we needed to store a blue noise table in
  the library, and some access routines for it. We incorporate a
  public domain blue noise texture as a table.

* ImageBufAlgo::noise() and `oiiotool --noise` now take "blue" as a
  noise name to return blue noise. Also, make "white" the (preferred)
  synonym for "uniform" (to disambiguate the fact that both white and
  blue noise are uniformly distributed; the difference is that white
  is independently random for each pixel, whereas blue shapes the
  spectrum to favor high frequencies, making it better suited for
  dithering and sampling purposes.

* ImageBufAlgo::bluenoise_image() returns a reference to a stored
  periodic blue noise image.

* oiiotool -d would let you say "uint10" or "uint12" to indicate 10 or
  12 bit output (for formats that support it), but had no way to ask
  for less than 8 bit output (for example, TIFF supports that). So we
  add "uint6", "uint4", "uint2", "uint1" as recognized names for the
  `-d` option in those rare cases when you specifically want to
  produce a low bit depth file. And furthermore, if you ask for
  `--dither` when using lower bit depths, the dither amplitude is
  adjusted to be right sized for the bit depth you are using.

* Many format output modules that support 8 bit output honor the
  option to dither the output, but in the "built-in plugins" chapter
  of the docs, most did not list this option in the section that
  describes which special output options it knows. So now we've added
  this to the docs for all the output plugins that did support it.

Author: lgritz

src/doc/builtinplugins.rst

@@ -230,6 +230,11 @@ control aspects of the writing itself:
      - ptr
      - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for
        example by writing to memory rather than the file system.
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
 
 **Custom I/O Overrides**
 
@@ -689,6 +694,7 @@ ICO
 ICO is an image file format used for small images (usually icons) on
 Windows.  ICO files use the file extension :file:`.ico`.
 
+**Attributes**
 
 .. list-table::
    :widths: 30 10 65
@@ -704,6 +710,24 @@ Windows.  ICO files use the file extension :file:`.ico`.
      - int
      - if nonzero, will cause the ICO to be written out using PNG format.
 
+**Configuration settings for ICO output**
+
+When opening an ICO ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
+
 **Limitations**
 
 * ICO only supports UINT8 and UINT16 formats; all output images will
@@ -742,6 +766,24 @@ IFF files are used by Autodesk Maya and use the file extension :file:`.iff`.
      - int
      - the true bits per sample of the IFF file.
 
+**Configuration settings for IFF output**
+
+When opening an IFF ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
+
 
 
 |
@@ -769,7 +811,7 @@ also blessed by the Joint Photographic Experts Group that attempt to
 address some of these issues, such as JPEG-2000, but these do not have
 anywhere near the acceptance of the original JPEG/JFIF format.
 
-
+**Attributes**
 
 .. list-table::
    :widths: 30 10 65
@@ -820,8 +862,9 @@ control aspects of the writing itself:
      - Meaning
    * - ``oiio:dither``
      - int
-     - If nonzero and outputting UINT8 values in the file, will add a small
-       amount of random dither to combat the appearance of banding.
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
    * - ``oiio:ioproxy``
      - ptr
      - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for
@@ -868,6 +911,7 @@ JPEG-2000 is not yet widely used, so OpenImageIO's support of it is
 preliminary.  In particular, we are not yet very good at handling the
 metadata robustly.
 
+**Attributes**
 
 .. list-table::
    :widths: 30 10 65
@@ -881,6 +925,23 @@ metadata robustly.
      - specifies the JPEG-2000 stream format (``"none"`` or ``"jpc"``)
 
 
+**Configuration settings for JPEG-2000 output**
+
+When opening a JPEG-2000 ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
 
 
 |
@@ -1309,8 +1370,9 @@ control aspects of the writing itself:
        example by writing to a memory buffer.
    * - ``oiio:dither``
      - int
-     - If nonzero and outputting UINT8 values in the file, will add a small
-       amount of random dither to combat the appearance of banding
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
 
 **Custom I/O Overrides**
 
@@ -1361,6 +1423,8 @@ other than 1 or 3 channels, no tiles, no multi-image, no MIPmapping.
 It's not a smart choice unless you are sending your images back to the
 1980's via a time machine.
 
+**Attributes**
+
 .. list-table::
    :widths: 30 10 65
    :header-rows: 1
@@ -1378,6 +1442,23 @@ It's not a smart choice unless you are sending your images back to the
        ASCII.  The PNM writer honors this attribute in the ImageSpec to
        determine whether to write an ASCII or binary file.
 
+**Configuration settings for PNM output**
+
+When opening a PNM ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
 
 
 |
@@ -1571,6 +1652,8 @@ originating from Wavefront Advanced Visualizer and used primarily by
 software developed at Wavefront.  RLA files commonly use the file extension
 :file:`.rla`.
 
+**Attributes**
+
 .. list-table::
    :widths: 30 10 65
    :header-rows: 1
@@ -1649,6 +1732,23 @@ software developed at Wavefront.  RLA files commonly use the file extension
      - float
      - the gamma correction value (if specified).
 
+**Configuration settings for RLA output**
+
+When opening a RLA ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
 
 **Limitations**
 
@@ -1673,6 +1773,7 @@ The SGI format is sometimes used for legacy apps, but has little merit
 otherwise: no support for tiles, no MIPmaps, no multi-subimage, only 8- and
 16-bit integer pixels (no floating point), only 1-4 channels.
 
+**Attributes**
 
 .. list-table::
    :widths: 30 10 65
@@ -1688,6 +1789,23 @@ otherwise: no support for tiles, no MIPmaps, no multi-subimage, only 8- and
      - string
      - Image name.
 
+**Configuration settings for SGI output**
+
+When opening an SGI ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
 
 
 |
@@ -1737,6 +1855,7 @@ files use the file extension :file:`.tga`, or, much more rarely,
 :file:`.tpic`. The official Targa format specification may be found at:
 http://www.dca.fee.unicamp.br/~martino/disciplinas/ea978/tgaffs.pdf
 
+**Attributes**
 
 .. list-table::
    :widths: 30 10 65
@@ -1783,13 +1902,31 @@ http://www.dca.fee.unicamp.br/~martino/disciplinas/ea978/tgaffs.pdf
      - float
      - the gamma correction value (if specified).
 
-
 If the TGA file contains a thumbnail, its dimensions will be stored in the
 attributes ``"thumbnail_width"``, ``"thumbnail_height"``, and
 ``"thumbnail_nchannels"``, and the thumbnail pixels themselves will be
 retrievable via `ImageInput::get_thumbnail()` or `ImageBuf::thumbnail()` or
 `ImageCache::get_thumbnail()`.
 
+**Configuration settings for Targa output**
+
+When opening a Targa ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
+
+
 **Limitations**
 
 * The Targa reader reserves enough memory for the entire image. Therefore it
@@ -1950,6 +2087,11 @@ aspects of the writing itself:
      - int
      - Requests a rescaling to a specific bits per sample (such as writing
        12-bit TIFFs).
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
    * - ``tiff:write_exif``
      - int
      - If zero, will not write any Exif data to the TIFF file. (The default
@@ -2167,6 +2309,8 @@ Webp
 WebP is an image file format developed by Google that is intended to be an
 open standard for lossy-compressed images for use on the web.
 
+**Attributes**
+
 .. list-table::
    :widths: 30 10 65
    :header-rows: 1
@@ -2185,6 +2329,24 @@ open standard for lossy-compressed images for use on the web.
      - int
      - Deprecated synonym for ``oiio:LoopCount``.
 
+**Configuration settings for WebP output**
+
+When opening a WebP ImageOutput, the following special metadata tokens
+control aspects of the writing itself:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:dither``
+     - int
+     - If nonzero and outputting UINT8 values in the file from a source of
+       higher bit depth, will add a small amount of random dither to combat
+       the appearance of banding.
+
 **Limitations**
 
 * WebP only supports 3-channel (RGB) or 4-channel (RGBA) images and must

src/doc/figures/bluenoise.jpg

@@ -252,8 +252,8 @@ checker() -- make a checker pattern
 |
 
 
-noise() -- make a noise pattern
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Noise patterns
+^^^^^^^^^^^^^^
 
 .. doxygenfunction:: noise(string_view noisetype, float A = 0.0f, float B = 0.1f, bool mono = false, int seed = 0, ROI roi = {}, int nthreads = 0)
 ..
@@ -277,19 +277,21 @@ noise() -- make a noise pattern
   ..
 
   .. |noiseimg1| image:: figures/unifnoise1.jpg
+     :height: 1.25 in
+  .. |noiseimg2| image:: figures/bluenoise.jpg
+     :height: 1.25 in
+  .. |noiseimg3| image:: figures/tahoe-gauss.jpg
      :height: 1.5 in
-  .. |noiseimg2| image:: figures/tahoe-gauss.jpg
-     :height: 1.5 in
-  .. |noiseimg3| image:: figures/tahoe-pepper.jpg
+  .. |noiseimg4| image:: figures/tahoe-pepper.jpg
      :height: 1.5 in
 
   ..
 
-    +------------------------+------------------------+------------------------+
-    | |noiseimg1|            | |noiseimg2|            | |noiseimg3|            |
-    +------------------------+------------------------+------------------------+
-    | uniform noise          | gaussian noise added   | salt & pepper dropouts |
-    +------------------------+------------------------+------------------------+
+    +------------------------+------------------------+------------------------+------------------------+
+    | |noiseimg1|            | |noiseimg2|            | |noiseimg3|            | |noiseimg4|            |
+    +------------------------+------------------------+------------------------+------------------------+
+    | white noise            | blue noise             | gaussian noise added   | salt & pepper dropouts |
+    +------------------------+------------------------+------------------------+------------------------+
 
   Result-as-parameter version:
 
@@ -298,6 +300,15 @@ noise() -- make a noise pattern
 |
 
 
+.. doxygenfunction:: bluenoise_image()
+..
+
+  Example::
+
+    const ImageBuf& A = ImageBufAlgo::bluenoise_image();
+
+
+
 Drawing shapes: points, lines, boxes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

src/doc/imagebufalgo.rst

@@ -30,8 +30,9 @@ ${OIIOTOOL} --pattern fill:top=0.1,0.1,0.1:bottom=0,0,0.75 320x240 3 --tocolorsp
 ${OIIOTOOL} --pattern fill:left=0.1,0.1,0.1:right=0,0.75,0 320x240 3 --tocolorspace sRGB -o gradienth.jpg
 ${OIIOTOOL} --pattern fill:topleft=.1,.1,.1:topright=1,0,0:bottomleft=0,1,0:bottomright=0,0,1 320x240 3 --tocolorspace sRGB -o gradient4.jpg
 ${OIIOTOOL} --pattern checker:width=16:height=16 256x256 3 --tocolorspace sRGB -o checker.jpg
-${OIIOTOOL} --pattern noise:type=uniform:min=0:max=1:mono=1 256x256 3 --tocolorspace sRGB -o unifnoise1.jpg
-${OIIOTOOL} --pattern noise:type=uniform:min=0:max=1 256x256 3 --tocolorspace sRGB -o unifnoise3.jpg
+${OIIOTOOL} --pattern noise:type=white:min=0:max=1:mono=1 256x256 3 --tocolorspace sRGB -o unifnoise1.jpg
+${OIIOTOOL} --pattern noise:type=white:min=0:max=1 256x256 3 --tocolorspace sRGB -o unifnoise3.jpg
+${OIIOTOOL} --pattern noise:type=blue:min=0:max=1:mono=1 256x256 3 --tocolorspace sRGB -o bluenoise.jpg
 ${OIIOTOOL} --pattern noise:type=gaussian:mean=0.5:stddev=0.2 256x256 3 --tocolorspace sRGB -o gaussnoise.jpg
 ${OIIOTOOL} tahoe-small.jpg --noise:type=gaussian:mean=0:stddev=0.1 -o tahoe-gauss.jpg
 ${OIIOTOOL} tahoe-small.jpg --noise:type=salt:portion=0.01:value=0:mono=1 -o tahoe-pepper.jpg