[VSC-1608] Feature/debug image viewer

[brianignacio5]

Description

This pull request introduces a new Image Viewer feature to the ESP-IDF extension, enabling users to visualize binary image data from debug variables during a debugging session. The feature supports LVGL, OpenCV, and raw pixel formats, and is accessible both via context menu and command palette. The implementation includes new commands, UI integration, and documentation in both English and Chinese.

Image Viewer Feature Integration

• Added new commands espIdf.viewVariableAsImage and espIdf.openImageViewer to package.json and registered them in the extension activation code, enabling users to view variables as images and open the image viewer manually. [1] [2] [3]
• Implemented the image viewer UI using Vue, with entry point src/views/image-view/main.ts and included it in the webpack build configuration. [1] [2]
• Added localization for new commands in English, Spanish, Portuguese, Russian, and Chinese. [1] [2] [3] [4] [5] [6]

Documentation Updates

• Added detailed documentation for the Image Viewer feature in both English (docs_espressif/en/debugproject.rst) and Chinese (docs_espressif/zh_CN/debugproject.rst), including usage instructions, supported formats, and examples. [1] [2]

Codebase Structure

• Imported and integrated ImageViewPanel in the extension code to handle the new image viewer functionality.

These changes collectively provide a user-friendly way to inspect image data in ESP-IDF projects during debugging, supporting a wide range of formats and improving developer productivity.

Type of change

• New feature (non-breaking change which adds functionality)

Steps to test this pull request

Using a variable name and size (any decoded image with given size, can use size variable name)

You need a project where you have converted an image into a decompressed byte array and use it in memory.

You can use these steps to convert a jpg into a c file that can be used in an example project. Replace magick and xxd for the equivalent command in your OS. (These I used in MacOS, magick needed to be installed with brew)

magick image.jpg -resize 320x240 -depth 8 -colorspace RGB -channel BGR -separate +channel -combine image.rgb
xxd -i image.rgb  > main/small_image.h

This steps generate a width 320 and height 240 using BGR888 format image you can use in your project.

For the ESP-IDF project, you can test:

#include "small_image.h"

void app_main(void)
{
    // Create local variables for debugging - these will show up in info locals
    const unsigned char* local_image_data = small_image_bgr888_data; // Replace this with name in small_image.h
    const unsigned int local_image_len = small_image_bgr888_data_len; // Replace this with name in small_image.h
    
    // Create a small buffer with first few bytes for easy inspection
    unsigned char first_bytes[32];
    for (int i = 0; i < 32 && i < (int)local_image_len; i++) {
        first_bytes[i] = local_image_data[i];
    }
    
    printf("Small BGR888 Image Test\n");
    printf("Image data address: %p\n", small_image_bgr888_data);
    printf("Image data length: %u bytes\n", small_image_bgr888_data_len);
    printf("Image dimensions: %dx%d pixels\n", 320, 240);
}

Set a breakpoint after local_image_len. use local_image_data as variable name, local_image_len 320 for width, 240 for height and RGB888 for format in ESP-IDF: Open Image Viewer.

1. Start a debug session with Eclipse CDT Debug Adapter. Set a breakpoint after data is available in debug session memory
2. Click on "ESP-IDF: Open Image Viewer". Enter the image array variable name and the size (either number or name of variable with size)
3. Enter the format used in the decompressed image width and height of your image and press Load Image button.
4. Observe results. Press update after changing width, height or image format.

Using LVGL

Use the ESP-BSP display example. To me was simple enough to test on different boards. Configure the project Compile Options to Debug without Optimization -O0.

After Line 82 of lvgl_demo_ui.c file add these lines to get the variable as local:

// Create a local variable reference to esp_logo for debugging
const lv_image_dsc_t *esp_logo_local = &esp_logo;
// Prevent optimization: use esp_logo_local in a volatile pointer assignment
volatile const lv_image_dsc_t *esp_logo_dbg = esp_logo_local;
printf("esp_logo_local address: %p\n", (void*)esp_logo_local);
printf("esp_logo_local->header.w: %d\n", esp_logo_local->header.w);
printf("esp_logo_local->header.h: %d\n", esp_logo_local->header.h);

1. Start a debug session. Set a breakpoint at https://github.com/espressif/esp-bsp/blob/master/examples/display/main/lvgl_demo_ui.c#L106 or after lv_obj_center(img_logo);.
2. On the local variables, right click on esp_logo_local and press View Variable as Image
3. The image viewer web view should open rendering the image.

Using OpenCV

I've made a test project here.

1. Start a debug session. Set a breakpoint at https://github.com/brianignacio5/opencv-test/blob/main/main/load_image.cpp#L133 or after cv::Mat opencv_image.
2. On the local variables, right click on opencv_image and press View Variable as Image
3. The image viewer web view should open rendering the image.

Using Libpng (custom image viewer variable format)

I've made a test project here. The project includes an example implementation of custom types for Image Viewer as json file: https://github.com/brianignacio5/libpng_example/blob/main/image_configs.json where you can define which variables represent fields need for image rendering. For libpng, the image data pointer and size is not stored in the png_image field but in other fields which are defined in this json file.

1. Start a debug session. Set a breakpoint at https://github.com/brianignacio5/libpng_example/blob/main/main/main.c#L39 or after png_image_finish_read .
2. On the local variables, right click at image and select View Variable as Image.
3. The image viewer web view should open rendering the image.

• Expected behaviour:
  The image can be rendered from debug session variable into the Image Viewer web view.

• Expected output:

Image is rendered in Image Viewer web view.

How has this been tested?

Manual testing following the steps above.

Test Configuration:

• ESP-IDF Version: 5.5.1
• OS (Windows,Linux and macOS): macOS

Checklist

• PR Self Reviewed
• Applied Code formatting
• Added Documentation
• Added Unit Test
• Verified on all platforms - Windows,Linux and macOS

[github-actions]

Download the artifacts for this pull request:
You can test these changes by installing this VSIX by click menu View -> Command Palette..., type Install from VSIX and then select downloaded esp-idf-extension.vsix file to install the extension.

• esp-idf-extension.vsix.zip
  Espressif documentation preview

[radurentea]

Nice work! LGTM

[github-actions]

Pull request has been marked as stale since there are no activities, and this will be closed in 5 days if there are no further activities