iv: tolerate partially-written EXR files

When iv opens an image file that was only partially written -- for
example, an EXR that a renderer crashed on or was killed before it
finished writing the pixel data -- the read fails and iv refuses to
display anything at all.

Now, if the straightforward read fails, iv reopens the file with the
new "openexr:missing_data_ok" configuration hint, which asks the
OpenEXR reader to fill unreadable scanlines or tiles with black instead
of failing the read (building on the existing missingcolor machinery).
Other readers simply ignore the hint. In the partial case, the status
bar displays a note explaining that the file is only partially
readable.

For images that were read through the ImageCache (where pixel data
isn't touched until display time), a cheap probe of the last scanline
or tile checks that the pixel data is intact, and falls back to the
hinted re-read if it isn't.

The hint is documented alongside oiio:missingcolor. As a side effect,
this also fixes an infinite recursion (stack overflow) in the chunk
cache path that could already be triggered by the existing
oiio:missingcolor feature when a multi-scanline chunk failed to decode.

Fixes #4713

Assisted-by: Claude Code:glm-5.3-flash
Signed-off-by: linsen <251731047+linsen458-spec@users.noreply.github.com>

Author: linsen458-spec

src/doc/builtinplugins.md

@@ -1718,6 +1718,14 @@ attributes are supported:
        tile/scanline read failure to be an error. This can be helpful when
        intentionally reading partially-written or incomplete files (such as
        an in-progress render).
+   * - ``openexr:missing_data_ok``
+     - int
+     - If nonzero, missing tiles or scanlines are filled with black rather
+       than considering a tile/scanline read failure to be an error. This is
+       equivalent to ``oiio:missingcolor`` with a black fill color, for the
+       common case of reading a partially-written file (such as one from a
+       renderer that was interrupted) where no particular fill color is
+       needed. Other readers ignore this hint.
 ```
 
 **Configuration settings for OpenEXR output**

src/iv/imageviewer.cpp

@@ -1164,6 +1164,11 @@ ImageViewer::updateStatusBar()
     message = Strutil::fmt::format("({}/{}) : ", m_current_image + 1,
                                    (int)m_images.size());
     message += cur()->shortinfo();
+    if (cur()->partially_loaded()) {
+        message += "  [partially readable file: ";
+        message += cur()->partial_error();
+        message += "]";
+    }
     statusImgInfo->setText(message.c_str());
 
     message.clear();

src/iv/imageviewer.h

@@ -104,6 +104,16 @@ class IvImage final : public ImageBuf {
     ///
     bool image_valid() const { return m_image_valid; }
 
+    /// True if the last read only partially succeeded, i.e. the image
+    /// specification was readable but some of the pixel data could not be
+    /// read (for example, a file that was only partially written before a
+    /// renderer crashed).
+    bool partially_loaded() const { return m_partially_loaded; }
+
+    /// If the last read was only partial (see partially_loaded()), a
+    /// message describing the problem.
+    const std::string& partial_error() const { return m_partial_error; }
+
     /// Copies data from the read buffer to the secondary buffer, selecting the
     /// given channel:
     ///  -2 = luminance
@@ -139,6 +149,10 @@ class IvImage final : public ImageBuf {
     mutable std::string m_longinfo;
     bool m_image_valid;    ///< Image is valid and pixels can be read.
     bool m_auto_subimage;  ///< Automatically use subimages when zooming-in/out.
+    bool m_partially_loaded = false;   ///< Only some pixel data was readable.
+    std::string m_partial_error;       ///< Description of what was unreadable.
+    ImageSpec m_input_config;          ///< Copy of the input configuration spec
+    bool m_have_input_config = false;  ///< Was an input configuration given?
 };
 
 

src/iv/ivimage.cpp

@@ -6,6 +6,7 @@
 #include <iostream>
 
 #include "imageviewer.h"
+#include "ivutils.h"
 #include <OpenImageIO/imagecache.h>
 #include <OpenImageIO/strutil.h>
 
@@ -20,6 +21,10 @@ IvImage::IvImage(const std::string& filename, const ImageSpec* input_config)
     , m_image_valid(false)
     , m_auto_subimage(false)
 {
+    if (input_config) {
+        m_input_config      = *input_config;
+        m_have_input_config = true;
+    }
 }
 
 
@@ -77,6 +82,46 @@ IvImage::read_iv(int subimage, int miplevel, bool force, TypeDesc format,
                                        progress_callback,
                                        progress_callback_data);
 
+    m_partially_loaded = false;
+    m_partial_error.clear();
+    if (m_image_valid && storage() == ImageBuf::IMAGECACHE) {
+        // The image is backed by the ImageCache, which means that the
+        // pixel data has not been touched yet and read failures will only
+        // turn up later, awkwardly, as pixels are fetched for display.
+        // For a file that was only partially written (for example, an EXR
+        // that a renderer didn't finish), check now whether the pixel
+        // data is really all readable, and if not, fall through to the
+        // tolerant re-read below.
+        ImageSpec* config = m_have_input_config ? &m_input_config : nullptr;
+        m_image_valid = image_data_readable(name(), config, subimage, miplevel);
+    }
+    if (!m_image_valid) {
+        // The straightforward read failed. This can happen for a file that
+        // was only partially written -- for example, an EXR file from a
+        // renderer that crashed or was killed before it finished writing
+        // all of the pixel data. Rather than showing nothing at all, reopen
+        // the file with the "openexr:missing_data_ok" hint, which asks the
+        // OpenEXR reader to fill the unreadable scanlines or tiles with
+        // black instead of failing the read. Other readers ignore the hint,
+        // so the re-read simply fails the same way for them.
+        ImageSpec config;
+        if (m_have_input_config)
+            config = m_input_config;
+        config.attribute("openexr:missing_data_ok", 1);
+        reset(name(), 0, 0, {}, &config);
+        m_image_valid = ImageBuf::read(subimage, miplevel, force, format,
+                                       progress_callback,
+                                       progress_callback_data);
+        if (m_image_valid) {
+            // The read succeeded where the straightforward one failed, so
+            // part of the pixel data must have been unreadable -- remember
+            // that so the status bar can let the user know.
+            m_partially_loaded = true;
+            m_partial_error    = "partially readable file, showing the "
+                                 "readable portion";
+        }
+    }
+
     if (m_image_valid && secondary_data && spec().format == TypeDesc::UINT8) {
         m_corrected_image.reset(ImageSpec(spec().width, spec().height,
                                           std::min(spec().nchannels, 4),
@@ -388,8 +433,10 @@ IvImage::invalidate()
 {
     ustring filename(name());
     reset(filename.string());
-    m_thumbnail_valid = false;
-    m_image_valid     = false;
+    m_thumbnail_valid  = false;
+    m_image_valid      = false;
+    m_partially_loaded = false;
+    m_partial_error.clear();
     if (imagecache())
         imagecache()->invalidate(filename);
 }

src/iv/ivutils.h

@@ -5,6 +5,13 @@
 #ifndef OPENIMAGEIO_IV_UTILS_H
 #define OPENIMAGEIO_IV_UTILS_H
 
+#include <algorithm>
+#include <cstring>
+#include <string>
+#include <vector>
+
+#include <OpenImageIO/imagebuf.h>
+#include <OpenImageIO/imageio.h>
 #include <OpenImageIO/oiioversion.h>
 
 OIIO_NAMESPACE_BEGIN
@@ -33,6 +40,56 @@ floor2f(float f)
     return powf(2.0f, floorf(logval));
 }
 
+
+/// Probe whether all of the pixel data of the image named `filename` is
+/// readable, without reading the whole image: attempt to read only the
+/// last scanline (for scanline files) or the last tile (for tiled files),
+/// which is the most likely region to be missing from a file that was
+/// only partially written. This is cheap enough to use as a check on
+/// files that were read through an ImageCache, where the pixel data is
+/// not touched until it is needed for display, at which point read
+/// failures are much less gracefully handled.
+///
+/// Returns true if the last scanline/tile could be read (and therefore it
+/// is likely that the entire pixel data block is intact), false if it
+/// could not (meaning that the file is probably truncated or otherwise
+/// partially written).
+inline bool
+image_data_readable(string_view filename, const ImageSpec* config, int subimage,
+                    int miplevel)
+{
+    auto in = ImageInput::open(filename, config);
+    if (!in)
+        return false;
+    if (!in->seek_subimage(subimage, miplevel)) {
+        in->close();
+        return false;
+    }
+    ImageSpec spec = in->spec(subimage, miplevel);
+    bool ok        = false;
+    if (spec.tile_width > 0) {
+        // Try to read the bottom-most, right-most tile.
+        int tx = spec.x
+                 + ((spec.width - 1) / spec.tile_width) * spec.tile_width;
+        int ty = spec.y
+                 + ((spec.height - 1) / spec.tile_height) * spec.tile_height;
+        int tz = spec.z
+                 + ((std::max(spec.depth - 1, 0))
+                    / std::max(spec.tile_depth, 1))
+                       * std::max(spec.tile_depth, 1);
+        std::vector<char> buf(spec.tile_bytes());
+        ok = in->read_tile(tx, ty, tz, spec.format, buf.data());
+    } else {
+        // Try to read the last scanline.
+        int y = spec.y + spec.height - 1;
+        std::vector<char> buf(spec.scanline_bytes());
+        ok = in->read_scanlines(subimage, miplevel, y, y + 1, spec.z, 0,
+                                spec.nchannels, TypeDesc::UNKNOWN, buf.data());
+    }
+    in->close();
+    return ok;
+}
+
 OIIO_NAMESPACE_END
 
 #endif  // OPENIMAGEIO_IV_UTILS_H

src/openexr.imageio/exr_pvt.h

@@ -265,6 +265,11 @@ class OpenEXRInput final : public ImageInput {
     bool read_native_scanlines(int subimage, int miplevel, int ybegin, int yend,
                                int z, int chbegin, int chend,
                                void* data) override;
+    // Internal version with a flag letting the per-scanline retry bypass the
+    // chunk cache (see read_native_scanlines_individually).
+    bool read_native_scanlines(int subimage, int miplevel, int ybegin, int yend,
+                               int z, int chbegin, int chend, void* data,
+                               bool bypass_chunk_cache);
     bool read_native_tile(int subimage, int miplevel, int x, int y, int z,
                           void* data) override;
     bool read_native_tiles(int subimage, int miplevel, int xbegin, int xend,
@@ -347,6 +352,7 @@ class OpenEXRInput final : public ImageInput {
     int m_nsubimages;                   ///< How many subimages are there?
     int m_miplevel;                     ///< What MIP level are we looking at?
     std::vector<float> m_missingcolor;  ///< Color for missing tile/scanline
+    bool m_missing_data_ok = false;     ///< Tolerate missing tile/scanline
     std::string m_filename;             // filename, if known
     ExrChunkCache m_chunkcache;
 
@@ -365,6 +371,7 @@ class OpenEXRInput final : public ImageInput {
         m_io                       = nullptr;
         m_local_io.reset();
         m_missingcolor.clear();
+        m_missing_data_ok = false;
         m_filename.clear();
     }
 
@@ -377,7 +384,8 @@ class OpenEXRInput final : public ImageInput {
     bool read_native_scanlines_individually(int subimage, int miplevel,
                                             int ybegin, int yend, int z,
                                             int chbegin, int chend, void* data,
-                                            stride_t ystride);
+                                            stride_t ystride,
+                                            bool bypass_chunk_cache = false);
     bool read_native_tiles_individually(int subimage, int miplevel, int xbegin,
                                         int xend, int ybegin, int yend,
                                         int zbegin, int zend, int chbegin,

src/openexr.imageio/exrinput.cpp

@@ -275,6 +275,12 @@ OpenEXRInput::open(const std::string& name, ImageSpec& newspec,
         if (mc.size())
             m_missingcolor = Strutil::extract_from_list_string<float>(mc);
     }
+    // "openexr:missing_data_ok" asks to tolerate missing scanlines or tiles
+    // -- for example, in a partially written file from a renderer that was
+    // interrupted -- by filling the unreadable regions with black instead of
+    // failing the read. Other readers will simply ignore this hint.
+    if (const ParamValue* mdo = config.find_attribute("openexr:missing_data_ok"))
+        m_missing_data_ok = mdo->get_int() != 0;
 
     // Before engaging further with OpenEXR, make sure it is using the right
     // number of threads.
@@ -1253,7 +1259,7 @@ OpenEXRInput::read_native_scanline(int subimage, int miplevel, int y, int z,
                                    void* data)
 {
     return read_native_scanlines(subimage, miplevel, y, y + 1, z, 0,
-                                 m_spec.nchannels, data);
+                                 m_spec.nchannels, data, false);
 }
 
 
@@ -1263,7 +1269,7 @@ OpenEXRInput::read_native_scanlines(int subimage, int miplevel, int ybegin,
                                     int yend, int z, void* data)
 {
     return read_native_scanlines(subimage, miplevel, ybegin, yend, z, 0,
-                                 m_spec.nchannels, data);
+                                 m_spec.nchannels, data, false);
 }
 
 
@@ -1280,11 +1286,15 @@ OpenEXRInput::read_cached_chunk(int subimage, int miplevel, int ybegin,
                            ybegin, yend, scanlinebytes, data))
         return true;
 
-    // Cache miss. Decode the whole chunk. This recursive call asks for
-    // exactly one full chunk, so it won't come back here.
+    // Cache miss. Decode the whole chunk. The bypass_chunk_cache flag of
+    // this recursive call asks for exactly one full chunk, so it won't come
+    // back here -- this matters when the decode fails and tolerance is on:
+    // without the bypass, the per-scanline retry would re-enter the chunk
+    // cache and recurse forever.
     default_init_vector<uint8_t> chunk(scanlinebytes * size_t(cend - cbegin));
     if (!read_native_scanlines(subimage, miplevel, cbegin, cend, 0, chbegin,
-                               chend, chunk.data()))
+                               chend, chunk.data(),
+                               /*bypass_chunk_cache=*/true))
         return false;
     memcpy(data, chunk.data() + scanlinebytes * size_t(ybegin - cbegin),
            scanlinebytes * size_t(yend - ybegin));
@@ -1298,6 +1308,15 @@ bool
 OpenEXRInput::read_native_scanlines(int subimage, int miplevel, int ybegin,
                                     int yend, int z, int chbegin, int chend,
                                     void* data)
+{
+    return read_native_scanlines(subimage, miplevel, ybegin, yend, z, chbegin,
+                                 chend, data, /*bypass_chunk_cache=*/false);
+}
+
+bool
+OpenEXRInput::read_native_scanlines(int subimage, int miplevel, int ybegin,
+                                    int yend, int z, int chbegin, int chend,
+                                    void* data, bool bypass_chunk_cache)
 {
     lock_guard lock(*this);
     if (!seek_subimage(subimage, miplevel))
@@ -1341,7 +1360,7 @@ OpenEXRInput::read_native_scanlines(int subimage, int miplevel, int ybegin,
         default_init_vector<uint8_t> scratch(fullscanbytes
                                              * size_t(yend - ybegin));
         if (!read_native_scanlines(subimage, miplevel, ybegin, yend, z, 0,
-                                   m_spec.nchannels, scratch.data()))
+                                   m_spec.nchannels, scratch.data(), false))
             return false;
         size_t choff = m_spec.pixel_bytes(0, chbegin, true);
         for (int y = ybegin; y < yend; ++y) {
@@ -1364,7 +1383,7 @@ OpenEXRInput::read_native_scanlines(int subimage, int miplevel, int ybegin,
     // swath) at a time will ask for the rest of that chunk next. (The
     // library has a stash of its own, but it drops it every time we set the
     // frame buffer, which we must do on every read.)
-    if (part.scansperchunk > 1 && !part.luminance_chroma
+    if (part.scansperchunk > 1 && !part.luminance_chroma && !bypass_chunk_cache
         && ybegin >= m_spec.y) {
         int ychunkstart = m_spec.y
                           + round_down_to_multiple(ybegin - m_spec.y,
@@ -1441,7 +1460,7 @@ OpenEXRInput::read_native_scanlines(int subimage, int miplevel, int ybegin,
         }
     } catch (const std::exception& e) {
         std::string err = e.what();
-        if (m_missingcolor.size()) {
+        if (m_missingcolor.size() || m_missing_data_ok) {
             // User said not to fail for bad or missing scanlines. If we
             // failed reading a single scanline, use the fill pattern. If we
             // failed reading many scanlines, we don't know which ones, so go
@@ -1456,10 +1475,10 @@ OpenEXRInput::read_native_scanlines(int subimage, int miplevel, int ybegin,
             } else {
                 // Read of many tiles -- don't know which failed, so try
                 // again to read them all individually.
-                return read_native_scanlines_individually(subimage, miplevel,
-                                                          ybegin, yend, z,
-                                                          chbegin, chend, data,
-                                                          scanlinebytes);
+                return read_native_scanlines_individually(
+                    subimage, miplevel, ybegin, yend, z, chbegin, chend, data,
+                    scanlinebytes,
+                    /*bypass_chunk_cache=*/true);
             }
         } else {
             errorfmt("Failed OpenEXR read: {}", err);
@@ -1593,7 +1612,7 @@ OpenEXRInput::read_native_tiles(int subimage, int miplevel, int xbegin,
         }
     } catch (const std::exception& e) {
         std::string err = e.what();
-        if (m_missingcolor.size()) {
+        if (m_missingcolor.size() || m_missing_data_ok) {
             // User said not to fail for bad or missing tiles. If we failed
             // reading a single tile, use the fill pattern. If we failed
             // reading many tiles, we don't know which ones, so go back and
@@ -1631,15 +1650,16 @@ bool
 OpenEXRInput::read_native_scanlines_individually(int subimage, int miplevel,
                                                  int ybegin, int yend, int z,
                                                  int chbegin, int chend,
-                                                 void* data, stride_t ystride)
+                                                 void* data, stride_t ystride,
+                                                 bool bypass_chunk_cache)
 {
     // Note: this is only called by read_native_scanlines, which still holds
     // the mutex, so it's safe to directly access m_spec.
     bool ok = true;
     for (int y = ybegin; y < yend; ++y) {
         char* d = (char*)data + (y - ybegin) * ystride;
         ok &= read_native_scanlines(subimage, miplevel, y, y + 1, z, chbegin,
-                                    chend, d);
+                                    chend, d, bypass_chunk_cache);
     }
     return ok;
 }
@@ -1679,7 +1699,13 @@ OpenEXRInput::fill_missing(int xbegin, int xend, int ybegin, int yend,
                            void* data, stride_t xstride, stride_t ystride)
 {
     std::vector<float> missingcolor = m_missingcolor;
-    missingcolor.resize(chend, m_missingcolor.back());
+    if (missingcolor.empty()) {
+        // No explicit missing color (the "openexr:missing_data_ok" case):
+        // fill the unreadable regions with black.
+        missingcolor.resize(chend, 0.0f);
+    } else {
+        missingcolor.resize(chend, m_missingcolor.back());
+    }
     bool stripe = missingcolor[0] < 0.0f;
     if (stripe)
         missingcolor[0] = fabsf(missingcolor[0]);