plotters_unstable/lib.rs
1/*!
2
3# Plotters - A Rust drawing library focus on data plotting for both WASM and native applications 🦀📈🚀
4
5<a href="https://crates.io/crates/plotters">
6 <img style="display: inline!important" src="https://img.shields.io/crates/v/plotters.svg"></img>
7</a>
8<a href="https://docs.rs/plotters">
9 <img style="display: inline!important" src="https://docs.rs/plotters/badge.svg"></img>
10</a>
11<a href="https://plotters-rs.github.io/rustdoc/plotters/">
12 <img style="display: inline! important" src="https://img.shields.io/badge/docs-development-lightgrey.svg"></img>
13</a>
14<a href="https://travis-ci.org/38/plotters">
15 <img style="display: inline! important" src="https://travis-ci.org/38/plotters.svg?branch=master"></img>
16</a>
17<a href="https://codecov.io/gh/38/plotters">
18 <img style="display: inline! important" src="https://codecov.io/gh/38/plotters/branch/master/graph/badge.svg" />
19</a>
20
21Plotters is drawing library designed for rendering figures, plots, and charts, in pure rust. Plotters supports various types of back-ends,
22including bitmap, vector graph, piston window, GTK/Cairo and WebAssembly.
23
24- A new Plotters Developer's Guide is working in progress. The preview version is available at [here](https://plotters-rs.github.io/book).
25- To try Plotters with interactive Jupyter notebook, or view [here](https://plotters-rs.github.io/plotters-doc-data/evcxr-jupyter-integration.html) for the static HTML version.
26- To view the WASM example, go to this [link](https://plumberserver.com/plotters-wasm-demo/index.html)
27- Currently we have all the internal code ready for console plotting, but a console based backend is still not ready. See [this example](https://github.com/38/plotters/blob/master/examples/console.rs) for how to plotting on Console with a customized backend.
28
29## Gallery
30
31<div class="galleryItem">
32 <a href="https://plotters-rs.github.io/plotters-doc-data/sample.png">
33 <img src="https://plotters-rs.github.io/plotters-doc-data/sample.png" class="galleryItem"></img>
34 </a>
35 <div class="galleryText">
36 Multiple Plot
37 <a href="https://github.com/38/plotters/blob/master/examples/chart.rs">[code]</a>
38 </div>
39</div>
40
41<div class="galleryItem">
42 <a href="https://plotters-rs.github.io/plotters-doc-data/stock.png">
43 <img src="https://plotters-rs.github.io/plotters-doc-data/stock.png" class="galleryItem"></img>
44 </a>
45 <div class="galleryText">
46 Candlestick Plot
47 <a href="https://github.com/38/plotters/blob/master/examples/stock.rs">[code]</a>
48 </div>
49</div>
50
51<div class="galleryItem">
52 <a href="https://plotters-rs.github.io/plotters-doc-data/histogram.png">
53 <img src="https://plotters-rs.github.io/plotters-doc-data/histogram.png" class="galleryItem"></img>
54 </a>
55 <div class="galleryText">
56 Histogram
57 <a href="https://github.com/38/plotters/blob/master/examples/histogram.rs">[code]</a>
58 </div>
59</div>
60
61<div class="galleryItem">
62 <a href="https://plotters-rs.github.io/plotters-doc-data/0.png">
63 <img src="https://plotters-rs.github.io/plotters-doc-data/0.png" class="galleryItem"></img>
64 </a>
65 <div class="galleryText">
66 Simple Chart
67 </div>
68</div>
69
70<div class="galleryItem">
71 <a href="https://plotters-rs.github.io/plotters-doc-data/console-2.png">
72 <img src="https://plotters-rs.github.io/plotters-doc-data/console-2.png" class="galleryItem"></img>
73 </a>
74 <div class="galleryText">
75 Plotting the Console
76 </div>
77</div>
78
79<div class="galleryItem">
80 <a href="https://plotters-rs.github.io/plotters-doc-data/mandelbrot.png">
81 <img src="https://plotters-rs.github.io/plotters-doc-data/mandelbrot.png" class="galleryItem"></img>
82 </a>
83 <div class="galleryText">
84 Mandelbrot set
85 <a href="https://github.com/38/plotters/blob/master/examples/mandelbrot.rs">[code]</a>
86 </div>
87</div>
88
89
90<div class="galleryItem">
91 <a href="https://plotters-rs.github.io/plotters-doc-data/evcxr_animation.gif">
92 <img src="https://plotters-rs.github.io/plotters-doc-data/evcxr_animation.gif" class="galleryItem"></img>
93 </a>
94 <div class="galleryText">
95 Jupyter Support
96 </div>
97</div>
98
99<div class="galleryItem">
100 <a href="https://plotters-rs.github.io/plotters-doc-data/plotters-piston.gif">
101 <img src="https://plotters-rs.github.io/plotters-doc-data/plotters-piston.gif" class="galleryItem"></img>
102 </a>
103 <div class="galleryText">
104 Real-time Rendering
105 <a href="https://github.com/38/plotters/tree/master/examples/piston-demo">[code]</a>
106 </div>
107</div>
108
109<div class="galleryItem">
110 <a href="https://plotters-rs.github.io/plotters-doc-data/normal-dist.png">
111 <img src="https://plotters-rs.github.io/plotters-doc-data/normal-dist.png" class="galleryItem"></img>
112 </a>
113 <div class="galleryText">
114 Histogram with Scatter
115 <a href="https://github.com/38/plotters/blob/master/examples/normal-dist.rs">[code]</a>
116 </div>
117</div>
118
119<div class="galleryItem">
120 <a href="https://plotters-rs.github.io/plotters-doc-data/twoscale.png">
121 <img src="https://plotters-rs.github.io/plotters-doc-data/twoscale.png" class="galleryItem"></img>
122 </a>
123 <div class="galleryText">
124 Dual Y-Axis Example
125 <a href="https://github.com/38/plotters/blob/master/examples/two-scales.rs">[code]</a>
126 </div>
127</div>
128
129<div class="galleryItem">
130 <a href="https://plotters-rs.github.io/plotters-doc-data/matshow.png">
131 <img src="https://plotters-rs.github.io/plotters-doc-data/matshow.png" class="galleryItem"></img>
132 </a>
133 <div class="galleryText">
134 The Matplotlib Matshow Example
135 <a href="https://github.com/38/plotters/blob/master/examples/matshow.rs">[code]</a>
136 </div>
137</div>
138
139<div class="galleryItem">
140 <a href="https://plotters-rs.github.io/plotters-doc-data/sierpinski.png">
141 <img src="https://plotters-rs.github.io/plotters-doc-data/sierpinski.png" class="galleryItem"></img>
142 </a>
143 <div class="galleryText">
144 The Sierpinski Carpet
145 <a href="https://github.com/38/plotters/blob/master/examples/sierpinski.rs">[code]</a>
146 </div>
147</div>
148
149<div class="galleryItem">
150 <a href="https://plotters-rs.github.io/plotters-doc-data/normal-dist2.png">
151 <img src="https://plotters-rs.github.io/plotters-doc-data/normal-dist2.png" class="galleryItem"></img>
152 </a>
153 <div class="galleryText">
154 The 1D Gaussian Distribution
155 <a href="https://github.com/38/plotters/blob/master/examples/nomal-dist2.rs">[code]</a>
156 </div>
157</div>
158
159<div class="galleryItem">
160 <a href="https://plotters-rs.github.io/plotters-doc-data/errorbar.png">
161 <img src="https://plotters-rs.github.io/plotters-doc-data/errorbar.png" class="galleryItem"></img>
162 </a>
163 <div class="galleryText">
164 The 1D Gaussian Distribution
165 <a href="https://github.com/38/plotters/blob/master/examples/errorbar.rs">[code]</a>
166 </div>
167</div>
168
169<div class="galleryItem">
170 <a href="https://plotters-rs.github.io/plotters-doc-data/slc-temp.png">
171 <img src="https://plotters-rs.github.io/plotters-doc-data/slc-temp.png" class="galleryItem"></img>
172 </a>
173 <div class="galleryText">
174 Monthly Time Coordinate
175 <a href="https://github.com/38/plotters/blob/master/examples/slc-temp.rs">[code]</a>
176 </div>
177</div>
178
179<div class="galleryItem">
180 <a href="https://plotters-rs.github.io/plotters-doc-data/area-chart.png">
181 <img src="https://plotters-rs.github.io/plotters-doc-data/area-chart.png" class="galleryItem"></img>
182 </a>
183 <div class="galleryText">
184 Monthly Time Coordinate
185 <a href="https://github.com/38/plotters/blob/master/examples/area-chart.rs">[code]</a>
186 </div>
187</div>
188
189<div class="galleryItem">
190 <a href="https://plotters-rs.github.io/plotters-doc-data/snowflake.png">
191 <img src="https://plotters-rs.github.io/plotters-doc-data/snowflake.png" class="galleryItem"></img>
192 </a>
193 <div class="galleryText">
194 Koch Snowflake
195 <a href="https://github.com/38/plotters/blob/master/examples/snowflake.rs">[code]</a>
196 </div>
197</div>
198
199
200<div class="galleryItem">
201 <a href="https://plotters-rs.github.io/plotters-doc-data/animation.gif">
202 <img src="https://plotters-rs.github.io/plotters-doc-data/animation.gif" class="galleryItem"></img>
203 </a>
204 <div class="galleryText">
205 Koch Snowflake Animation
206 <a href="https://github.com/38/plotters/blob/master/examples/animation.rs">[code]</a>
207 </div>
208</div>
209
210
211<div class="galleryItem">
212 <a href="https://plotters-rs.github.io/plotters-doc-data/console.png">
213 <img src="https://plotters-rs.github.io/plotters-doc-data/console.png" class="galleryItem"></img>
214 </a>
215 <div class="galleryText">
216 Drawing on a Console
217 <a href="https://github.com/38/plotters/blob/master/examples/console.rs">[code]</a>
218 </div>
219</div>
220
221<div class="galleryItem">
222 <a href="https://plotters-rs.github.io/plotters-doc-data/blit-bitmap.png">
223 <img src="https://plotters-rs.github.io/plotters-doc-data/blit-bitmap.png" class="galleryItem"></img>
224 </a>
225 <div class="galleryText">
226 Drawing bitmap on chart
227 <a href="https://github.com/38/plotters/blob/master/examples/blit-bitmap.rs">[code]</a>
228 </div>
229</div>
230
231<div class="galleryItem">
232 <a href="https://plotters-rs.github.io/plotters-doc-data/boxplot.svg">
233 <img src="https://plotters-rs.github.io/plotters-doc-data/boxplot.svg" class="galleryItem"></img>
234 </a>
235 <div class="galleryText">
236 Drawing bitmap on chart
237 <a href="https://github.com/38/plotters/blob/master/examples/boxplot.rs">[code]</a>
238 </div>
239</div>
240
241
242## Table of Contents
243 * [Gallery](#gallery)
244 * [Quick Start](#quick-start)
245 * [Trying with Jupyter evcxr Kernel Interactively](#trying-with-jupyter-evcxr-kernel-interactively)
246 * [Interactive Tutorial with Jupyter Notebook](#interactive-tutorial-with-jupyter-notebook)
247 * [Plotting in Rust](#plotting-in-rust)
248 * [Plotting on HTML5 canvas with WASM Backend](#plotting-on-html5-canvas-with-wasm-backend)
249 * [What types of figure are supported?](#what-types-of-figure-are-supported)
250 * [Concepts by examples](#concepts-by-examples)
251 + [Drawing Back-ends](#drawing-backends)
252 + [Drawing Area](#drawing-area)
253 + [Elements](#elements)
254 + [Composable Elements](#composable-elements)
255 + [Chart Context](#chart-context)
256 * [Misc](#misc)
257 + [Development Version](#development-version)
258 + [Reducing Depending Libraries && Turning Off Backends](#reducing-depending-libraries--turning-off-backends)
259 + [List of Features](#list-of-features)
260 * [FAQ List](#faq-list)
261
262## Quick Start
263
264To use Plotters, you can simply add Plotters into your `Cargo.toml`
265```toml
266[dependencies]
267plotters = "^0.2.15"
268```
269
270And the following code draws a quadratic function. `src/main.rs`,
271
272```rust
273use plotters::prelude::*;
274fn main() -> Result<(), Box<dyn std::error::Error>> {
275 let root = BitMapBackend::new("plotters-doc-data/0.png", (640, 480)).into_drawing_area();
276 root.fill(&WHITE)?;
277 let mut chart = ChartBuilder::on(&root)
278 .caption("y=x^2", ("sans-serif", 50).into_font())
279 .margin(5)
280 .x_label_area_size(30)
281 .y_label_area_size(30)
282 .build_ranged(-1f32..1f32, -0.1f32..1f32)?;
283
284 chart.configure_mesh().draw()?;
285
286 chart
287 .draw_series(LineSeries::new(
288 (-50..=50).map(|x| x as f32 / 50.0).map(|x| (x, x * x)),
289 &RED,
290 ))?
291 .label("y = x^2")
292 .legend(|(x, y)| PathElement::new(vec![(x, y), (x + 20, y)], &RED));
293
294 chart
295 .configure_series_labels()
296 .background_style(&WHITE.mix(0.8))
297 .border_style(&BLACK)
298 .draw()?;
299
300 Ok(())
301}
302```
303
304
305
306
307## Trying with Jupyter evcxr Kernel Interactively
308
309Plotters now supports integrate with `evcxr` and is able to interactively drawing plots in Jupyter Notebook.
310The feature `evcxr` should be enabled when including Plotters to Jupyter Notebook.
311
312The following code shows a minimal example of this.
313
314```text
315:dep plotters = { git = "https://github.com/38/plotters", default_features = false, features = ["evcxr"] }
316extern crate plotters;
317use plotters::prelude::*;
318
319let figure = evcxr_figure((640, 480), |root| {
320 root.fill(&WHITE);
321 let mut chart = ChartBuilder::on(&root)
322 .caption("y=x^2", ("Arial", 50).into_font())
323 .margin(5)
324 .x_label_area_size(30)
325 .y_label_area_size(30)
326 .build_ranged(-1f32..1f32, -0.1f32..1f32)?;
327
328 chart.configure_mesh().draw()?;
329
330 chart.draw_series(LineSeries::new(
331 (-50..=50).map(|x| x as f32 / 50.0).map(|x| (x, x * x)),
332 &RED,
333 )).unwrap()
334 .label("y = x^2")
335 .legend(|(x,y)| PathElement::new(vec![(x,y), (x + 20,y)], &RED));
336
337 chart.configure_series_labels()
338 .background_style(&WHITE.mix(0.8))
339 .border_style(&BLACK)
340 .draw()?;
341 Ok(())
342});
343figure
344```
345
346<img src="https://plotters-rs.github.io/plotters-doc-data/evcxr_animation.gif" width="450px"></img>
347
348## Interactive Tutorial with Jupyter Notebook
349
350*This tutorial is now working in progress and isn't complete*
351
352Thanks to the evcxr, now we have an interactive tutorial for Plotters!
353To use the interactive notebook, you must have Jupyter and evcxr installed on your computer.
354Follow the instruction on [this page](https://github.com/google/evcxr/tree/master/evcxr_jupyter) below to install it.
355
356After that, you should be able to start your Jupyter server locally and load the tutorial!
357
358```bash
359git clone https://github.com/38/plotters-doc-data
360cd plotteres-doc-data
361jupyter notebook
362```
363
364And select the notebook called `evcxr-jupyter-integration.ipynb`.
365
366Also, there's a static HTML version of this notebook available at the [this location](https://plumberserver.com/plotters-docs/evcxr-jupyter-integration.html)
367
368## Plotting in Rust
369
370Rust is a perfect language for data visualization. Although there are many mature visualization libraries in many different languages.
371But Rust is one of the best languages fits the need.
372
373* **Easy to use** Rust has a very good iterator system built into the standard library. With the help of iterators,
374Plotting in Rust can be as easy as most of the high-level programming languages. The Rust based plotting library
375can be very easy to use.
376
377* **Fast** If you need rendering a figure with trillions of data points,
378Rust is a good choice. Rust's performance allows you to combine data processing step
379and rendering step into a single application. When plotting in high-level programming languages,
380e.g. Javascript or Python, data points must be down-sampled before feeding into the plotting
381program because of the performance considerations. Rust is fast enough to do the data processing and visualization
382within a single program. You can also integrate the
383figure rendering code into your application handling a huge amount of data and visualize it in real-time.
384
385* **WebAssembly Support** Rust is one of few the language with the best WASM support. Plotting in Rust could be
386very useful for visualization on a web page and would have a huge performance improvement comparing to Javascript.
387
388## Plotting on HTML5 canvas with WASM Backend
389
390Plotters currently supports backend that uses the HTML5 canvas. To use the WASM support, you can simply use
391`CanvasBackend` instead of other backend and all other API remains the same!
392
393There's a small demo for Plotters + WASM under `examples/wasm-demo` directory of this repo.
394To play with the deployed version, follow this [link](https://plumberserver.com/plotters-wasm-demo/index.html).
395
396
397## What types of figure are supported?
398
399Plotters is not limited to any specific type of figure.
400You can create your own types of figures easily with the Plotters API.
401
402But Plotters provides some builtin figure types for convenience.
403Currently, we support line series, point series, candlestick series, and histogram.
404And the library is designed to be able to render multiple figure into a single image.
405But Plotter is aimed to be a platform that is fully extendable to support any other types of figure.
406
407## Concepts by examples
408
409### Drawing Back-ends
410Plotters can use different drawing back-ends, including SVG, BitMap, and even real-time rendering. For example, a bitmap drawing backend.
411
412```rust
413use plotters::prelude::*;
414fn main() -> Result<(), Box<dyn std::error::Error>> {
415 // Create a 800*600 bitmap and start drawing
416 let mut backend = BitMapBackend::new("plotters-doc-data/1.png", (300, 200));
417 // And if we want SVG backend
418 // let backend = SVGBackend::new("output.svg", (800, 600));
419 backend.draw_rect((50, 50), (200, 150), &RED, true)?;
420 Ok(())
421}
422```
423
424
425
426### Drawing Area
427Plotters uses a concept called drawing area for layout purpose.
428Plotters support multiple integrating into a single image.
429This is done by creating sub-drawing-areas.
430
431Besides that, the drawing area also allows the customized coordinate system, by doing so, the coordinate mapping is done by the drawing area automatically.
432
433```rust
434use plotters::prelude::*;
435fn main() -> Result<(), Box<dyn std::error::Error>> {
436 let root_drawing_area =
437 BitMapBackend::new("plotters-doc-data/2.png", (300, 200)).into_drawing_area();
438 // And we can split the drawing area into 3x3 grid
439 let child_drawing_areas = root_drawing_area.split_evenly((3, 3));
440 // Then we fill the drawing area with different color
441 for (area, color) in child_drawing_areas.into_iter().zip(0..) {
442 area.fill(&Palette99::pick(color))?;
443 }
444 Ok(())
445}
446```
447
448
449
450### Elements
451
452In Plotters, elements are build blocks of figures. All elements are able to draw on a drawing area.
453There are different types of built-in elements, like lines, texts, circles, etc.
454You can also define your own element in the application code.
455
456You may also combine existing elements to build a complex element.
457
458To learn more about the element system, please read the [element module documentation](./element/index.html).
459
460```rust
461use plotters::prelude::*;
462fn main() -> Result<(), Box<dyn std::error::Error>> {
463 let root = BitMapBackend::new("plotters-doc-data/3.png", (300, 200)).into_drawing_area();
464 root.fill(&WHITE)?;
465 // Draw an circle on the drawing area
466 root.draw(&Circle::new(
467 (100, 100),
468 50,
469 Into::<ShapeStyle>::into(&GREEN).filled(),
470 ))?;
471 Ok(())
472}
473```
474
475
476
477### Composable Elements
478
479Besides the built-in elements, elements can be composed into a logic group we called composed elements.
480When composing new elements, the upper-left corner is given in the target coordinate, and a new pixel-based
481coordinate which has the upper-left corner defined as `(0,0)` is used for further element composition purpose.
482
483For example, we can have an element which includes a dot and its coordinate.
484
485```rust
486use plotters::prelude::*;
487use plotters::coord::types::RangedCoordf32;
488
489fn main() -> Result<(), Box<dyn std::error::Error>> {
490 let root = BitMapBackend::new("plotters-doc-data/4.png", (640, 480)).into_drawing_area();
491
492 root.fill(&RGBColor(240, 200, 200))?;
493
494 let root = root.apply_coord_spec(Cartesian2d::<RangedCoordf32, RangedCoordf32>::new(
495 0f32..1f32,
496 0f32..1f32,
497 (0..640, 0..480),
498 ));
499
500 let dot_and_label = |x: f32, y: f32| {
501 return EmptyElement::at((x, y))
502 + Circle::new((0, 0), 3, ShapeStyle::from(&BLACK).filled())
503 + Text::new(
504 format!("({:.2},{:.2})", x, y),
505 (10, 0),
506 ("sans-serif", 15.0).into_font(),
507 );
508 };
509
510 root.draw(&dot_and_label(0.5, 0.6))?;
511 root.draw(&dot_and_label(0.25, 0.33))?;
512 root.draw(&dot_and_label(0.8, 0.8))?;
513 Ok(())
514}
515```
516
517
518
519### Chart Context
520
521In order to draw a chart, Plotters need a data object built on top of the drawing area called `ChartContext`.
522The chart context defines even higher level constructs compare to the drawing area.
523For example, you can define the label areas, meshes, and put a data series onto the drawing area with the help
524of the chart context object.
525
526```rust
527use plotters::prelude::*;
528fn main() -> Result<(), Box<dyn std::error::Error>> {
529 let root = BitMapBackend::new("plotters-doc-data/5.png", (640, 480)).into_drawing_area();
530 root.fill(&WHITE);
531 let root = root.margin(10, 10, 10, 10);
532 // After this point, we should be able to draw construct a chart context
533 let mut chart = ChartBuilder::on(&root)
534 // Set the caption of the chart
535 .caption("This is our first plot", ("sans-serif", 40).into_font())
536 // Set the size of the label region
537 .x_label_area_size(20)
538 .y_label_area_size(40)
539 // Finally attach a coordinate on the drawing area and make a chart context
540 .build_ranged(0f32..10f32, 0f32..10f32)?;
541
542 // Then we can draw a mesh
543 chart
544 .configure_mesh()
545 // We can customize the maximum number of labels allowed for each axis
546 .x_labels(5)
547 .y_labels(5)
548 // We can also change the format of the label text
549 .y_label_formatter(&|x| format!("{:.3}", x))
550 .draw()?;
551
552 // And we can draw something in the drawing area
553 chart.draw_series(LineSeries::new(
554 vec![(0.0, 0.0), (5.0, 5.0), (8.0, 7.0)],
555 &RED,
556 ))?;
557 // Similarly, we can draw point series
558 chart.draw_series(PointSeries::of_element(
559 vec![(0.0, 0.0), (5.0, 5.0), (8.0, 7.0)],
560 5,
561 &RED,
562 &|c, s, st| {
563 return EmptyElement::at(c) // We want to construct a composed element on-the-fly
564 + Circle::new((0,0),s,st.filled()) // At this point, the new pixel coordinate is established
565 + Text::new(format!("{:?}", c), (10, 0), ("sans-serif", 10).into_font());
566 },
567 ))?;
568 Ok(())
569}
570```
571
572
573
574## Misc
575
576### Development Version
577
578To use the latest development version, pull https://github.com/38/plotters.git. In `Cargo.toml`
579
580```toml
581[dependencies]
582plotters = { git = "https://github.com/38/plotters.git" }
583```
584
585### Reducing Depending Libraries && Turning Off Backends
586Plotters now supports use features to control the backend dependencies. By default, `BitMapBackend` and `SVGBackend` are supported,
587use `default_features = false` in the dependency description in `Cargo.toml` and you can cherry-pick the backend implementations.
588
589- `svg` Enable the `SVGBackend`
590- `bitmap` Enable the `BitMapBackend`
591
592For example, the following dependency description would avoid compiling with bitmap support:
593
594```toml
595[dependencies]
596plotters = { git = "https://github.com/38/plotters.git", default_features = false, features = ["svg"] }
597```
598
599The library also allows consumers to make use of the [`Palette`](https://crates.io/crates/palette/) crate's color types by default.
600This behavior can also be turned off by setting `default_features = false`.
601
602### List of Features
603
604This is the full list of features that is defined by `Plotters` crate.
605Use `default_features = false` to disable those default enabled features,
606and then you should be able to cherry-pick what features you want to include into `Plotters` crate.
607By doing so, you can minimize the number of dependencies down to only `itertools` and compile time is less than 6s.
608
609The following list is a complete list of features that can be opt in and out.
610
611- Drawing backends related features
612
613| Name | Description | Additional Dependency |Default?|
614|---------|--------------|--------|------------|
615| image\_encoder | Allow `BitMapBackend` save the result to bitmap files | image, rusttype, font-kit | Yes |
616| svg | Enable `SVGBackend` Support | None | Yes |
617| gif\_backend| Opt-in GIF animation Rendering support for `BitMapBackend`, implies `bitmap` enabled | gif | Yes |
618| piston | Enable `PistonWindowBackend` | piston\_window, rusttype, font-kit | No |
619| cairo | Enable `CairoBackend` | cairo-rs, rusttype, font-kit | No |
620
621- Font manipulation features
622
623| Name | Description | Additional Dependency |Default?|
624|---------|--------------|--------|------------|
625| ttf | Allows TrueType font support | rusttype, font-kit | Yes |
626
627- Coordinate features
628
629| Name | Description | Additional Dependency |Default?|
630|---------|--------------|--------|------------|
631| datetime | Eanble the date and time coordinate support | chrono | Yes |
632
633- Element, series and util functions
634
635| Name | Description | Additional Dependency |Default?|
636|---------|--------------|--------|------------|
637| errorbar | The errorbar element support | None | Yes |
638| candlestick | The candlestick element support | None | Yes |
639| boxplot | The boxplot element support | None | Yes |
640| area\_series | The area series support | None | Yes |
641| line\_series | The line series support | None | Yes |
642| histogram | The histogram series support | None | Yes |
643| point\_series| The point series support | None | Yes |
644
645- Misc
646
647| Name | Description | Additional Dependency |Default?|
648|---------|--------------|--------|------------|
649| deprecated\_items | This feature allows use of deprecated items which is going to be removed in the future | None | Yes |
650| debug | Enable the code used for debugging | None | No |
651
652
653## FAQ List
654
655* Why does the WASM example break on my machine ?
656
657 The WASM example requires using `wasm32` target to build. Using `cargo build` is likely to use the default target
658 which in most of the case is any of the x86 target. Thus you need add `--target=wasm32-unknown-unknown` in the cargo
659 parameter list to build it.
660
661* How to draw text/circle/point/rectangle/... on the top of chart ?
662
663 As you may realized, Plotters is a drawing library rather than a traditional data plotting library,
664 you have the freedom to draw anything you want on the drawing area.
665 Use `DrawingArea::draw` to draw any element on the drawing area.
666
667
668<style>
669 img {
670 display: block;
671 margin: 0 auto;
672 max-width: 500px;
673 }
674 .galleryItem {
675 width: 250px;
676 display: inline-block;
677 }
678 .galleryImg {
679 max-width: 100%;
680 }
681 .galleryText {
682 text-align: center;
683 }
684</style>
685
686
687*/
688pub mod chart;
689pub mod coord;
690pub mod data;
691pub mod drawing;
692pub mod element;
693pub mod series;
694pub mod style;
695
696#[cfg(feature = "evcxr")]
697pub mod evcxr;
698
699#[cfg(test)]
700pub use crate::drawing::{check_color, create_mocked_drawing_area};
701
702#[cfg(feature = "palette_ext")]
703pub use palette;
704
705/// The module imports the most commonly used types and modules in Plotters
706pub mod prelude {
707 // Chart related types
708 pub use crate::chart::{ChartBuilder, ChartContext, LabelAreaPosition, SeriesLabelPosition};
709
710 // Coordinates
711 pub use crate::coord::{
712 cartesian::Cartesian2d,
713 combinators::{
714 make_partial_axis, BindKeyPointMethod, BindKeyPoints, BuildNestedCoord, GroupBy,
715 IntoLinspace, IntoLogRange, IntoPartialAxis, Linspace, LogCoord, LogRange, LogScalable,
716 NestedRange, NestedValue, ToGroupByRange,
717 },
718 ranged1d::{DiscreteRanged, IntoSegmentedCoord, Ranged, SegmentValue},
719 CoordTranslate,
720 };
721
722 #[cfg(feature = "chrono")]
723 pub use crate::coord::types::{
724 IntoMonthly, IntoYearly, RangedDate, RangedDateTime, RangedDuration,
725 };
726
727 // Re-export the backend for backward compatibility
728 pub use plotters_backend::DrawingBackend;
729
730 pub use crate::drawing::*;
731
732 // Series helpers
733 #[cfg(feature = "area_series")]
734 pub use crate::series::AreaSeries;
735 #[cfg(feature = "histogram")]
736 pub use crate::series::Histogram;
737 #[cfg(feature = "line_series")]
738 pub use crate::series::LineSeries;
739 #[cfg(feature = "point_series")]
740 pub use crate::series::PointSeries;
741
742 // Styles
743 pub use crate::style::{
744 AsRelative, Color, FontDesc, FontFamily, FontStyle, FontTransform, HSLColor, IntoFont,
745 Palette, Palette100, Palette99, Palette9999, PaletteColor, RGBColor, ShapeStyle, TextStyle,
746 };
747 pub use crate::style::{BLACK, BLUE, CYAN, GREEN, MAGENTA, RED, TRANSPARENT, WHITE, YELLOW};
748
749 // Elements
750 pub use crate::element::{
751 Circle, Cross, DynElement, EmptyElement, IntoDynElement, MultiLineText, PathElement, Pixel,
752 Polygon, Rectangle, Text, TriangleMarker,
753 };
754
755 #[cfg(feature = "boxplot")]
756 pub use crate::element::Boxplot;
757 #[cfg(feature = "candlestick")]
758 pub use crate::element::CandleStick;
759 #[cfg(feature = "errorbar")]
760 pub use crate::element::ErrorBar;
761
762 #[cfg(feature = "bitmap_backend")]
763 pub use crate::element::BitMapElement;
764
765 // Data
766 pub use crate::data::Quartiles;
767
768 // TODO: This should be deprecated and completely removed
769 #[cfg(feature = "deprecated_items")]
770 #[allow(deprecated)]
771 pub use crate::element::Path;
772
773 #[allow(type_alias_bounds)]
774 /// The type used to returns a drawing operation that can be failed
775 /// - `T`: The return type
776 /// - `D`: The drawing backend type
777 pub type DrawResult<T, D: DrawingBackend> =
778 Result<T, crate::drawing::DrawingAreaErrorKind<D::ErrorType>>;
779
780 #[cfg(feature = "evcxr")]
781 pub use crate::evcxr::evcxr_figure;
782
783 // Re-export tier 1 backends for backward compatibility
784 #[cfg(feature = "bitmap_backend")]
785 pub use plotters_bitmap::BitMapBackend;
786
787 #[cfg(feature = "svg_backend")]
788 pub use plotters_svg::SVGBackend;
789}