Python bindings

[brenocq]

@pthom did some amazing work in imgui_bundle to create python bindings for ImPlot3D.

The discussion about imgui_bundle started in #43 and was moved here to better track the feature progress and potential changes to the ImPlot3D API.

Thanks for the heavy work @pthom!

[brenocq]

@pthom provided the following example in #43

from imgui_bundle import imgui, immapp, implot3d
import numpy as np


def demo3d_lineplots():
    xs1 = np.linspace(0, 1, 1001)
    ys1 = 0.5 + 0.5 * np.cos(50 * (xs1 + imgui.get_time() / 10))
    zs1 = 0.5 + 0.5 * np.sin(50 * (xs1 + imgui.get_time() / 10))

    xs2 = np.linspace(0, 1, 20)
    ys2 = xs2 * xs2
    zs2 = xs2 * ys2

    if implot3d.begin_plot("Line Plots"):
        implot3d.setup_axes("x", "y", "z")
        implot3d.plot_line("f(x)", xs1, ys1, zs1)
        implot3d.set_next_marker_style(implot3d.Marker_.circle.value)
        implot3d.plot_line("g(x)", xs2, ys2, zs2, implot3d.LineFlags_.segments.value)
        implot3d.end_plot()


immapp.run(demo3d_lineplots, with_implot3d=True)

I tried testing it locally following these commands:

python -m venv .env
source .env/bin/activate.fish
pip install imgui-bundle
pip install opencv-python
pip install pyGLM
python imgui_bundle.py

However, I got the following error:

Traceback (most recent call last):
  File "/home/breno/Downloads/bundle-test/imgui_bundle.py", line 1, in <module>
    from imgui_bundle import imgui, immapp, implot3d
  File "/home/breno/Downloads/bundle-test/imgui_bundle.py", line 1, in <module>
    from imgui_bundle import imgui, immapp, implot3d
ImportError: cannot import name 'imgui' from partially initialized module 'imgui_bundle' (most likely due to a circular import) (/home/breno/Downloads/bundle-test/imgui_bundle.py)

Here is the pip freeze for reference

annotated-types==0.7.0
glfw==2.8.0
imgui-bundle==1.6.1
munch==4.0.0
numpy==2.2.1
opencv-python==4.10.0.84
pillow==11.1.0
pydantic==2.10.4
pydantic_core==2.27.2
PyGLM==2.7.3
PyOpenGL==3.1.7
typing_extensions==4.12.2

Let me know if I did something wrong! I would love to test the python bindings :)

[pthom]

I suppose you looked at the install instruction here.
However, I do not know where you found this instruction "python imgui_bundle.py" (is one of my documentation page inaccurate?)

Anyhow, you were very close to the solution: you should have run

> demo_imgui_bundle

However, this will install imgui_bundle v1.6.1 which does not include implot3d yet.

If you want to give a try to a version which includes implot3D, you can download a recent wheel from the wheels CI. The latest wheels are available here.

From there you unzip it, then pip install the wanted whl file, then you run demo_imgui_bundle. You can even copy paste the code I gave you, it should work.
Note: there is a demo for ImPlot and ImPlot3D, where you can access the python code:

v.mp4

[brenocq]

However, I do not know where you found this instruction "python imgui_bundle.py" (is one of my documentation page inaccurate?)

Hey! I created the file imgui_bundle.py with the example code before running those commands

from imgui_bundle import imgui, immapp, implot3d
import numpy as np


def demo3d_lineplots():
    xs1 = np.linspace(0, 1, 1001)
    ys1 = 0.5 + 0.5 * np.cos(50 * (xs1 + imgui.get_time() / 10))
    zs1 = 0.5 + 0.5 * np.sin(50 * (xs1 + imgui.get_time() / 10))

    xs2 = np.linspace(0, 1, 20)
    ys2 = xs2 * xs2
    zs2 = xs2 * ys2

    if implot3d.begin_plot("Line Plots"):
        implot3d.setup_axes("x", "y", "z")
        implot3d.plot_line("f(x)", xs1, ys1, zs1)
        implot3d.set_next_marker_style(implot3d.Marker_.circle.value)
        implot3d.plot_line("g(x)", xs2, ys2, zs2, implot3d.LineFlags_.segments.value)
        implot3d.end_plot()


immapp.run(demo3d_lineplots, with_implot3d=True)

Sorry I'm not very familiar with imgui_bundle so I supposed that's what I needed to do to test the minimal example hahah

When I execute demo_imgui_bundle I get the following error:

