Support for advanced plots/graphs

[dmccloskey]

I noticed on the feature/roadmap list an item for plots/graphs. I would be interested in seeing several common chart types that are currently not available (i.e., scatter, pie, box and whiskers, heatmap, etc.,) that could then be integrated with the rest of the ImGui framework to create a dynamic dashboard.

Where would you recommend a contributing developer to start on adding in this type of support? I would imagine support for defining axes, tick marks, legends, scales, color scales, and the like would be a pre-requisite for any advanced plotting and graphing functionality.

[ocornut]

Hello Douglas,

I would suggest checking the old topics marked with the plot/graph to get few ideas. This is generally a wide topic so I don't really have much answers now. My rough intuition was to create a structure that would hold temporary state, and provide a bunch of helpers that the user can combine manually and freely:

ImGuiPlotter plotter("id");
plotter.CalcRanges() ?
plotter.DrawGrid()
plotter.PlotLines(data, color, ...)
// query hovered position, etc.
plotter.PlotLines(data, color, ...)

(Consider this a dumb example, it's only there to suggest that we can't possibly fit everything in a single function call).

The system would use the window storage or custom global storage to persist information e.g. allowing user to scroll/scale the view or interact with it in various way.

This is probably a thing that needs to be iterated on a lot and for a while before finding the right sweet spot. I reckon I could come up with a nice prototype if I spent a week on it. You could give it a try, would be happy to see results out of it!

Having an exhaustive, ideal list of every desirable features would be good so we can refer to it while designing the system.

I think this could perfectly be implemented/iterated in a separate file, taking advantage of imgui_internal.h access to private data structures/functions. Depending on how useful and how big it becomes, we may consider either integrating it in the default imgui distribution (either merged in imgui.cpp or a different file), or possibly making it an official extension. As imgui is growing those questions will come back for a few other features. The main thing to pay attention to is to work with the same coding style as the regular imgui library (e.g. no dependency on STL, being mindful of performances and memory allocations).

[dmccloskey]

List of plotting library features

list inspired by d3.js and matplotlib

Common plot components

• Figure size and layout attributes
• Subplots
• Scales (numeric and color)
• Axes (ticks, titles)
• Labels

Chart types

• stem
• scatter (normal, loglog, semilog, logx, logy)
• line
• area
• bar (vertical, horizontal, broken)
• stacked (bar, area)
• boxplot (with whiskers, horizontal/vertical)
• pie (doughnut)
• stream
• polar (bar, scatter)
• radar
• step
• hexagonal binning
• histogram (density, etc.,)
• 2D histogram
• Power spectral density
• violin plot
• contour plot
• facet grid
• heatmap (with or without clusters/dendrograms)
• joint plot
• strip plot
• lvplot
• swarm plot
• pcolor

Chart components

• error bar
• time series error shades
• legend
• color bar

Layout types

• circos layout
• swim lanes
• bundle diagram
• chord diagram
• force directed graph
• force layout
• indented tree layout
• pack layout
• partition layout
• radial dendrogram
• radial tree layout
• sankey diagram
• treemap layout
• vertical dendrogram

[dmccloskey]

Hi Omar,

Thanks for those pointers. This will definitely be something that will need quite a few iterations. There are some very nice plotting libraries out already that one can take inspiration from (e.g., matplotlib or several of the plotting libraries sitting on top of d3.js).

I can start taking some shots at it over the next few weeks. Your reviews/comments on the code when the time comes will be greatly appreciated

[dmccloskey]

Hi Omar,

I had a few questions that I did not see on the wiki:

1. coding style: would you approve of the use of templates? I don't think have seen any in your code base so far.
2. code quality: are there any unit tests or suggestions for incorporating unit tests for debugging? There are some math related additions (e.g., bspline interpolation) where a couple of simple unit tests would be great for basic sanity checking.

This is the branch that I will be adding the code to: https://github.com/dmccloskey/imgui/tree/feature/imguiplotter. The plot code will be added to the file "imgui_plot.h" and "imgui_plot.c". The only sections in the main code base that I see additions being made to are in the IMGUI_DEFINE_MATH_OPERATORS section of "imgui_internal.h".

There is not much new to report at the moment. It is mostly an outline, but if you do find time to peruse the code, any feedback is more than welcome. In particular, your thoughts on what you think the interfaces should look like if they differ from what you would envision.

