implot

ImPlot: 2D plots for Dear ImGui: lines, scatter, bars, shaded areas, heatmaps, histograms, pie charts, real-time data.

A plot lives between begin_plot() and end_plot(): the setup_* functions (axes, limits, legend) come first, then the plot_* functions. Run the app with immapp.run(..., with_implot=True), which creates ImPlot’s context.

In Python, the data are numpy arrays. ImPlot’s functions are templated on one numeric type, so the arrays of one call must share their dtype: convert them first (xs = xs.astype(ys.dtype)). Mismatched dtypes raise an error.

Start with: begin_plot, end_plot, plot_line, plot_scatter, setup_axes.

implot.h¶

BoxedValue (class)¶

BoxedValue.__init__¶

def __init__(self, value: float = float()) -> None

Auto-generated default constructor with named params

Enums and Types¶

Forward declarations¶

Enums/Flags

ImAxis_ (enum)¶

Axis indices. The values assigned may change; NEVER hardcode these.

Prop_ (enum)¶

Plotting properties. These provide syntactic sugar for creating ImPlotSpecs from (ImPlotProp,value) pairs. See ImPlotSpec documentation.

Flags_ (enum)¶

Options for plots (see BeginPlot).

AxisFlags_ (enum)¶

Options for plot axes (see SetupAxis).

SubplotFlags_ (enum)¶

Options for subplots (see BeginSubplot)

LegendFlags_ (enum)¶

Options for legends (see SetupLegend)

MouseTextFlags_ (enum)¶

Options for mouse hover text (see SetupMouseText)

DragToolFlags_ (enum)¶

Options for DragPoint, DragLine, DragRect

ColormapScaleFlags_ (enum)¶

Flags for ColormapScale

ItemFlags_ (enum)¶

Flags for ANY PlotX function. Used by setting ImPlotSpec::Flags.

LineFlags_ (enum)¶

Flags for PlotLine. Used by setting ImPlotSpec::Flags.

ScatterFlags_ (enum)¶

Flags for PlotScatter. Used by setting ImPlotSpec::Flags.

BubblesFlags_ (enum)¶

Flags for PlotBubbles. Used by setting ImPlotSpec::Flags.

PolygonFlags_ (enum)¶

Flags for PlotPolygon. Used by setting ImPlotSpec::Flags.

StairsFlags_ (enum)¶

Flags for PlotStairs. Used by setting ImPlotSpec::Flags.

ShadedFlags_ (enum)¶

Flags for PlotShaded (placeholder). Used by setting ImPlotSpec::Flags.

BarsFlags_ (enum)¶

Flags for PlotBars. Used by setting ImPlotSpec::Flags.

BarGroupsFlags_ (enum)¶

Flags for PlotBarGroups. Used by setting ImPlotSpec::Flags.

ErrorBarsFlags_ (enum)¶

Flags for PlotErrorBars. Used by setting ImPlotSpec::Flags.

StemsFlags_ (enum)¶

Flags for PlotStems. Used by setting ImPlotSpec::Flags.

InfLinesFlags_ (enum)¶

Flags for PlotInfLines. Used by setting ImPlotSpec::Flags.

PieChartFlags_ (enum)¶

Flags for PlotPieChart. Used by setting ImPlotSpec::Flags.

HeatmapFlags_ (enum)¶

Flags for PlotHeatmap. Used by setting ImPlotSpec::Flags.

HistogramFlags_ (enum)¶

Flags for PlotHistogram and PlotHistogram2D. Used by setting ImPlotSpec::Flags.

DigitalFlags_ (enum)¶

Flags for PlotDigital (placeholder). Used by setting ImPlotSpec::Flags.

ImageFlags_ (enum)¶

Flags for PlotImage (placeholder). Used by setting ImPlotSpec::Flags.

TextFlags_ (enum)¶

Flags for PlotText. Used by setting ImPlotSpec::Flags.

DummyFlags_ (enum)¶

Flags for PlotDummy (placeholder). Used by setting ImPlotSpec::Flags.

Cond_ (enum)¶

Represents a condition for SetupAxisLimits etc. (same as ImGuiCond, but we only support a subset of those enums)

Col_ (enum)¶

Plot styling colors.

StyleVar_ (enum)¶

Plot styling variables.

Scale_ (enum)¶

Axis scale

Marker_ (enum)¶

Marker specifications.

Colormap_ (enum)¶

Built-in colormaps

Location_ (enum)¶

Used to position items on a plot (e.g. legends, labels, etc.)

Bin_ (enum)¶

Enums for different automatic histogram binning methods (k = bin count or w = bin width)

Spec (class)¶

Plot item styling specification. Provide these to PlotX functions to override styling, specify offsetting or stride, or set optional flags. This struct can be used in the following ways:

1. By declaring and defining a struct instance:

   ImPlotSpec spec;
   spec.LineColor = ImVec4(1,0,0,1);
   spec.LineWeight = 2.0;
   spec.Marker = ImPlotMarker_Circle;
   spec.Flags = ImPlotItemFlags_NoLegend | ImPlotLineFlags_Segments;
   ImPlot::PlotLine("MyLine", xs, ys, 100, spec);

2. Inline using (ImPlotProp,value) pairs (order does NOT matter):

   ImPlot::PlotLine(“MyLine”, xs, ys, 100, { ImPlotProp_LineColor, ImVec4(1,0,0,1),
   ImPlotProp_LineWeight, 2.0,
   ImPlotProp_Marker, ImPlotMarker_Circle,
   ImPlotProp_Flags, ImPlotItemFlags_NoLegend | ImPlotLineFlags_Segments

   });

Spec.__init__¶

def __init__(self, line_color: Optional[ImVec4Like] = None, line_weight: float = 1.0, fill_color: Optional[ImVec4Like] = None, fill_alpha: float = 1.0, marker: Optional[Marker] = None, marker_size: float = 4, marker_line_color: Optional[ImVec4Like] = None, marker_fill_color: Optional[ImVec4Like] = None, size: float = 4, offset: int = 0, stride: int = IMPLOT_AUTO, flags: ItemFlags = ItemFlags_None) -> None

Auto-generated default constructor with named params

Point (class)¶

Point.__init__¶

@overload
def __init__(self) -> None

@overload
def __init__(self, _x: float, _y: float) -> None

@overload
def __init__(self, p: ImVec2Like) -> None

constexpr ImPlotPoint() : x(0.0), y(0.0);
constexpr ImPlotPoint(double _x, double _y) : x(_x), y(_y);
constexpr ImPlotPoint(const ImVec2& p) : x((double)p.x), y((double)p.y);

Range (class)¶

Range defined by a min/max value.

Range.__init__¶

@overload
def __init__(self) -> None

@overload
def __init__(self, _min: float, _max: float) -> None

