plotters/
lib.rs

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