Dear ImGui port of Image Viewer (imiv) with Vulkan/Metal/OpenGL backends for Windowns/Linux/MacOS

[ssh4net]

Description

This PR adds imiv to OpenImageIO as a full application, with its own build integration, documentation, and test coverage.
The goal here is to upstream the whole app in a usable state rather than split it into a long series of smaller PRs.

What is included:

• the new src/imiv/ application and CMake integration
• renderer backends for:
  • Vulkan
  • OpenGL
  • Metal
• runtime backend selection, probing, and preferences UI
• OCIO preview support across the supported backends
• Dear ImGui Test Engine integration and Python-based GUI regression tooling
• backend verification tools for macOS, Windows, and Linux/WSL
• multi-image workflows:
  • startup multi-open
  • drag and drop
  • Open Folder...
  • docked Image List
  • multi-view image windows
• per-view preview state:
  • exposure
  • gamma
  • shift
  • interpolation
  • channel/display mode
  • OCIO display/view/image color space
• GUI-driven CPU export paths:
  • Save As...
  • Save Selection As...
  • Export As...
  • Export Selection As...
• embedded runtime assets for:
  • DroidSans.ttf
  • DroidSansMono.ttf
  • static Vulkan upload/preview SPIR-V shaders
• user, developer, and test documentation for imiv

A few implementation notes that are probably useful to reviewers:

• Vulkan remains the reference backend for renderer-side behavior.
• OpenGL and Metal follow the same viewer semantics using native backend paths.
• Static Vulkan shaders are embedded at build time, but OCIO shader generation remains runtime-driven.
• Recent work also hardened large-image upload and backend switching behavior, especially around Vulkan resource lifetime and cross-backend verification.

This is meant to be the first upstreamable version of imiv, not the last word on its architecture. There is still room for follow-up work, especially around larger-image tiling/proxy paths and longer-term refinement, but the app is now in a shape where it can be reviewed and used as part of the tree.

Warning: This project heavily used Codex GPT5.4 in Extra High, but the Vulkan and OpenGL integration of the image viewer itself is based on my personal projects and prior experience in similar tools.

In a project, working time code multiply times was passed a code review using an alternative LLM like Opus 4.6 to avoid single model bias. The issues found at that time were fixed.

I have not polished the GUI layout, and some proper use of ImGui Table/Forms is still needed to make the GUI better respond to layouts.

Tests

This PR adds a dedicated imiv regression suite built around Dear ImGui Test Engine, plus backend-level verification tools.

Coverage includes focused GUI regressions for:

• navigation and UX actions
• selection and area probe
• RGB input handling
• sampling / interpolation
• drag and drop
• Open Folder...
• multi-view and Image List
• backend preferences
• OCIO fallback / config source / live update / live display
• export and selection export paths
• large-image switching

It also includes shared backend verifier coverage for:

• smoke
• rgb
• ux
• sampling
• ocio_missing
• ocio_config_source
• ocio_live
• ocio_live_display

Validation was done on the current development platforms:

• macOS:
  • shared backend verifier passes on Metal, OpenGL, and Vulkan
• Linux / WSL:
  • combined Vulkan + OpenGL build validated with focused regressions and backend verification
• Windows:
  • Vulkan and OpenGL were validated through current regression and manual bring-up paths, including folder-open and multi-image workflows

New dependencies:

Required / core for imiv

• Dear ImGui
  • Repo: https://github.com/ocornut/imgui
  • Reason: main UI framework for imiv, including docking, widgets, layout, and backend glue.
• GLFW
  • Repo: https://github.com/glfw/glfw
  • Reason: cross-platform windowing, input, native window handles, and backend bootstrap for Vulkan/OpenGL/Metal.

Optional but imiv-specific

• Dear ImGui Test Engine
  • Repo: https://github.com/ocornut/imgui_test_engine
  • Reason: GUI automation and regression coverage for imiv; test-only, not required for normal runtime.
• nativefiledialog-extended
  • Repo: https://github.com/btzy/nativefiledialog-extended
  • Reason: native open/save dialogs for desktop platforms; optional, imiv can build without it, but without open file/folder dialogues.
• glslang
  • Repo: https://github.com/KhronosGroup/glslang
  • Reason: runtime Vulkan shader compilation for the OCIO Vulkan path; optional depending on backend/features/build.
• Vulkan loader / headers
  • Loader repo: https://github.com/KhronosGroup/Vulkan-Loader
  • Headers repo: https://github.com/KhronosGroup/Vulkan-Headers
  • Reason: only needed for the Vulkan backend itself.

Vendored helper in imiv

