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