implot.Tk

Tcl/Tk bindings for ImPlot and ImPlot3D : fast interactive 2D / 3D plots (GPU, OpenGL) in a Tk widget.

Dependencies

• Tcl/Tk >= 9.0
• Tcl cffi >= 2.0
• TkGL : OpenGL widget for Tk
• A C library with through cimgui, cimplot and cimplot3d

Cross-Platform

• Windows, Linux, macOS support.

Installation

• Download the package of your platform from the GitHub Releases : it contains implot.tk, the C library and TkGL built for Tcl/Tk 9.
• Or build everything yourself, see lib/BUILD.md.

Quick start

package require implot.tk

# 1. Creates the surface (no Tk widget yet) and sets its options.
set f [implottk::surface new]
$f SetOptions -width 600 -height 400 -title "Line" -axisName {x y}

# 2. Adds the commands, evaluated at each frame.
$f AddPlotCmd {
    implottk::static {
        set xs [implottk::doubleToPointer {0 1 2 3 4}]
        set ys [implottk::doubleToPointer {0 1 0.5 4 1}]
    }
    implot::PlotLine_doublePtrdoublePtr "Line 1" $xs $ys 5 {LineColor {x 1 y 0 z 0 w 1}}
}

# 3. Render creates the Tk widget and returns its path, 4. pack it.
pack [$f Render] -fill both -expand 1

Options of the surface

Option	Value	Default
-width, -height	size of the widget (pixels)	600, 400
-title	title of the plot added by the surface (##... : hidden)	##title
-axisName	names of the axes {x y} of the plot added by the surface	{}
-background	color of the window {r g b}, {} : color of the theme	{}
-color	ImGui colors {windowBackground {r g b} popupBackground {r g b} text {r g b}}	-
-colorPlot	ImPlot colors {plotBackground .. frameBackground .. axisText .. legendBackground .. legendText ..}	-
-fonts	{file.ttf size}, or a Tk font {TkDefaultFont ?size?}	ImGui font
-idleFps	frames per second without event	10
-framebufferScale	pixels per Tk unit (e.g. 2.0 on a retina display)	1.0

Scripts

Note

Dear ImGui is an immediate mode GUI : the scripts are evaluated at each frame, AddGuiCmd scripts first (widgets : sliders, checkboxes...), then AddPlotCmd scripts (plots). Every function declared in src/imgui/funcs.tcl, src/implot/funcs.tcl and src/implot3d/funcs.tcl can be called.

The style of an item is an ImPlotSpec, written as a dictionary (missing fields keep their default value) :

implot::PlotLine_doublePtrdoublePtr "Line 2" $xs $ys 5 {
    LineColor  {x 0 y 0.5 z 1 w 1}
    LineWeight 2
    Marker     ImPlotMarker_Circle
    Flags      ImPlotLineFlags_Segments
}

When a script calls implot::BeginPlot itself, the other ImPlot functions must only be called when it returns true.

Variables of the scripts :

implottk::static initializes the data only the first time :

$f AddPlotCmd {
    # a script evaluated only the first time...
    implottk::static {
        set rectXMin 0.0025 ; set rectYMin 0.0
        set rectXMax 0.0045 ; set rectYMax 0.5
    }
    # ... or pairs 'name value'.
    implottk::static flags 0

    imgui::CheckboxFlags_UintPtr "NoCursors" flags 1
    if {[implot::BeginPlot "##Main"]} {
        implot::DragRect 0 rectXMin rectYMin rectXMax rectYMax {x 1 y 0 z 1 w 1} $flags clicked hovered held
        implot::EndPlot
    }
}

Supported plots

• line, shaded, scatter, stairs, stems, infinite lines
• bars (vertical / horizontal / stacked, groups), error bars
• pie charts, heatmaps, 1D / 2D histograms
• bubbles, polygons, digital plots, text, dummy
• getters (PlotLineG)
• images
• 3D (ImPlot3D) : line, scatter, triangle, quad, surface and mesh plots, text

Examples

See demo folder.

Known issues

• macOS : On a retina display set -framebufferScale 2.0 (not tested yet).
• Calling an ImPlot function outside of a plot (when BeginPlot returned false) can crash the application.
• And probably many others...

Inspiration

• opengl-tcltk
• Tcl cffi examples

License

implot.tk is covered under the terms of the MIT license. The packages also contain Dear ImGui, ImPlot, ImPlot3D, cimgui, cimplot, cimplot3d and TkGL, under their own licenses : see THIRD_PARTY_NOTICES.md.

Release

• 15-Sep-2022 : 1.0b0
• 19-Sep-2022 : 1.0b1
  • Add SubplotsSizing + SubplotItemSharing (drag & drop) demo.
  • Cosmetic changes + adding imgui functions.
• 01-Oct-2022 : 1.0b2
  • Add examples.
  • Fix bug when my frame was mapped or unmapped.
  • Rename win32.tcl file by user32.tcl
• 08-Oct-2026 : 1.0
  • Full redesign of the library.
  • More examples and GitHub Actions.