4bb4 / implot-rs Goto Github PK

Rust bindings to https://github.com/epezent/implot

License: Apache License 2.0

Rust 100.00%

implot-rs's Introduction

implot-rs

Rust bindings for ImPlot, built by running bindgen on cimplot.

The bindings are currently based on ImPlot version 0.9-WIP (see implot-sys/third-party for the exact commit currently pointed to). The status section below provides detailed information on implementation status.

Important note: As long as the code is pre-1.0 release, the API is expected to have breaking changes between minor versions. Patch versions should be backwards compatible. After 1.0, semver will be followed more properly.

Requirements

imgui-rs requires minimum Rust version 1.40, so this project requires at least that. The sys crate compiles implot, so a C++ compiler will also be required.

Examples

Examples are being built in the implot-examples crate in this repo. To try them out, clone the repo, change into the implot-examples directory and try for example

  cargo run --example line_plots

Documentation

For released versions, see . Make sure to look at the right release, since the API is still changing. For the master branch, the docs can be built by cloning this repository and then running

  cargo doc --open

An effort is made to document everything as it is being added. Feel free to open an issue if documentation is unclear or lacking. Note that doc aliases are being added now, which means one should be able to look for things with the name they have in the C++ code and rustdoc should show the correspondingly-named item. Sometimes this is just a matter of changing camelcase to snake case, other times the idiomatic bindings do things a bit differently. These aliases only work with Rust 1.48 or newer.

Implementation status

Currently a work in progress, coverage of the C++ API is increased steadily. The author is open to collaboration, if you'd like to help, feel free to reach out via a Github issue.

At this point, raw bindings are working in implot-sys, and more idiomatic interfaces for plot creation as well a subset of the functionality for plots are implemented.

While the raw bindings have versions of most functions for different data types such as 32-bit or 64-bit floats and various integers, the higher-level bindings are currently only created for 64-bit floats.

Developer documentation

Design approach

This repo tries to follow the approaches and style used in imgui-rs somewhat closely, because implot is to be used within imgui programs, and hence keeping the interfaces and design philosophies close should make it easier to do that.

If you spot any design inconsistencies or paper cuts, feel free to open an issue.

implot-rs's People

Contributors

Stargazers

Watchers

Forkers

benmkw maoe strogo a1ien birktj kylc aeledfyr dbr eiz thombrom jadegeek kohlten hussainaloum aholtzma-am equalent andraantariksa domwilliams0 ddunwoody flplv

implot-rs's Issues

Drawing many rects possible?

Thanks for providing bindings to ImPlot, it seems to have a lot of great potential! :)
(Unfortunately it's not on crates.io, I first searched there and couldn't find it, I only found it by accident.)

I'm familiar with imgui-rs but haven't use implot yet. I need to decide what the best way is to render dynamic data (rendering as ~10k rects each frame).

Is it possible to render something like this with implot?

Does it support the following?

(transparent) rects
with border color different from fill color
border thickness
10k rects without high CPU usage?
text labels anywhere in the "canvas" with flat-colored background to make them more readable
rendering without axes & axis labels

save as image api/ example

maybe by using a backend like imgui-rs/imgui-rs#482 this crate would be nice for creating images as well (also ref https://github.com/38/plotters)

Otherwise a simple wgpu example which saves the buffer using the image crate could probably be added.

error: use of undeclared identifier 'isnan' on macOS Big Sur (11.4 and 11.5)

When cargo build in a clean checkout, I get:

% cargo build
   Compiling implot-sys v0.4.0 (/Users/maoe/src/github.com/4bb4/implot-rs/implot-sys)
The following warnings were emitted during compilation:

warning: In file included from third-party/cimplot/implot/implot.cpp:69:
warning: In file included from third-party/cimplot/implot/implot_internal.h:39:
warning: In file included from /Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0
/third-party/imgui/imgui_internal.h:48:
warning: In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Develo
per/SDKs/MacOSX.sdk/usr/include/c++/v1/math.h:309:
warning: In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Develo
per/SDKs/MacOSX.sdk/usr/include/c++/v1/type_traits:417:
warning: In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Develo
per/SDKs/MacOSX.sdk/usr/include/c++/v1/cstddef:37:
warning: /Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/third-party/version:1
:1: error: unknown type name 'Generated'
warning: Generated by cimgui version 98e6ff7051df19b76854bc3eb3cea2798f8d3bc5
warning: ^
warning: /Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/third-party/version:1
:13: error: expected ';' after top level declarator
warning: Generated by cimgui version 98e6ff7051df19b76854bc3eb3cea2798f8d3bc5
warning:             ^
warning: In file included from third-party/cimplot/implot/implot.cpp:69:
warning: third-party/cimplot/implot/implot_internal.h:101:84: error: use of undeclared identifier 'isnan'
warning: inline bool ImNanOrInf(double val) { return val == HUGE_VAL || val == -HUGE_VAL || isnan(val); }
warning:                                                                                    ^
warning: third-party/cimplot/implot/implot_internal.h:103:51: error: use of undeclared identifier 'isnan'
warning: inline double ImConstrainNan(double val) { return isnan(val) ? 0 : val; }
warning:                                                   ^
warning: 4 errors generated.

