imgui refactor by kushalkolar · Pull Request #1066 · fastplotlib/fastplotlib

kushalkolar · 2026-07-25T01:29:53Z

Replace EdgeWindow with ImguiWindow which can be located on an edge, floating, or fixed-rect windows. Can create with a single function containing UI elements decorate a function of imgui UI element calls.
Can append to ImguiWindow instances.
replace HistogramLUTTool with an imgui ImguiColorbar.
Revamped popup API, now ImguiPopup. Supports appending too.
window menu example by overriding draw() and having full control.
imgui docs guide and reference containing all elements with images.

Not related to imgui but made it anyways:

ImageGamma graphic feature.

Replace `HistogramLUTTool` with an imgui created one: `ImguiColorbar` that can also just be a colorbar. This is gives us higher performance so we don't have to create lots of docks when there are lots of images.

allow floating or fixed-location windows

decorators for add and append for `ImguiWindow` and `ImguiPopup` and easier, cleaner API to add popups/right-click menus.

# a floating window is auto-sized by imgui and can be dragged by the user
@figure.add_imgui_window(location="floating", title="floating", window_flags=imgui.WindowFlags_.none)
def floating_gui(fig):
    if imgui.button("randomize"):
        fig[0, 0]["image"].data = np.random.rand(128, 128)

For popup, can be figure, subplot, or graphic level. Can also append to the standard right click menu on a figure:

# append elements to the standard right-click menu
@figure.append_imgui_right_click()
def more_items(fig):
    imgui.separator()
    if imgui.menu_item("Autoscale all subplots", "", False)[0]:
        for subplot in fig:
            subplot.auto_scale()


# a popup set on a subplot replaces the standard menu within that subplot
@figure[0, 1].set_imgui_right_click()
def line_popup(subplot):
    imgui.text(f"subplot: {subplot.name}")
    imgui.separator()
    _, line.thickness = imgui.slider_float("thickness", line.thickness, 1.0, 20.0)
    changed, color = imgui.color_edit3("color", tuple(float(c) for c in line.colors)[:3])
    if changed:
        line.colors = (*color, 1.0)

# a popup can contain any imgui elements, it is not restricted to menu items
def image_processing(image):
    ui = image.metadata

    imgui.text(image.name)
    imgui.separator()

    changed_noise, ui["noise"] = imgui.slider_float("noise sigma", ui["noise"], 0.0, 100.0)
    changed_filter, ui["filter"] = imgui.checkbox("gaussian filter", ui["filter"])

    imgui.begin_disabled(not ui["filter"])
    changed_sigma, ui["sigma"] = imgui.slider_float("filter sigma", ui["sigma"], 0.1, 10.0)
    imgui.end_disabled()

    if imgui.button("reset"):
        ui.update(noise=0.0, sigma=1.0, filter=False)
        changed_noise = True

    if changed_noise or changed_filter or changed_sigma:
        data = raw[image] + np.random.normal(scale=ui["noise"], size=raw[image].shape)

        if ui["filter"]:
            data = gaussian_filter(data, sigma=ui["sigma"])

        image.data = data

can append to an imgui window or subplot toolbar:

# create an edge window
@figure.add_imgui_window(location="right", size=200, title="controls")
def gui(fig):
    if imgui.button("randomize"):
        fig[0, 0]["line"].data[:, 1] = np.random.rand(100)


# append more elements to the same window
@figure.append_imgui_window(location="right")
def more(fig):
    line = fig[0, 0]["line"]
    _, line.thickness = imgui.slider_float("thickness", v=line.thickness, v_min=2.0, v_max=50.0)


# append a button to the subplot toolbar that toggles axes visibility
@figure[0, 0].append_imgui_window(location="toolbar")
def toolbar_extra(subplot):
    imgui.same_line()
    _, subplot.axes.visible = imgui.checkbox(fa.ICON_FA_RULER_COMBINED, subplot.axes.visible)
    if imgui.is_item_hovered(0):
        imgui.set_tooltip("Axes visibility")