[ocornut]

Hello Douglas,

Thanks! Quick feedback:

• C++ template: if necessary (they are being used for ImVector<>), but the problem is that if you define low-level types this way you'll probably end dragging everything in header files (along with creating more duplicated function instances). If the code pass in pointer to data blocks then better have a public interface using e.g. void* data_ptr, enum ImGuiDataType data_type then if needed the leaf code in the .cpp file may dispatch processing to template functions.

• I am not sure I understand understand PlotDatum nor the the ImVector structure at the moment. Does PlotDatum represent a set of values (where x/y are scales and series is the data?) or a single sample to be plotted? Dear ImGui strive to avoid requiring the user duplicating data, so for the samples themselves the API should ideally work with raw data that the user already have. Moreover, we are talking about code that will execute every frame, so extraneous copies, touching entire data set or even allocations are generally undesirable at all and needs a strong justification.

• I suggest focusing on pseudo code + pseudo API along with iterating on data structure, it'll make their usage more obvious. So you can iterate on both the simple example (how would the code look like if I want to plot 1-2 arrays of data as lines?) along more advanced one. The sweet spot would be to make the common use cases very simple and obvious, with natural path toward more advanced usage.

• Not knowing much about advanced plotting, personally I was thinking more in terms of humble steps focused on things like: plotting multiple data set (with simple techniques like Lines or Bar), interacting with the view (translate/zoom, etc.), draw grids, let the calling code access info about what the user is hovering. That's not in opposition with any of your work, I'm here just stating how I imagined what the first usable version of the code would provide. I might as well experiment with the interactive side of thing and our work could merge.

• Data could come from discrete samples but also from functions. As highlighted by the really weird and misleading code in imgui_demo displaying a sin() wave, the current API uses indices which is not a best fit for every use case. Ideally we could be able to display a perfect sin() wave - using a function which would be sampled by the plotter based on the current view - alongside with a discrete sampled data.

• The functions you added to imgui_internal.h could just be added in imgui_plot.cpp for now, that will ease your merging for?. You might as well work in an isolated repository and have imgui as an external repo. If those functions become useful for other cases then why not moving them to imgui_internal but it seems like there's no immediate needs.

• Unit tests: there's none at the moment. It is one of my target for 2018 but until then you may use e.g. asserts or a bit of custom glue to create tests.

• Code formatting: imgui doesn't uses tabs and use MembersName, local_variable casing. Note very important for now.

Omar

[dmccloskey]

Hi Omar,

Thank you for your feedback. Your comments are greatly appreciated.

I have made some changes based on your comments. I have also constructed a “minimal” (and quite buggy) scatter plot example as a means to prototype classes and user interfaces exposed by “imgui_plot.h” so far. The example is in the directory “examples/sdl_opengl2_plot_example”. This folder (and any other lingering files from prototyping) will of course be deleted prior to submitting any merge request.

I wanted to check in on the following:

1. If my changes are inline with your previous comments
2. I wanted to inquire about some odd behavior I am getting when using DrawList. In the example, I call methods of class ImPlot2D called ShowXAxisTop and ShowLegend. However, they are never rendered. The method bodies are executed, but it looks like nothing is rendered to the window. Is there a simple mistake that I am making? Whatever the problem is, I am completely baffled at this point.

Douglas

[dmccloskey]

@ocornut by any chance would you have time to chat over Gitter or over e.g., Skype? I have several questions that I think could be addressed quite quickly.

Best,

Douglas

[ocornut]

@dmccloskey Send me an e-mail. My e-mail is in the README.

[dmccloskey]

A workable scatter plot with tooltip, a legend, axes, ticks, and 1 axis label - the other axis label should be available in the next iteration ;).

[sashabel]

Hello, it this feature going to be merged in the master ? I am really waiting for the advanced plotting (especially 3d and multiline). It would be also nice to include optionally a background image (suppose a map) so I could plot a function on top of it.

[epezent]

@dmccloskey and others: I've been working on a plotting API you may be interested in.

See https://github.com/ocornut/imgui/issues/3173 or ImPlot

[dmccloskey]

@epezent That is is awesome! I see some similarities in the code to what we were developing, but notable quite a bit more polished and importantly ready to use. I look forward to giving it a run.