plotters/chart/context/cartesian3d/
mod.rs

1use crate::chart::{axes3d::Axes3dStyle, ChartContext};
2use crate::coord::{
3    cartesian::Cartesian3d,
4    ranged1d::{Ranged, ValueFormatter},
5    ranged3d::{ProjectionMatrix, ProjectionMatrixBuilder},
6};
7use plotters_backend::DrawingBackend;
8
9mod draw_impl;
10
11#[derive(Clone, Debug)]
12pub(crate) enum Coord3D<X, Y, Z> {
13    X(X),
14    Y(Y),
15    Z(Z),
16}
17
18impl<X, Y, Z> Coord3D<X, Y, Z> {
19    fn get_x(&self) -> &X {
20        match self {
21            Coord3D::X(ret) => ret,
22            _ => panic!("Invalid call!"),
23        }
24    }
25    fn get_y(&self) -> &Y {
26        match self {
27            Coord3D::Y(ret) => ret,
28            _ => panic!("Invalid call!"),
29        }
30    }
31    fn get_z(&self) -> &Z {
32        match self {
33            Coord3D::Z(ret) => ret,
34            _ => panic!("Invalid call!"),
35        }
36    }
37
38    fn build_coord([x, y, z]: [&Self; 3]) -> (X, Y, Z)
39    where
40        X: Clone,
41        Y: Clone,
42        Z: Clone,
43    {
44        (x.get_x().clone(), y.get_y().clone(), z.get_z().clone())
45    }
46}
47
48impl<'a, DB, X, Y, Z, XT, YT, ZT> ChartContext<'a, DB, Cartesian3d<X, Y, Z>>
49where
50    DB: DrawingBackend,
51    X: Ranged<ValueType = XT> + ValueFormatter<XT>,
52    Y: Ranged<ValueType = YT> + ValueFormatter<YT>,
53    Z: Ranged<ValueType = ZT> + ValueFormatter<ZT>,
54{
55    /**
56    Create an axis configuration object, to set line styles, labels, sizes, etc.
57
58    Default values for axis configuration are set by function `Axes3dStyle::new()`.
59
60    # Example
61
62    ```
63    use plotters::prelude::*;
64    let drawing_area = SVGBackend::new("configure_axes.svg", (300, 200)).into_drawing_area();
65    drawing_area.fill(&WHITE).unwrap();
66    let mut chart_builder = ChartBuilder::on(&drawing_area);
67    let mut chart_context = chart_builder.margin_bottom(30).build_cartesian_3d(0.0..4.0, 0.0..3.0, 0.0..2.7).unwrap();
68    chart_context.configure_axes().tick_size(8).x_labels(4).y_labels(3).z_labels(2)
69        .max_light_lines(5).axis_panel_style(GREEN.mix(0.1)).bold_grid_style(BLUE.mix(0.3))
70        .light_grid_style(BLUE.mix(0.2)).label_style(("Calibri", 10))
71        .x_formatter(&|x| format!("x={x}")).draw().unwrap();
72    ```
73
74    The resulting chart reflects the customizations specified through `configure_axes()`:
75
76    ![](https://cdn.jsdelivr.net/gh/facorread/plotters-doc-data@4c3cef4/apidoc/configure_axes.svg)
77
78    All these customizations are `Axes3dStyle` methods.
79
80    In the chart, `tick_size(8)` produces tick marks 8 pixels long. You can use
81    `(5u32).percent().max(5).in_pixels(chart.plotting_area()` to tell Plotters to calculate the tick mark
82    size as a percentage of the dimensions of the figure. See [`crate::style::RelativeSize`] and
83    [`crate::style::SizeDesc`] for more information.
84
85    `x_labels(4)` specifies a maximum of 4
86    tick marks and labels in the X axis. `max_light_lines(5)` specifies a maximum of 5 minor grid lines
87    between any two tick marks. `axis_panel_style(GREEN.mix(0.1))` specifies the style of the panels in
88    the background, a light green color. `bold_grid_style(BLUE.mix(0.3))` and `light_grid_style(BLUE.mix(0.2))`
89    specify the style of the major and minor grid lines, respectively. `label_style()` specifies the text
90    style of the axis labels, and `x_formatter(|x| format!("x={x}"))` specifies the string format of the X
91    axis labels.
92
93    # See also
94
95    [`ChartContext::configure_mesh()`], a similar function for 2D plots
96    */
97    pub fn configure_axes(&mut self) -> Axes3dStyle<'a, '_, X, Y, Z, DB> {
98        Axes3dStyle::new(self)
99    }
100}
101
102impl<'a, DB, X: Ranged, Y: Ranged, Z: Ranged> ChartContext<'a, DB, Cartesian3d<X, Y, Z>>
103where
104    DB: DrawingBackend,
105{
106    /// Override the 3D projection matrix. This function allows to override the default projection
107    /// matrix.
108    /// - `pf`: A function that takes the default projection matrix configuration and returns the
109    ///   projection matrix. This function will allow you to adjust the pitch, yaw angle and the
110    ///   centeral point of the projection, etc. You can also build a projection matrix which is not
111    ///   relies on the default configuration as well.
112    pub fn with_projection<P: FnOnce(ProjectionMatrixBuilder) -> ProjectionMatrix>(
113        &mut self,
114        pf: P,
115    ) -> &mut Self {
116        let (actual_x, actual_y) = self.drawing_area.get_pixel_range();
117        self.drawing_area
118            .as_coord_spec_mut()
119            .set_projection(actual_x, actual_y, pf);
120        self
121    }
122    /// Sets the 3d coordinate pixel range.
123    pub fn set_3d_pixel_range(&mut self, size: (i32, i32, i32)) -> &mut Self {
124        let (actual_x, actual_y) = self.drawing_area.get_pixel_range();
125        self.drawing_area
126            .as_coord_spec_mut()
127            .set_coord_pixel_range(actual_x, actual_y, size);
128        self
129    }
130}
plotters/chart/context/cartesian3d/mod.rs

plotters/chart/context/cartesian3d/
mod.rs