For information, demos sources are available in /home/breno/Downloads/test_imgui_bundle/.env/lib/python3.12/site-packages/imgui_bundle/demos_python
Traceback (most recent call last):
  File "/home/breno/Downloads/test_imgui_bundle/.env/bin/demo_imgui_bundle", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/breno/Downloads/test_imgui_bundle/.env/lib/python3.12/site-packages/imgui_bundle/demos_python/demo_imgui_bundle.py", line 139, in main
    immapp.run(runner_params=runner_params, add_ons_params=addons)
  File "/home/breno/Downloads/test_imgui_bundle/.env/lib/python3.12/site-packages/imgui_bundle/demos_python/demo_imgui_bundle.py", line 78, in win_fn
    show_module_demo(demo_module_name, demo_module.demo_gui)
  File "/home/breno/Downloads/test_imgui_bundle/.env/lib/python3.12/site-packages/imgui_bundle/demos_python/demo_imgui_bundle.py", line 28, in show_module_demo
    demo_function()
  File "/home/breno/Downloads/test_imgui_bundle/.env/lib/python3.12/site-packages/imgui_bundle/demos_python/demo_imgui_show_demo_window.py", line 45, in demo_gui
    imgui.show_demo_window()
RuntimeError: IM_ASSERT( g.CurrentDpiScale > 0.0f && g.CurrentDpiScale < 99.0f )   ---   imgui.cpp:15655

---

Since I was having those problems with pip, I also tried building it from the source. This worked without problems to execute demo_imgui_bundle!

After building from source I tried creating the file imgui_bundle.py with the minimal example and execute it with python imgui_bundle.py, but got the following error:

Traceback (most recent call last):
  File "/home/breno/Downloads/imgui_bundle/imgui_bundle.py", line 1, in <module>
    from imgui_bundle import imgui, immapp, implot3d
  File "/home/breno/Downloads/imgui_bundle/imgui_bundle.py", line 1, in <module>
    from imgui_bundle import imgui, immapp, implot3d
ImportError: cannot import name 'imgui' from partially initialized module 'imgui_bundle' (most likely due to a circular import) (/home/breno/Downloads/imgui_bundle/imgui_bundle.py)

Please let me know if I'm doing something wrong :)

[pthom]

Hey! I created the file imgui_bundle.py with the example code before running those commands

from imgui_bundle import imgui, immapp, implot3d
...

ImportError: cannot import name 'imgui' from partially initialized module 'imgui_bundle'

I understand now: the first line from imgui_bundle import imgui, immapp, implot3d should mean "import from the pypi package". However the presence of imgui_bundle.py takes precedence! Just rename this file to anything but imgui_bundle.py :-)

IM_ASSERT( g.CurrentDpiScale > 0.0f && g.CurrentDpiScale < 99.0f )

I need to release a corrective patch today (v1.6.2). It will correct this, and add support for ImPlot3D !

[brenocq]

I understand now: the first line from imgui_bundle import imgui, immapp, implot3d should mean "import from the pypi package". However the presence of imgui_bundle.py takes precedence! Just rename this file to anything but imgui_bundle.py :-)

HAhahhah I chose the one name I shouldn't have. After renaming it it worked super well!! I'll start using your imgui_bundle instead of matplotlib from now on :)

I need to release a corrective patch today (v1.6.2). It will correct this, and add support for ImPlot3D !

Uhuuul! 🎊

[brenocq]

@pthom in #43

The integration went smoothly. I had to make a fork for implot3d, since one part of the API was impossible to port to python without manual adjustments (see this commit which adapts the API for PlotSurface for Python bindings)

We can discuss in this thread about the potential API change for ImPlot3D.

[brenocq]

I don't mind having two signatures for the SurfacePlot. Ideally, we would have only one method to avoid confusing some users, but having two signatures sounds worth it if it is the only way to get SurfacePlot Python binding.

[pthom]

At the moment, I do have a fork (which I also have for ImPlot). It is not a very big deal, since I maintain there minimal changes, and having two API might end up being very confusing for C++ users.

See changes:
https://github.com/pthom/implot3d/blob/b6e2e817188233ea76b6e059b694adaad1fb6167/implot3d.h#L388-L411
(Note: via IMGUI_BUNDLE_PYTHON_UNSUPPORTED_API and IMGUI_BUNDLE_PYTHON_API, I am able to select which API is published to Python)

Those changes are required for my automatic binding generator (litgen).

litgen offers sophisticated handling of buffers between C++ (bare pointers) and Python (numpy arrays): see relevant doc

However, to achieve this magic, it needs a parameter which is the exact count of items in the array(s), which was not the case for SurfacePlot.

I'm not sure there is an easy way to have an API that is easily translatable between C++ and Python in this case.

[brenocq]

At the moment, I do have a fork (which I also have for ImPlot). It is not a very big deal, since I maintain there minimal changes, and having two API might end up being very confusing for C++ users.

Oooh that's great then! In that case from what I understood no changes to the source code will be needed in brenocq/implot3d right? So we could just update the README to talk about the python binding?

Those changes are required for my automatic binding generator (litgen).

Damn that's such a nice tool

[pthom]

At the moment, I do have a fork (which I also have for ImPlot). It is not a very big deal, since I maintain there minimal changes, and having two API might end up being very confusing for C++ users.

Oooh that's great then! In that case from what I understood no changes to the source code will be needed in brenocq/implot3d right? So we could just update the README to talk about the python binding?

Absolutely. No other change is required at the moment.

Those changes are required for my automatic binding generator (litgen).

Damn that's such a nice tool

Thanks :-) It took a lot of work to develop, but ended up being quite useful!