error: failed to run custom build command for `implot-sys v0.4.0 (/Users/maoe/src/github.com/4bb4/implot-r
s/implot-sys)`

Caused by:
  process didn't exit successfully: `/Users/maoe/src/github.com/4bb4/implot-rs/target/debug/build/implot-s
ys-3e514974c2ebd667/build-script-build` (exit status: 1)
  --- stdout
  TARGET = Some("x86_64-apple-darwin")
  OPT_LEVEL = Some("0")
  HOST = Some("x86_64-apple-darwin")
  CXX_x86_64-apple-darwin = None
  CXX_x86_64_apple_darwin = None
  HOST_CXX = None
  CXX = None
  CXXFLAGS_x86_64-apple-darwin = None
  CXXFLAGS_x86_64_apple_darwin = None
  HOST_CXXFLAGS = None
  CXXFLAGS = None
  CRATE_CC_NO_DEFAULTS = None
  DEBUG = Some("true")
  CARGO_CFG_TARGET_FEATURE = Some("fxsr,sse,sse2,sse3,ssse3")
  CXX_x86_64-apple-darwin = None
  CXX_x86_64_apple_darwin = None
  HOST_CXX = None
  CXX = None
  CXXFLAGS_x86_64-apple-darwin = None
  CXXFLAGS_x86_64_apple_darwin = None
  HOST_CXXFLAGS = None
  CXXFLAGS = None
  CRATE_CC_NO_DEFAULTS = None
  CARGO_CFG_TARGET_FEATURE = Some("fxsr,sse,sse2,sse3,ssse3")
  CXX_x86_64-apple-darwin = None
  CXX_x86_64_apple_darwin = None
  HOST_CXX = None
  CXX = None
  CXXFLAGS_x86_64-apple-darwin = None
  CXXFLAGS_x86_64_apple_darwin = None
  HOST_CXXFLAGS = None
  CXXFLAGS = None
  CRATE_CC_NO_DEFAULTS = None
  CARGO_CFG_TARGET_FEATURE = Some("fxsr,sse,sse2,sse3,ssse3")
  CXX_x86_64-apple-darwin = None
  CXX_x86_64_apple_darwin = None
  HOST_CXX = None
  CXX = None
  CXXFLAGS_x86_64-apple-darwin = None
  CXXFLAGS_x86_64_apple_darwin = None
  HOST_CXXFLAGS = None
  CXXFLAGS = None
  CRATE_CC_NO_DEFAULTS = None
  CARGO_CFG_TARGET_FEATURE = Some("fxsr,sse,sse2,sse3,ssse3")
  running: "c++" "-O0" "-ffunction-sections" "-fdata-sections" "-fPIC" "-g" "-fno-omit-frame-pointer" "-m6
4" "-arch" "x86_64" "-I" "/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/thir
d-party" "-I" "/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/third-party/img
ui" "-I" "third-party/cimplot/implot/" "-Wall" "-Wextra" "-Wno-return-type-c-linkage" "-Wno-unused-paramet
er" "-std=c++11" "-DCIMGUI_NO_EXPORT" "-DIMGUI_DISABLE_OSX_FUNCTIONS" "-DIMGUI_DISABLE_WIN32_FUNCTIONS" "-
o" "/Users/maoe/src/github.com/4bb4/implot-rs/target/debug/build/implot-sys-3c5e13d3fc633769/out/third-par
ty/cimplot/cimplot.o" "-c" "third-party/cimplot/cimplot.cpp"
  exit status: 0
  running: "c++" "-O0" "-ffunction-sections" "-fdata-sections" "-fPIC" "-g" "-fno-omit-frame-pointer" "-m6
4" "-arch" "x86_64" "-I" "/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/thir
d-party" "-I" "/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/third-party/img
ui" "-I" "third-party/cimplot/implot/" "-Wall" "-Wextra" "-Wno-return-type-c-linkage" "-Wno-unused-paramet
er" "-std=c++11" "-DCIMGUI_NO_EXPORT" "-DIMGUI_DISABLE_OSX_FUNCTIONS" "-DIMGUI_DISABLE_WIN32_FUNCTIONS" "-
o" "/Users/maoe/src/github.com/4bb4/implot-rs/target/debug/build/implot-sys-3c5e13d3fc633769/out/third-par
ty/cimplot/implot/implot.o" "-c" "third-party/cimplot/implot/implot.cpp"
  cargo:warning=In file included from third-party/cimplot/implot/implot.cpp:69:
  cargo:warning=In file included from third-party/cimplot/implot/implot_internal.h:39:
  cargo:warning=In file included from /Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sy
s-0.6.0/third-party/imgui/imgui_internal.h:48:
  cargo:warning=In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform
/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/math.h:309:
  cargo:warning=In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform
/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/type_traits:417:
  cargo:warning=In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform
/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/cstddef:37:
  cargo:warning=/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/third-party/ve
rsion:1:1: error: unknown type name 'Generated'
  cargo:warning=Generated by cimgui version 98e6ff7051df19b76854bc3eb3cea2798f8d3bc5
  cargo:warning=^
  cargo:warning=/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/third-party/ve
rsion:1:13: error: expected ';' after top level declarator
  cargo:warning=Generated by cimgui version 98e6ff7051df19b76854bc3eb3cea2798f8d3bc5
  cargo:warning=            ^
  cargo:warning=In file included from third-party/cimplot/implot/implot.cpp:69:
  cargo:warning=third-party/cimplot/implot/implot_internal.h:101:84: error: use of undeclared identifier '
isnan'
  cargo:warning=inline bool ImNanOrInf(double val) { return val == HUGE_VAL || val == -HUGE_VAL || isnan(v
al); }
  cargo:warning=                                                                                   ^
  cargo:warning=third-party/cimplot/implot/implot_internal.h:103:51: error: use of undeclared identifier '
isnan'
  cargo:warning=inline double ImConstrainNan(double val) { return isnan(val) ? 0 : val; }
  cargo:warning=                                                  ^
  cargo:warning=4 errors generated.
  exit status: 1

  --- stderr


  error occurred: Command "c++" "-O0" "-ffunction-sections" "-fdata-sections" "-fPIC" "-g" "-fno-omit-fram
e-pointer" "-m64" "-arch" "x86_64" "-I" "/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui
-sys-0.6.0/third-party" "-I" "/Users/maoe/.cargo/registry/src/github.com-1ecc6299db9ec823/imgui-sys-0.6.0/
third-party/imgui" "-I" "third-party/cimplot/implot/" "-Wall" "-Wextra" "-Wno-return-type-c-linkage" "-Wno
-unused-parameter" "-std=c++11" "-DCIMGUI_NO_EXPORT" "-DIMGUI_DISABLE_OSX_FUNCTIONS" "-DIMGUI_DISABLE_WIN3
2_FUNCTIONS" "-o" "/Users/maoe/src/github.com/4bb4/implot-rs/target/debug/build/implot-sys-3c5e13d3fc63376
9/out/third-party/cimplot/implot/implot.o" "-c" "third-party/cimplot/implot/implot.cpp" with args "c++" di
d not execute successfully (status code exit status: 1).

where

% c++ --version
Apple clang version 12.0.5 (clang-1205.0.22.11)
Target: x86_64-apple-darwin20.5.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

I'm on MacBook Pro 16'' 2019 (Intel). I'm sure it used to work but it stopped working at some point. Maybe when I upgraded the OS to Big Sur? I'm not sure.

How to run examples? cimplot cannot be accessed

Hi,

I tried running the examples but cannot compile.
rustc 1.66.0 (69f9c33d7 2022-12-12)
I cloned your repo, cd in implot-examples, and at first clance, line_plot is not present.
error: no example target named "line_plots". so I guess the readme might be up little outdated,
ls the dir and i see

d-----        18/02/2023     13:09                examples-shared
d-----        18/02/2023     13:13                implot-glium-demo
d-----        18/02/2023     13:08                implot-wgpu-demo
-a----        18/02/2023     13:08            762 README.md

So i try cargo run --example implot-glium-demo, but again error: no example target named "implot-glium-demo".

might be me not knowing how to use the --example flag. So I cd in implot-glium-demo and run cargo run.

It compiles until

error: failed to run custom build command for `implot-sys v0.6.0  [REDACTED]\implot-rs\implot-sys)`

Caused by:
  process didn't exit successfully: ` [REDACTED]\implot-rs\implot-examples\implot-glium-demo\target\debug\build\implot-sys-669e58a21423fafe\build-script-build` (exit code: 101)
  --- stderr
  thread 'main' panicked at 'Can't access third-party/cimplot/cimplot.cpp. Did you forget to fetch git submodules?', [REDACTED]\implot-rs\implot-sys\build.rs:21:13
  note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
warning: build failed, waiting for other jobs to finish...

what am i missing?

Update to Imgui-rs 0.7.0 and create a new release

There has been a new release of imgui-rs with new features, so I plan to update to that once I figure out everything still works ok. This is also a good time to create a new release.

`PlotHeatmap::with_label_format` is (probably) unsound

Allowing user control of the label format string is unsound, as implot passes it directly into sprintf with a 32 char buffer. (See epezent/implot#310)

Plot heatmap uses the provided format string here:
https://github.com/epezent/implot/blob/4fcc6e01aca406ef17d5a2dabdcbc9e1bd962c0d/implot_items.cpp#L2063

Setting the format string to "%100f" overflows the 32 character buffer and writes into stack memory (though on my system, glibc detects it and aborts).

The same issue is present in PlotPieChart, but that does not currently have a binding in this library.

For now, I think the safest options would be either removing it or manually generating it on the rust side (ie. generate a string `"%.{n}f" with a given level of precision, while ensuring that it is still safe)