location can be the edge of Subplot and not just edges of a Figure

See the colorbar examples which add it to the right edge of a subplot.

LLM Disclosure: claude on ultracode setting was babysat through this, every line was reviewed, everything tested manually.

kushalkolar · 2026-07-25T14:15:02Z

We have our own imgui API docs that corresponds to imgui_bundle so we don't have to refer to pyimgui and then consolidate the differences with imgui_bundle by looking at the source :D

kushalkolar · 2026-07-25T14:20:39Z

@FlynnOConnell

Comments on the API? You've been asking for this for ages.

Here's the imgui docs guide as an html as it currently is in the docs:
guide.html

FlynnOConnell · 2026-07-26T20:33:14Z

This is amazing. My previous widgets would be much better suited as a floating window because we want as much data visible as possible.

In the future this could be extended to allowing users to switch between floating and sticky maybe via a default right click menu for each newly created ImguiWindow. "Dock Left" "Dock Right" etc. could go in this menu as well.

For the colorbar, I think switching begin_popup_context_item -> begin_popup_context_window makes sense so that right-clicking anywhere in the widget should bring up the cmap selection choices, I know examples of users missing this functionality.

kushalkolar · 2026-07-26T22:42:16Z

I'll leave the docking functionality to you once you get to UTSWMC 😆

kushalkolar · 2026-07-27T15:41:37Z

changed colorbar/hlut window to bring up colormap popup if it's right clicked anywhere and not just the colorbar.

clewis7 · 2026-07-27T18:58:44Z

No deployments on this branch???

kushalkolar · 2026-07-27T19:01:38Z

No deployments on this branch???

You mean docs? yea because only branches targetting main run through CI, this targets ndwidget branch. so I tested the docs build locally.