constexpr ImPlotRange() : Min(0.0), Max(0.0);
constexpr ImPlotRange(double _min, double _max) : Min(_min), Max(_max);

Range.contains¶

def contains(self, value: float) -> bool

IMPLOT_API bool Contains(double value) const;

Range.size¶

def size(self) -> float

IMPLOT_API double Size() const;

Range.clamp¶

def clamp(self, value: float) -> float

IMPLOT_API double Clamp(double value) const;

Rect (class)¶

Combination of two range limits for X and Y axes. Also an AABB defined by Min()/Max().

Rect.__init__¶

@overload
def __init__(self) -> None

@overload
def __init__(self, x_min: float, x_max: float, y_min: float, y_max: float) -> None

constexpr ImPlotRect() : X(0.0,0.0), Y(0.0,0.0);
constexpr ImPlotRect(double x_min, double x_max, double y_min, double y_max) : X(x_min, x_max), Y(y_min, y_max);

Rect.contains¶

@overload
def contains(self, p: Point) -> bool

@overload
def contains(self, x: float, y: float) -> bool

IMPLOT_API bool Contains(const ImPlotPoint& p) const;
IMPLOT_API bool Contains(double x, double y) const;

Rect.size¶

def size(self) -> Point

IMPLOT_API ImPlotPoint Size() const;

Rect.clamp¶

@overload
def clamp(self, p: Point) -> Point

@overload
def clamp(self, x: float, y: float) -> Point

IMPLOT_API ImPlotPoint Clamp(const ImPlotPoint& p) const;
IMPLOT_API ImPlotPoint Clamp(double x, double y) const;

Rect.min¶

def min(self) -> Point

IMPLOT_API ImPlotPoint Min() const;

Rect.max¶

def max(self) -> Point

IMPLOT_API ImPlotPoint Max() const;

Style (class)¶

Plot style structure (has support for copy.copy)

Style.color_¶

def color_(self, idx_color: int) -> ImVec4

inline IMPLOT_API ImVec4& Color_(size_t idxColor);

Array of styling colors (index from implot.Col_.xxx)

Style.set_color_¶

def set_color_(self, idx_color: int, color: ImVec4Like) -> None

inline IMPLOT_API void SetColor_(size_t idxColor, ImVec4 color);

Array of styling colors (index from implot.Col_.xxx)

Style.__init__¶

def __init__(self) -> None

IMPLOT_API ImPlotStyle();

Support for legacy versions¶

InputMap (class)¶

Input mapping structure. Default values listed. See also MapInputDefault, MapInputReverse.

InputMap.__init__¶

def __init__(self) -> None

IMPLOT_API ImPlotInputMap();

Contexts¶

create_context¶

def create_context() -> Context

IMPLOT_API ImPlotContext* CreateContext();

Creates a new ImPlot context. Call this after ImGui::CreateContext.

destroy_context¶

def destroy_context(ctx: Optional[Context] = None) -> None

IMPLOT_API void DestroyContext(ImPlotContext* ctx = nullptr);

Destroys an ImPlot context. Call this before ImGui::DestroyContext. None = destroy current context.

get_current_context¶

def get_current_context() -> Context

IMPLOT_API ImPlotContext* GetCurrentContext();

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

set_current_context¶

def set_current_context(ctx: Context) -> None

IMPLOT_API void SetCurrentContext(ImPlotContext* ctx);

Sets the current ImPlot context.

set_imgui_context¶

def set_imgui_context(ctx: ImGui_Context) -> None

IMPLOT_API void SetImGuiContext(ImGuiContext* ctx);

Sets the current ImGui context. This is ONLY necessary if you are compiling
ImPlot as a DLL (not recommended) separate from your ImGui compilation. It sets the global variable GImGui, which is not shared across DLL boundaries.
See GImGui documentation in imgui.cpp for more details.

Begin/End Plot¶

begin_plot¶

def begin_plot(title_id: str, size: Optional[ImVec2Like] = None, flags: Flags = 0) -> bool

IMPLOT_API bool BeginPlot(const char* title_id, const ImVec2& size=ImVec2(-1,0), ImPlotFlags flags=0);

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

 if (BeginPlot(...)) {
     PlotLine(...);
     ...
     EndPlot();
 }

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 ImVec2(0,0)) can be modified in your ImPlotStyle.

end_plot¶

def end_plot() -> None

IMPLOT_API void EndPlot();

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

Begin/End Subplots¶

SubplotsRowColRatios (class)¶

SubplotsRowColRatios.__init__¶

def __init__(self, row_ratios: Optional[List[float]] = None, col_ratios: Optional[List[float]] = None) -> None

Auto-generated default constructor with named params

begin_subplots¶

def begin_subplots(title_id: str, rows: int, cols: int, size: ImVec2Like, flags: SubplotFlags = 0, row_col_ratios: Optional[SubplotsRowColRatios] = None) -> bool

IMPLOT_API inline bool BeginSubplotsWithRatios(const char* title_id, int rows, int cols, const ImVec2& size, ImPlotSubplotFlags flags = 0, SubplotsRowColRatios* row_col_ratios = nullptr);

end_subplots¶

def end_subplots() -> None

IMPLOT_API void EndSubplots();

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

Setup¶

setup_axis¶

def setup_axis(axis: ImAxis, label: Optional[str] = None, flags: AxisFlags = 0) -> None

IMPLOT_API void SetupAxis(ImAxis axis, const char* label=nullptr, ImPlotAxisFlags flags=0);

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

The following API allows you to setup and customize various aspects of the current plot. The functions should be called immediately after BeginPlot and before any other API calls. Typical usage is as follows:

if (BeginPlot(...)) {                     1) begin a new plot
    SetupAxis(ImAxis_X1, "My X-Axis");    2) make Setup calls
    SetupAxis(ImAxis_Y1, "My Y-Axis");
    SetupLegend(ImPlotLocation_North);
    ...
    SetupFinish();                        3) [optional] explicitly finish setup
    PlotLine(...);                        4) plot items
    ...
    EndPlot();                            5) end the plot
}

Important notes:

• Always call Setup code at the top of your BeginPlot conditional statement.

• Setup is locked once you start plotting or explicitly call SetupFinish.
  Do NOT call Setup code after you begin plotting or after you make any non-Setup API calls (e.g. utils like PlotToPixels also lock Setup)

• Calling SetupFinish is OPTIONAL, but probably good practice. If you do not call it yourself, then the first subsequent plotting or utility function will call it for you.

setup_axis_limits¶

def setup_axis_limits(axis: ImAxis, v_min: float, v_max: float, cond: Optional[Cond] = None) -> None

IMPLOT_API void SetupAxisLimits(ImAxis axis, double v_min, double v_max, ImPlotCond cond = ImPlotCond_Once);

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