drawing is broken when using special characters for axis labels

I used "€" so I assume only ascii is allowed or maybe it would have to be wrapped into im_str! or sth. on an api level. I've not looked into the internals but maybe this helps someone debugging :)

add original names as doc aliases to functions

https://blog.rust-lang.org/2020/11/19/Rust-1.48.html#adding-search-aliases

An interesting use case for aliases is FFI wrapper crates, where each Rust function could be aliased to the C function it wraps. Existing users of the underlying C library would then be able to easily search the right Rust functions!

I think this is a good idea and I should do the same for imnodes/ I already put the names in the comments. My approach was to basically tag a function with the name of every native function that gets called inside it.

Candlestick charts

Thanks for this crate!
I'd be really interested in the candlestick chart type.
I'd also be interested to work on that myself, if nobody else is.

Btw, can multiple charts be layered on top of another?
E.g. layering a candlestick chart with other plot types (indicators) as overlay?

Collaborate with similar projects

It seems there are a few projects around that make use of ImGUI in some form, in particular the Rust bindings. It was mentioned over at imgui-rs/imgui-rs#339 that other people have an interest in having implot Rust bindings as well, so let's talk about in what form we could collaborate.

@aloucks, it seems to me that you have quite a bit more experience than I do in creating bindings crates. If you're interested in collaboration, there are various ways we could do that:

