slimgui - ImPlot API reference

from slimgui import imgui
from slimgui import implot

Create an ImPlot context. Call this after imgui.create_context().

Destroys an ImPlot context. Call this before imgui.destroy_context(). None = destroy current context.

Returns the current ImPlot context. None if no context has ben set.

Sets the current ImPlot context.

Starts a 2D plotting context. If this function returns True, implot.end_plot() MUST be called! You are encouraged to use the following convention:

if implot.begin_plot(...):
    implot.plot_line(...)
    ...
    implot.end_plot()

Important notes:

• title_id must be unique to the current ImGui ID scope. If you need to avoid ID collisions or don't want to display a title in the plot, use double hashes (e.g. "MyPlot##HiddenIdText" or "##NoTitle").

• size is the frame size of the plot widget, not the plot area. The default size of plots (i.e. when (0,0)) can be modified in your implot.Style.

Only call implot.end_plot() if implot.begin_plot() returns True! Typically called at the end of an if statement conditioned on implot.begin_plot(). See example above.

if implot.begin_subplots("My Subplot", 2, 3, (800, 400)):
    for i in range(6):
        if implot.begin_plot(...):
            implot.plot_line(...)
            ...
            implot.end_plot()
    implot.end_subplots()

  [0] | [1] | [2]
  ----|-----|----
  [3] | [4] | [5]

See https://nurpax.github.io/slimgui/apiref_implot.html#subplots for details.

if implot.begin_plot(...):                     # 1) begin a new plot
    implot.setup_axis(im_axis_x1, "My X-Axis") # 2) make setup calls
    implot.setup_axis(im_axis_y1, "My Y-Axis")
    implot.setup_legend(im_plot_location_north)
    ...
    implot.setup_finish()                      # 3) [optional] explicitly finish setup
    implot.plot_line(...)                      # 4) plot items
    ...
    implot.end_plot()                          # 5) end the plot

Enables an axis or sets the label and/or flags for an existing axis. Leave label=None for no label.

Sets an axis range limits. If Cond.ALWAYS is used, the axes limits will be locked. Inversion with v_min > v_max is not supported; use implot.setup_axis_limits instead.

Sets the format of numeric axis labels via formater specifier (default="%g"). Formated values will be double (i.e. use %f). Note that the format string is specified in C printf syntax!

Sets an axis' ticks and optionally the labels. To keep the default ticks, set keep_default=True.

Sets an axis' scale using built-in options.

Sets an axis' limits constraints.

Sets an axis' zoom constraints.

Sets the label and/or flags for primary X and Y axes (shorthand for two calls to implot.setup_Axis()).

Sets the primary X and Y axes range limits. If Cond.ALWAYS is used, the axes limits will be locked (shorthand for two calls to implot.setup_axis_limits()).

Sets up the plot legend. This can also be called immediately after implot.begin_subplots() when using SubplotFlags.SHARE_ITEMS.

Set the location of the current plot's mouse position text (default = South|East).

Explicitly finalize plot setup. Once you call this, you cannot make anymore Setup calls for the current plot!

Note that calling this function is OPTIONAL; it will be called by the first subsequent setup-locking API call.

if imgui.button("Center Plot"):
    implot.set_next_axes_limits(-1, 1, -1, 1)
if implot.begin_plot(...):
    ...
    implot.end_plot()

Sets an upcoming axis range limits. If ImPlotCond_Always is used, the axes limits will be locked.

Set an upcoming axis to auto fit to its data.

Sets the upcoming primary X and Y axes range limits. If Cond.ALWAYS is used, the axes limits will be locked (shorthand for two calls to implot.setup_axis_limits()).

Sets all upcoming axes to auto fit to their data.

Plots a standard 2D line plot. The x values are spaced evenly along the x axis, starting at xstart and spaced by xscale. The y values are taken from the values array.

Plots a standard 2D line plot. The x values are taken from the xs array, and the y values are taken from the ys array.

Plots a standard 2D scatter plot. Default marker is Marker.CIRCLE.

Plots a stairstep graph. The y value is continued constantly to the right from every x position, i.e. the interval [x[i], x[i+1]) has the value y[i]

Plots a shaded (filled) region between two lines, or a line and a horizontal reference. Set yref to +/-INFINITY for infinite fill extents.

Plots a bar graph. Vertical by default. bar_size and shift are in plot units.

Plots a group of bars. values is a matrix with a shape (item_count, group_count). label_ids should have item_count elements.

