Skip to main content

plotters_ternary/chart/
builder.rs

1use plotters::backend::DrawingBackend;
2use plotters::chart::ChartBuilder;
3use plotters::coord::Shift;
4use plotters::drawing::DrawingArea;
5use plotters::style::{IntoTextStyle, TextStyle};
6
7use crate::coord::{
8    PixelRect, TernaryGeometry, TernaryViewport, Tolerance, ViewportAlignment, ViewportFit,
9    ViewportTransform,
10};
11
12use super::{TernaryChart, TernaryChartError};
13
14const DEFAULT_MARGIN: u32 = 20;
15
16/// Builder for an owned, Cartesian-backed [`TernaryChart`].
17///
18/// The implicit viewport is resolved at build time from the current geometry.
19/// Once [`TernaryChartBuilder::viewport`] is called, later geometry changes do
20/// not replace that explicit viewport.
21pub struct TernaryChartBuilder<'root, DB: DrawingBackend> {
22    root: &'root DrawingArea<DB, Shift>,
23    geometry: TernaryGeometry,
24    viewport: Option<TernaryViewport>,
25    fit: ViewportFit,
26    alignment: ViewportAlignment,
27    caption: Option<(String, TextStyle<'root>)>,
28    margin: u32,
29    tolerance: Tolerance,
30}
31
32impl<'root, DB: DrawingBackend> TernaryChartBuilder<'root, DB> {
33    /// Begin a ternary chart in a Plotters root drawing area.
34    pub fn on(root: &'root DrawingArea<DB, Shift>) -> Self {
35        Self {
36            root,
37            geometry: TernaryGeometry::default(),
38            viewport: None,
39            fit: ViewportFit::default(),
40            alignment: ViewportAlignment::default(),
41            caption: None,
42            margin: DEFAULT_MARGIN,
43            tolerance: Tolerance::default(),
44        }
45    }
46
47    /// Set the triangle geometry.
48    ///
49    /// An implicit full viewport follows this geometry at build time. An
50    /// explicitly selected viewport is preserved.
51    pub const fn geometry(mut self, geometry: TernaryGeometry) -> Self {
52        self.geometry = geometry;
53        self
54    }
55
56    /// Select an explicit logical clipping viewport.
57    pub const fn viewport(mut self, viewport: TernaryViewport) -> Self {
58        self.viewport = Some(viewport);
59        self
60    }
61
62    /// Select aspect preservation or explicit stretching.
63    pub const fn viewport_fit(mut self, fit: ViewportFit) -> Self {
64        self.fit = fit;
65        self
66    }
67
68    /// Align an aspect-fitted plotting subarea.
69    pub const fn viewport_alignment(mut self, alignment: ViewportAlignment) -> Self {
70        self.alignment = alignment;
71        self
72    }
73
74    /// Add a Plotters-rendered caption outside the fitted ternary viewport.
75    pub fn caption<S, Style>(mut self, caption: S, style: Style) -> Self
76    where
77        S: AsRef<str>,
78        Style: IntoTextStyle<'root>,
79    {
80        self.caption = Some((
81            caption.as_ref().to_owned(),
82            style.into_text_style(self.root),
83        ));
84        self
85    }
86
87    /// Set equal outer margins in backend pixels.
88    pub const fn margin(mut self, margin: u32) -> Self {
89        self.margin = margin;
90        self
91    }
92
93    /// Build the owned Cartesian chart on an aspect-fitted Plotters subarea.
94    pub fn build<'chart>(self) -> Result<TernaryChart<'chart, DB>, TernaryChartError<DB::ErrorType>>
95    where
96        DB: 'chart,
97    {
98        let viewport = self.resolved_viewport();
99        let mut allocated = self.root.clone();
100        if let Some((caption, style)) = self.caption {
101            allocated = allocated.titled(&caption, style)?;
102        }
103
104        let (available_width, available_height) = allocated.dim_in_pixel();
105        let total_margin = self.margin.saturating_mul(2);
106        if available_width <= total_margin || available_height <= total_margin {
107            return Err(TernaryChartError::InsufficientDrawingArea {
108                width: available_width.saturating_sub(total_margin),
109                height: available_height.saturating_sub(total_margin),
110            });
111        }
112        allocated = allocated.margin(self.margin, self.margin, self.margin, self.margin);
113
114        let (width, height) = allocated.dim_in_pixel();
115
116        let pixel_rect = PixelRect::new(0, 0, width, height)?;
117        let transform = ViewportTransform::new(viewport, pixel_rect, self.fit, self.alignment)?;
118        let fitted = integer_fitted_rect(transform, width, height)?;
119        let fitted_area = allocated.shrink(
120            (fitted.x, fitted.y),
121            (fitted.width as i32, fitted.height as i32),
122        );
123
124        let context = ChartBuilder::on(&fitted_area).build_cartesian_2d(
125            viewport.x_min()..viewport.x_max(),
126            viewport.y_min()..viewport.y_max(),
127        )?;
128
129        Ok(TernaryChart {
130            context,
131            geometry: self.geometry,
132            viewport,
133            fit: self.fit,
134            alignment: self.alignment,
135            tolerance: self.tolerance,
136        })
137    }
138
139    pub(crate) fn resolved_viewport(&self) -> TernaryViewport {
140        self.viewport
141            .unwrap_or_else(|| TernaryViewport::full(self.geometry))
142    }
143}
144
145fn integer_fitted_rect<E: std::error::Error + Send + Sync>(
146    transform: ViewportTransform,
147    allocated_width: u32,
148    allocated_height: u32,
149) -> Result<PixelRect, TernaryChartError<E>> {
150    let bounds = transform.fitted_pixel_bounds();
151    let x_min = bounds.x_min.round().clamp(0.0, f64::from(allocated_width)) as i32;
152    let y_min = bounds.y_min.round().clamp(0.0, f64::from(allocated_height)) as i32;
153    let x_max = bounds.x_max.round().clamp(0.0, f64::from(allocated_width)) as i32;
154    let y_max = bounds.y_max.round().clamp(0.0, f64::from(allocated_height)) as i32;
155    let width = (x_max - x_min).max(0) as u32;
156    let height = (y_max - y_min).max(0) as u32;
157    if width == 0 || height == 0 {
158        return Err(TernaryChartError::InsufficientDrawingArea { width, height });
159    }
160    PixelRect::new(x_min, y_min, width, height).map_err(TernaryChartError::from)
161}
162
163#[cfg(test)]
164mod tests {
165    use plotters::prelude::*;
166
167    use super::*;
168    use crate::{TriangleOrientation, VertexOrder};
169
170    #[test]
171    fn explicit_viewport_survives_later_geometry_selection() {
172        let mut buffer = vec![0; 200 * 200 * 3];
173        let root = BitMapBackend::with_buffer(&mut buffer, (200, 200)).into_drawing_area();
174        let viewport = TernaryViewport::new(0.6, 0.9, 0.1, 0.4).unwrap();
175        let geometry = TernaryGeometry::new(TriangleOrientation::Down, VertexOrder::default());
176        let builder = TernaryChartBuilder::on(&root)
177            .viewport(viewport)
178            .geometry(geometry);
179        assert_eq!(builder.resolved_viewport(), viewport);
180    }
181
182    #[test]
183    fn implicit_viewport_tracks_downward_geometry() {
184        let mut buffer = vec![0; 200 * 200 * 3];
185        let root = BitMapBackend::with_buffer(&mut buffer, (200, 200)).into_drawing_area();
186        let geometry = TernaryGeometry::new(TriangleOrientation::Down, VertexOrder::default());
187        let builder = TernaryChartBuilder::on(&root).geometry(geometry);
188        assert_eq!(builder.resolved_viewport(), TernaryViewport::full(geometry));
189    }
190
191    #[test]
192    fn excessive_margin_returns_a_layout_error() {
193        let mut buffer = vec![0; 100 * 100 * 3];
194        let root = BitMapBackend::with_buffer(&mut buffer, (100, 100)).into_drawing_area();
195        let result = TernaryChartBuilder::on(&root).margin(60).build();
196        assert!(matches!(
197            result,
198            Err(TernaryChartError::InsufficientDrawingArea {
199                width: 0,
200                height: 0
201            })
202        ));
203    }
204
205    #[test]
206    fn preserve_aspect_keeps_equal_logical_scales_after_integer_rounding() {
207        let geometry = TernaryGeometry::new(TriangleOrientation::Down, VertexOrder::default());
208        let viewport = TernaryViewport::full(geometry);
209        let transform = ViewportTransform::new(
210            viewport,
211            PixelRect::new(0, 0, 920, 700).unwrap(),
212            ViewportFit::PreserveAspect,
213            ViewportAlignment::Center,
214        )
215        .unwrap();
216        let fitted = integer_fitted_rect::<std::io::Error>(transform, 920, 700).unwrap();
217        let x_scale = f64::from(fitted.width) / viewport.width();
218        let y_scale = f64::from(fitted.height) / viewport.height();
219        assert!((x_scale - y_scale).abs() <= 1.0);
220    }
221}