plotters/coord/ranged1d/
mod.rs

Help
1/*!
2  The one-dimensional coordinate system abstraction.
3
4  Plotters build complex coordinate system with a combinator pattern and all the coordinate system is
5  built from the one dimensional coordinate system. This module defines the fundamental types used by
6  the one-dimensional coordinate system.
7
8  The key trait for a one dimensional coordinate is [Ranged](trait.Ranged.html). This trait describes a
9  set of values which served as the 1D coordinate system in Plotters. In order to extend the coordinate system,
10  the new coordinate spec must implement this trait.
11
12  The following example demonstrate how to make a customized coordinate specification
13  ```
14use plotters::coord::ranged1d::{Ranged, DefaultFormatting, KeyPointHint};
15use std::ops::Range;
16
17struct ZeroToOne;
18
19impl Ranged for ZeroToOne {
20    type ValueType = f64;
21    type FormatOption = DefaultFormatting;
22
23    fn map(&self, &v: &f64, pixel_range: (i32, i32)) -> i32 {
24       let size = pixel_range.1 - pixel_range.0;
25       let v = v.min(1.0).max(0.0);
26       ((size as f64) * v).round() as i32
27    }
28
29    fn key_points<Hint:KeyPointHint>(&self, hint: Hint) -> Vec<f64> {
30        if hint.max_num_points() < 3 {
31            vec![]
32        } else {
33            vec![0.0, 0.5, 1.0]
34        }
35    }
36
37    fn range(&self) -> Range<f64> {
38        0.0..1.0
39    }
40}
41
42use plotters::prelude::*;
43
44let mut buffer = vec![0; 1024 * 768 * 3];
45let root = BitMapBackend::with_buffer(&mut buffer, (1024, 768)).into_drawing_area();
46
47let chart = ChartBuilder::on(&root)
48    .build_cartesian_2d(ZeroToOne, ZeroToOne)
49    .unwrap();
50
51  ```
52*/
53use std::fmt::Debug;
54use std::ops::Range;
55
56pub(super) mod combinators;
57pub(super) mod types;
58
59mod discrete;
60pub use discrete::{DiscreteRanged, IntoSegmentedCoord, SegmentValue, SegmentedCoord};
61
62/// Since stable Rust doesn't have specialization, it's very hard to make our own trait that
63/// automatically implemented the value formatter. This trait uses as a marker indicates if we
64/// should automatically implement the default value formater based on it's `Debug` trait
65pub trait DefaultValueFormatOption {}
66
67/// This makes the ranged coord uses the default `Debug` based formatting
68pub struct DefaultFormatting;
69impl DefaultValueFormatOption for DefaultFormatting {}
70
71/// This markers prevent Plotters to implement the default `Debug` based formatting
72pub struct NoDefaultFormatting;
73impl DefaultValueFormatOption for NoDefaultFormatting {}
74
75/// Determine how we can format a value in a coordinate system by default
76pub trait ValueFormatter<V> {
77    /// Format the value
78    fn format(value: &V) -> String;
79}
80
81// By default the value is formatted by the debug trait
82impl<R: Ranged<FormatOption = DefaultFormatting>> ValueFormatter<R::ValueType> for R
83where
84    R::ValueType: Debug,
85{
86    fn format(value: &R::ValueType) -> String {
87        format!("{:?}", value)
88    }
89}
90
91/// Specify the weight of key points.
92pub enum KeyPointWeight {
93    // Allows only bold key points
94    Bold,
95    // Allows any key points
96    Any,
97}
98
99impl KeyPointWeight {
100    /// Check if this key point weight setting allows light point
101    pub fn allow_light_points(&self) -> bool {
102        match self {
103            KeyPointWeight::Bold => false,
104            KeyPointWeight::Any => true,
105        }
106    }
107}
108
109/// The trait for a hint provided to the key point algorithm used by the coordinate specs.
110/// The most important constraint is the `max_num_points` which means the algorithm could emit no more than specific number of key points
111/// `weight` is used to determine if this is used as a bold grid line or light grid line
112/// `bold_points` returns the max number of coresponding bold grid lines
113pub trait KeyPointHint {
114    /// Returns the max number of key points
115    fn max_num_points(&self) -> usize;
116    /// Returns the weight for this hint
117    fn weight(&self) -> KeyPointWeight;
118    /// Returns the point number constraint for the bold points
119    fn bold_points(&self) -> usize {
120        self.max_num_points()
121    }
122}
123
124impl KeyPointHint for usize {
125    fn max_num_points(&self) -> usize {
126        *self
127    }
128
129    fn weight(&self) -> KeyPointWeight {
130        KeyPointWeight::Any
131    }
132}
133
134///  The key point hint indicates we only need key point for the bold grid lines
135pub struct BoldPoints(pub usize);
136
137impl KeyPointHint for BoldPoints {
138    fn max_num_points(&self) -> usize {
139        self.0
140    }
141
142    fn weight(&self) -> KeyPointWeight {
143        KeyPointWeight::Bold
144    }
145}
146
147/// The key point hint indicates that we are using the key points for the light grid lines
148pub struct LightPoints {
149    bold_points_num: usize,
150    light_limit: usize,
151}
152
153impl LightPoints {
154    /// Create a new light key point hind
155    pub fn new(bold_count: usize, requested: usize) -> Self {
156        Self {
157            bold_points_num: bold_count,
158            light_limit: requested,
159        }
160    }
161}
162
163impl KeyPointHint for LightPoints {
164    fn max_num_points(&self) -> usize {
165        self.light_limit
166    }
167
168    fn bold_points(&self) -> usize {
169        self.bold_points_num
170    }
171
172    fn weight(&self) -> KeyPointWeight {
173        KeyPointWeight::Any
174    }
175}
176
177/// The trait that indicates we have a ordered and ranged value
178/// Which is used to describe any 1D axis.
179pub trait Ranged {
180    /// This marker decides if Plotters default [ValueFormatter](trait.ValueFormatter.html) implementation should be used.
181    /// This assicated type can be one of follow two types:
182    /// - [DefaultFormatting](struct.DefaultFormatting.html) will allow Plotters automatically impl
183    /// the formatter based on `Debug` trait, if `Debug` trait is not impl for the `Self::Value`,
184    /// [ValueFormatter](trait.ValueFormatter.html) will not impl unless you impl it manually.
185    ///
186    /// - [NoDefaultFormatting](struct.NoDefaultFormatting.html) Disable the automatical `Debug`
187    /// based value formatting. Thus you have to impl the
188    /// [ValueFormatter](trait.ValueFormatter.html) manually.
189    ///
190    type FormatOption: DefaultValueFormatOption;
191
192    /// The type of this value in this range specification
193    type ValueType;
194
195    /// This function maps the value to i32, which is the drawing coordinate
196    fn map(&self, value: &Self::ValueType, limit: (i32, i32)) -> i32;
197
198    /// This function gives the key points that we can draw a grid based on this
199    fn key_points<Hint: KeyPointHint>(&self, hint: Hint) -> Vec<Self::ValueType>;
200
201    /// Get the range of this value
202    fn range(&self) -> Range<Self::ValueType>;
203
204    /// This function provides the on-axis part of its range
205    #[allow(clippy::range_plus_one)]
206    fn axis_pixel_range(&self, limit: (i32, i32)) -> Range<i32> {
207        if limit.0 < limit.1 {
208            limit.0..limit.1
209        } else {
210            (limit.1 + 1)..(limit.0 + 1)
211        }
212    }
213}
214
215/// The trait indicates the ranged value can be map reversely, which means
216/// an pixel-based coordinate is given, it's possible to figure out the underlying
217/// logic value.
218pub trait ReversibleRanged: Ranged {
219    fn unmap(&self, input: i32, limit: (i32, i32)) -> Option<Self::ValueType>;
220}
221
222/// The trait for the type that can be converted into a ranged coordinate axis
223pub trait AsRangedCoord: Sized {
224    type CoordDescType: Ranged<ValueType = Self::Value> + From<Self>;
225    type Value;
226}
227
228impl<T> AsRangedCoord for T
229where
230    T: Ranged,
231{
232    type CoordDescType = T;
233    type Value = T::ValueType;
234}
plotters/coord/ranged1d/mod.rs

plotters/coord/ranged1d/
mod.rs
