Skip to content
Back to search

OpenImageDebugger

An advanced in-memory image visualization plugin for GDB and LLDB on Linux, with experimental support for MacOS and Windows. Previously known as gdb-imagewatch. Also available as an extension for VSCode and forks

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openimagedebugger--openimagedebugger/badge.svg)](/listings/openimagedebugger--openimagedebugger)

HTML

<a href="/listings/openimagedebugger--openimagedebugger"><img src="/api/listings/openimagedebugger--openimagedebugger/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

VS Code and forks

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

* [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=OpenImageDebugger.openimagedebugger-vscode) * [Open VSX](https://open-vsx.org/extension/openimagedebugger/openimagedebugger-vscode)

CLion and Android Studio

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

* [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33640-open-image-debugger)

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 the submodules:

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't exist) 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 `lldb` installed from [Homebrew](https://brew.sh/) (the system-provided LLDB from the Xcode Command Line Tools is not supported). Install them with:

brew install python3 llvm

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

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`, for example:

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 window with the buffers `sample_buffer_1` and `sample_buffer_2`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 365 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Open Image Debugger: Enabling visualization of in-memory buffers on GDB/LLDB
  2. [![VS Code Marketplace Downloads](https://vsmarketplacebadges.dev/downloads-short/OpenImageDebugger.openimagedebugger-vscode.svg?label=VS%20Code%20Marketplace%20Downloads&color=007ACC)](https://marketplace.visualstudio.com/items?itemName=OpenImageDebugger.openimagedebugger-vscode)
  3. [![Open VSX Downloads](https://img.shields.io/open-vsx/dt/openimagedebugger/openimagedebugger-vscode?label=Open%20VSX%20Downloads&color=a60ee5)](https://open-vsx.org/extension/openimagedebugger/openimagedebugger-vscode)
  4. [![JetBrains Marketplace Downloads](https://img.shields.io/jetbrains/plugin/d/33640?label=JetBrains%20Marketplace%20Downloads&color=fe2857)](https://plugins.jetbrains.com/plugin/33640-open-image-debugger)
  5. Open Image Debugger is a tool for visualizing in-memory buffers during debug
  6. sessions, compatible with both GDB and LLDB. It works out of the box with
  7. instances of the OpenCV `Mat` class and `Eigen` matrices, but can also be
  8. customized to work with any arbitrary data structure.
  9. ![Sample window](doc/sample_window.png)
  10. > **Prefer VS Code or a fork (Cursor, VSCodium, Windsurf, …)?** Skip the manual
  11. > build — install the extension from the
  12. > [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=OpenImageDebugger.openimagedebugger-vscode)
  13. > or [Open VSX](https://open-vsx.org/extension/openimagedebugger/openimagedebugger-vscode).
  14. > See [Installation](#vs-code-and-forks) below.
  15. > **New — using CLion or Android Studio?** The Open Image Debugger plugin is
  16. > now on the
  17. > [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33640-open-image-debugger):
  18. > plot buffers straight from the native C/C++ debugger, inside the IDE. See
  19. > [Installation](#clion-and-android-studio) below.
  20. > **New — declarative custom types.** You can now describe your own buffer types
  21. > in a `.oid/types.json` file instead of writing Python; the same file works in
  22. > gdb, lldb, and the VS Code and JetBrains extensions. See
  23. > [doc/declarative-types.md](doc/declarative-types.md).
  24. # Download (experimental) [![OID Eternal Download Count](https://img.shields.io/github/downloads/openimagedebugger/openimagedebugger/total.svg)](https://tooomm.github.io/github-release-stats/?username=OpenImageDebugger&repository=OpenImageDebugger&search=0)
  25. ## A bit experimental, better to compile manually
  26. ## Features
  27. * GUI interactivity:
  28. * Scroll to zoom, left click+drag to move the buffer around;
  29. * Rotate buffers 90&deg; clockwise or counterclockwise;
  30. * Go-to widget that quickly takes you to any arbitrary pixel location;
  31. * Buffer values: Zoom in close enough to inspect the numerical contents of any pixel.
  32. * Auto update: Whenever a breakpoint is hit, the buffer view is automatically
  33. updated.
  34. * Auto contrast: The entire range of values present in the buffer can be
  35. automatically mapped to the visualization range `[0, 1]`, where `0`
  36. represents black and `1` represents white.
  37. * The contrast range can be manually adjusted, which is useful for inspecting
  38. buffers with extreme values (e.g. infinity, nan and other outliers).
  39. * Link views together, moving all watched buffers simultaneously when any
  40. single buffer is moved on the screen
  41. * Supported buffer types: uint8_t, int16_t, uint16_t, int32_t, uint32_t,
  42. float and double
  43. * Supported buffer channels: Up to four channels (Grayscale, two-channels, RGB
  44. and RGBA)
  45. * GPU accelerated
  46. * Supports large buffers whose dimensions exceed GL_MAX_TEXTURE_SIZE.
  47. * Supports data structures that map to a ROI of a larger buffer.
  48. * Exports buffers as png images (with auto contrast) or octave/matlab matrix
  49. files (unprocessed).
  50. * Auto-load buffers being visualized in the previous debug session
  51. * Designed to scale well for HighDPI displays
  52. * Works on Linux, macOS X and Windows (experimental)
  53. ## Supported OSes
  54. * OID is developed with Ubuntu as the main target. The goal is to support the two latest LTS versions at a given time.
  55. * 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`
  56. * There are currently no plans to support other Linux distros. OID may or may not compile on your favorite distro, your mileage may vary.
  57. * 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.
  58. ## Requirements
  59. * A C++20 compliant compiler
  60. * GDB **15.0.50+** or LLDB **18.1.3+**
  61. * CMake **3.28.3+**
  62. * Python **3.12.3+** development packages
  63. * OpenGL **2.1+** support
  64. * 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.
  65. All other third-party libraries are bundled as git submodules and built from source, so they don't need to be installed:
  66. * [Dear ImGui](https://github.com/ocornut/imgui) — viewer UI
  67. * [GLFW](https://github.com/glfw/glfw) — window and OpenGL context management
  68. * [Eigen](https://gitlab.com/libeigen/eigen) — linear algebra for the visualization layer
  69. * [Asio](https://github.com/chriskohlhoff/asio) (standalone) — IPC between the debugger bridge and the viewer
  70. * [nlohmann/json](https://github.com/nlohmann/json) — settings persistence
  71. * [stb](https://github.com/nothings/stb) — image decoding for opening files, plus PNG export and text rendering (`stb_image`, `stb_image_write`, `stb_truetype`)
  72. * [nanosvg](https://github.com/memononen/nanosvg) — toolbar icon rasterization
  73. * [nativefiledialog-extended](https://github.com/btzy/nativefiledialog-extended) — native OS dialog for File → Open (native builds only)
  74. * [GoogleTest](https://github.com/google/googletest) — unit tests
  75. 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>.
  76. ## Installation
  77. ### VS Code and forks
  78. The quickest way to get started is the Open Image Debugger extension, available for
  79. VS Code and compatible forks (Cursor, VSCodium, Windsurf, and others):
  80. * [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=OpenImageDebugger.openimagedebugger-vscode)
  81. * [Open VSX](https://open-vsx.org/extension/openimagedebugger/openimagedebugger-vscode)
  82. ### CLion and Android Studio
  83. The Open Image Debugger plugin brings the same viewer to JetBrains IDEs with a
  84. native C/C++ debugger — CLion, and Android Studio with the NDK:
  85. * [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33640-open-image-debugger)
  86. If you'd rather build and integrate the desktop version manually, follow the steps below.
  87. ### Ubuntu Linux dependencies
  88. On Ubuntu, you can install most of the dependencies with the following command:
  89. ```bash
  90. sudo apt install build-essential cmake libgl1-mesa-dev libgtk-3-dev libpython3-dev \
  91. python3-dev libwayland-dev libxcursor-dev libxi-dev libxinerama-dev \
  92. libxkbcommon-dev libxrandr-dev pkg-config
  93. ```
  94. ### Building the Open Image Debugger
  95. Clone the source code to any folder you prefer and initialize the
  96. submodules:
  97. ```bash
  98. git clone https://github.com/OpenImageDebugger/OpenImageDebugger.git --recurse-submodules
  99. ```
  100. Now run the following commands to build it:
  101. ```bash
  102. cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/path/to/installation/folder
  103. cmake --build build --config Release --target install -j 4
  104. ```
  105. **GDB integration:** Edit the file `~/.gdbinit` (create it if it doesn't exist)
  106. and append the following line:
  107. ```bash
  108. source /path/to/OpenImageDebugger/oid.py
  109. ```
  110. **LLDB integration:** Edit the file `~/.lldbinit` (create it if it doesn't
  111. exist) and append the following line:
  112. ```bash
  113. command script import /path/to/OpenImageDebugger/oid.py
  114. ```
  115. ### MacOS Installation
  116. At the moment, the MacOS build is only known to work with `python3` and `lldb`
  117. installed from [Homebrew](https://brew.sh/) (the system-provided LLDB from the
  118. Xcode Command Line Tools is not supported). Install them with:
  119. ```bash
  120. brew install python3 llvm
  121. ```
  122. Make sure `python3` resolves to the Homebrew one — run `which python3` and
  123. confirm it points under the Homebrew prefix (`/opt/homebrew` on Apple Silicon,
  124. `/usr/local` on Intel; `brew --prefix` prints it), rather than a pyenv, conda or
  125. system Python. The standard Homebrew install puts that prefix's `bin` on your
  126. `PATH`.
  127. Then debug your program using the Homebrew LLDB, for example:
  128. ```bash
  129. BREW_PREFIX=$(brew --prefix)
  130. "$BREW_PREFIX"/opt/llvm/bin/lldb /path/to/your/executable
  131. ```
  132. ### Testing your installation
  133. After compiling the plugin, you can test it by running the following command
  134. (use the same Python 3 interpreter CMake found when building):
  135. ```bash
  136. python3 /path/to/OpenImageDebugger/oid.py --test
  137. ```
  138. On MacOS, invoke the test with the full path to the Homebrew `python3`, for
  139. example:
  140. ```bash
  141. BREW_PREFIX=$(brew --prefix)
  142. "$BREW_PREFIX"/bin/python3 /path/to/OpenImageDebugger/oid.py --test
  143. ```
  144. If the installation was succesful, you should see the Open Image Debugger window
  145. with the buffers `sample_buffer_1` and `sample_buffer_2`.
  146. ## Using plugin
  147. When the debugger hits a breakpoint, the Open Image Debugger window will be
  148. opened. You only need to type the name of the buffer to be watched in the
  149. "add symbols" input, and press `<enter>`.
  150. ### Opening image files directly
  151. You can also open an image or NumPy array in the viewer without a debugger
  152. session at all, either from the **File → Open** menu (shortcut `Ctrl+O`) or
  153. from the command line.
  154. From the command line, pass one or more files with the repeatable `-o` /
  155. `--open` flag:
  156. ```bash
  157. oidwindow --open path/to/image.png --open path/to/array.npy
  158. ```
  159. Supported formats:
  160. | Category | Extensions |
  161. | --- | --- |
  162. | Images (via stb_image) | `png`, `jpg`/`jpeg`, `bmp`, `tga`, `gif`, `psd`, `hdr`, `ppm`/`pgm`/`pnm` |
  163. | NumPy arrays | `npy` (little-endian `uint8`/`uint16`/`int16`/`int32`/`float32`/`float64`; 2-D grayscale or 3-D with 1&ndash;4 channels) |
  164. Files opened this way are shown alongside any debugger buffers, but they are
  165. never reported back to a debugger and are not saved as session state.
  166. > **Linux build note:** the native file dialog requires GTK 3
  167. > (`libgtk-3-dev`) at build time, or configure with `-DNFD_PORTAL=ON` to use
  168. > the xdg-desktop-portal (D-Bus) backend instead. MacOS and Windows need no
  169. > extra packages.
  170. Open Image Debugger does not register itself as a system handler for these
  171. file types; use the **File → Open** menu or the `--open` flag to load them.
  172. ### <img src="doc/auto-contrast.svg" width="20"/> Auto-contrast and manual contrast
  173. The (min) and (max) fields on top of the buffer view can be changed to control
  174. autocontrast settings. By default, Open Image Debugger will automatically fill these
  175. fields with the mininum and maximum values inside the entire buffer, and the
  176. channel values will be normalized from these values to the range [0, 1] inside
  177. the renderer.
  178. Sometimes, your buffer may contain trash, uninitialized values that are either
  179. too large or too small, making the entire image look flat because of this
  180. normalization. If you know the expected range for your image, you can manually
  181. change the (min) and (max) values to focus on the range that you are
  182. interested.
  183. ### <img src="doc/link-views.svg" width="20"/> Locking buffers
  184. Sometimes you want to compare two buffers being visualized, and need to zoom in
  185. different places of these buffers. If they are large enough, this can become a
  186. very hard task, especially if you are comparing pixel values. This task is made
  187. easier by the `lock buffers` tool (which is toggled by the button with a chain
  188. icon).
  189. When it is activated, all buffers are moved/zoomed simultaneously by the same
  190. amount. This means you only need to align the buffers being compared once;
  191. after activating the `lock buffers` mode, you can zoom in anywhere you wish in
  192. one buffer that all other buffers will be zoomed in the same location.
  193. ### <img src="doc/location.svg" width="20"/> Quickly moving to arbitrary coordinates
  194. If you need to quickly move to any pixel location, then the *go to*
  195. functionality is what you are looking for. Press *Ctrl+L* and two input fields
  196. corresponding to the target destination in format `<x, y>` will appear at the
  197. bottom right corner of the buffer screen. Type the desired location, then press
  198. enter to quickly zoom into that location.
  199. ### Exporting bufers
  200. Sometimes you may want to export your buffers to be able to process them in an
  201. external tool. In order to do that, right click the thumbnail corresponding to
  202. the buffer you wish to export on the left pane and select "export buffer".
  203. Open Image Debugger supports two export modes. You can save your buffer as a PNG
  204. (which may result in loss of data if your buffer type is not `uint8_t`) or as a
  205. binary file that can be opened with any tool.
  206. ### Loading exported buffers on Octave/Matlab
  207. Buffers exported in the `Octave matrix` format can be loaded with the function
  208. `oid_load.m`, which is available in the `matlab` folder. To use it, add this
  209. folder to Octave/Matlab `path` variable and call
  210. `oid_load('/path/to/buffer.dump')`.
  211. ### AI agent access (MCP, experimental)
  212. Open Image Debugger ships an experimental **MCP server** (`oid-mcp`) that
  213. lets AI coding agents inspect your buffers in a live gdb/lldb session —
  214. list observable symbols at a breakpoint, view renderings, read exact
  215. values, dump lossless `.npy` copies, and mirror buffers into the viewer.
  216. Agents can also control and read back a running viewer's view — pan,
  217. zoom, rotate, channel, and auto-contrast — including one opened
  218. standalone with no debugger attached. It is opt-in (launch the debugger
  219. with `OID_AGENT=1`) and exposes debuggee memory to local processes, so
  220. enable it only in trusted, local development.
  221. See [`resources/oidmcp/README.md`](resources/oidmcp/README.md) for
  222. deployment and usage instructions.
  223. ## Configuration
  224. By default, the plugin works with several data types, including OpenCV's `Mat`,
  225. `CvMat` and `IplImage` and Eigen's `Matrix` and `Map`.
  226. Supported library versions: OpenCV 2–5 and Eigen 3.x. The OpenCV
  227. `Mat`/`CvMat` channel count is read from the type-flag bit packing in a
  228. version-adaptive way, so both the pre-5 and the OpenCV 5 layouts resolve
  229. correctly; `CvMat` and `IplImage` are the legacy C API and therefore apply
  230. only to OpenCV builds that still expose it (4.x and earlier).
  231. ### Custom types (recommended): declarative JSON
  232. To support a different buffer type, describe it in a `.oid/types.json` file at
  233. your workspace root — no Python required. The common case is five fields:
  234. ```json
  235. {
  236. "version": 1,
  237. "types": [
  238. { "match": "^MyImage$",
  239. "pointer": "{sym}.data",
  240. "width": "{sym}.w",
  241. "height": "{sym}.h",
  242. "dtype": "float32" }
  243. ]
  244. }
  245. ```
  246. The same file is read by gdb, lldb, and the VS Code and JetBrains
  247. extensions. You can also
  248. point OID at files outside the workspace with the `OID_TYPES_PATH` environment
  249. variable. The full format — every field, the expression grammar, dtype names,
  250. discovery and precedence, and a walkthrough migrating an existing Python
  251. inspector — is documented in
  252. [doc/declarative-types.md](doc/declarative-types.md), and the built-in types in
  253. `resources/oidscripts/oidtypes/builtin_types.json` double as a worked-example
  254. gallery.
  255. ### Custom types (legacy): Python inspectors
  256. The original Python path is still supported for cases the declarative format
  257. cannot express, but it is no longer the preferred approach for new types.
  258. Implement a `TypeInspectorInterface` subclass from
  259. `resources/oidscripts/oidtypes/interface.py`; see
  260. [doc/python-inspectors.md](doc/python-inspectors.md) for the full instructions —
  261. the interface methods, the buffer-metadata dictionary contract, and the debug
  262. decorators.
  263. ### Resetting the UI
  264. Open Image Debugger remembers its window size and position, the width of the
  265. symbol list pane, the auto-contrast and link-views toggles, the buffers you
  266. viewed last, and the directory you last exported to. The application writes
  267. this state itself — it is not a preferences file meant to be edited by hand —
  268. and keeps it in `OpenImageDebugger/imgui_settings.json` under:
  269. | OS | Directory |
  270. | --- | --- |
  271. | Linux | `$XDG_CONFIG_HOME`, or `$HOME/.config` when that is unset |
  272. | macOS | `$HOME/Library/Application Support` |
  273. | Windows | `%APPDATA%` |
  274. Delete that file while the viewer is not running to restore the defaults — a
  275. running viewer rewrites it shortly after any change to that state, and again
  276. when it exits. This is the fix if the viewer reopens at a window position that
  277. is off-screen.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.