{
  "markdown": "# Open Image Debugger: Enabling visualization of in-memory buffers on GDB/LLDB\n\n[![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)\n[![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)\n[![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)\n\nOpen Image Debugger is a tool for visualizing in-memory buffers during debug\nsessions, compatible with both GDB and LLDB. It works out of the box with\ninstances of the OpenCV `Mat` class and `Eigen` matrices, but can also be\ncustomized to work with any arbitrary data structure.\n\n![Sample window](doc/sample_window.png)\n\n> **Prefer VS Code or a fork (Cursor, VSCodium, Windsurf, …)?** Skip the manual\n> build — install the extension from the\n> [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=OpenImageDebugger.openimagedebugger-vscode)\n> or [Open VSX](https://open-vsx.org/extension/openimagedebugger/openimagedebugger-vscode).\n> See [Installation](#vs-code-and-forks) below.\n\n> **New — using CLion or Android Studio?** The Open Image Debugger plugin is\n> now on the\n> [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33640-open-image-debugger):\n> plot buffers straight from the native C/C++ debugger, inside the IDE. See\n> [Installation](#clion-and-android-studio) below.\n\n> **New — declarative custom types.** You can now describe your own buffer types\n> in a `.oid/types.json` file instead of writing Python; the same file works in\n> gdb, lldb, and the VS Code and JetBrains extensions. See\n> [doc/declarative-types.md](doc/declarative-types.md).\n\n# 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)\n## A bit experimental, better to compile manually\n\n## Features\n\n* GUI interactivity:\n  * Scroll to zoom, left click+drag to move the buffer around;\n  * Rotate buffers 90&deg; clockwise or counterclockwise;\n  * Go-to widget that quickly takes you to any arbitrary pixel location;\n* Buffer values: Zoom in close enough to inspect the numerical contents of any pixel.\n* Auto update: Whenever a breakpoint is hit, the buffer view is automatically\n  updated.\n* Auto contrast: The entire range of values present in the buffer can be\n  automatically mapped to the visualization range `[0, 1]`, where `0`\n  represents black and `1` represents white.\n* The contrast range can be manually adjusted, which is useful for inspecting\n  buffers with extreme values (e.g. infinity, nan and other outliers).\n* Link views together, moving all watched buffers simultaneously when any\n  single buffer is moved on the screen\n* Supported buffer types: uint8_t, int16_t, uint16_t, int32_t, uint32_t,\n  float and double\n* Supported buffer channels: Up to four channels (Grayscale, two-channels, RGB\n  and RGBA)\n* GPU accelerated\n* Supports large buffers whose dimensions exceed GL_MAX_TEXTURE_SIZE.\n* Supports data structures that map to a ROI of a larger buffer.\n* Exports buffers as png images (with auto contrast) or octave/matlab matrix\n  files (unprocessed).\n* Auto-load buffers being visualized in the previous debug session\n* Designed to scale well for HighDPI displays\n* Works on Linux, macOS X and Windows (experimental)\n\n## Supported OSes\n\n* OID is developed with Ubuntu as the main target. The goal is to support the two latest LTS versions at a given time.\n  * 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`\n* There are currently no plans to support other Linux distros. OID may or may not compile on your favorite distro, your mileage may vary.\n* 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.\n\n## Requirements\n\n* A C++20 compliant compiler\n* GDB **15.0.50+** or LLDB **18.1.3+**\n* CMake **3.28.3+**\n* Python **3.12.3+** development packages\n* OpenGL **2.1+** support\n* 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.\n\nAll other third-party libraries are bundled as git submodules and built from source, so they don't need to be installed:\n\n* [Dear ImGui](https://github.com/ocornut/imgui) — viewer UI\n* [GLFW](https://github.com/glfw/glfw) — window and OpenGL context management\n* [Eigen](https://gitlab.com/libeigen/eigen) — linear algebra for the visualization layer\n* [Asio](https://github.com/chriskohlhoff/asio) (standalone) — IPC between the debugger bridge and the viewer\n* [nlohmann/json](https://github.com/nlohmann/json) — settings persistence\n* [stb](https://github.com/nothings/stb) — image decoding for opening files, plus PNG export and text rendering (`stb_image`, `stb_image_write`, `stb_truetype`)\n* [nanosvg](https://github.com/memononen/nanosvg) — toolbar icon rasterization\n* [nativefiledialog-extended](https://github.com/btzy/nativefiledialog-extended) — native OS dialog for File → Open (native builds only)\n* [GoogleTest](https://github.com/google/googletest) — unit tests\n\nNote: 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>.\n\n## Installation\n\n### VS Code and forks\n\nThe quickest way to get started is the Open Image Debugger extension, available for\nVS Code and compatible forks (Cursor, VSCodium, Windsurf, and others):\n\n* [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=OpenImageDebugger.openimagedebugger-vscode)\n* [Open VSX](https://open-vsx.org/extension/openimagedebugger/openimagedebugger-vscode)\n\n### CLion and Android Studio\n\nThe Open Image Debugger plugin brings the same viewer to JetBrains IDEs with a\nnative C/C++ debugger — CLion, and Android Studio with the NDK:\n\n* [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33640-open-image-debugger)\n\nIf you'd rather build and integrate the desktop version manually, follow the steps below.\n\n### Ubuntu Linux dependencies\n\nOn Ubuntu, you can install most of the dependencies with the following command:\n\n```bash\nsudo apt install build-essential cmake libgl1-mesa-dev libgtk-3-dev libpython3-dev \\\n    python3-dev libwayland-dev libxcursor-dev libxi-dev libxinerama-dev \\\n    libxkbcommon-dev libxrandr-dev pkg-config\n```\n\n### Building the Open Image Debugger\n\nClone the source code to any folder you prefer and initialize the\nsubmodules:\n\n```bash\ngit clone https://github.com/OpenImageDebugger/OpenImageDebugger.git --recurse-submodules\n```\n\nNow run the following commands to build it:\n\n```bash\ncmake -S . -B build -DCMAKE_INSTALL_PREFIX=/path/to/installation/folder\ncmake --build build --config Release --target install -j 4\n```\n\n**GDB integration:** Edit the file `~/.gdbinit` (create it if it doesn't exist)\nand append the following line:\n\n```bash\nsource /path/to/OpenImageDebugger/oid.py\n```\n\n**LLDB integration:** Edit the file `~/.lldbinit` (create it if it doesn't\nexist) and append the following line:\n\n```bash\ncommand script import /path/to/OpenImageDebugger/oid.py\n```\n\n### MacOS Installation\n\nAt the moment, the MacOS build is only known to work with `python3` and `lldb`\ninstalled from [Homebrew](https://brew.sh/) (the system-provided LLDB from the\nXcode Command Line Tools is not supported). Install them with:\n\n```bash\nbrew install python3 llvm\n```\n\nMake sure `python3` resolves to the Homebrew one — run `which python3` and\nconfirm it points under the Homebrew prefix (`/opt/homebrew` on Apple Silicon,\n`/usr/local` on Intel; `brew --prefix` prints it), rather than a pyenv, conda or\nsystem Python. The standard Homebrew install puts that prefix's `bin` on your\n`PATH`.\n\nThen debug your program using the Homebrew LLDB, for example:\n\n```bash\nBREW_PREFIX=$(brew --prefix)\n\"$BREW_PREFIX\"/opt/llvm/bin/lldb /path/to/your/executable\n```\n\n### Testing your installation\n\nAfter compiling the plugin, you can test it by running the following command\n(use the same Python 3 interpreter CMake found when building):\n\n```bash\npython3 /path/to/OpenImageDebugger/oid.py --test\n```\n\nOn MacOS, invoke the test with the full path to the Homebrew `python3`, for\nexample:\n\n```bash\nBREW_PREFIX=$(brew --prefix)\n\"$BREW_PREFIX\"/bin/python3 /path/to/OpenImageDebugger/oid.py --test\n```\n\nIf the installation was succesful, you should see the Open Image Debugger window\nwith the buffers `sample_buffer_1` and `sample_buffer_2`.\n\n## Using plugin\n\nWhen the debugger hits a breakpoint, the Open Image Debugger window will be\nopened. You only need to type the name of the buffer to be watched in the\n\"add symbols\" input, and press `<enter>`.\n\n### Opening image files directly\n\nYou can also open an image or NumPy array in the viewer without a debugger\nsession at all, either from the **File → Open** menu (shortcut `Ctrl+O`) or\nfrom the command line.\n\nFrom the command line, pass one or more files with the repeatable `-o` /\n`--open` flag:\n\n```bash\noidwindow --open path/to/image.png --open path/to/array.npy\n```\n\nSupported formats:\n\n| Category | Extensions |\n| --- | --- |\n| Images (via stb_image) | `png`, `jpg`/`jpeg`, `bmp`, `tga`, `gif`, `psd`, `hdr`, `ppm`/`pgm`/`pnm` |\n| NumPy arrays | `npy` (little-endian `uint8`/`uint16`/`int16`/`int32`/`float32`/`float64`; 2-D grayscale or 3-D with 1&ndash;4 channels) |\n\nFiles opened this way are shown alongside any debugger buffers, but they are\nnever reported back to a debugger and are not saved as session state.\n\n> **Linux build note:** the native file dialog requires GTK 3\n> (`libgtk-3-dev`) at build time, or configure with `-DNFD_PORTAL=ON` to use\n> the xdg-desktop-portal (D-Bus) backend instead. MacOS and Windows need no\n> extra packages.\n\nOpen Image Debugger does not register itself as a system handler for these\nfile types; use the **File → Open** menu or the `--open` flag to load them.\n\n### <img src=\"doc/auto-contrast.svg\" width=\"20\"/> Auto-contrast and manual contrast\n\nThe (min) and (max) fields on top of the buffer view can be changed to control\nautocontrast settings. By default, Open Image Debugger will automatically fill these\nfields with the mininum and maximum values inside the entire buffer, and the\nchannel values will be normalized from these values to the range [0, 1] inside\nthe renderer.\n\nSometimes, your buffer may contain trash, uninitialized values that are either\ntoo large or too small, making the entire image look flat because of this\nnormalization. If you know the expected range for your image, you can manually\nchange the (min) and (max) values to focus on the range that you are\ninterested.\n\n### <img src=\"doc/link-views.svg\" width=\"20\"/> Locking buffers\n\nSometimes you want to compare two buffers being visualized, and need to zoom in\ndifferent places of these buffers. If they are large enough, this can become a\nvery hard task, especially if you are comparing pixel values. This task is made\neasier by the `lock buffers` tool (which is toggled by the button with a chain\nicon).\n\nWhen it is activated, all buffers are moved/zoomed simultaneously by the same\namount. This means you only need to align the buffers being compared once;\nafter activating the `lock buffers` mode, you can zoom in anywhere you wish in\none buffer that all other buffers will be zoomed in the same location.\n\n### <img src=\"doc/location.svg\" width=\"20\"/> Quickly moving to arbitrary coordinates\n\nIf you need to quickly move to any pixel location, then the *go to*\nfunctionality is what you are looking for. Press *Ctrl+L* and two input fields\ncorresponding to the target destination in format `<x, y>` will appear at the\nbottom right corner of the buffer screen. Type the desired location, then press\nenter to quickly zoom into that location.\n\n### Exporting bufers\n\nSometimes you may want to export your buffers to be able to process them in an\nexternal tool. In order to do that, right click the thumbnail corresponding to\nthe buffer you wish to export on the left pane and select \"export buffer\".\n\nOpen Image Debugger supports two export modes. You can save your buffer as a PNG\n(which may result in loss of data if your buffer type is not `uint8_t`) or as a\nbinary file that can be opened with any tool.\n\n### Loading exported buffers on Octave/Matlab\n\nBuffers exported in the `Octave matrix` format can be loaded with the function\n`oid_load.m`, which is available in the `matlab` folder. To use it, add this\nfolder to Octave/Matlab `path` variable and call\n`oid_load('/path/to/buffer.dump')`.\n\n### AI agent access (MCP, experimental)\n\nOpen Image Debugger ships an experimental **MCP server** (`oid-mcp`) that\nlets AI coding agents inspect your buffers in a live gdb/lldb session —\nlist observable symbols at a breakpoint, view renderings, read exact\nvalues, dump lossless `.npy` copies, and mirror buffers into the viewer.\nAgents can also control and read back a running viewer's view — pan,\nzoom, rotate, channel, and auto-contrast — including one opened\nstandalone with no debugger attached. It is opt-in (launch the debugger\nwith `OID_AGENT=1`) and exposes debuggee memory to local processes, so\nenable it only in trusted, local development.\n\nSee [`resources/oidmcp/README.md`](resources/oidmcp/README.md) for\ndeployment and usage instructions.\n\n## Configuration\n\nBy default, the plugin works with several data types, including OpenCV's `Mat`,\n`CvMat` and `IplImage` and Eigen's `Matrix` and `Map`.\n\nSupported library versions: OpenCV 2–5 and Eigen 3.x. The OpenCV\n`Mat`/`CvMat` channel count is read from the type-flag bit packing in a\nversion-adaptive way, so both the pre-5 and the OpenCV 5 layouts resolve\ncorrectly; `CvMat` and `IplImage` are the legacy C API and therefore apply\nonly to OpenCV builds that still expose it (4.x and earlier).\n\n### Custom types (recommended): declarative JSON\n\nTo support a different buffer type, describe it in a `.oid/types.json` file at\nyour workspace root — no Python required. The common case is five fields:\n\n```json\n{\n  \"version\": 1,\n  \"types\": [\n    { \"match\": \"^MyImage$\",\n      \"pointer\": \"{sym}.data\",\n      \"width\": \"{sym}.w\",\n      \"height\": \"{sym}.h\",\n      \"dtype\": \"float32\" }\n  ]\n}\n```\n\nThe same file is read by gdb, lldb, and the VS Code and JetBrains\nextensions. You can also\npoint OID at files outside the workspace with the `OID_TYPES_PATH` environment\nvariable. The full format — every field, the expression grammar, dtype names,\ndiscovery and precedence, and a walkthrough migrating an existing Python\ninspector — is documented in\n[doc/declarative-types.md](doc/declarative-types.md), and the built-in types in\n`resources/oidscripts/oidtypes/builtin_types.json` double as a worked-example\ngallery.\n\n### Custom types (legacy): Python inspectors\n\nThe original Python path is still supported for cases the declarative format\ncannot express, but it is no longer the preferred approach for new types.\nImplement a `TypeInspectorInterface` subclass from\n`resources/oidscripts/oidtypes/interface.py`; see\n[doc/python-inspectors.md](doc/python-inspectors.md) for the full instructions —\nthe interface methods, the buffer-metadata dictionary contract, and the debug\ndecorators.\n\n### Resetting the UI\n\nOpen Image Debugger remembers its window size and position, the width of the\nsymbol list pane, the auto-contrast and link-views toggles, the buffers you\nviewed last, and the directory you last exported to. The application writes\nthis state itself — it is not a preferences file meant to be edited by hand —\nand keeps it in `OpenImageDebugger/imgui_settings.json` under:\n\n| OS | Directory |\n| --- | --- |\n| Linux | `$XDG_CONFIG_HOME`, or `$HOME/.config` when that is unset |\n| macOS | `$HOME/Library/Application Support` |\n| Windows | `%APPDATA%` |\n\nDelete that file while the viewer is not running to restore the defaults — a\nrunning viewer rewrites it shortly after any change to that state, and again\nwhen it exits. This is the fix if the viewer reopens at a window position that\nis off-screen.\n",
  "bytes": 17146,
  "sha": "287e510f1bae15e075a96af6953e52b4e34a963d5a7ba613349ecd331b8ed090",
  "repo_slug": "openimagedebugger/openimagedebugger",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_openimagedebugger_oid_mcp_b033ce5a/readme"
}