Plots vertical error bar. The label_id should be the same as the label_id of the associated line or bar plot.

Plots a 2D heatmap chart. values is expected to have shape (rows, cols). Leave scale_min and scale_max both at 0 for automatic color scaling, or set them to a predefined range. label_fmt can be set to None for no labels.

Plots digital data. Digital plots do not respond to y drag or zoom, and are always referenced to the bottom of the plot.

Plots an axis-aligned image. bounds_min/bounds_max are in plot coordinates (y-up) and uv0/uv1 are in texture coordinates (y-down).

Plots a centered text label at point x,y with an optional pixel offset. Text color can be changed with implot.push_style_color(Col.INLAY_TEXT, ...).

Plots a dummy item (i.e. adds a legend entry colored by Col.LINE).

Plots a horizontal histogram. bins can be a positive integer or a method specified with the implot.Bin enum. If range is left unspecified, the min/max of values will be used as the range. Otherwise, outlier values outside of the range are not binned. The largest bin count or density is returned.

Plots two dimensional, bivariate histogram as a heatmap. x_bins and y_bins can be a positive integer or a method specified with the implot.Bin enum. If range is left unspecified, the min/max of xs an ys will be used as the ranges. Otherwise, outlier values outside of range are not binned. The largest bin count or density is returned.

The range parameter in plot_histogram2d is typed as a pair of float 2-tuples. The first element is the range (min,max) for xs, the second for ys.

Shows a draggable point at point. The updated drag position will be written to the point array. Color col defaults to imgui.Col.TEXT. out_clicked, out_hovered, and out_held are optional single bool np.arrays that will be set to True if the point is clicked, hovered, or held, respectively. Returns True if the point was dragged.

The input np.array arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to. See https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools for details.

Shows a draggable vertical guide line at an x-value. The updated drag position will be written to the x array. Color col defaults to imgui.Col.TEXT. out_clicked, out_hovered, and out_held are optional single bool np.arrays that will be set to True if the point is clicked, hovered, or held, respectively. Returns True if the line was dragged.

The input np.array arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to. See https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools for details.

Shows a draggable horizontal guide line at a y-value. The updated drag position will be written to the y array. Color col defaults to imgui.Col.TEXT. out_clicked, out_hovered, and out_held are optional single bool np.arrays that will be set to True if the line is clicked, hovered, or held, respectively. Returns True if the line was dragged.

The input np.array arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to. See https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools for details.

