leaf by leaf, as each one is ready (after Tolkien)

from the bookshelves ·

Dynamically Loading EXR and HDR Files During QT's Paint

How I implemented dynamically loading EXR and HDR files for the asset thumbnails in the Universal Asset Browser.

Context

For rendering thousands of items on the screen, your only choice in QT is to use delegates (QStyledItemDelegate); widgets are too memory-costly to keep thousands at once alive. Delegates, however, are drawn during paint, which (in short) means that every time the user interacts with the view, delegates are re-rendered.

The problem is this: not every HDR or EXR file (or other heavy file types, but implemented now is HDR and EXR) is guaranteed to come with a pre-rendered preview. As such, they have to be decoded, tone-mapped, gamma-corrected, and resampled on-the-fly. Without anything external to painting the delegates, this process is repeated for each delegate, up to something like 60 times every second, which makes the application so slow as to be unusable.

As such, I implemented an asynchronous HDR/EXR thumbnail loading system.

Implementation

Details about how this system is architected and works in the context of the Universal Asset Browser.

A unified base class architecture with specialized loaders:

Base Class: ThumbnailLoaderBase

Abstract base class (QThread) providing:

Uses QMutexLocker for thread-safe queue access. The run() loop processes items, calls _process_item(), and emits batch/all-complete signals.

Subclass 1: NetworkThumbnailLoader

Extends ThumbnailLoaderBase for network thumbnail downloads:

Subclass 2: LocalImageLoader

Extends ThumbnailLoaderBase for local file processing:

Layers

The layers of this system ()

Delegate Layer (AssetDelegate)

Loading State Tracking:

# short version
if cached:
    return cached

if suffix in (".hdr", ".exr"):
    if asset_id not in _loading_assets and _image_loader is not None:
        _loading_assets.add(asset_id)
        _image_loader.add_item((asset_id, path, max_size))
        if not _image_loader.isRunning():
            _image_loader.start()
        return _get_loading_placeholder()
python

Handler Methods:

View Layer (BrowserView)

Initialization:

Update Handler:

Data Flow

  1. User scrolls → paint() called for visible items
  2. _get_thumbnail() checks cache → not found
  3. For HDR/EXR: adds to _loading_assets, queues load request, returns placeholder
  4. Background thread: LocalImageLoader._process_item() calls load_hdri_thumbnail()
  5. On completion: emits thumbnail_loaded(asset_id, pixmap)
  6. Main thread: _on_image_thumbnail_loaded() updates cache, emits thumbnail_ready(asset_id)
  7. View: _on_thumbnail_ready() finds index, calls update(index) → repaint with actual thumbnail

Technical Challenges and Solutions

A brief discussion of challenges and problems I faced, and how I handled them.

1. Challenge: Thread Safety

2. Challenge: Queue Management

3. Problem: HDR files appeared darker in Houdini than in the standalone desktop app

I think either because of a different imageio version or color space management, but I'm not sure about this one. Needs more research.

Solution: Adaptive exposure based on median luminance:

# actual implementation
luminance = 0.2126 * hdr_data[:, :, 0] + 0.7152 * hdr_data[:, :, 1] + 0.0722 * hdr_data[:, :, 2]
median_lum = np.median(luminance[luminance > 0])
if median_lum > 0:
    target_lum = 0.18  # Middle gray
    exposure = target_lum / median_lum
    exposure = max(0.1, min(10.0, exposure))  # Clamp to reasonable range
python

This normalizes brightness across different HDR files and environments, though minor differences persist. Will come back to this.

4. Problem: Caching thousands of assets

I've implemented a simple LRU cache capped at 200, which is pretty arbitrary, but was chosen for:

QPixmap Memory Footprint:

And because given physical size constraints of the browser, it should be very rare that 200 assets is not at least several screen-fulls.

Side note: functools has a built-in LRU cache in functools.lru_cache. Lesson learned to check if there's a built-in solution for data structures in the future. I'm sure their implementation is way more robust than mine.

Questions

  1. Does Houdini apply anything to images with tonemapping, color spaces, etc. that would cause the dynamically rendered HDR/EXR's to look different? I'm confused because this process is very similar to my first implemenation that used widgets instead of delegates, and the coloration between the embedded Houdini version and the standalone desktop version was consistent.

  2. Is this how Nuke, Unreal, etc. render EXR thumbnail images? Is there a better way to accomplish this?

  3. Architecturally, does it make a meaningful difference to have implemented an interface for thumbnail loading, since there are only ever two ways to get a thumbnail (from disk or from network)?

Implementation Reference

Quick reference for my implementation and some places I read about these concepts.

Universal Asset Browser

  1. Delegates
  2. Thumbnail loader interface, local implementation, and HDR/EXR conversion
  3. Network implementation and usage

PySide6 Documentation

  1. QStyledItemDelegate
  2. What is a mutex? (this is my first time touching threading)
  3. LRU Cache Concept (this is also my first time implementing an LRU cache)
  4. LRU Cache Implementation