You can see the python equivalent of implot3d.h and implot3d_internal.h here:
https://github.com/pthom/imgui_bundle/tree/main/bindings/imgui_bundle/implot3d

Those are Python stubs that provide autocompletion and documentation from any Python IDE.

[pthom]

Here is another small "Haiku" using ImPlot3D

"""# Lorenz Attractor & Butterfly Effect
This is a simple example of the Lorenz Attractor. It shows two trajectories that diverge
because of a small initial difference, illustrating chaos theory in action.

The term **butterfly effect** in popular media may stem from the real-world implications
of the Lorenz attractor, namely that tiny changes in initial conditions evolve to
completely different trajectories.
"""

import numpy as np
from imgui_bundle import implot3d, immapp, imgui, imgui_md, hello_imgui
from dataclasses import dataclass


@dataclass
class LorenzParams:
    sigma: float = 10.0
    rho: float = 28.0
    beta: float = 8.0 / 3.0
    dt: float = 0.01
    max_size: int = 2000

PARAMS = LorenzParams()


class AnimatedLorenzTrajectory:
    def __init__(self, x, y, z):
        self.xs = np.array([x])
        self.ys = np.array([y])
        self.zs = np.array([z])

    def step(self):
        x, y, z = self.xs[-1], self.ys[-1], self.zs[-1]
        dx = PARAMS.sigma * (y - x)
        dy = x * (PARAMS.rho - z) - y
        dz = x * y - PARAMS.beta * z
        x += dx * PARAMS.dt
        y += dy * PARAMS.dt
        z += dz * PARAMS.dt

        self.xs = np.concatenate([self.xs, [x]])
        self.ys = np.concatenate([self.ys, [y]])
        self.zs = np.concatenate([self.zs, [z]])
        if len(self.xs) > PARAMS.max_size:
            self.xs = self.xs[-PARAMS.max_size:]
            self.ys = self.ys[-PARAMS.max_size:]
            self.zs = self.zs[-PARAMS.max_size:]


class CompareLorenzTrajectories:
    initial_delta = 0.1
    def __init__(self):
        self.init_trajectories()

    def init_trajectories(self):
        x, y, z = 0.0, 1.0, 1.05
        self.traj1 = AnimatedLorenzTrajectory(x, y, z)
        self.traj2 = AnimatedLorenzTrajectory(x + self.initial_delta, y, z)

    def gui_params(self):
        _, PARAMS.sigma = imgui.slider_float("Sigma", PARAMS.sigma, 0.0, 100.0)
        imgui.set_item_tooltip("Controls the rate of divergence between nearby points (chaos level).")

        _, PARAMS.rho = imgui.slider_float("Rho", PARAMS.rho, 0.0, 100.0)
        imgui.set_item_tooltip("Determines the size and shape of the attractor.")

        _, PARAMS.beta = imgui.slider_float("Beta", PARAMS.beta, 0.0, 10.0)
        imgui.set_item_tooltip("A damping parameter affecting vertical movement.")

        _, PARAMS.dt = imgui.slider_float("dt", PARAMS.dt, 0.0, 0.05)
        imgui.set_item_tooltip("Time step size for numerical integration (smaller is smoother).")

        _, self.initial_delta = imgui.slider_float("Initial Delta", self.initial_delta, 0.0, 0.2)
        imgui.set_item_tooltip("Initial difference between trajectories to demonstrate divergence.")

        if imgui.button("Reset"):
            self.init_trajectories()

    def gui_plot(self):
        if implot3d.begin_plot("Lorenz Attractor", hello_imgui.em_to_vec2(40, 40)):
            implot3d.setup_axes("X", "Y", "Z",
                                implot3d.AxisFlags_.auto_fit.value, implot3d.AxisFlags_.auto_fit.value, implot3d.AxisFlags_.auto_fit.value)
            implot3d.plot_line("Trajectory", self.traj1.xs, self.traj1.ys, self.traj1.zs)
            implot3d.plot_line("Trajectory2", self.traj2.xs, self.traj2.ys, self.traj2.zs)
            implot3d.end_plot()
        self.traj1.step()
        self.traj2.step()

    def gui(self):
        imgui_md.render_unindented(__doc__)
        imgui.separator_text("Parameters")
        self.gui_params()
        imgui.separator_text("Plot")
        self.gui_plot()


lorenz_comparer = CompareLorenzTrajectories()

immapp.run(lambda: lorenz_comparer.gui(),
           with_implot3d=True,
           with_markdown=True,
           window_size_auto=True,
           window_title="Butterfly Effect",
           fps_idle=0)

[brenocq]

This looks amazing!!! 😍

[pthom]

ImGui Bundle v1.6.2 is out and includes ImPlot3D:

• C++
• Python

[brenocq]

Amazing!!! I just tested it with:

pip install imgui-bundle
vim lorenz.py # Copy/paste your code here
python lorenz.py

and it worked without any problems!

[brenocq]

@pthom thank you soooo much for adding ImPlot3D to imgui-bundle! I'll be closing this discussion now (we can reopen it if you feel the need 🙂)