<commit_before># Advanced GDB ImageWatch
GDB ImageWatch is a tool for visualizing in-memory buffers during debug
sessions using GDB. It works out of the box with instances of the OpenCV `Mat`
class, but can also be customized to work with any arbitrary data structure.

![](doc/sample_window.png)

## Features

* GUI interactivity: Scroll to zoom, left click+drag to move the buffer around.
* Buffer values: Zoom in close enough to see the numerical values of the
  buffer.
* Auto update: Whenever a breakpoint is hit, the buffer view is automatically
  updated.
* Auto contrast
* Editable contrast clamp values, useful when inspecting a buffer that contains
  uninitialized values.
* Link views together, moving all watched buffers when a single buffer is moved
  on the screen
* GPU accelerated
* Supported buffer types: uint8_t, int16_t, uint16_t, int32_t, uint32_t,
  float and double
* Supported buffer channels: Grayscale, two-channels, RGB and RGBA
* Supports big buffers whose dimensions exceed GL_MAX_TEXTURE_SIZE.
* Supports data structures that map to a ROI of a bigger buffer.
* Exports buffers as png images (with auto contrast) or octave matrix files
  (unprocessed).
* Rotate buffers 90&deg; clockwise or counterclockwise.
* Auto-load buffers being visualized in the previous debug session

## Requirements

 * An OpenGL 2.0+ compliant GPU
 * A C++11 compliant compiler (gcc-5 or later is recommended)

## Installation

### Dependencies

GDB ImageWatch requires python 3+, lib freetype 2, Qt SDK, GLEW, GLFW, Qt 5+
and GDB 7.10+ (which must be compiled with python 3 support). On Ubuntu, you
can install these packages with the following command:

    sudo apt-get install libpython3-dev libglew-dev python3-numpy python3-pip qt-sdk texinfo libfreetype6-dev libeigen3-dev
    sudo pip3 install pysigset

