Open Image Debugger: Enabling visualization of in-memory buffers on GDB/LLDB

Open Image Debugger: Enabling visualization of in-memory buffers on GDB/LLDB

Open Image Debugger is a tool for visualizing in-memory buffers during debugsessions, compatible with both GDB and LLDB. It works out of the box withinstances of the OpenCV Mat class and Eigen matrices, but can also becustomized to work with any arbitrary data structure.

Prefer VS Code or a fork (Cursor, VSCodium, Windsurf, …)? Skip the manualbuild — install the extension from theVS Code Marketplaceor Open VSX.See Installation below.

New — using CLion or Android Studio? The Open Image Debugger plugin isnow on theJetBrains Marketplace:plot buffers straight from the native C/C++ debugger, inside the IDE. SeeInstallation below.

New — declarative custom types. You can now describe your own buffer typesin a .oid/types.json file instead of writing Python; the same file works ingdb, lldb, and the VS Code and JetBrains extensions. Seedoc/declarative-types.md.

Download (experimental)

A bit experimental, better to compile manually

Features

• GUI interactivity:
  • Scroll to zoom, left click+drag to move the buffer around;
  • Rotate buffers 90° clockwise or counterclockwise;
  • Go-to widget that quickly takes you to any arbitrary pixel location;
• Buffer values: Zoom in close enough to inspect the numerical contents of any pixel.
• Auto update: Whenever a breakpoint is hit, the buffer view is automaticallyupdated.
• Auto contrast: The entire range of values present in the buffer can beautomatically mapped to the visualization range [0, 1], where 0represents black and 1 represents white.
• The contrast range can be manually adjusted, which is useful for inspectingbuffers with extreme values (e.g. infinity, nan and other outliers).
• Link views together, moving all watched buffers simultaneously when anysingle buffer is moved on the screen
• Supported buffer types: uint8_t, int16_t, uint16_t, int32_t, uint32_t,float and double
• Supported buffer channels: Up to four channels (Grayscale, two-channels, RGBand RGBA)
• GPU accelerated
• Supports large buffers whose dimensions exceed GL_MAX_TEXTURE_SIZE.
• Supports data structures that map to a ROI of a larger buffer.
• Exports buffers as png images (with auto contrast) or octave/matlab matrixfiles (unprocessed).
• Auto-load buffers being visualized in the previous debug session
• Designed to scale well for HighDPI displays
• Works on Linux, macOS X and Windows (experimental)

Supported OSes

• OID is developed with Ubuntu as the main target. The goal is to support the two latest LTS versions at a given time.
  • Ubuntu is also used as a basis for the minimum versions of the dependencies: we try to support the default versions of the packages you get via apt install