setup_axis_links¶

def setup_axis_links(axis: ImAxis, link_min: BoxedValue, link_max: BoxedValue) -> None

IMPLOT_API inline void SetupAxisLinks(ImAxis axis, BoxedValue* link_min, BoxedValue* link_max);

Links an axis range limits to external values. Use BoxedValue to transmit values (which will be updated after EndPlot).

setup_axis_format¶

def setup_axis_format(axis: ImAxis, fmt: str) -> None

IMPLOT_API void SetupAxisFormat(ImAxis axis, const char* fmt);

Sets the format of numeric axis labels via formatter specifier (default=“%g”). Formatted values will be double (i.e. use %f).

setup_axis_scale¶

def setup_axis_scale(axis: ImAxis, scale: Scale) -> None

IMPLOT_API void SetupAxisScale(ImAxis axis, ImPlotScale scale);

Sets an axis’ scale using built-in options.

setup_axis_limits_constraints¶

def setup_axis_limits_constraints(axis: ImAxis, v_min: float, v_max: float) -> None

IMPLOT_API void SetupAxisLimitsConstraints(ImAxis axis, double v_min, double v_max);

Sets an axis’ limits constraints.

setup_axis_zoom_constraints¶

def setup_axis_zoom_constraints(axis: ImAxis, z_min: float, z_max: float) -> None

IMPLOT_API void SetupAxisZoomConstraints(ImAxis axis, double z_min, double z_max);

Sets an axis’ zoom constraints.

setup_axes¶

def setup_axes(x_label: str, y_label: str, x_flags: AxisFlags = 0, y_flags: AxisFlags = 0) -> None

IMPLOT_API void SetupAxes(const char* x_label, const char* y_label, ImPlotAxisFlags x_flags=0, ImPlotAxisFlags y_flags=0);

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

setup_axes_limits¶

def setup_axes_limits(x_min: float, x_max: float, y_min: float, y_max: float, cond: Optional[Cond] = None) -> None

IMPLOT_API void SetupAxesLimits(double x_min, double x_max, double y_min, double y_max, ImPlotCond cond = ImPlotCond_Once);

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

setup_legend¶

def setup_legend(location: Location, flags: LegendFlags = 0) -> None

IMPLOT_API void SetupLegend(ImPlotLocation location, ImPlotLegendFlags flags=0);

Sets up the plot legend. This can also be called immediately after BeginSubplots when using ImPlotSubplotFlags_ShareItems.

setup_mouse_text¶

def setup_mouse_text(location: Location, flags: MouseTextFlags = 0) -> None

IMPLOT_API void SetupMouseText(ImPlotLocation location, ImPlotMouseTextFlags flags=0);

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

setup_finish¶

def setup_finish() -> None

IMPLOT_API void SetupFinish();

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.

SetNext¶

set_next_axis_limits¶

def set_next_axis_limits(axis: ImAxis, v_min: float, v_max: float, cond: Optional[Cond] = None) -> None

IMPLOT_API void SetNextAxisLimits(ImAxis axis, double v_min, double v_max, ImPlotCond cond = ImPlotCond_Once);

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

Though you should default to the Setup API above, there are some scenarios where (re)configuring a plot or axis before BeginPlot is needed (e.g. if using a preceding button or slider widget to change the plot limits). In this case, you can use the SetNext API below. While this is not as feature rich as the Setup API, most common needs are provided. These functions can be called anywhere except for inside of Begin/EndPlot. For example: if (ImGui::Button(“Center Plot”))

    ImPlot::SetNextPlotLimits(-1,1,-1,1);
if (ImPlot::BeginPlot(...)) {
    ...
    ImPlot::EndPlot();
}

Important notes:

• You must still enable non-default axes with SetupAxis for these functions to work properly.

set_next_axis_links¶

def set_next_axis_links(axis: ImAxis, link_min: BoxedValue, link_max: BoxedValue) -> None

IMPLOT_API inline void SetNextAxisLinks(ImAxis axis, BoxedValue* link_min, BoxedValue* link_max);

Links an upcoming axis range limits to external values. Use BoxedValue to transmit values (which will be updated after EndPlot).

set_next_axis_to_fit¶

def set_next_axis_to_fit(axis: ImAxis) -> None

IMPLOT_API void SetNextAxisToFit(ImAxis axis);

Set an upcoming axis to auto fit to its data.

set_next_axes_limits¶

def set_next_axes_limits(x_min: float, x_max: float, y_min: float, y_max: float, cond: Optional[Cond] = None) -> None

IMPLOT_API void SetNextAxesLimits(double x_min, double x_max, double y_min, double y_max, ImPlotCond cond = ImPlotCond_Once);

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

set_next_axes_to_fit¶

def set_next_axes_to_fit() -> None

IMPLOT_API void SetNextAxesToFit();

Sets all upcoming axes to auto fit to their data.

Plot Items¶

plot_line¶