• dnd_glfw
  • In-tree: src/imiv/external/dnd_glfw (Repo: https://github.com/ssh4net/dnd_glfw)
  • Reason: richer drag-and-drop behavior around GLFW, especially drag-enter / drag-over / drag-leave overlay handling on Windows/Linux and macOS.

Checklist:

• I have read the guidelines on contributions and code review procedures.
• I have read the Policy on AI Coding Assistants
  and I have used AI coding assistants Codex CLI/ Codex GPT5.4 Extra High
• I have updated the documentation if my PR adds features or changes
  behavior.
• I am sure that this PR's changes are tested in the testsuite.
• I have run and passed the testsuite in CI before submitting the
  PR, by pushing the changes to my fork and seeing that the automated CI
  passed there. (Exceptions: If most tests pass and you can't figure out why
  the remaining ones fail, it's ok to submit the PR and ask for help. Or if
  any failures seem entirely unrelated to your change; sometimes things break
  on the GitHub runners.)
• My code follows the prevailing code style of this project and I
  fixed any problems reported by the clang-format CI test.
• If I added or modified a public C++ API call, I have also amended the
  corresponding Python bindings. If altering ImageBufAlgo functions, I also
  exposed the new functionality as oiiotool options.

[lgritz]

It looks like you have been working on this branch for a while and lots has diverged. Can you please rebase on top of the current main?

[lgritz]

This is just a first set of comments on a few organizational things. It's a lot to review, and I haven't really dug into the meat of the code yet. We'll do a little bit at a time.

[lgritz]

This is one of several spots where something unrelated to this PR seems to have changed for no reason.

[lgritz]

What's with all the changes here?

[lgritz]

Where the contents of Doxyfile changed on purpose?

[lgritz]

I think only the user documentation should be in src/doc and appear in the ReadTheDocs page that explains how users should use OIIO. I believe the developer documentation (contents of imiv_dev and imiv_tests, I believe) should go in docs/dev with the rest of the developer documentation that explains how we develop the code.

[lgritz]

Is dnd_glfw an existing external project? Oh, I see: https://github.com/ssh4net/dnd_glfw
You should definitely reference that here, and point out that the reason we're keeping this in a separate external/ directory is so that new versions of the external one can just be dropped in, so it's not too mixed with the rest of the code that might drift separately?

I think it would be helpful for the periodic license scanning, if the dnd_glfw file had at their top the same kind of // SPDX-License-Identifier: MIT identifier and copyright notice (though with your name, if you are the external author).

[lgritz]

Why does this file change?

[lgritz]

This line is fine, but about 10 lines higher up, you probably need an ENABLE_imiv switch for the SKBUILD case.

(GitHub reviews unfortunately do not line you add comments to code that didn't change, even if you are just trying to point a place that SHOULD have changed!)

[lgritz]

Can all of the find_package file in this file just be changed to checked_find_package, gain all the extra features that provides, and then you don't need to add record_build_dependency or other changes to dependency_utils.cmake?

[lgritz]

imiv/CMakeLists.txt is absolutely enormous! Is there any way that it can be simplified?

[lgritz]

I've never programmed for Dear Imgui before, so I don't know if what I'm asking is naive. Maybe I am misunderstanding how Imgui projects are typically structured. But the amount of code and even the number of added source code modules is absolutely humongous compared to the existing iv.

Old iv using Qt:

• 12 files (*.cpp, *.h, CMakeLists.txt) containing 7042 lines of code
• admittedly, has no tests

New iv using Dear ImGUI:

• 74 files containing 33181 lines for the implementation
• Plus another 41 files containing 12981 lines just for testing infrastructure and tooling

Does this seem right? Does a fairly simple image viewer need so much boilerplate with Imgui that it's nearly 5x more implementation code than the equivalent app using Qt (plus an additional 1.5x for testing infrastructure)?

That feels off to me, but that's just my intuition. If you had asked me beforehand what I expected the imgui version of iv to be like, I would have guessed that it would be similar size and complexity as the old Qt one (maybe I could even hoped for some kind of simplification?), but bringing the advantage of allowing us to drop Qt as a dependency (which is a small but concrete benefit to builders, because Qt is so huge and onerous to build). It's an entirely different set of tradeoffs to consider if the cost of dropping Qt is a 5x increase in OIIO-side implementation code size for the viewer app.

[ssh4net]

@lgritz imgui for sure need more boilerplate, especially Vulkan backend or support multiply backends. But I will check if a code base can be reduced.
Qt for sure has own advantages that you need write less for basic GUI.

[lgritz]

New iv using Dear ImGUI:
* 74 files containing 33181 lines for the implementation
* Plus another 41 files containing 12981 lines just for testing infrastructure and tooling

Contrasting data point: https://github.com/wkjarosz/hdrview
This is also an ImGui-based image viewer, not too dissimilar to iv (though undoubtedly nicer and more feature rich, so should be more code than us).

It has a total of 133 source files, 47,140 LOC. It doesn't use OIIO or a similar comprehensive format library, so it has a lot of code dedicated to reading the formats (37 source files, 12069 lines). Excluding that, then, the total is 96 files, 35k LOC.)

With those high-level stats, it could be that it proves that it's roughly the same size as Vlad's imiv, and that's just what is to be expected for an ImGui-based viewer. Or it could be that only a small subset of those 35k LOC are directly related to ImGui, indicating that we're being much more repetitive and verbose than needed?

Might be worth a look to see what they're doing.

[lgritz]

By the way, given the existence of hdrview and other very nice viewers, one might be tempted to ask, "Does OIIO need a viewer at all?" And also, "if so, how good does it need to be?" is important when evaluating tradeoffs like this PR.

Here is my answer. The goals of iv are:

• To be able to view any format, and any feature of that format, that OIIO can read. That's hard to control for other viewers. (As an example, the very nice hdrview can't read DPX files.)
• It's helpful to have specialized tools that aren't available in other viewers. (Example: most viewers don't let you examine individual MIP levels of a texture, or channels beyond RGBA, but we need this to validate if OIIO is reading and writing those properly.)
• For debugging, it's helpful to directly visualize the data coming through OIIO's APIs, especially when something is going wrong.
• To have at least a minimal viewer available to anybody who builds OIIO.
• To have a second, independent viewer code path to validate, and compare to, other viewers.

So, then, it's primarily a validation and debugging tool for OIIO itself (and therefore still necessary, IMHO). And secondarily, people may find it a good viewer in its own right, if their needs aren't too strenuous, but we are not trying to make it a comprehensive, production-quality studio viewer (and therefore, there is a point of diminishing returns on added complexity and ongoing maintenance cost).

[ssh4net]

Yes, @lgritz, I also always was in thoughs is oiio should have a full-featured image viewer, when a proper GUI app required a lot of attention. And got carried away from the original idea, making only the OpenGL version, with all that multi-backend fun.
I will close this commit, and do not think this work was a waste of resources, as I definitely will use a lot of findings from it in my other projects 😉

[lgritz]

Wait, are you being too hasty here? I was not necessarily implying that we shouldn't pursue this, and definitely wasn't prodding you to close this PR.

I'm still trying to understand a basic question -- can iv switch to a lighter-weight dependency than Qt, without it somehow exploding the amount of code we have to maintain by a large factor? I think there's merit to dropping Qt for something simpler, as long as there is not too high a cost imposed somewhere else.

There also is merit to improving iv. I'm definitely not against that, it's just a matter of cost for benefit, and what we mean by "improve." Two things to say about this:

1. It may be one thing to say "we don't want to divert resources to iv at the expense of our core goals", but if new resources come just for iv (say, somebody who is willing to put that effort in, not at the expense of things others are committed to doing elsewhere), that changes the calculus. Phrased another way: there's a difference between somebody asking for iv to be better and our reply needing to be "it's not a priority", versus somebody coming to us and saying "I will do that work to make iv better." Different situations entirely.
2. There is an enormous gulf between the capabilities of iv and the kind of viewer that we use in a big studio like where I work. I don't want OIIO becoming a project dominated by making that kind of tool. But it's possible that somebody could hear me say "we don't want iv to be that" and mistakenly think I mean "we don't want iv to be better", but those are really two very different things. I'm all for it improving substantially at displaying and examining still images. I don't think it should be an image editing tool like Lightroom, or a studio-quality media and review tool like OpenRV. We're the wrong project for either of those.

[ssh4net]

For sure, something that should be a simple image viewer becomes overcomplicated.
Qt has a huge advantage in that it hides a lot of low-level control from a coder. Maybe in the scope of OIIO, Qt was the right choice.
So i don't know...
I still try to refactor the code, but don't see yet if it's possible to halve the LOC.

[lgritz]

I'm curious what you think if you take a quick skim of hdrview. Do you look at that and think "yeah, looks roughly the same as imiv", or do you think "wow, they made the imgui parts much smaller"? I don't know enough about imgui to make the judgment myself, I don't know what to look for.

I know that lots of projects really like imgui and I've heard great things about it. I don't recall anybody saying "but OMG it makes the code 5x bigger". But maybe everybody but me already understands that and it doesn't need to be said out loud?

[lgritz]

Maybe in the scope of OIIO, Qt was the right choice.

Could be. But if so, it's kinda coincidence. When I wrote iv in early 2008, I think the only toolkits that seemed capable and cross-platform at that time were Qt, WxWidgets, and Fltk. I'd used fltk before, but it seemed kind of old fashioned. I picked Qt somewhat arbitrarily, and because I knew that in vfx, it was becoming more common. Since then, it's just been inertia. Lots of other GUI toolkits have popped up (including ImGui), and I never stopped to directly compare them. We are not using Qt for any principled reason.

[ssh4net]

I will review Imiv with HDRiview. Maybe i missing something in a logic.

[ssh4net]

@lgritz looks like Hdrview is heavily related to the HelloImGui and ImPlot libraries, which are themselves layer libraries on top of ImGui. Personally, I slightly fear relating to the ImGui 3rd-party libraries as they are not maintained as well as ImGui itself.
Also, at this moment, ImGui does not look like it provides such fine-grained control for Metal texture creation, and this is a reason why imiv has quite a big mm file with Metal code (mainly to enable/disable interpolation). I thought to check how this was made and maybe propose these changes to the ImGui project.
So overall, yes, ImGui has more LOC, but some of them are from native ImGui use, ImGui Test Engine hooks, and regression tests hooks.

[lgritz]

I'm going to re-open this. Let's just let it sit for a while and gather other people's opinions before deciding if this is a tradeoff that makes sense for us in the long run.