Build and install instructions

Install for Python

Install from pypi

pip install imgui-bundle
pip install opencv-contrib-python # (1)
  1. in order to run the immvision module, install opencv-python or opencv-contrib-python

Note: under windows, you might need to install msvc redist.

Install from source:

git clone
cd imgui_bundle
git submodule update --init --recursive # (1)
pip install -v . # (2)
pip install opencv-contrib-python
  1. Since there are lots of submodules, this might take a few minutes

  2. The build process might take up to 5 minutes

Run the python demo

Simply run demo_imgui_bundle.

The source for the demos can be found inside bindings/imgui_bundle/demos_python.

Consider demo_imgui_bundle as an always available manual for Dear ImGui Bundle with lots of examples and related code source.

Install for C++

Click to expand


import os.path

import numpy as np
from typing import Any
from numpy.typing import NDArray
from enum import Enum
import cv2  # type: ignore
import math

from imgui_bundle import imgui, immvision, immapp, imgui_md
from imgui_bundle.demos_python import demo_utils

ImageRgb = NDArray[np.uint8]
ImageFloat = NDArray[np.floating[Any]]

class SobelParams:
    """The parameters for our image processing pipeline"""

    class Orientation(Enum):
        Horizontal = 0
        Vertical = 1

    blur_size = 1.25
    deriv_order = 1  # order of the derivative
    k_size = 7  # size of the extended Sobel kernel it must be 1, 3, 5, or 7 (or -1 for Scharr)
    orientation: Orientation = Orientation.Vertical

def compute_sobel(image: ImageRgb, params: SobelParams) -> ImageFloat:
    """Our image processing pipeline"""
    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    img_float = gray / 255.0
    blurred = cv2.GaussianBlur(
        img_float, (0, 0), sigmaX=params.blur_size, sigmaY=params.blur_size

    good_scale = 1.0 / math.pow(2.0, (params.k_size - 2 * params.deriv_order - 2))

    if params.orientation == SobelParams.Orientation.Vertical:
        dx = params.deriv_order
        dy = 0
        dx = 0
        dy = params.deriv_order
    r = cv2.Sobel(
        blurred, ddepth=cv2.CV_64F, dx=dx, dy=dy, ksize=params.k_size, scale=good_scale
    return r

def gui_sobel_params(params: SobelParams) -> bool:
    """A GUI to edit the parameters for our image processing pipeline"""
    changed = False

    # Blur size
    imgui.set_next_item_width(immapp.em_size() * 10)
    c, params.blur_size = imgui.slider_float("Blur size", params.blur_size, 0.5, 10)
    if c:
        changed = True
    imgui.text(" | ")

    # Deriv order
    imgui.text("Deriv order")
    for deriv_order in (1, 2, 3, 4):
        c, params.deriv_order = imgui.radio_button(
            str(deriv_order), params.deriv_order, deriv_order
        if c:
            changed = True

    imgui.text(" | ")

    if imgui.radio_button(
        "Horizontal", params.orientation == SobelParams.Orientation.Horizontal
        changed = True
        params.orientation = SobelParams.Orientation.Horizontal
    if imgui.radio_button(
        "Vertical", params.orientation == SobelParams.Orientation.Vertical
        changed = True
        params.orientation = SobelParams.Orientation.Vertical

    return changed

# Our Application State contains:
#     - the original & processed image (image & imageSobel)
#     - our parameters for the processing pipeline (sobelParams)
#     - parameters to display the images via ImmVision: they share the same zoom key,
#       so that we can move the two image in sync
class AppState:
    image: ImageRgb
    image_sobel: ImageFloat
    sobel_params: SobelParams

    immvision_params: immvision.ImageParams
    immvision_params_sobel: immvision.ImageParams

    def __init__(self, image_file: str):
        self.image = cv2.imread(image_file)
        self.sobel_params = SobelParams()
        self.image_sobel = compute_sobel(self.image, self.sobel_params)

        self.immvision_params = immvision.ImageParams()
        self.immvision_params.image_display_size = (int(immapp.em_size(22)), 0)
        self.immvision_params.zoom_key = "z"

        self.immvision_params_sobel = immvision.ImageParams()
        self.immvision_params_sobel.image_display_size = (int(immapp.em_size(22)), 0)
        self.immvision_params_sobel.zoom_key = "z"
        self.immvision_params_sobel.show_options_panel = True

# Our GUI function
#    (which instantiates a static app state at startup)
def demo_gui():
    static = demo_gui

    if static.app_state is None:
        this_dir = os.path.dirname(__file__)
        static.app_state = AppState(this_dir + "/../../demos_assets/images/house.jpg")

        This example shows a example of image processing (sobel filter) where you can adjust the params and see their effect in real time.

        * Pan and zoom the image with the mouse and the mouse wheel
        * Apply Colormaps to the filtered image in the options tab.

    changed = gui_sobel_params(static.app_state.sobel_params)
    if changed:
        static.app_state.image_sobel = compute_sobel(
            static.app_state.image, static.app_state.sobel_params
    static.app_state.immvision_params_sobel.refresh_image = changed

        "Original", static.app_state.image, static.app_state.immvision_params
        "Deriv", static.app_state.image_sobel, static.app_state.immvision_params_sobel

# The main entry point will run our GUI function
if __name__ == "__main__":
    immapp.run_with_markdown(demo_gui, window_size=(1000, 1000))

==== Integrate Dear ImGui Bundle in your own project in 5 minutes

The easiest way to use Dear ImGui Bundle in an external project is to use the template available at

This template includes everything you need to set up your own project.

==== Build from source

If you choose to clone this repo, follow these instructions:

git clone
cd imgui_bundle
git submodule update --init --recursive # (1)
mkdir build
cd build
make -j
  1. Since there are lots of submodules, this might take a few minutes

  2. The flag -DIMMVISION_FETCH_OPENCV=ON is optional. If set, a minimal version of OpenCV will be downloaded a compiled at this stage (this might require a few minutes)

The immvision module will only be built if OpenCV can be found. Otherwise, it will be ignored, and no error will be emitted.

If you have an existing OpenCV install, set its path via:

cmake .. -DOpenCV_DIR=/.../path/to/OpenCVConfig.cmake

==== Run the C++ demo

If you built ImGuiBundle from source, Simply run build/bin/demo_imgui_bundle.

The source for the demos can be found inside bindings/imgui_bundle/demos_cpp.

Consider demo_imgui_bundle as a manual with lots of examples and related code source. It is always available online