Download and install the latest version of GDB with python3 support (if you
already don't have it):

    wget http://ftp.gnu.org/gnu/gdb/gdb-7.10.tar.gz
    tar -zxvf gdb-7.10.tar.gz
    cd gdb-7.10
    ./configure --with-python=python3 --disable-werror
    make -j8
    sudo make install

Notice that if you already have an older version of GDB, you will need to
either reconfigure your environment running `update-alternatives` or
reconfigure your IDE to use the updated version (which, by default, will be
installed on `/usr/local/bin/gdb`).

After the installation, you can remove both the file `gdb-7.10.tar.gz` and the
folder `gdb-7.10`.

Finally, clone the GDB ImageWatch plugin to any folder you prefer:

    git clone https://github.com/csantosbh/gdb-imagewatch

### Ubuntu 16.04 manual installation with QtCreator

Ubuntu 16.04 comes with qt4, which is not compatible with GDB ImageWatch. In
order to compile it, you need to install qt5 and use its corresponding qmake
during the compilation step.

If you are using QtCreator, this can be done by going to Tools->Options->Build
& Run->Kits and set Qt version to any Qt version >= 5.

### Build plugin and configure GDB

To build this plugin, create a `build` folder, open a terminal window inside it
and run:

    qmake ..
    make -j4
    make install

The `make install` step is absolutely required, and will only copy the
dependencies to the build folder (thus, it doesn't require any special user
privileges).

#### Loading plugin: QtCreator

If you use QtCreator, the best way to integrate GDB ImageWatch into your
workflow is by using it as an *extra debugging helper*. This can be achieved by
going to the menu `Tools`->`Options`->`Debugger` and adding the file
`/path/to/gdb-imagewatch/build/gdb-imagewatch.py` in the option
`Extra debugging Helpers`.

This will automatically load the plugin for every debug session, and will
reload the local variables when switching between threads/stack level when the
debugger is paused.

#### Loading pugin: GDB/Other IDEs

If you are not using QtCreator, simply edit the `~/.gdbinit` file (create it if
it doesn't exist) and append the following line:

    source /path/to/gdb-imagewatch/build/gdb-imagewatch.py

This way, GDB will automatically load the GDB imagewatch plugin every time it
starts.

### Ubuntu 16.04 Automated Installation without QtCreator

If you are not using QtCreator, we provide the script `configure_ubuntu_16.sh`
which handles the Qt version issue and automates the installation of GDB ImageWatch
on Ubuntu 16.04. From the root directory of this project, execute the following:

    bash configure_ubuntu_16.sh
    
Follow this step with the instructions below in the section `Testing your installation`.

## Testing your installation

After compiling the plugin, you can test it by opening a console in the
installation folder and running the following command:

    python3 gdb-imagewatch.py --test

If the installation was succesful, you should see the GDB ImageWatch window
with the same python_test and python_test2 buffers from the image on the header
of this page.

## Using plugin

When GDB hits a breakpoint, the GDB ImageWatch window will be opened. You only
need to type the name of the buffer to be watched in the "add symbols" input,
and press `<enter>`.

Alternatively, you can also invoke the GDB ImageWatch window directly from GDB
with the following command:

    plot variable_name

### <img src="resources/icons/contrast.png" width="20"/> Auto-contrast and manual contrast

The (min) and (max) fields on top of the buffer view can be changed to control
autocontrast settings. By default, GDB ImageWatch will automatically fill these
fields with the mininum and maximum values inside the entire buffer, and the
channel values will be normalized from these values to the range [0, 1] inside
the renderer.

Sometimes, your buffer may contain trash, uninitialized values that are either
too big or too small, making the entire image look flat because of this
normalization. If you know the expected range for your image, you can manually
change the (min) and (max) values to focus on the range that you are
interested.

### <img src="resources/icons/link.png" width="20"/> Locking buffers<commit_msg>clarify testing instructions<commit_after># Advanced GDB ImageWatch
GDB ImageWatch is a tool for visualizing in-memory buffers during debug
sessions using GDB. It works out of the box with instances of the OpenCV `Mat`
class, but can also be customized to work with any arbitrary data structure.

![](doc/sample_window.png)

## Features

* GUI interactivity: Scroll to zoom, left click+drag to move the buffer around.
* Buffer values: Zoom in close enough to see the numerical values of the
  buffer.
* Auto update: Whenever a breakpoint is hit, the buffer view is automatically
  updated.
* Auto contrast
* Editable contrast clamp values, useful when inspecting a buffer that contains
  uninitialized values.
* Link views together, moving all watched buffers when a single buffer is moved
  on the screen
* GPU accelerated
* Supported buffer types: uint8_t, int16_t, uint16_t, int32_t, uint32_t,
  float and double
* Supported buffer channels: Grayscale, two-channels, RGB and RGBA
* Supports big buffers whose dimensions exceed GL_MAX_TEXTURE_SIZE.
* Supports data structures that map to a ROI of a bigger buffer.
* Exports buffers as png images (with auto contrast) or octave matrix files
  (unprocessed).
* Rotate buffers 90&deg; clockwise or counterclockwise.
* Auto-load buffers being visualized in the previous debug session

## Requirements

 * An OpenGL 2.0+ compliant GPU
 * A C++11 compliant compiler (gcc-5 or later is recommended)

## Installation

### Dependencies

GDB ImageWatch requires python 3+, lib freetype 2, Qt SDK, GLEW, GLFW, Qt 5+
and GDB 7.10+ (which must be compiled with python 3 support). On Ubuntu, you
can install these packages with the following command:

    sudo apt-get install libpython3-dev libglew-dev python3-numpy python3-pip qt-sdk texinfo libfreetype6-dev libeigen3-dev
    sudo pip3 install pysigset

Download and install the latest version of GDB with python3 support (if you
already don't have it):

    wget http://ftp.gnu.org/gnu/gdb/gdb-7.10.tar.gz
    tar -zxvf gdb-7.10.tar.gz
    cd gdb-7.10
    ./configure --with-python=python3 --disable-werror
    make -j8
    sudo make install

Notice that if you already have an older version of GDB, you will need to
either reconfigure your environment running `update-alternatives` or
reconfigure your IDE to use the updated version (which, by default, will be
installed on `/usr/local/bin/gdb`).

After the installation, you can remove both the file `gdb-7.10.tar.gz` and the
folder `gdb-7.10`.

Finally, clone the GDB ImageWatch plugin to any folder you prefer:

    git clone https://github.com/csantosbh/gdb-imagewatch

### Ubuntu 16.04 manual installation with QtCreator

Ubuntu 16.04 comes with qt4, which is not compatible with GDB ImageWatch. In
order to compile it, you need to install qt5 and use its corresponding qmake
during the compilation step.

If you are using QtCreator, this can be done by going to Tools->Options->Build
& Run->Kits and set Qt version to any Qt version >= 5.

### Build plugin and configure GDB

To build this plugin, create a `build` folder, open a terminal window inside it
and run:

    qmake ..
    make -j4
    make install

The `make install` step is absolutely required, and will only copy the
dependencies to the build folder (thus, it doesn't require any special user
privileges).

#### Loading plugin: QtCreator

If you use QtCreator, the best way to integrate GDB ImageWatch into your
workflow is by using it as an *extra debugging helper*. This can be achieved by
going to the menu `Tools`->`Options`->`Debugger` and adding the file
`/path/to/gdb-imagewatch/build/gdb-imagewatch.py` in the option
`Extra debugging Helpers`.

This will automatically load the plugin for every debug session, and will
reload the local variables when switching between threads/stack level when the
debugger is paused.

#### Loading pugin: GDB/Other IDEs

If you are not using QtCreator, simply edit the `~/.gdbinit` file (create it if
it doesn't exist) and append the following line:

    source /path/to/gdb-imagewatch/build/gdb-imagewatch.py

This way, GDB will automatically load the GDB imagewatch plugin every time it
starts.

### Ubuntu 16.04 Automated Installation without QtCreator

If you are not using QtCreator, we provide the script `configure_ubuntu_16.sh`
which handles the Qt version issue and automates the installation of GDB ImageWatch
on Ubuntu 16.04. From the root directory of this project, execute the following:

    bash configure_ubuntu_16.sh
    
Follow this step with the instructions below in the section `Testing your installation`.

## Testing your installation

After compiling the plugin, you can test it by opening a console in the
installation folder and running the following command from the root project directory:

    python3 build/gdb-imagewatch.py --test

If the installation was succesful, you should see the GDB ImageWatch window
with the same python_test and python_test2 buffers from the image on the header
of this page.

## Using plugin

When GDB hits a breakpoint, the GDB ImageWatch window will be opened. You only
need to type the name of the buffer to be watched in the "add symbols" input,
and press `<enter>`.

Alternatively, you can also invoke the GDB ImageWatch window directly from GDB
with the following command:

    plot variable_name

### <img src="resources/icons/contrast.png" width="20"/> Auto-contrast and manual contrast

The (min) and (max) fields on top of the buffer view can be changed to control
autocontrast settings. By default, GDB ImageWatch will automatically fill these
fields with the mininum and maximum values inside the entire buffer, and the
channel values will be normalized from these values to the range [0, 1] inside
the renderer.

Sometimes, your buffer may contain trash, uninitialized values that are either
too big or too small, making the entire image look flat because of this
normalization. If you know the expected range for your image, you can manually
change the (min) and (max) values to focus on the range that you are
interested.

### <img src="resources/icons/link.png" width="20"/> Locking buffers
{'fraction_non_alphanumeric': 0.059981947977352915, 'fraction_numerical': 0.012964634446541397, 'mean_word_length': 4.251184834123222, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 21, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '844752', 'n_tokens_mistral': 3522, 'n_tokens_neox': 3291, 'n_words': 1728}