@overload
def plot_line(label_id: str, values: np.ndarray, xscale: float = 1, xstart: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_line(label_id: str, xs: np.ndarray, ys: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotLine(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotLine(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

The main plotting API is provided below. Call these functions between
Begin/EndPlot and after any Setup API calls. Each plots data on the current x and y axes, which can be changed with SetAxis/Axes.
The templated functions are explicitly instantiated in implot_items.cpp.
They are not intended to be used generically with custom types. You will get a linker error if you try! All functions support the following scalar types: float, double, ImS8, ImU8, ImS16, ImU16, ImS32, ImU32, ImS64, ImU64
If you need to plot custom or non-homogenous data you have a few options:

1. If your data is a simple struct/class (e.g. Vector2f), you can use striding in your ImPlotSpec.
   This is the most performant option if applicable.

   struct Vector2f { float X, Y; };
   ...
   Vector2f data[42];
   ImPlot::PlotLine("line", &data[0].x, &data[0].y, 42, {ImPlotProp_Stride, sizeof(Vector2f});

2. Write a custom getter C function or C++ lambda and pass it and optionally your data to an ImPlot function post-fixed with a G (e.g. PlotScatterG). This has a slight performance cost, but probably not enough to worry about unless your data is very large. Examples:

   ImPlotPoint MyDataGetter(int idx, None* data) {
       MyData* my_data = (MyData*)data;
       ImPlotPoint p;
       p.x = my_data->GetTime(idx);
       p.y = my_data->GetValue(idx);

   return p

   }
   ...
   auto my_lambda = [](int idx, None*) {
       double t = idx / 999.0;
       return ImPlotPoint(t, 0.5+0.5*std::sin(2*PI*10*t));
   };
   ...
   if (ImPlot::BeginPlot("MyPlot")) {
       MyData my_data;
       ImPlot::PlotScatterG("scatter", MyDataGetter, &my_data, my_data.Size());
       ImPlot::PlotLineG("line", my_lambda, None, 1000);
       ImPlot::EndPlot();
   }

NB: All types are converted to double before plotting. You may lose information if you try plotting extremely large 64-bit integral types. Proceed with caution!
Plots a standard 2D line plot.

plot_scatter¶

@overload
def plot_scatter(label_id: str, values: np.ndarray, xscale: float = 1, xstart: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_scatter(label_id: str, xs: np.ndarray, ys: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotScatter(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotScatter(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots a standard 2D scatter plot. Default marker is ImPlotMarker_Circle.

plot_bubbles¶

@overload
def plot_bubbles(label_id: str, values: np.ndarray, szs: np.ndarray, xscale: float = 1, xstart: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_bubbles(label_id: str, xs: np.ndarray, ys: np.ndarray, szs: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotBubbles(const char* label_id, const T* values, const T* szs, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotBubbles(const char* label_id, const T* xs, const T* ys, const T* szs, int count, const ImPlotSpec& spec=ImPlotSpec());

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

Plots a bubble graph. #szs are the radius of each bubble in plot units.

plot_polygon¶

def plot_polygon(label_id: str, xs: np.ndarray, ys: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotPolygon(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots a polygon. Points are specified in counter-clockwise order. If concave, make sure to set the Concave flag.

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

plot_stairs¶

@overload
def plot_stairs(label_id: str, values: np.ndarray, xscale: float = 1, xstart: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_stairs(label_id: str, xs: np.ndarray, ys: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotStairs(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotStairs(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots a 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]

plot_shaded¶

@overload
def plot_shaded(label_id: str, values: np.ndarray, yref: float = 0, xscale: float = 1, xstart: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_shaded(label_id: str, xs: np.ndarray, ys: np.ndarray, yref: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_shaded(label_id: str, xs: np.ndarray, ys1: np.ndarray, ys2: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotShaded(const char* label_id, const T* values, int count, double yref=0, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotShaded(const char* label_id, const T* xs, const T* ys, int count, double yref=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotShaded(const char* label_id, const T* xs, const T* ys1, const T* ys2, int count, const ImPlotSpec& spec=ImPlotSpec());

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

plot_bars¶

@overload
def plot_bars(label_id: str, values: np.ndarray, bar_size: float = 0.67, shift: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_bars(label_id: str, xs: np.ndarray, ys: np.ndarray, bar_size: float, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotBars(const char* label_id, const T* values, int count, double bar_size=0.67, double shift=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotBars(const char* label_id, const T* xs, const T* ys, int count, double bar_size, const ImPlotSpec& spec=ImPlotSpec());

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

plot_bar_groups¶

def plot_bar_groups(label_ids: List[str], values: np.ndarray, group_size: float = 0.67, shift: float = 0, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotBarGroups(const std::vector<std::string>& label_ids, const T* values, int count, double group_size=0.67, double shift=0, const ImPlotSpec& spec=ImPlotSpec());

Plots a group of bars.

• values should be a 1 dimension numpy array of values.

• label_ids should be a list of strings corresponding to bars labels

plot_error_bars¶

@overload
def plot_error_bars(label_id: str, xs: np.ndarray, ys: np.ndarray, err: np.ndarray, spec: Optional[Spec] = None) -> None

@overload
def plot_error_bars(label_id: str, xs: np.ndarray, ys: np.ndarray, neg: np.ndarray, pos: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotErrorBars(const char* label_id, const T* xs, const T* ys, const T* err, int count, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotErrorBars(const char* label_id, const T* xs, const T* ys, const T* neg, const T* pos, int count, const ImPlotSpec& spec=ImPlotSpec());

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

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

plot_stems¶

@overload
def plot_stems(label_id: str, values: np.ndarray, ref: float = 0, scale: float = 1, start: float = 0, spec: Optional[Spec] = None) -> None

@overload
def plot_stems(label_id: str, xs: np.ndarray, ys: np.ndarray, ref: float = 0, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotStems(const char* label_id, const T* values, int count, double ref=0, double scale=1, double start=0, const ImPlotSpec& spec=ImPlotSpec());
IMPLOT_TMP void PlotStems(const char* label_id, const T* xs, const T* ys, int count, double ref=0, const ImPlotSpec& spec=ImPlotSpec());

Plots stems. Vertical by default.

plot_inf_lines¶

def plot_inf_lines(label_id: str, values: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotInfLines(const char* label_id, const T* values, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots infinite vertical or horizontal lines (e.g. for references or asymptotes).

plot_pie_chart¶

def plot_pie_chart(label_ids: List[str], values: np.ndarray, x: float, y: float, radius: float, label_fmt: str = '%.1f', angle0: float = 90, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotPieChart(const char* const label_ids[], const T* values, int count, double x, double y, double radius, const char* label_fmt="%.1f", double angle0=90, const ImPlotSpec& spec=ImPlotSpec());

Plots a pie chart. Center and radius are in plot units. #label_fmt can be set to None for no labels.

plot_histogram¶

def plot_histogram(label_id: str, values: np.ndarray, bins: int = Bin_Sturges, bar_scale: float = 1.0, range: Optional[Range] = None, spec: Optional[Spec] = None) -> float

IMPLOT_TMP double PlotHistogram(const char* label_id, const T* values, int count, int bins=ImPlotBin_Sturges, double bar_scale=1.0, ImPlotRange range=ImPlotRange(), const ImPlotSpec& spec=ImPlotSpec());

Plots a horizontal histogram. #bins can be a positive integer or an ImPlotBin_ method. 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.

plot_histogram_2d¶

def plot_histogram_2d(label_id: str, xs: np.ndarray, ys: np.ndarray, x_bins: int = Bin_Sturges, y_bins: int = Bin_Sturges, range: Optional[Rect] = None, spec: Optional[Spec] = None) -> float

IMPLOT_TMP double PlotHistogram2D(const char* label_id, const T* xs, const T* ys, int count, int x_bins=ImPlotBin_Sturges, int y_bins=ImPlotBin_Sturges, ImPlotRect range=ImPlotRect(), const ImPlotSpec& spec=ImPlotSpec());

Plots two dimensional, bivariate histogram as a heatmap. #x_bins and #y_bins can be a positive integer or an ImPlotBin. 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.

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

plot_digital¶

def plot_digital(label_id: str, xs: np.ndarray, ys: np.ndarray, spec: Optional[Spec] = None) -> None

IMPLOT_TMP void PlotDigital(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

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

plot_image¶

def plot_image(label_id: str, tex_ref: ImTextureRef, bounds_min: Point, bounds_max: Point, uv0: Optional[ImVec2Like] = None, uv1: Optional[ImVec2Like] = None, tint_col: Optional[ImVec4Like] = None, spec: Optional[Spec] = None) -> None

IMPLOT_API void PlotImage(const char* label_id, ImTextureRef tex_ref, const ImPlotPoint& bounds_min, const ImPlotPoint& bounds_max, const ImVec2& uv0 = ImVec2(0, 0), const ImVec2& uv1 = ImVec2(1, 1), const ImVec4& tint_col = ImVec4(1, 1, 1, 1), const ImPlotSpec& spec=ImPlotSpec());

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

plot_text¶

def plot_text(text: str, x: float, y: float, pix_offset: Optional[ImVec2Like] = None, spec: Optional[Spec] = None) -> None

IMPLOT_API void PlotText(const char* text, double x, double y, const ImVec2& pix_offset=ImVec2(0,0), const ImPlotSpec& spec=ImPlotSpec());

Plots a centered text label at point x,y with an optional pixel offset. Text color can be changed with ImPlot::PushStyleColor(ImPlotCol_InlayText, ...).

plot_dummy¶

def plot_dummy(label_id: str, spec: Optional[Spec] = None) -> None

IMPLOT_API void PlotDummy(const char* label_id, const ImPlotSpec& spec=ImPlotSpec());

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

Plot Tools¶

drag_point¶

def drag_point(id_: int, x: float, y: float, col: ImVec4Like, size: float = 4, flags: DragToolFlags = 0, out_clicked: Optional[bool] = None, out_hovered: Optional[bool] = None, out_held: Optional[bool] = None) -> Tuple[bool, float, float, Optional[bool], Optional[bool], Optional[bool]]

IMPLOT_API bool DragPoint(int id, double* x, double* y, const ImVec4& col, float size = 4, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable point at x,y. #col defaults to ImGuiCol_Text.

The following can be used to render interactive elements and/or annotations.
Like the item plotting functions above, they apply to the current x and y axes, which can be changed with SetAxis/SetAxes. These functions return True when user interaction causes the provided coordinates to change. Additional user interactions can be retrieved through the optional output parameters.

drag_line_x¶

def drag_line_x(id_: int, x: float, col: ImVec4Like, thickness: float = 1, flags: DragToolFlags = 0, out_clicked: Optional[bool] = None, out_hovered: Optional[bool] = None, out_held: Optional[bool] = None) -> Tuple[bool, float, Optional[bool], Optional[bool], Optional[bool]]

IMPLOT_API bool DragLineX(int id, double* x, const ImVec4& col, float thickness = 1, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable vertical guide line at an x-value. #col defaults to ImGuiCol_Text.

drag_line_y¶

def drag_line_y(id_: int, y: float, col: ImVec4Like, thickness: float = 1, flags: DragToolFlags = 0, out_clicked: Optional[bool] = None, out_hovered: Optional[bool] = None, out_held: Optional[bool] = None) -> Tuple[bool, float, Optional[bool], Optional[bool], Optional[bool]]

IMPLOT_API bool DragLineY(int id, double* y, const ImVec4& col, float thickness = 1, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable horizontal guide line at a y-value. #col defaults to ImGuiCol_Text.

drag_rect¶

def drag_rect(id_: int, x1: float, y1: float, x2: float, y2: float, col: ImVec4Like, flags: DragToolFlags = 0, out_clicked: Optional[bool] = None, out_hovered: Optional[bool] = None, out_held: Optional[bool] = None) -> Tuple[bool, float, float, float, float, Optional[bool], Optional[bool], Optional[bool]]

IMPLOT_API bool DragRect(int id, double* x1, double* y1, double* x2, double* y2, const ImVec4& col, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable and resizeable rectangle.

annotation¶

@overload
def annotation(x: float, y: float, col: ImVec4Like, pix_offset: ImVec2Like, clamp: bool, round: bool = False) -> None

@overload
def annotation(x: float, y: float, col: ImVec4Like, pix_offset: ImVec2Like, clamp: bool, fmt: str) -> None

IMPLOT_API void Annotation(double x, double y, const ImVec4& col, const ImVec2& pix_offset, bool clamp, bool round = false);
IMPLOT_API void Annotation(double x, double y, const ImVec4& col, const ImVec2& pix_offset, bool clamp, const char* fmt, ...) ;

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

tag_x¶

@overload
def tag_x(x: float, col: ImVec4Like, round: bool = False) -> None

@overload
def tag_x(x: float, col: ImVec4Like, fmt: str) -> None

IMPLOT_API void TagX(double x, const ImVec4& col, bool round = false);
IMPLOT_API void TagX(double x, const ImVec4& col, const char* fmt, ...) ;

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

tag_y¶

@overload
def tag_y(y: float, col: ImVec4Like, round: bool = False) -> None

@overload
def tag_y(y: float, col: ImVec4Like, fmt: str) -> None

IMPLOT_API void TagY(double y, const ImVec4& col, bool round = false);
IMPLOT_API void TagY(double y, const ImVec4& col, const char* fmt, ...) ;

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

Plot Utils¶

set_axis¶

def set_axis(axis: ImAxis) -> None

IMPLOT_API void SetAxis(ImAxis axis);

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

set_axes¶

def set_axes(x_axis: ImAxis, y_axis: ImAxis) -> None

IMPLOT_API void SetAxes(ImAxis x_axis, ImAxis y_axis);

pixels_to_plot¶

@overload
def pixels_to_plot(pix: ImVec2Like, x_axis: Optional[ImAxis] = None, y_axis: Optional[ImAxis] = None) -> Point

@overload
def pixels_to_plot(x: float, y: float, x_axis: Optional[ImAxis] = None, y_axis: Optional[ImAxis] = None) -> Point

IMPLOT_API ImPlotPoint PixelsToPlot(const ImVec2& pix, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
IMPLOT_API ImPlotPoint PixelsToPlot(float x, float y, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Convert pixels to a position in the current plot’s coordinate system. Passing IMPLOT_AUTO uses the current axes.

plot_to_pixels¶

@overload
def plot_to_pixels(plt: Point, x_axis: Optional[ImAxis] = None, y_axis: Optional[ImAxis] = None) -> ImVec2

@overload
def plot_to_pixels(x: float, y: float, x_axis: Optional[ImAxis] = None, y_axis: Optional[ImAxis] = None) -> ImVec2

IMPLOT_API ImVec2 PlotToPixels(const ImPlotPoint& plt, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
IMPLOT_API ImVec2 PlotToPixels(double x, double y, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Convert a position in the current plot’s coordinate system to pixels. Passing IMPLOT_AUTO uses the current axes.

get_plot_pos¶

def get_plot_pos() -> ImVec2

IMPLOT_API ImVec2 GetPlotPos();

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

get_plot_size¶

def get_plot_size() -> ImVec2

IMPLOT_API ImVec2 GetPlotSize();

Get the current Plot size in pixels.

get_plot_mouse_pos¶

def get_plot_mouse_pos(x_axis: Optional[ImAxis] = None, y_axis: Optional[ImAxis] = None) -> Point

IMPLOT_API ImPlotPoint GetPlotMousePos(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

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

get_plot_limits¶

def get_plot_limits(x_axis: Optional[ImAxis] = None, y_axis: Optional[ImAxis] = None) -> Rect

IMPLOT_API ImPlotRect GetPlotLimits(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Returns the current plot axis range.

is_plot_hovered¶

def is_plot_hovered() -> bool

IMPLOT_API bool IsPlotHovered();

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

is_axis_hovered¶

def is_axis_hovered(axis: ImAxis) -> bool

IMPLOT_API bool IsAxisHovered(ImAxis axis);

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

is_subplots_hovered¶

def is_subplots_hovered() -> bool

IMPLOT_API bool IsSubplotsHovered();

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

is_plot_selected¶

def is_plot_selected() -> bool

IMPLOT_API bool IsPlotSelected();

Returns True if the current plot is being box selected.

get_plot_selection¶

def get_plot_selection(x_axis: Optional[ImAxis] = None, y_axis: Optional[ImAxis] = None) -> Rect

IMPLOT_API ImPlotRect GetPlotSelection(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Returns the current plot box selection bounds. Passing IMPLOT_AUTO uses the current axes.

cancel_plot_selection¶

def cancel_plot_selection() -> None

IMPLOT_API void CancelPlotSelection();

Cancels a the current plot box selection.

hide_next_item¶

def hide_next_item(hidden: bool = True, cond: Optional[Cond] = None) -> None

IMPLOT_API void HideNextItem(bool hidden = true, ImPlotCond cond = ImPlotCond_Once);

Hides or shows the next plot item (i.e. as if it were toggled from the legend).
Use ImPlotCond_Always if you need to forcefully set this every frame.

begin_aligned_plots¶

def begin_aligned_plots(group_id: str, vertical: bool = True) -> bool

IMPLOT_API bool BeginAlignedPlots(const char* group_id, bool vertical = true);

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

Use the following around calls to Begin/EndPlot to align l/r/t/b padding.
Consider using Begin/EndSubplots first. They are more feature rich and accomplish the same behaviour by default. The functions below offer lower level control of plot alignment.

end_aligned_plots¶

def end_aligned_plots() -> None

IMPLOT_API void EndAlignedPlots();

Only call EndAlignedPlots() if BeginAlignedPlots() returns True!

Legend Utils¶

begin_legend_popup¶

def begin_legend_popup(label_id: str, mouse_button: MouseButton = 1) -> bool

IMPLOT_API bool BeginLegendPopup(const char* label_id, ImGuiMouseButton mouse_button=1);

Begin a popup for a legend entry.

end_legend_popup¶

def end_legend_popup() -> None

IMPLOT_API void EndLegendPopup();

End a popup for a legend entry.

is_legend_entry_hovered¶

def is_legend_entry_hovered(label_id: str) -> bool

IMPLOT_API bool IsLegendEntryHovered(const char* label_id);

Returns True if a plot item legend entry is hovered.

Drag and Drop¶

begin_drag_drop_target_plot¶

def begin_drag_drop_target_plot() -> bool

IMPLOT_API bool BeginDragDropTargetPlot();

Turns the current plot’s plotting area into a drag and drop target. Don’t forget to call EndDragDropTarget!

begin_drag_drop_target_axis¶

def begin_drag_drop_target_axis(axis: ImAxis) -> bool

IMPLOT_API bool BeginDragDropTargetAxis(ImAxis axis);

Turns the current plot’s X-axis into a drag and drop target. Don’t forget to call EndDragDropTarget!

begin_drag_drop_target_legend¶

def begin_drag_drop_target_legend() -> bool

IMPLOT_API bool BeginDragDropTargetLegend();

Turns the current plot’s legend into a drag and drop target. Don’t forget to call EndDragDropTarget!

end_drag_drop_target¶

def end_drag_drop_target() -> None

IMPLOT_API void EndDragDropTarget();

Ends a drag and drop target (currently just an alias for ImGui::EndDragDropTarget).

begin_drag_drop_source_plot¶

def begin_drag_drop_source_plot(flags: DragDropFlags = 0) -> bool

IMPLOT_API bool BeginDragDropSourcePlot(ImGuiDragDropFlags flags=0);

Turns the current plot’s plotting area into a drag and drop source. You must hold Ctrl. Don’t forget to call EndDragDropSource!

NB: By default, plot and axes drag and drop sources require holding the Ctrl modifier to initiate the drag.
You can change the modifier if desired. If ImGuiMod_None is provided, the axes will be locked from panning.

begin_drag_drop_source_axis¶

def begin_drag_drop_source_axis(axis: ImAxis, flags: DragDropFlags = 0) -> bool

IMPLOT_API bool BeginDragDropSourceAxis(ImAxis axis, ImGuiDragDropFlags flags=0);

Turns the current plot’s X-axis into a drag and drop source. You must hold Ctrl. Don’t forget to call EndDragDropSource!

begin_drag_drop_source_item¶

def begin_drag_drop_source_item(label_id: str, flags: DragDropFlags = 0) -> bool

IMPLOT_API bool BeginDragDropSourceItem(const char* label_id, ImGuiDragDropFlags flags=0);

Turns an item in the current plot’s legend into drag and drop source. Don’t forget to call EndDragDropSource!

end_drag_drop_source¶

def end_drag_drop_source() -> None

IMPLOT_API void EndDragDropSource();

Ends a drag and drop source (currently just an alias for ImGui::EndDragDropSource).

Styling¶

get_style¶

def get_style() -> Style

IMPLOT_API ImPlotStyle& GetStyle();

Styling colors in ImPlot works similarly to styling colors in ImGui, but with one important difference. Like ImGui, all style colors are stored in an indexable array in ImPlotStyle. You can permanently modify these values through
GetStyle().Colors, or temporarily modify them with Push/Pop functions below.
However, by default all style colors in ImPlot default to a special color
IMPLOT_AUTO_COL. IMPLOT_AUTO_COL tells ImPlot to set that color from color data in your ImGuiStyle. The ImGuiCol_ that these style colors default to are detailed above, and in general have been mapped to produce plots visually consistent with your current ImGui style. Of course, you are free to manually set these colors to whatever you like, and further can Push/Pop them around individual plots for plot-specific styling (e.g. coloring axes).
Provides access to plot style structure for permanent modifications to colors, sizes, etc.

set_style¶

def set_style(style: Style) -> None

IMPLOT_API void SetStyle(const ImPlotStyle& style);

style_colors_auto¶

def style_colors_auto(dst: Optional[Style] = None) -> None

IMPLOT_API void StyleColorsAuto(ImPlotStyle* dst = nullptr);

Style plot colors for current ImGui style (default).

style_colors_classic¶

def style_colors_classic(dst: Optional[Style] = None) -> None

IMPLOT_API void StyleColorsClassic(ImPlotStyle* dst = nullptr);

Style plot colors for ImGui “Classic”.

style_colors_dark¶

def style_colors_dark(dst: Optional[Style] = None) -> None

IMPLOT_API void StyleColorsDark(ImPlotStyle* dst = nullptr);

Style plot colors for ImGui “Dark”.

style_colors_light¶

def style_colors_light(dst: Optional[Style] = None) -> None

IMPLOT_API void StyleColorsLight(ImPlotStyle* dst = nullptr);

Style plot colors for ImGui “Light”.

push_style_color¶

@overload
def push_style_color(idx: Col, col: ImU32) -> None

@overload
def push_style_color(idx: Col, col: ImVec4Like) -> None

IMPLOT_API void PushStyleColor(ImPlotCol idx, ImU32 col);
IMPLOT_API void PushStyleColor(ImPlotCol idx, const ImVec4& col);

Use PushStyleX to temporarily modify your ImPlotStyle. The modification will last until the matching call to PopStyleX. You MUST call a pop for every push, otherwise you will leak memory! This behaves just like ImGui.
Temporarily modify a style color. Don’t forget to call PopStyleColor!

pop_style_color¶

def pop_style_color(count: int = 1) -> None

IMPLOT_API void PopStyleColor(int count = 1);

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

push_style_var¶

@overload
def push_style_var(idx: StyleVar, val: int) -> None

@overload
def push_style_var(idx: StyleVar, val: float) -> None

@overload
def push_style_var(idx: StyleVar, val: ImVec2Like) -> None

IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, int val);
IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, float val);
IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, const ImVec2& val);

Temporarily modify a style variable of int type. Don’t forget to call PopStyleVar!

pop_style_var¶

def pop_style_var(count: int = 1) -> None

IMPLOT_API void PopStyleVar(int count = 1);

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

get_last_item_color¶

def get_last_item_color() -> ImVec4

IMPLOT_API ImVec4 GetLastItemColor();

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

get_style_color_name¶

def get_style_color_name(idx: Col) -> str

IMPLOT_API const char* GetStyleColorName(ImPlotCol idx);

Returns the null terminated string name for an ImPlotCol.

get_marker_name¶

def get_marker_name(idx: Marker) -> str

IMPLOT_API const char* GetMarkerName(ImPlotMarker idx);

Returns the null terminated string name for an ImPlotMarker.

next_marker¶

def next_marker() -> Marker

IMPLOT_API ImPlotMarker NextMarker();

Returns the next marker and advances the marker for the current plot. You need to call this between Begin/EndPlot!

Colormaps¶

get_colormap_count¶

def get_colormap_count() -> int

IMPLOT_API int GetColormapCount();

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

Item styling is based on colormaps when the relevant ImPlotCol_XXX is set to
IMPLOT_AUTO_COL (default). Several built-in colormaps are available. You can add and then push/pop your own colormaps as well. To permanently set a colormap, modify the Colormap index member of your ImPlotStyle.
Colormap data will be ignored and a custom color will be used if you have done one of the following: 1) Modified an item style color in your ImPlotStyle to anything other than IMPLOT_AUTO_COL. 2) Pushed an item style color using PushStyleColor(). 3) Set the next item style with a SetNextXXXStyle function.
Add a new colormap. The color data will be copied. The colormap can be used by pushing either the returned index or the string name with PushColormap. The colormap name must be unique and the size must be greater than 1. You will receive an assert otherwise! By default colormaps are considered to be qualitative (i.e. discrete). If you want to create a continuous colormap, set #qual=False. This will treat the colors you provide as keys, and ImPlot will build a linearly interpolated lookup table. The memory footprint of this table will be exactly ((size-1)*255+1)*4 bytes.

get_colormap_name¶

def get_colormap_name(cmap: Colormap) -> str

IMPLOT_API const char* GetColormapName(ImPlotColormap cmap);

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

get_colormap_index¶

def get_colormap_index(name: str) -> Colormap

IMPLOT_API ImPlotColormap GetColormapIndex(const char* name);

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

push_colormap¶

@overload
def push_colormap(cmap: Colormap) -> None

@overload
def push_colormap(name: str) -> None

IMPLOT_API void PushColormap(ImPlotColormap cmap);
IMPLOT_API void PushColormap(const char* name);

Temporarily switch to one of the built-in (i.e. ImPlotColormap_XXX) or user-added colormaps (i.e. a return value of AddColormap). Don’t forget to call PopColormap!

pop_colormap¶

def pop_colormap(count: int = 1) -> None

IMPLOT_API void PopColormap(int count = 1);

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

next_colormap_color¶

def next_colormap_color() -> ImVec4

IMPLOT_API ImVec4 NextColormapColor();

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 Begin/EndPlot!

get_colormap_size¶

def get_colormap_size(cmap: Optional[Colormap] = None) -> int

IMPLOT_API int GetColormapSize(ImPlotColormap cmap = IMPLOT_AUTO);

Returns the size of a colormap.

Colormap utils. If cmap = IMPLOT_AUTO (default), the current colormap is assumed.
Pass an explicit colormap index (built-in or user-added) to specify otherwise.

get_colormap_color¶

def get_colormap_color(idx: int, cmap: Optional[Colormap] = None) -> ImVec4

IMPLOT_API ImVec4 GetColormapColor(int idx, ImPlotColormap cmap = IMPLOT_AUTO);

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

sample_colormap¶

def sample_colormap(t: float, cmap: Optional[Colormap] = None) -> ImVec4

IMPLOT_API ImVec4 SampleColormap(float t, ImPlotColormap cmap = IMPLOT_AUTO);

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

colormap_scale¶

def colormap_scale(label: str, scale_min: float, scale_max: float, size: Optional[ImVec2Like] = None, format: str = '%g', flags: ColormapScaleFlags = 0, cmap: Optional[Colormap] = None) -> None

IMPLOT_API void ColormapScale(const char* label, double scale_min, double scale_max, const ImVec2& size = ImVec2(0,0), const char* format = "%g", ImPlotColormapScaleFlags flags = 0, ImPlotColormap cmap = IMPLOT_AUTO);

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.

colormap_slider¶

def colormap_slider(label: str, t: float, out: Optional[ImVec4Like] = None, format: str = '', cmap: Optional[Colormap] = None) -> Tuple[bool, float]

IMPLOT_API bool ColormapSlider(const char* label, float* t, ImVec4* out = nullptr, const char* format = "", ImPlotColormap cmap = IMPLOT_AUTO);

Shows a horizontal slider with a colormap gradient background. Optionally returns the color sampled at t in [0 1].

colormap_button¶

def colormap_button(label: str, size: Optional[ImVec2Like] = None, cmap: Optional[Colormap] = None) -> bool

IMPLOT_API bool ColormapButton(const char* label, const ImVec2& size = ImVec2(0,0), ImPlotColormap cmap = IMPLOT_AUTO);

Shows a button with a colormap gradient background.

bust_color_cache¶

def bust_color_cache(plot_title_id: Optional[str] = None) -> None

IMPLOT_API void BustColorCache(const char* plot_title_id = nullptr);

When items in a plot sample their color from a colormap, the color is cached and does not change unless explicitly overridden. 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 None, 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).

Input Mapping¶

get_input_map¶

def get_input_map() -> InputMap

IMPLOT_API ImPlotInputMap& GetInputMap();

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

map_input_default¶

def map_input_default(dst: Optional[InputMap] = None) -> None

IMPLOT_API void MapInputDefault(ImPlotInputMap* dst = nullptr);

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

map_input_reverse¶

def map_input_reverse(dst: Optional[InputMap] = None) -> None

IMPLOT_API void MapInputReverse(ImPlotInputMap* dst = nullptr);

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

Miscellaneous¶

item_icon¶

@overload
def item_icon(col: ImVec4Like) -> None

@overload
def item_icon(col: ImU32) -> None

IMPLOT_API void ItemIcon(const ImVec4& col);
IMPLOT_API void ItemIcon(ImU32 col);

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

colormap_icon¶

def colormap_icon(cmap: Colormap) -> None

IMPLOT_API void ColormapIcon(ImPlotColormap cmap);

get_plot_draw_list¶

def get_plot_draw_list() -> ImDrawList

IMPLOT_API ImDrawList* GetPlotDrawList();

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

push_plot_clip_rect¶

def push_plot_clip_rect(expand: float = 0) -> None

IMPLOT_API void PushPlotClipRect(float expand=0);

Push clip rect for rendering to current plot area. The rect can be expanded or contracted by #expand pixels. Call between Begin/EndPlot.

pop_plot_clip_rect¶

def pop_plot_clip_rect() -> None

IMPLOT_API void PopPlotClipRect();

Pop plot clip rect. Call between Begin/EndPlot.

show_style_selector¶

def show_style_selector(label: str) -> bool

IMPLOT_API bool ShowStyleSelector(const char* label);

Shows ImPlot style selector dropdown menu.

show_colormap_selector¶

def show_colormap_selector(label: str) -> bool

IMPLOT_API bool ShowColormapSelector(const char* label);

Shows ImPlot colormap selector dropdown menu.

show_input_map_selector¶

def show_input_map_selector(label: str) -> bool

IMPLOT_API bool ShowInputMapSelector(const char* label);

Shows ImPlot input map selector dropdown menu.

show_style_editor¶

def show_style_editor(ref: Optional[Style] = None) -> None

IMPLOT_API void ShowStyleEditor(ImPlotStyle* ref = nullptr);

Shows ImPlot style editor block (not a window).

show_user_guide¶

def show_user_guide() -> None

IMPLOT_API void ShowUserGuide();

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

show_metrics_window¶

def show_metrics_window(p_popen: Optional[bool] = None) -> Optional[bool]

IMPLOT_API void ShowMetricsWindow(bool* p_popen = nullptr);

Shows ImPlot metrics/debug information window.

Demo¶

show_demo_window¶

def show_demo_window(p_open: Optional[bool] = None) -> Optional[bool]

IMPLOT_API void ShowDemoWindow(bool* p_open = nullptr);

Shows the ImPlot demo window (add implot_demo.cpp to your sources!)

show_demo_window_maybe_docked¶

def show_demo_window_maybe_docked(create_window: bool, p_open: Optional[bool] = None, initial_extra_flags: WindowFlags = 0, window_pos: Optional[ImVec2Like] = None, window_size: Optional[ImVec2Like] = None) -> Optional[bool]

IMPLOT_API void ShowDemoWindow_MaybeDocked(bool create_window, bool* p_open = NULL, ImGuiWindowFlags initial_extra_flags = 0, ImVec2 window_pos = ImVec2(0, 0), ImVec2 window_size = ImVec2(0, 0));

Bundle: ShowDemoWindow_MaybeDocked is ShowDemoWindow, but can be used without creating an ImGui window.

Python helpers (manual bindings)¶

Add a new colormap. The color data will be copied. The colormap can be used by pushing either the returned index or the string name with PushColormap. The colormap name must be unique and the size must be greater than 1. You will receive an assert otherwise! By default, colormaps are considered to be qualitative (i.e. discrete). If you want to create a continuous colormap, set #qual=False. This will treat the colors you provide as keys, and ImPlot will build a linearly interpolated lookup table. The memory footprint of this table will be exactly ((size-1)*255+1)*4 bytes.
Warning:
The colormap ‘cols’ must either be a 1D array of type uint32 (if using hexadecimal colors), or a 2D (Nx4 ->RGBA) array of type float32 (if using float values between 0 and 1)

add_colormap¶

def add_colormap(name: str, cols: np.ndarray, qual: bool = True) -> Colormap

setup_axis_ticks¶

@overload
def setup_axis_ticks(axis: ImAxis, v_min: float, v_max: float, n_ticks: int, labels: List[str] | None = None, keep_default: bool = False) -> None

@overload
def setup_axis_ticks(axis: ImAxis, values: List[float], labels: List[str] | None = None, keep_default: bool = False) -> None

Sets an axis’ ticks and optionally the labels for the next plot. To keep the default ticks, set #keep_default=true.

IMPLOT_API void SetupAxisTicks(ImAxis axis, double v_min, double v_max, int n_ticks, const char* const labels[]=nullptr, bool keep_default=false);

plot_heatmap¶

def plot_heatmap(label_id: str, values: np.ndarray, scale_min: float = 0.0, scale_max: float = 0.0, label_fmt: str = '%.1f', bounds_min: Point = Point(0, 0), bounds_max: Point = Point(1, 1), spec: Spec = Spec()) -> None

IMPLOT_TMP void PlotHeatmap(const char* label_id, const T* values, int rows, int cols, double scale_min=0, double scale_max=0, const char* label_fmt="%.1f", const ImPlotPoint& bounds_min=ImPlotPoint(0,0), const ImPlotPoint& bounds_max=ImPlotPoint(1,1), ImPlotHeatmapFlags flags=0);

Plots a 2D heatmap chart. Values are expected to be in row-major order by default. 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 NULL for no labels.