• There are currently no plans to support other Linux distros. OID may or may not compile on your favorite distro, your mileage may vary.
• Support for MacOS and Windows are somewhat experimental now - the code should be able to compile (see https://github.com/OpenImageDebugger/OpenImageDebugger/releases), but the binaries are not actively tested - in fact we currently have no automated tests at all for any OS - help is more than welcome in this regard. Also, we haven't come up with a simple installation/usage guides for these OSes yet.

Requirements

• A C++20 compliant compiler
• GDB 15.0.50+ or LLDB 18.1.3+
• CMake 3.28.3+
• Python 3.12.3+ development packages
• OpenGL 2.1+ support
• Linux only: Wayland and X11 development packages (needed to build the bundled GLFW) and GTK 3 development packages (needed by the native file-open dialog); see the apt install command below. Alternatively, configure with -DNFD_PORTAL=ON to use the xdg-desktop-portal (D-Bus) dialog backend instead of GTK.

All other third-party libraries are bundled as git submodules and built from source, so they don't need to be installed:

• Dear ImGui — viewer UI
• GLFW — window and OpenGL context management
• Eigen — linear algebra for the visualization layer
• Asio (standalone) — IPC between the debugger bridge and the viewer
• nlohmann/json — settings persistence
• stb — image decoding for opening files, plus PNG export and text rendering (stb_image, stb_image_write, stb_truetype)
• nanosvg — toolbar icon rasterization
• nativefiledialog-extended — native OS dialog for File → Open (native builds only)
• GoogleTest — unit tests

Note: this list might get out-of-date by accident. For a more accurate list of requirements, please check what is used in https://github.com/OpenImageDebugger/OpenImageDebugger/blob/main/.github/workflows/build.yml and in the CI container images defined in https://github.com/OpenImageDebugger/dockerfiles.

Installation

VS Code and forks

The quickest way to get started is the Open Image Debugger extension, available forVS Code and compatible forks (Cursor, VSCodium, Windsurf, and others):

• VS Code Marketplace
• Open VSX

CLion and Android Studio

The Open Image Debugger plugin brings the same viewer to JetBrains IDEs with anative C/C++ debugger — CLion, and Android Studio with the NDK:

• JetBrains Marketplace

If you'd rather build and integrate the desktop version manually, follow the steps below.

Ubuntu Linux dependencies

On Ubuntu, you can install most of the dependencies with the following command:

sudo apt install build-essential cmake libgl1-mesa-dev libgtk-3-dev libpython3-dev \
    python3-dev libwayland-dev libxcursor-dev libxi-dev libxinerama-dev \
    libxkbcommon-dev libxrandr-dev pkg-config

Building the Open Image Debugger

Clone the source code to any folder you prefer and initialize thesubmodules:

git clone https://github.com/OpenImageDebugger/OpenImageDebugger.git --recurse-submodules

Now run the following commands to build it:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/path/to/installation/folder
cmake --build build --config Release --target install -j 4

GDB integration: Edit the file ~/.gdbinit (create it if it doesn't exist)and append the following line:

source /path/to/OpenImageDebugger/oid.py

LLDB integration: Edit the file ~/.lldbinit (create it if it doesn'texist) and append the following line:

command script import /path/to/OpenImageDebugger/oid.py

MacOS Installation

At the moment, the MacOS build is only known to work with python3 and lldbinstalled from Homebrew (the system-provided LLDB from theXcode Command Line Tools is not supported). Install them with:

brew install python3 llvm

Make sure python3 resolves to the Homebrew one — run which python3 andconfirm it points under the Homebrew prefix (/opt/homebrew on Apple Silicon,/usr/local on Intel; brew --prefix prints it), rather than a pyenv, conda orsystem Python. The standard Homebrew install puts that prefix's bin on yourPATH.

Then debug your program using the Homebrew LLDB, for example:

BREW_PREFIX=$(brew --prefix)
"$BREW_PREFIX"/opt/llvm/bin/lldb /path/to/your/executable

Testing your installation

After compiling the plugin, you can test it by running the following command(use the same Python 3 interpreter CMake found when building):

python3 /path/to/OpenImageDebugger/oid.py --test

On MacOS, invoke the test with the full path to the Homebrew python3, forexample:

BREW_PREFIX=$(brew --prefix)
"$BREW_PREFIX"/bin/python3 /path/to/OpenImageDebugger/oid.py --test

If the installation was succesful, you should see the Open Image Debugger windowwith the buffers sample_buffer_1 and sample_buffer_2.

Using plugin

When the debugger hits a breakpoint, the Open Image Debugger window will beopened. You only need to type the name of the buffer to be watched in the"add symbols" input, and press <enter>.

Opening image files directly

You can also open an image or NumPy array in the viewer without a debuggersession at all, either from the File → Open menu (shortcut Ctrl+O) orfrom the command line.

From the command line, pass one or more files with the repeatable -o /--open flag:

oidwindow --open path/to/image.png --open path/to/array.npy

Supported formats:

Files opened this way are shown alongside any debugger buffers, but they arenever reported back to a debugger and are not saved as session state.

Linux build note: the native file dialog requires GTK 3(libgtk-3-dev) at build time, or configure with -DNFD_PORTAL=ON to usethe xdg-desktop-portal (D-Bus) backend instead. MacOS and Windows need noextra packages.

Open Image Debugger does not register itself as a system handler for thesefile types; use the File → Open menu or the --open flag to load them.

Auto-contrast and manual contrast

The (min) and (max) fields on top of the buffer view can be changed to controlautocontrast settings. By default, Open Image Debugger will automatically fill thesefields with the mininum and maximum values inside the entire buffer, and thechannel values will be normalized from these values to the range [0, 1] insidethe renderer.

Sometimes, your buffer may contain trash, uninitialized values that are eithertoo large or too small, making the entire image look flat because of thisnormalization. If you know the expected range for your image, you can manuallychange the (min) and (max) values to focus on the range that you areinterested.

Locking buffers

Sometimes you want to compare two buffers being visualized, and need to zoom indifferent places of these buffers. If they are large enough, this can become avery hard task, especially if you are comparing pixel values. This task is madeeasier by the lock buffers tool (which is toggled by the button with a chainicon).

When it is activated, all buffers are moved/zoomed simultaneously by the sameamount. This means you only need to align the buffers being compared once;after activating the lock buffers mode, you can zoom in anywhere you wish inone buffer that all other buffers will be zoomed in the same location.

Quickly moving to arbitrary coordinates

If you need to quickly move to any pixel location, then the go tofunctionality is what you are looking for. Press Ctrl+L and two input fieldscorresponding to the target destination in format <x, y> will appear at thebottom right corner of the buffer screen. Type the desired location, then pressenter to quickly zoom into that location.

Exporting bufers

Sometimes you may want to export your buffers to be able to process them in anexternal tool. In order to do that, right click the thumbnail corresponding tothe buffer you wish to export on the left pane and select "export buffer".

Open Image Debugger supports two export modes. You can save your buffer as a PNG(which may result in loss of data if your buffer type is not uint8_t) or as abinary file that can be opened with any tool.

Loading exported buffers on Octave/Matlab

Buffers exported in the Octave matrix format can be loaded with the functionoid_load.m, which is available in the matlab folder. To use it, add thisfolder to Octave/Matlab path variable and calloid_load('/path/to/buffer.dump').

AI agent access (MCP, experimental)

Open Image Debugger ships an experimental MCP server (oid-mcp) thatlets AI coding agents inspect your buffers in a live gdb/lldb session —list observable symbols at a breakpoint, view renderings, read exactvalues, dump lossless .npy copies, and mirror buffers into the viewer.Agents can also control and read back a running viewer's view — pan,zoom, rotate, channel, and auto-contrast — including one openedstandalone with no debugger attached. It is opt-in (launch the debuggerwith OID_AGENT=1) and exposes debuggee memory to local processes, soenable it only in trusted, local development.

See resources/oidmcp/README.md fordeployment and usage instructions.

Configuration

By default, the plugin works with several data types, including OpenCV's Mat,CvMat and IplImage and Eigen's Matrix and Map.

Supported library versions: OpenCV 2–5 and Eigen 3.x. The OpenCVMat/CvMat channel count is read from the type-flag bit packing in aversion-adaptive way, so both the pre-5 and the OpenCV 5 layouts resolvecorrectly; CvMat and IplImage are the legacy C API and therefore applyonly to OpenCV builds that still expose it (4.x and earlier).

Custom types (recommended): declarative JSON

To support a different buffer type, describe it in a .oid/types.json file atyour workspace root — no Python required. The common case is five fields:

{
  "version": 1,
  "types": [
    { "match": "^MyImage$",
      "pointer": "{sym}.data",
      "width": "{sym}.w",
      "height": "{sym}.h",
      "dtype": "float32" }
  ]
}

The same file is read by gdb, lldb, and the VS Code and JetBrainsextensions. You can alsopoint OID at files outside the workspace with the OID_TYPES_PATH environmentvariable. The full format — every field, the expression grammar, dtype names,discovery and precedence, and a walkthrough migrating an existing Pythoninspector — is documented indoc/declarative-types.md, and the built-in types inresources/oidscripts/oidtypes/builtin_types.json double as a worked-examplegallery.

Custom types (legacy): Python inspectors

The original Python path is still supported for cases the declarative formatcannot express, but it is no longer the preferred approach for new types.Implement a TypeInspectorInterface subclass fromresources/oidscripts/oidtypes/interface.py; seedoc/python-inspectors.md for the full instructions —the interface methods, the buffer-metadata dictionary contract, and the debugdecorators.

Resetting the UI

Open Image Debugger remembers its window size and position, the width of thesymbol list pane, the auto-contrast and link-views toggles, the buffers youviewed last, and the directory you last exported to. The application writesthis state itself — it is not a preferences file meant to be edited by hand —and keeps it in OpenImageDebugger/imgui_settings.json under:

Delete that file while the viewer is not running to restore the defaults — arunning viewer rewrites it shortly after any change to that state, and againwhen it exits. This is the fix if the viewer reopens at a window position thatis off-screen.