1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
/*! Defines the drawing elements, the high-level drawing unit in Plotters drawing system ## Introduction An element is the drawing unit for Plotter's high-level drawing API. Different from low-level drawing API, an element is a logic unit of component in the image. There are few built-in elements, including `Circle`, `Pixel`, `Rectangle`, `Path`, `Text`, etc. All element can be drawn onto the drawing area using API `DrawingArea::draw(...)`. Plotters use "iterator of elements" as the abstraction of any type of plot. ## Implementing your own element You can also define your own element, `CandleStick` is a good sample of implementing complex element. There are two trait required for an element: - `PointCollection` - the struct should be able to return an iterator of key-points under guest coordinate - `Drawable` - the struct is a pending drawing operation on a drawing backend with pixel-based coordinate An example of element that draws a red "X" in a red rectangle onto the backend: ```rust use std::iter::{Once, once}; use plotters::element::{PointCollection, Drawable}; use plotters::drawing::backend::{BackendCoord, DrawingErrorKind}; use plotters::style::IntoTextStyle; use plotters::prelude::*; // Any example drawing a red X struct RedBoxedX((i32, i32)); // For any reference to RedX, we can convert it into an iterator of points impl <'a> PointCollection<'a, (i32, i32)> for &'a RedBoxedX { type Borrow = &'a (i32, i32); type IntoIter = Once<&'a (i32, i32)>; fn point_iter(self) -> Self::IntoIter { once(&self.0) } } // How to actually draw this element impl <DB:DrawingBackend> Drawable<DB> for RedBoxedX { fn draw<I:Iterator<Item = BackendCoord>>( &self, mut pos: I, backend: &mut DB, _: (u32, u32), ) -> Result<(), DrawingErrorKind<DB::ErrorType>> { let pos = pos.next().unwrap(); let color = RED.to_rgba(); backend.draw_rect(pos, (pos.0 + 10, pos.1 + 12), &color, false)?; let text_style = &("sans-serif", 20).into_text_style(backend).color(&color); backend.draw_text("X", &text_style, pos) } } fn main() -> Result<(), Box<dyn std::error::Error>> { let root = BitMapBackend::new( "plotters-doc-data/element-0.png", (640, 480) ).into_drawing_area(); root.draw(&RedBoxedX((200, 200)))?; Ok(()) } ``` ![](https://plotters-rs.github.io/plotters-doc-data/element-0.png) ## Composable Elements You also have an convenient way to build an element that isn't built into the Plotters library by combining existing elements into a logic group. To build an composable element, you need to use an logic empty element that draws nothing to the backend but denotes the relative zero point of the logical group. Any element defined with pixel based offset coordinate can be added into the group later using the `+` operator. For example, the red boxed X element can be implemented with Composable element in the following way: ```rust use plotters::prelude::*; fn main() -> Result<(), Box<dyn std::error::Error>> { let root = BitMapBackend::new( "plotters-doc-data/element-1.png", (640, 480) ).into_drawing_area(); let font:FontDesc = ("sans-serif", 20).into(); root.draw(&(EmptyElement::at((200, 200)) + Text::new("X", (0, 0), &"sans-serif".into_font().resize(20.0).color(&RED)) + Rectangle::new([(0,0), (10, 12)], &RED) ))?; Ok(()) } ``` ![](https://plotters-rs.github.io/plotters-doc-data/element-1.png) ## Dynamic Elements By default, Plotters uses static dispatch for all the elements and series. For example, the `ChartContext::draw_series` method accepts an iterator of `T` where type `T` implements all the traits a element should implement. Although, we can use the series of composable element for complex series drawing. But sometimes, we still want to make the series heterogynous, which means the iterator should be able to holds elements in different type. For example, a point series with cross and circle. This requires the dynamically dispatched elements. In plotters, all the elements can be converted into `DynElement`, the dynamic dispatch container for all elements (include external implemented ones). Plotters automatically implements `IntoDynElement` for all elements, by doing so, any dynamic element should have `into_dyn` function which would wrap the element into a dynamic element wrapper. For example, the following code counts the number of factors of integer and mark all prime numbers in cross. ```rust use plotters::prelude::*; fn num_of_factor(n: i32) -> i32 { let mut ret = 2; for i in 2..n { if i * i > n { break; } if n % i == 0 { if i * i != n { ret += 2; } else { ret += 1; } } } return ret; } fn main() -> Result<(), Box<dyn std::error::Error>> { let root = BitMapBackend::new("plotters-doc-data/element-3.png", (640, 480)) .into_drawing_area(); root.fill(&WHITE)?; let mut chart = ChartBuilder::on(&root) .x_label_area_size(40) .y_label_area_size(40) .margin(5) .build_ranged(0..50, 0..10)?; chart .configure_mesh() .disable_x_mesh() .disable_y_mesh() .draw()?; chart.draw_series((0..50).map(|x| { let center = (x, num_of_factor(x)); // Although the arms of if statement has different types, // but they can be placed into a dynamic element wrapper, // by doing so, the type is unified. if center.1 == 2 { Cross::new(center, 4, Into::<ShapeStyle>::into(&RED).filled()).into_dyn() } else { Circle::new(center, 4, Into::<ShapeStyle>::into(&GREEN).filled()).into_dyn() } }))?; Ok(()) } ``` ![](https://plotters-rs.github.io/plotters-doc-data/element-3.png) */ use crate::drawing::backend::{BackendCoord, DrawingBackend, DrawingErrorKind}; use std::borrow::Borrow; mod basic_shapes; pub use basic_shapes::*; mod text; pub use text::*; mod points; pub use points::*; mod composable; pub use composable::{ComposedElement, EmptyElement}; #[cfg(feature = "candlestick")] mod candlestick; #[cfg(feature = "candlestick")] pub use candlestick::CandleStick; #[cfg(feature = "errorbar")] mod errorbar; #[cfg(feature = "errorbar")] pub use errorbar::{ErrorBar, ErrorBarOrientH, ErrorBarOrientV}; #[cfg(feature = "boxplot")] mod boxplot; #[cfg(feature = "boxplot")] pub use boxplot::Boxplot; #[cfg(feature = "bitmap")] mod image; #[cfg(feature = "bitmap")] pub use self::image::BitMapElement; mod dynelem; pub use dynelem::{DynElement, IntoDynElement}; /// A type which is logically a collection of points, under any given coordinate system pub trait PointCollection<'a, Coord> { /// The item in point iterator type Borrow: Borrow<Coord>; /// The point iterator type IntoIter: IntoIterator<Item = Self::Borrow>; /// framework to do the coordinate mapping fn point_iter(self) -> Self::IntoIter; } /// The trait indicates we are able to draw it on a drawing area pub trait Drawable<DB: DrawingBackend> { /// Actually draws the element. The key points is already translated into the /// image coordinate and can be used by DC directly fn draw<I: Iterator<Item = BackendCoord>>( &self, pos: I, backend: &mut DB, parent_dim: (u32, u32), ) -> Result<(), DrawingErrorKind<DB::ErrorType>>; }