If you're willing to put in the time to help me in places, I could build implot-rs myself. This might take some time, but teach me how to do bindings crates.
If you'd prefer getting a working implot-rs rather sooner than later and think you'd be much faster doing it yourself, I could also close the project here down and let you take over. In the end, I want the bindings, I don't much care about having my name on them.

If anyone else is interested in taking part in the project, just let me know. In the meantime I'll experiment with things some more.

Update cimplot pin

There is some new functionality like labels for second and third Y axis in BeginPlot.

Auto-scaling axis (FitNextPlotAxes)

If I have a graph with some data, by default the X and Y axes show 0-1 ranges. It would be useful to have an easy way to scale the graph to fit the data

There is the FitNextPlotAxes API which does this, but not sure how it would best integrate with the Rust API

The use cases I can think of are:

A button for the user to fit the graph (in either a specific axis like this, or maybe a shortcut to fit all)
A way to have the graph fitted on first display
Same but have the graph always fitted (and not zoomable)

Linked plots not properly loading "min" value

If I change implot-examples/examples-shared/src/line_plots.rs as follows,

     pub fn new() -> Self {
         Self {
-            linked_limits: Rc::new(RefCell::new(ImPlotRange { Min: 0.0, Max: 1.0 })),
+            linked_limits: Rc::new(RefCell::new(ImPlotRange { Min: 100.0, Max: 200.0 })),
         }
     }

The Min value is not loaded, and instead the plot defaults to the range 0..200. Same happens with linked_x_limits. Most confusingly, with Min: -100.0 things work as expected