Shows a draggable rectangle at [[x0, y0], [x1, y1] coordinates, loaded from rect. The updated drag rectangle will be written to the point array. Color col defaults to imgui.Col.TEXT. out_clicked, out_hovered, and out_held are optional single bool np.arrays that will be set to True if the point is clicked, hovered, or held, respectively. Returns True if the rectangle was dragged.

The input np.array arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to. See https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools for details.

Shows an annotation callout at a chosen point. Clamping keeps annotations in the plot area. Annotations are always rendered on top.

Shows a x-axis tag at the specified coordinate value.

Shows a y-axis tag at the specified coordinate value.

Select which axis/axes will be used for subsequent plot elements.

Select which axis/axes will be used for subsequent plot elements.

Convert pixels to a position in the current plot's coordinate system. Passing implot.AUTO uses the current axes.

Convert a position in the current plot's coordinate system to pixels. Passing implot.AUTO uses the current axes.

Get the current Plot position (top-left) in pixels.

Get the curent Plot size in pixels.

Returns the mouse position in x,y coordinates of the current plot. Passing implot.AUTO uses the current axes.

Returns True if the plot area in the current plot is hovered.

Returns True if the axis label area in the current plot is hovered.

Returns True if the bounding frame of a subplot is hovered.

Returns True if the current plot is being box selected.

Cancels a the current plot box selection.

Hides or shows the next plot item (i.e. as if it were toggled from the legend).

Use Cond.ALWAYS if you need to forcefully set this every frame.

Align axis padding over multiple plots in a single row or column. group_id must be unique. If this function returns True, implot.end_aligned_plots() must be called.

Only call implot.end_aligned_plots() if implot.begin_aligned_plots() returns True!

Begin a popup for a legend entry.

End a popup for a legend entry.

Returns True if a plot item legend entry is hovered.

Turns the current plot's plotting area into a drag and drop target. Don't forget to call implot.end_drag_drop_target()!

Turns the current plot's X-axis into a drag and drop target. Don't forget to call implot.end_drag_drop_target()!

Turns the current plot's legend into a drag and drop target. Don't forget to call implot.end_drag_drop_target()!

Ends a drag and drop target (currently just an alias for imgui.end_drag_drop_target()).

Turns the current plot's plotting area into a drag and drop source. You must hold Ctrl. Don't forget to call implot.end_drag_drop_source()!

Turns the current plot's X-axis into a drag and drop source. You must hold Ctrl. Don't forget to call implot.end_drag_drop_source()!

Turns an item in the current plot's legend into drag and drop source. Don't forget to call implot.end_drag_drop_source()!

Ends a drag and drop source (currently just an alias for imgui.end_drag_drop_source()).

Provides access to plot style structure for permanant modifications to colors, sizes, etc.

Style plot colors for current ImGui style (default).

Style plot colors for ImGui "Classic".

Style plot colors for ImGui "Dark".

Style plot colors for ImGui "Light".

Temporarily modify a style color. Don't forget to call implot.pop_style_color()!

Undo temporary style color modification(s). Undo multiple pushes at once by increasing count.

Temporarily modify a style variable of int type. Don't forget to call implot.pop_style_var()!

Temporarily modify a style variable of float type. Don't forget to call implot.pop_style_var()!

Temporarily modify a style variable of float 2-tuple. Don't forget to call implot.pop_style_var()!

Undo temporary style variable modification(s). Undo multiple pushes at once by increasing count.

Set the line color and weight for the next item only.

Set the fill color for the next item only.

Set the marker style for the next item only.

Set the error bar style for the next item only.

Gets the last item primary color (i.e. its legend icon color)

Returns the string name for an implot.Col.

Returns the string name for an ImPlotMarker.

Returns the number of available colormaps (i.e. the built-in + user-added count).

Returns a string name for a colormap given an index. Returns None if index is invalid.

Returns an index number for a colormap given a valid string name. Returns -1 if name is invalid.

Temporarily switch to one of the built-in (i.e. ImPlotColormap_XXX) or user-added colormaps (i.e. a return value of implot.add_colormap()). Don't forget to call implot.pop_colormap()!

Push a colormap by string name. Use built-in names such as "Default", "Deep", "Jet", etc. or a string you provided to implot.add_colormap(). Don't forget to callimplot.pop_colormap()`!

Undo temporary colormap modification(s). Undo multiple pushes at once by increasing count.

Returns the next color from the current colormap and advances the colormap for the current plot.

Can also be used with no return value to skip colors if desired. You need to call this between implot.begin_plot()/implot.end_plot()!

Returns the size of a colormap.

Returns a color from a colormap given an index >= 0 (modulo will be performed).

Sample a color from the current colormap given t between 0 and 1.

Shows a vertical color scale with linear spaced ticks using the specified color map. Use double hashes to hide label (e.g. "##NoLabel"). If scale_min > scale_max, the scale to color mapping will be reversed.

Shows a button with a colormap gradient brackground.

When items in a plot sample their color from a colormap, the color is cached and does not change unless explicitly overriden. Therefore, if you change the colormap after the item has already been plotted, item colors will NOT update. If you need item colors to resample the new colormap, then use this function to bust the cached colors. If #plot_title_id is nullptr, then every item in EVERY existing plot will be cache busted. Otherwise only the plot specified by #plot_title_id will be busted. For the latter, this function must be called in the same ImGui ID scope that the plot is in. You should rarely if ever need this function, but it is available for applications that require runtime colormap swaps (e.g. Heatmaps demo).

Provides access to input mapping structure for permanant modifications to controls for pan, select, etc.

Default input mapping: pan = LMB drag, box select = RMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.

Reverse input mapping: pan = RMB drag, box select = LMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.

Render icons similar to those that appear in legends (nifty for data lists).

Render icons similar to those that appear in legends (nifty for data lists).

Get the plot draw list for custom rendering to the current plot area. Call between Begin/EndPlot.

Push clip rect for rendering to current plot area. The rect can be expanded or contracted by #expand pixels. Call between implot.begin_plot()/implot.end_plot().

Pop plot clip rect. Call between implot.begin_plot()/implot.end_plot().

Shows ImPlot style selector dropdown menu.

Shows ImPlot colormap selector dropdown menu.

Shows ImPlot input map selector dropdown menu.

Shows ImPlot style editor block (not a window).

Add basic help/info block for end users (not a window).

Shows ImPlot metrics/debug information window.

Shows the ImPlot demo window.