heif: Handle unassociated alpha (#3146)

Turns out that heif files that contain alpha can have either
associated or unassociated alpha. We had been assuming
associated. With LibHeif 1.12 and beyond, you can ask, so now we
do. Thanks Frédéric Devernay for pointing this out.

Similar to other formats that optionally have unassociated alpha:

* The default behavior is to associate/premultiply automatically when
  reading, but set metadata "heif:UnassociatedAlpha" to indicate that
  it was unassociated in the file.

* Open configuration hint "oiio:UnassociatedAlpha", when nonzero,
  means to please keep the data unassociated and not premultiply. In
  that case, metadata "oiio:UnassociatedAlpha" will be set in the
  ImageSpec to indicate that the returned image (not just the file)
  consists of unassociated values.

I did a couple other minor docs touch-ups while I was at it.

Fixes #3129

Author: lgritz

INSTALL.md

@@ -54,7 +54,7 @@ NEW or CHANGED MINIMUM dependencies since the last major release are **bold**.
      * giflib >= 4.1 (tested through 5.2; 5.0+ is strongly recommended for
        stability and thread safety)
  * If you want support for HEIF/HEIC or AVIF images:
-     * libheif >= 1.3 (1.7 required for AVIF support, tested through 1.11)
+     * libheif >= 1.3 (1.7 required for AVIF support, tested through 1.12)
      * libheif must be built with an AV1 encoder/decoder for AVIF support.
      * Avoid libheif 1.10 on Mac, it is very broken. Libheif 1.11 is fine.
  * If you want support for DDS files:

src/doc/builtinplugins.rst

@@ -639,12 +639,31 @@ currently supported for reading, but not yet writing. All pixel data is
 uint8, though we hope to add support for HDR (more than 8 bits) in the
 future.
 
+**Configuration settings for HEIF input**
+
+When opening an HEIF ImageInput with a *configuration* (see
+Section :ref:`sec-inputwithconfig`), the following special configuration
+attributes are supported:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Input Configuration Attribute
+     - Type
+     - Meaning
+   * - ``oiio:UnassociatedAlpha``
+     - int
+     - If nonzero, and the file contains unassociated alpha, this will
+       cause the reader to leave alpha unassociated (versus the default of
+       premultiplying color channels by alpha if the alpha channel is
+       unassociated).
+
 **Configuration settings for HEIF output**
 
 When opening an HEIF ImageOutput, the following special metadata tokens
 control aspects of the writing itself:
 
-
 .. list-table::
    :widths: 30 10 65
    :header-rows: 1
@@ -1896,7 +1915,8 @@ options are supported:
      - Meaning
    * - ``oiio:UnassociatedAlpha``
      - int
-     - If nonzero, will leave alpha unassociated (versus the default of
+     - If nonzero, and the file contains unassociated alpha, this will
+       cause the reader to leave alpha unassociated (versus the default of
        premultiplying color channels by alpha if the alpha channel is
        unassociated).
    * - ``oiio:RawColor``
@@ -2128,10 +2148,12 @@ aware of:
      - The actual bits per sample in the file (may differ from `ImageSpec::format`).
    * - ``oiio:UnassociatedAlpha``
      - int
-     - Nonzero if the alpha channel contained "unassociated" alpha.
-
-
-
+     - Nonzero if the data returned by OIIO will have "unassociated" alpha.
+   * - ``tiff:UnassociatedAlpha``
+     - int
+     - Nonzero if the data in the file had "unassociated" alpha (even if using
+       the usual convention of returning associated alpha from the read
+       methods).
 
 
 

src/heif.imageio/heifinput.cpp

@@ -39,12 +39,17 @@ class HeifInput final : public ImageInput {
     virtual bool seek_subimage(int subimage, int miplevel) override;
     virtual bool read_native_scanline(int subimage, int miplevel, int y, int z,
                                       void* data) override;
+    virtual bool read_scanline(int y, int z, TypeDesc format, void* data,
+                               stride_t xstride) override;
 
 private:
     std::string m_filename;
-    int m_subimage      = -1;
-    int m_num_subimages = 0;
-    int m_has_alpha     = false;
+    int m_subimage                 = -1;
+    int m_num_subimages            = 0;
+    int m_has_alpha                = false;
+    bool m_associated_alpha        = true;
+    bool m_keep_unassociated_alpha = false;
+    bool m_do_associate            = false;
     std::unique_ptr<heif::Context> m_ctx;
     heif_item_id m_primary_id;             // id of primary image
     std::vector<heif_item_id> m_item_ids;  // ids of all other images
@@ -108,7 +113,7 @@ HeifInput::open(const std::string& name, ImageSpec& newspec)
 
 bool
 HeifInput::open(const std::string& name, ImageSpec& newspec,
-                const ImageSpec& /*config*/)
+                const ImageSpec& config)
 {
     m_filename = name;
     m_subimage = -1;
@@ -117,6 +122,9 @@ HeifInput::open(const std::string& name, ImageSpec& newspec,
     m_himage  = heif::Image();
     m_ihandle = heif::ImageHandle();
 
+    m_keep_unassociated_alpha
+        = (config.get_int_attribute("oiio:UnassociatedAlpha") != 0);
+
     try {
         m_ctx->read_from_file(name);
         // FIXME: should someday be read_from_reader to give full flexibility
@@ -155,8 +163,11 @@ HeifInput::close()
     m_himage  = heif::Image();
     m_ihandle = heif::ImageHandle();
     m_ctx.reset();
-    m_subimage      = -1;
-    m_num_subimages = 0;
+    m_subimage                = -1;
+    m_num_subimages           = 0;
+    m_associated_alpha        = true;
+    m_keep_unassociated_alpha = false;
+    m_do_associate            = false;
     return true;
 }
 
@@ -200,6 +211,27 @@ HeifInput::seek_subimage(int subimage, int miplevel)
 
     m_spec.attribute("oiio:ColorSpace", "sRGB");
 
+#if LIBHEIF_HAVE_VERSION(1, 12, 0)
+    // Libheif >= 1.12 added API call to find out if the image is associated
+    // alpha (i.e. colors are premultiplied).
+    m_associated_alpha = m_himage.is_premultiplied_alpha();
+    m_do_associate     = (!m_associated_alpha && m_spec.alpha_channel >= 0
+                      && !m_keep_unassociated_alpha);
+    if (!m_associated_alpha && m_spec.nchannels >= 4) {
+        // Indicate that file stored unassociated alpha data
+        m_spec.attribute("heif:UnassociatedAlpha", 1);
+        // If we don't have 4 chans, we need not consider
+        m_keep_unassociated_alpha &= (m_spec.nchannels >= 4);
+        if (m_keep_unassociated_alpha) {
+            // Indicate that we are returning unassociated data if the file
+            // had associated and we were asked to keep it that way.
+            m_spec.attribute("oiio:UnassociatedAlpha", 1);
+        }
+    }
+#else
+    m_associated_alpha = true;  // assume/hope
+#endif
+
     auto meta_ids = m_ihandle.get_list_of_metadata_block_IDs();
     // std::cout << "nmeta? " << meta_ids.size() << "\n";
     for (auto m : meta_ids) {
@@ -270,4 +302,29 @@ HeifInput::read_native_scanline(int subimage, int miplevel, int y, int /*z*/,
 }
 
 
+
+bool
+HeifInput::read_scanline(int y, int z, TypeDesc format, void* data,
+                         stride_t xstride)
+{
+    bool ok = ImageInput::read_scanline(y, z, format, data, xstride);
+    if (ok && m_do_associate) {
+        // If alpha is unassociated and we aren't requested to keep it that
+        // way, multiply the colors by alpha per the usual OIIO conventions
+        // to deliver associated color & alpha.  Any auto-premultiplication
+        // by alpha should happen after we've already done data format
+        // conversions. That's why we do it here, rather than in
+        // read_native_blah.
+        {
+            lock_guard lock(*this);
+            if (format == TypeUnknown)  // unknown -> retrieve native type
+                format = m_spec.format;
+        }
+        OIIO::premult(m_spec.nchannels, m_spec.width, 1, 1, 0 /*chbegin*/,
+                      m_spec.nchannels /*chend*/, format, data, xstride,
+                      AutoStride, AutoStride, m_spec.alpha_channel);
+    }
+    return ok;
+}
+
 OIIO_PLUGIN_NAMESPACE_END