* start ndprocessors * basic timeseries * add __init__ * heatmap for timeseries works! * NDPositions, basics work, reorganize, increase default scatter size * black * NDPositions working with multi-dim stack of lines, need to test window funcs * scatter collection * progress, need to change to other branch so committing * better * interpolation for heatmap * better place for check * window functions working on n_datapoints dim * p dim window funcs working for single and multiple dims I think * black * index_mappings is working I think, lightly tested on p dim * remove nd_timeseries since nd_positions is sufficient * auto-replace buffers (#974) * remove isolated_buffer * remove isolated_buffer from mixin * basics works for positions data * replaceable buffers for all positions related features * image data buffer can change * resizeable buffers for volume * black * buffer resize condition checked only if new value is an array * gc for buffer managers * uniform colors WIP * switching color modes works! * typo * balck * update tests for color_mode * update examples * backend tests passing * default for all uniforms is True * update examples * forgot * update test * example tests passing * dereferencing test and fixes * simplify texture array tests a bit * image replace buffer tests pass yay * forgot a file * comments, check image graphic * add image reshaping example * add buffer replace imgui thing for manual testing * black * dont call wgpu_obj.destroy(), seems to work and clear VRAM with normal dereferencing * slower changes * update * update example * fixes and tweaks for test * remove unecessary stuff * update * docstrings * fix example * update example * update example * update docs * some basic OOC working * max num of dipslay datapoints * scatter stack, not tested * progress * scatter collection updates * tootip handlers for ndpositions * refactoring, general NDPP_Pandas processor for any dataframe data * separate array logic and graphic logic in `ImageWidget` (#868) * start separating iw plotting and array logic * some more basics down * comment * collapse into just having a window function, no frame_function * progress * placeholder for computing histogram * formatting * remove spaghetti * more progress * basics working :D * black * most of the basics work in iw * fix * progress * progress but still broken * flippin display dims works * camera scale must be positive for MIP rendering * a very difficult to encounter iterator bug! * patch iterator caveats * mostly worksgit status * add ArrayProtocol * rename * fixes * set camera orthogonal to xy plane when going from 3d -> 2d * naming, cleaning * cleanup, correct way to push and pop dims * quality of life improvements * new histogram lut tool * new hlut tool * imagewidget rgb toggle works * more progress * support rgb(a) image volumes * ImageGraphic cleanup * cleanup, docs * fix * updates * new per-data array properties work * black formatting * fixes and other things * typing tweaks * better iterator, fix bugs * fixes * show tooltips in right clck menu * ignore nans and inf for histogram * histogram of zeros * docstrings * fix imgui pixels * iw indices event handlers only get a tuple of the indices * bugfix * fix cmap setter * spatial_func better name * bugfix * hist specify quantile * fix typos (#991) * fix typos * add rendercanvas to intersphinx_mapping * nd-iw backup * correct ImageGraphic w.r.t. ndw * last fixes in ndi * update * basic minimal ndw orchestration working * implement auto-x for timeseries * bugfix update worldobject -> graphic map for image tiles * bugfix linear selector set limits * linear selector for timeseries * return full data if display_window is Noen * arrow key to step indices * imgui separator * fix and ui stuff * both auto x range modes working * progress * moving stuff * much much better organization of things * GlobalIndexVector working with ndpostions and ndimage * examples * progress * do not reset vmin vmax when replacing Image buffer * WIP migrate to xarray * window funcs in NDProcessor class using xarray, WIP, not tested * typo * basic single index slicing working with xarray * window funcs working for NDPositions and NDPP_Pands * display_window window funcs working for NDPositions * imgui stuff * finish migrate NDImage to xarray, basics work * NDImage working mostly, behavior viz is back * better flipping logic * update examples * more progress * update example * histogram working for images * NDProcessor property aliases * more aliasing * fix * update example * fix * ui * cleanup old iw-array, imports, add deprecation warning on old iw * add ndwidget section to deps with xarray * nice repr for NDProcessor * imgui right click menu for ndgraphics * better * controller options separate window * update imgui * fix * fix compute histogram * other features WIP * basics of other features works with ScatterStack for colors, markers, sizes, need to keep testing * require min pygfx v0.16.0 due to gc hash fix necessary for NDWidget * fix PlotArea.y_range * fix to create isolated buffer for colors when buffer replaced * np.empty * cmap_transform_each WIP * progress * fix * replace graphic when data changed, tweak index_mappings * Update installation docs (#1013) * add simplejpeg to notebook deps * Update guide.rst * Update guide.rst * Update README.md * cmap lib handles image colormaps now * multi-windows ndwidget, maintain features like cmap when switching graphics * progress * lighting objects only when a mesh is added * fix * update axes only when camera or view changes * clean heatmap func * stupid print * docstrings, comments * remove unused attr, comments * remove print * add NDGraphic.pause, expose histogram widget * ndg pause in imgui * add helper function to convert heatmap timeseries to postional data shape * index wans't calling handlers * remove * allow image types other than float32 (#1027) * Includes code for doing batched transforms in both directions (#1025) * Includes code for doing batched transforms in both directions * Streamlined parsing logic and updated docstrings for model to world code * Fixes inconsistent error messages * More streamlined type checking * Gets rid of checks and uses np asarray * Some more aesthetic updates to the syntax * Update fastplotlib/graphics/_base.py --------- Co-authored-by: Kushal Kolar <kushalkolar@gmail.com> * async NDProcessor (#1026) * async NDProcessor established, NOT TESTED * ASYNC NDPROC IS WORKING :D :D CELEBRATE * comments * type annot * fix * fix * polish async integration, cuda also integrated * no longer using xarray, allow simpler ArrayProtocol * comments * comments * docs * forgot to set back to False * remove xarray from pyproject.toml * throttling * Adds nd vector graphic (#1034) * Includes nd vector code that works * Faster position assignment, no more for loop * Batched computations for vector set function * Formatting updates * Includes improved annotations and changes ordering of the data slice from the vectors graphic * Some further improvements to the pylinalg code * Fixes remaining formatting and naming issues * Apply suggestions from code review Co-authored-by: Kushal Kolar <kushalkolar@gmail.com> --------- Co-authored-by: Kushal Kolar <kushalkolar@gmail.com> * Adds kwargs so user can customize vector field estimates (#1036) * Adds kwargs so user can customize vector field estimates * Does the kwarg organization the way ndpositions does * fixes graphic constructor * implement yuv and other colorspaces and "bufferless" `TextureArray` (#1033) * implement yuv and 'bufferless' TextureArraY * unbuffered and yuv420 works * warning on tooltip * NDImage always uses unbuffered, support colorspaces in NDIMage * update docstrings * by default disable AA and set pixel_scale=1.0 for performance * unpacked yuv support * independent graphics and texture features for rgb and yuv * docstrings * docstrings * import order * yuv graphic working nicely * add enum to top level namespace * update script to produce add graphics mixin * add yuv example * update ndimage with yuv stuff * fixes * yuv video working well with NDWidget * cleanup * `SelectionVector`, `HighlightSelector`, `VisibilitySelector`, `SelectorCollection` (#1038) * start selection vector stuff, protocol * highlight selector WIP * fixes * progress * lut repeat * highlight and visibility selectors working, selection vector working * PlotArea checks for SelectorProtocol instead, move some stuff around * selector collection, not yet tested * cleanup * bugfix for linear selector limits * add example * better append, remove * cleanup * basically rewrote entire ImageHighlightSelector * black * happy with iamge selectors * toy multi session example * correct mapping stuff * better scalar/vector handling * comments * compute capabilities (#1040) * allow setting texture usage directly * ImageHighlightSelector, VisibilitySelector and ImageVisibilitySelector can handle 'None' as placeholders in the selection * fix example * comments * better axes padding for tick labels, settable axis label (#1049) * better axes padding for tick labels, settable axis label * cleanup * move axes to tools * update * move stuff around * update docs * update * update * use fully fledged async, `NDPositions` improvements (#1050) * use fully fledged async * better throttling * torch.Tensor.tranpose() doesn't like tuples * we need time-based throttling, but it can be gentler * improvements * improvements * fixes * x_range fix * fix NDPandasProcessor * fix * HighlightSelector fix to append None * cleanup better * know ndg current dipslayed indices * improve example * docstrings, cleanup * remove __array_ufunc__ from required attrs * do not require __array__() to be implemented for ndwidget * auto ref ranges * fix imgui * tear out NDTimeseries from NDPositions * imgui refactor (#1066) * start imgui window refactor * update w.r.t. imgui changes * imgui hlut colorbar stuff * better focus logic * imgui popup stuff * update docs * update examples, remove HistogramLUTTool * update examples * imgui menubar example * update docs, tweaks * docs * doc fixes * docs * fix * right click anywhere in colorbar/hlut window * inf line, dashing, thin bool (#1064) * Create partial_camera_linking.py (#1020) * inf line, dashing, thin bool * tests * new screenshots * Selection vector improve (#1061) * Full selection vector implementation * Includes some documentation at top of SelectionVector * Minor typing fix in linear selector selection setter * First working version with selection vector * Reworks the logic for adding selectors, improves some documentation, adds partial instead of lambda functions, improves typing in highlight selector * Fixes casting bug in the integer version of the code * Update fastplotlib/graphics/selectors/_selection_vector.py * Update fastplotlib/graphics/selectors/_selection_vector.py * Removes unused init time parameter and also updates the typing on the default inverse mapping function to always return an integer * Adds a nonneg check in selection vector selection setter * Adds nonneg test for inverse handler --------- Co-authored-by: Kushal Kolar <kushalkolar@gmail.com> * Includes basic np dlpack function that is tested to work across jax a… (#1067) * Includes basic np dlpack function that is tested to work across jax and torch * delays dimension permutation for all code that uses ndprocessor * Eliminates old comment * Updates the numpy dep to be the min version that allows dlpack conversion across devices * Includes code to update spatial dims indices whenever spatial dims is changed * Moves the spatial dims indices computation to the read only property in the base class, updates docs, uses public property in the ndprocessor subclasses * Filters for None values in the inv handler (#1073) * bugfix after last PR * alpha is material.opacity (#1074) * clamp vmin, vmax in colorbar histogram LUT tool (#1076) * Flat graphic features 2nd edition (#1072) * refactor cmap and cmap_transform for positional graphics * color mode stuff * WIP * more WIP * better add_graphic autogen * more progress * mostly done refactoring positions graphics cmap stuff * forgot to update mixin * cmap_transform tweaks * wip, JaggedArray * mostly works, writing tests * remove a print * image collection examples * fix * feature inheritance in PositionsGraphic and cmap_range * cmap handling * cmap tweaks * remove parse_cmap_values, rely on cmap lib * fix example, remove unused line of code * Image just uses cmap lib now too * delete_ndgraphic() * ndtimeseries cmap example * steps for stacks * ndtimeseries sets stack steps * docstrings * docstrings * comments * renames * docstring * fixes * update tests/test_colors_buffer_manager.py * update test_markers_buffer_manager.py * update plot_helpers test * update test_point_rotations_buffer_manager.py * update test_positions_graphics.py * update another test * more tests * update yet more tests * remove unused * infline tests * collections tests * updating examples, wip * more examples updates * more examples updates * more example updates * more example updates * example and docstring * docstring * remove complex line collection slicing example, stick with real usecases * better line stack example * update example * update example * update link * update more examples * examples and fixes * fix * more fixes * fix * updates * Fix * update docs * docs * add image collection to docs conf.py * update docs * Ndw rename consistency (#1078) * rename for consistency * more consistency * more * final renames * fix * cursor fix * missed renames * pandas fix * restore ImageWidget, auto-collapse NDWidget sliders UI if no slider dims and no appended UIs * imagewidget stuff * ImageVolumeGraphic args fix * NDWSubplot dims check only for array-like * collapsed property on ImaguiWindoW * update iw examples * colorbar fix * lingering rename * fix * type * clim_quantile for NDImage, other fixes * public 'max_display_datapoints' property * dw setter * imgui right click for NDGraphics * axes label tweaks * remove unused zarr placeholder * fix docstring * config system (#1080) * basic scaffold done * inheritance * done * config works! * config on graphics * axes config * full config implementation basically works * fix * mixins call Graphic construtors with kwargs nothing is positional * print * config presets * comments, docstrings * docstrings * remove ConfigValue * comments * much better add graphics mixin using descriptors, examples, fix a test * anotehr example * GlobalConfig.to_dict() * docs * reset to default config after each screenshot test * add_<graphics>() stub generator, fix maintain_aspect logic w.r.t. config stuff * change so maintain_aspect can be tested better * docstring * reset config after running each docs gallery examle * better example * docs * remove randon shit * ndw stuff is all top level importable, move types to utils * fix black * fix import * matplotlib migration docs * wording * uncommnet iw for docs conf.py * update example * update * update * temp skip nds_extras in docs * temp comment out vis selector example * fix usage args * just make usage a kwarg to ImageGraphic * update api docs stuff * update example * fix docstrings etc. * type annots * ndw import stuff * docs for nds extras * docs reqs * nds extras * ReferenceIndices.pop_dims * graphics stubs * fix for None data, remove delete_ndgraphic() for now * collections stubs * ndw docs, WIP * ndw guide * types fix * better axes ticks text outline, WIP on ndwidget playback in docs, stubs * ndw animate in docs works * fix display_dims bug * remove tranpose from ArrayProtocol * bugfix, spatial func stuff * ndw tests * black * more balck * add example * fixes * fix * update * other CI fiel * skip ndw and imgui test if not present * garbage collection of graphics in imgui popup * temp imgui ping * fix * update CI * Update screenshots.yml * update screenshots * fix docstrings * update test thresholds, remove line dashing from screenshot tests * update api docs * another example * skip testing an example * higher RMSE threshold on mac because I am so done with this shit * Update ci.yml * Update ci-pygfx-release.yml --------- Co-authored-by: Amol Pasarkar <amolpasarkar@gmail.com> Co-authored-by: Flynn <75346097+FlynnOConnell@users.noreply.github.com> Co-authored-by: Caitlin Lewis <caitlin9165@gmail.com>

kushalkolar added 2 commits July 23, 2026 22:45

start imgui window refactor

098ff78

update w.r.t. imgui changes

f6fd14b

kushalkolar changed the title ~~New hlut cbar~~ imgui refactor Jul 25, 2026

kushalkolar added 12 commits July 24, 2026 22:53

imgui hlut colorbar stuff

264dc0e

better focus logic

e00f269

imgui popup stuff

de66427

update docs

31804d2

update examples, remove HistogramLUTTool

7c71c8c

update examples

eeabf7d

imgui menubar example

546f430

update docs, tweaks

69ae248

docs

703c903

doc fixes

88c9b82

docs

6251cad

fix

6920ab7

kushalkolar marked this pull request as ready for review July 25, 2026 14:20

kushalkolar requested a review from clewis7 as a code owner July 25, 2026 14:20

right click anywhere in colorbar/hlut window

fba3b03

clewis7 approved these changes Jul 27, 2026

View reviewed changes

kushalkolar merged commit 91faf5b into ndwidget Jul 27, 2026

kushalkolar deleted the new-hlut-cbar branch July 27, 2026 19:02

This was referenced Aug 4, 2026

Providing API docs similar to pyimgui pthom/imgui_bundle#491

Open

@Figure.add_gui and append_gui decorators #849

Closed

kushalkolar mentioned this pull request Aug 5, 2026

propose getting rid of subplot docks for better performance #1031

Closed

Navigation Menu

imgui refactor - #1066

imgui refactor#1066
kushalkolar merged 15 commits into
ndwidgetfrom
new-hlut-cbar

kushalkolar commented Jul 25, 2026 •

edited

Loading

Uh oh!

kushalkolar commented Jul 25, 2026

Uh oh!

kushalkolar commented Jul 25, 2026 •

edited

Loading

Uh oh!

FlynnOConnell commented Jul 26, 2026

Uh oh!

kushalkolar commented Jul 26, 2026

Uh oh!

kushalkolar commented Jul 27, 2026

Uh oh!

clewis7 commented Jul 27, 2026

Uh oh!

kushalkolar commented Jul 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

kushalkolar commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Replace HistogramLUTTool with an imgui created one: ImguiColorbar that can also just be a colorbar. This is gives us higher performance so we don't have to create lots of docks when there are lots of images.

allow floating or fixed-location windows

decorators for add and append for ImguiWindow and ImguiPopup and easier, cleaner API to add popups/right-click menus.

can append to an imgui window or subplot toolbar:

location can be the edge of Subplot and not just edges of a Figure

LLM Disclosure: claude on ultracode setting was babysat through this, every line was reviewed, everything tested manually.

Uh oh!

kushalkolar commented Jul 25, 2026

Uh oh!

kushalkolar commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FlynnOConnell commented Jul 26, 2026

Uh oh!

kushalkolar commented Jul 26, 2026

Uh oh!

kushalkolar commented Jul 27, 2026

Uh oh!

clewis7 commented Jul 27, 2026

Uh oh!

kushalkolar commented Jul 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kushalkolar commented Jul 25, 2026 •

edited

Loading

Replace `HistogramLUTTool` with an imgui created one: `ImguiColorbar` that can also just be a colorbar. This is gives us higher performance so we don't have to create lots of docks when there are lots of images.

decorators for add and append for `ImguiWindow` and `ImguiPopup` and easier, cleaner API to add popups/right-click menus.

kushalkolar commented Jul 25, 2026 •

edited

Loading