ImView for VS Code

A VS Code extension for visualizing image data during C/C++ and Python debugging sessions. Similar to Visual Studio's ImView, this extension allows you to inspect OpenCV cv::Mat, NumPy arrays, PIL images, PyTorch tensors, and other image types in real-time while debugging.

Features

• Real-time Image Visualization: View image variables during debug sessions
• Multiple Image Types: Support for OpenCV cv::Mat, cv::Mat_<T>, cv::Matx, CvMat, IplImage, NumPy ndarray, PIL Image, PyTorch Tensor, and custom types
• Multiple Debuggers: Works with GDB (cppdbg), LLDB (lldb), MSVC (cppvsdbg), and Python (debugpy) debuggers
• Interactive Viewer:
  • Zoom and pan with mouse wheel and drag
  • Pixel value inspection on hover
  • Channel-wise viewing (R/G/B/A)
  • Auto-normalization for non-8-bit images
  • Colormap support for single-channel images (grayscale, jet, hot, cool, viridis, plasma)
• Dual View Modes: Sidebar panel and separate editor tab modes
• Context Menu Integration: Right-click on variables in the debug panel to view or add to watch list
• Watch Expressions: Add custom expressions to watch list
• Export: Save the rendered image as PNG/JPEG or export its display buffer as raw binary

Supported Platforms

• Windows x64/ARM64
• macOS x64/Apple silicon
• Linux x64/ARM64

The extension itself is platform-neutral TypeScript. Native debugger and Python package support still depends on the debugger extension and interpreter installed on the target machine.

Supported Image Types

C++ (OpenCV)

Python

Supported Pixel Depths

Usage

Quick Start (C++)

1. Start a debug session with a C/C++ program that uses OpenCV
2. Set a breakpoint where image variables are in scope
3. When the debugger stops, the ImView panel shows detected image variables
4. Click on an image to view it in the viewer panel

Quick Start (Python)

1. Start a debug session with a Python program that uses NumPy/OpenCV/PIL/PyTorch
2. Set a breakpoint where image variables are in scope
3. When the debugger stops, image variables appear in the ImView panel
4. Click on an image or right-click and select "View Image" to visualize

# Example Python script
import numpy as np
import cv2
from PIL import Image
import torch

# NumPy array (via OpenCV)
img_cv = cv2.imread('image.jpg')

# NumPy array (random)
img_np = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)

# PIL Image
img_pil = Image.open('image.jpg')

# PyTorch tensor (CPU or accelerator; copied to CPU for display)
img_torch = torch.rand(3, 64, 64)

breakpoint()  # Set breakpoint here to visualize images

Viewing Images from Debug Variables

• Right-click on any variable in the VARIABLES or WATCH panel
• Select "View Image" to add the clicked expression to ImView and display it immediately; no manual re-entry is required
• Select "Add to ImView" to add to the watch list

Viewing Images from Editor

• Select a variable name in the code editor
• Right-click and select "View Image" or "Add to ImView"

Watch Expressions

Add custom expressions to monitor:

• Click the + button in the Image List panel
• Enter expressions like myImage, images[0], or ptr->frame

Viewer Controls

PNG/JPEG exports contain the rendered pixels after normalization, colormap, channel selection, and alpha handling. Zoom, grids, and inspector overlays are not included; JPEG composites transparent pixels onto white.

Image Operators

Transform images using @ operators in watch expressions:

@abs(img)              - Absolute value
@band(img, n)          - Extract channel n
@thresh(img, t)        - Binary threshold
@clamp(img, min, max)  - Clamp values
@scale(img, f)         - Scale by factor
@norm8(img)            - Normalize /255 into float32
@norm16(img)           - Normalize /65535 into float32
@diff(img1, img2)      - Absolute difference
@fliph(img)            - Flip horizontal
@flipv(img)            - Flip vertical
@rot90(img)            - Rotate 90° CW
@rot180(img)           - Rotate 180°
@rot270(img)           - Rotate 270° CW

Operators can be nested: @abs(@diff(img1, img2))

Raw debugger memory can be watched explicitly:

@mem(0x12345678, uint8, 3, 640, 480)
@mem(0x12345678, uint16, 1, 640, 480, 1280)  # optional row stride

The address must be a non-null hexadecimal pointer. Dimensions, channels, stride, and configured transfer limits are validated before memory is read.

Configuration

Custom Type Configuration

Define custom image types in settings:

"imview.customTypes": [
  {
    "typeName": "MyImage",
    "properties": {
      "width": "m_width",
      "height": "m_height",
      "channels": 3,
      "data": "m_data",
      "stride": "m_stride",
      "pixelType": "uint8"
    }
  }
]

Supported pixelType values: uint8, int8, uint16, int16, int32, float32, float64

Requirements

• VS Code 1.85.0 or later
• One of the following debugger extensions:
  • C/C++ Extension (for cppdbg and cppvsdbg)
  • CodeLLDB (for lldb)
  • Python Extension with Debugpy (for Python debugging)

Installation

From VSIX

code --install-extension imview-0.1.1.vsix

Building from Source

# Install dependencies
npm ci

# Compile
npm run compile

# Package a validated VSIX
npm run package:vsix

Known Limitations

• Image dimensions and transfer size are bounded by imview.maxImageSize and imview.maxImageBytes
• Some debugger configurations may not support readMemory requests
• Python: Accelerator-backed PyTorch tensors are copied to CPU and may pause longer for large tensors
• Python: Very large images may take longer to transfer due to base64 encoding

Troubleshooting

Image not displaying

1. Make sure the debugger is paused at a breakpoint
2. Verify the variable is in scope
3. Check the Output panel for error messages

"Debugger must be paused" message

The debugger must be stopped at a breakpoint to read memory. Step through your code or set a breakpoint.

Variable not recognized as image type

The extension recognizes OpenCV types by their type names. If using a custom type, configure it in imview.customTypes.

License

MIT. See the LICENSE.txt file included with this extension.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.