Shorter way to set ranges

I may be missing something in the API, but currently to set the ranges of the X and Y axes requires quite a long chunk of code

Plot::new()
    .x_limits(
        &ImPlotRange { Min: 0.0, Max: 2.0 },
        implot::Condition::Always,
    )
    .y_limits(
        &ImPlotRange {Min: 0.0, Max: 20.0},
        implot::YAxisChoice::First,
        implot::Condition::Always,
    )

..which is quite verbose

One simple change which would make things more consistent with imgui-rs would to take the ranges at [f32; 2] (and convert them to ImPlotRange internally if required), this would shorten the example to:

Plot::new("Example")
    .x_limits([0.0, 2.0], implot::Condition::Always)
    .y_limits(
        [0.0, 2.0],
        implot::YAxisChoice::First,
        implot::Condition::Always,
    )

I always wonder if the y_limits could be by for the first Y limit, and a second method for the secondary Y axis if present,

Plot::new("Example")
    .y_limits([0.0, 2.0], implot::Condition::Always)
    .y2_limits([0.0, 2.0], implot::Condition::Always)
    .y3_limits([0.0, 2.0], implot::Condition::Always)

..or something along those lines (not too sure about the specific naming, would probably be easier to find if y_limits_2 etc)

Only semi-related, but Plot::new().size(100.0, 200.0) could also use this same convention for passing sizes as an array, which would fit more neatly with imgui-rs:

let full_area = ui.content_region_avail();
Plot::new("Example")
    .size(full_area[0], full_area[1])

could become just:

Plot::new("Example")
    .size(ui.content_region_avail())
`

switch to Lazy global instead of Context+Mutex

implot-rs/src/context.rs

Lines 30 to 34 in cdc7e27

    
           /// Create a context. This will also activate the context in ImPlot, and hence creating 
        
           /// a second context when one already exists is an error and will panic. 
        
           pub fn create() -> Self { 
        
               let _guard = CTX_MUTEX.lock(); 
        
               assert!(

It seems to me like it would be easier for the user if it would just have something like

static CONTEXT: Lazy<CONTEXT> = Lazy::new(|| {
    Context::create()
});

and then not have the PlotUi parameter everywhere.

because there will always only ever be one context? This could still be wrapped in a mutex if necessary.

demo build failed?

F:\rs\implot-rs\implot-examples\implot-glium-demo>cargo run
Updating ustc index
Compiling winapi v0.3.9
Compiling winit v0.25.0
Compiling imgui-sys v0.8.0
Compiling implot-sys v0.6.0 (F:\rs\implot-rs\implot-sys)
error: failed to run custom build command for implot-sys v0.6.0 (F:\rs\implot-rs\implot-sys)

Caused by:
process didn't exit successfully: F:\rs\implot-rs\implot-examples\implot-glium-demo\target\debug\build\implot-sys-87fe32f44bcaa047\build-script-build (exit code: 1)
--- stderr

error occurred: Command "d:\Program Files (x86)\Microsoft Visual Studio\2019\Preview\VC\Tools\MSVC\14.29.30132\bin\HostX64\x64\cl.exe" "-nologo" "-MT" "-Z7" "-Brepro" "-I" "C:\Users\Administrator\.cargo\registry\src\mirrors.ustc.edu.cn-12df342d903acd47\imgui-sys-0.8.0\third-party" "-I" "C:\Users\Administrator\.cargo\registry\src\mirrors.ustc.edu.cn-12df342d903acd47\imgui-sys-0.8.0\third-party\imgui" "-I" "third-party/cimplot/implot/" "-W4" "-DCIMGUI_NO_EXPORT" "-DIMGUI_DISABLE_OSX_FUNCTIONS" "-DIMGUI_DISABLE_WIN32_FUNCTIONS" "-DIMGUI_USE_WCHAR32" "-FoF:\rs\implot-rs\implot-examples\implot-glium-demo\target\debug\build\implot-sys-6132c7af9f575321\out\third-party/cimplot/cimplot.o" "-c" "third-party/cimplot/cimplot.cpp" with args "cl.exe" did not execute successfully (status code exit code: 2).

warning: build failed, waiting for other jobs to finish...
error: build failed

	/// Create a context. This will also activate the context in ImPlot, and hence creating
	/// a second context when one already exists is an error and will panic.
	pub fn create() -> Self {
	let _guard = CTX_MUTEX.lock();
	assert!(