Skip to main content

plotters_ternary/chart/
context.rs

1use plotters::backend::DrawingBackend;
2use plotters::chart::{ChartContext, SeriesAnno, SeriesLabelStyle};
3use plotters::coord::cartesian::Cartesian2d;
4use plotters::coord::types::RangedCoordf64;
5use plotters::drawing::DrawingArea;
6use plotters::element::{Drawable, PointCollection};
7use plotters::style::ShapeStyle;
8
9use crate::coord::{TernaryGeometry, TernaryViewport, Tolerance, ViewportAlignment, ViewportFit};
10use crate::series::{
11    PointMarkerStyleProvider, SeriesError, TernaryPointSeries, TernarySeries, prepare_points,
12};
13
14use super::{TernaryChartError, TernaryMeshConfig};
15
16/// The concrete Cartesian context used internally by a ternary chart.
17pub type CartesianChartContext<'a, DB> =
18    ChartContext<'a, DB, Cartesian2d<RangedCoordf64, RangedCoordf64>>;
19
20/// The concrete logical plotting area used internally by a ternary chart.
21pub type CartesianPlottingArea<DB> = DrawingArea<DB, Cartesian2d<RangedCoordf64, RangedCoordf64>>;
22
23/// A ternary chart backed by an owned Plotters Cartesian chart context.
24///
25/// The lifetime parameter belongs to Plotters' stored series annotations. The
26/// context owns a cloned drawing area and does not borrow the builder's root.
27pub struct TernaryChart<'a, DB: DrawingBackend> {
28    pub(crate) context: CartesianChartContext<'a, DB>,
29    pub(crate) geometry: TernaryGeometry,
30    pub(crate) viewport: TernaryViewport,
31    pub(crate) fit: ViewportFit,
32    pub(crate) alignment: ViewportAlignment,
33    pub(crate) tolerance: Tolerance,
34}
35
36impl<'a, DB: DrawingBackend> TernaryChart<'a, DB> {
37    /// Configure and draw the Milestone 3 boundary, grid, and basic names.
38    pub fn configure_mesh(&mut self) -> TernaryMeshConfig<'_, 'a, DB> {
39        TernaryMeshConfig::new(self)
40    }
41    /// Draw a ternary-aware series and return Plotters' native annotation.
42    pub fn draw_series<'chart, S>(
43        &'chart mut self,
44        series: S,
45    ) -> Result<&'chart mut SeriesAnno<'a, DB>, TernaryChartError<DB::ErrorType>>
46    where
47        DB: 'a,
48        S: TernarySeries<DB>,
49    {
50        series.draw(self)
51    }
52
53    /// Draw points with an owned ordinary Plotters element from a custom closure.
54    ///
55    /// The closure receives the projected logical anchor, configured backend
56    /// pixel size, and Plotters `ShapeStyle`. Composable elements can begin at
57    /// `EmptyElement::at(anchor)` and use local backend coordinates thereafter.
58    pub fn draw_point_series<'chart, I, P, Provider, F, E>(
59        &'chart mut self,
60        series: TernaryPointSeries<I, Provider>,
61        make_marker: F,
62    ) -> Result<&'chart mut SeriesAnno<'a, DB>, TernaryChartError<DB::ErrorType>>
63    where
64        DB: 'a,
65        I: IntoIterator<Item = P>,
66        P: Into<crate::coord::TernaryPoint>,
67        Provider: PointMarkerStyleProvider,
68        F: Fn((f64, f64), u32, ShapeStyle) -> E,
69        for<'element> &'element E: PointCollection<'element, (f64, f64)>,
70        E: Drawable<DB>,
71    {
72        let (
73            points,
74            size,
75            style,
76            _marker,
77            _custom_style,
78            _provider,
79            clip_mode,
80            normalization,
81            tolerance,
82            invalid_policy,
83        ) = series.into_parts();
84        if size == 0 {
85            return Err(SeriesError::InvalidMarkerSize { size }.into());
86        }
87        let anchors = prepare_points(
88            self.geometry,
89            self.viewport,
90            points,
91            normalization,
92            tolerance,
93            invalid_policy,
94            clip_mode,
95        )?;
96        let elements = anchors
97            .into_iter()
98            .map(move |point| make_marker((point.x, point.y), size, style));
99        self.context.draw_series(elements).map_err(Into::into)
100    }
101
102    /// Forward ordinary Plotters legend configuration without wrapping it.
103    pub fn configure_series_labels<'chart>(
104        &'chart mut self,
105    ) -> SeriesLabelStyle<'a, 'chart, DB, Cartesian2d<RangedCoordf64, RangedCoordf64>>
106    where
107        DB: 'a,
108    {
109        self.context.configure_series_labels()
110    }
111
112    /// Borrow the underlying Cartesian Plotters chart.
113    pub const fn cartesian_chart(&self) -> &CartesianChartContext<'a, DB> {
114        &self.context
115    }
116
117    /// Mutably borrow the underlying Cartesian Plotters chart.
118    pub fn cartesian_chart_mut(&mut self) -> &mut CartesianChartContext<'a, DB> {
119        &mut self.context
120    }
121
122    /// Borrow the underlying logical Cartesian plotting area.
123    pub fn plotting_area(&self) -> &CartesianPlottingArea<DB> {
124        self.context.plotting_area()
125    }
126
127    /// Return the triangle geometry used by this chart.
128    pub const fn geometry(&self) -> TernaryGeometry {
129        self.geometry
130    }
131
132    /// Return the requested logical clipping viewport.
133    pub const fn viewport(&self) -> TernaryViewport {
134        self.viewport
135    }
136
137    /// Return the selected fitting policy.
138    pub const fn viewport_fit(&self) -> ViewportFit {
139        self.fit
140    }
141
142    /// Return the selected alignment inside unused allocated space.
143    pub const fn viewport_alignment(&self) -> ViewportAlignment {
144        self.alignment
145    }
146}