Update docs

Author: 38

src/chart/axes3d.rs

@@ -13,6 +13,7 @@ use crate::drawing::DrawingAreaErrorKind;
 
 use plotters_backend::DrawingBackend;
 
+/// The configurations about the 3D plot's axes
 pub struct Axes3dStyle<'a, 'b, X: Ranged, Y: Ranged, Z: Ranged, DB: DrawingBackend> {
     pub(super) parent_size: (u32, u32),
     pub(super) target: Option<&'b mut ChartContext<'a, DB, Cartesian3d<X, Y, Z>>>,
@@ -36,22 +37,26 @@ where
     Z: Ranged<ValueType = ZT> + ValueFormatter<ZT>,
     DB: DrawingBackend,
 {
+    /// Set the size of the tick mark
     pub fn tick_size<Size: SizeDesc>(&mut self, size: Size) -> &mut Self {
         let actual_size = size.in_pixels(&self.parent_size);
         self.tick_size = actual_size;
         self
     }
 
+    /// Set the number of labels on the X axes
     pub fn x_labels(&mut self, n: usize) -> &mut Self {
         self.n_labels[0] = n;
         self
     }
 
+    /// Set the number of labels on the Y axes
     pub fn y_labels(&mut self, n: usize) -> &mut Self {
         self.n_labels[1] = n;
         self
     }
 
+    /// Set the number of labels on the Z axes
     pub fn z_labels(&mut self, n: usize) -> &mut Self {
         self.n_labels[2] = n;
         self

src/chart/builder.rs

@@ -307,6 +307,12 @@ impl<'a, 'b, DB: DrawingBackend> ChartBuilder<'a, 'b, DB> {
         })
     }
 
+    /// Build a 3 dimensional cartesian chart. The function will returns a chart
+    /// context, where data series can be rendered on.
+    /// - `x_spec`: The specification of X axis
+    /// - `y_spec`: The specification of Y axis
+    /// - `z_sepc`: The specification of Z axis
+    /// - Returns: A chart context
     pub fn build_cartesian_3d<X: AsRangedCoord, Y: AsRangedCoord, Z: AsRangedCoord>(
         &mut self,
         x_spec: X,

src/chart/context.rs

@@ -588,6 +588,12 @@ impl<'a, DB, X: Ranged, Y: Ranged, Z: Ranged> ChartContext<'a, DB, Cartesian3d<X
 where
     DB: DrawingBackend,
 {
+    /// Override the 3D projection matrix. This function allows to override the default projection
+    /// matrix.
+    /// - `pf`: A function that takes the default projection matrix configuration and returns the
+    /// projection matrix. This function will allow you to adjust the pitch, yaw angle and the
+    /// centeral point of the projection, etc. You can also build a projection matrix which is not
+    /// relies on the default configuration as well.
     pub fn with_projection<P: FnOnce(ProjectionMatrixBuilder) -> ProjectionMatrix>(
         &mut self,
         pf: P,
@@ -921,7 +927,6 @@ mod test {
             .expect("Drawing error");
     }
 
-
     #[test]
     fn test_chart_context_3d() {
         let drawing_area = create_mocked_drawing_area(200, 200, |_| {});
@@ -936,7 +941,7 @@ mod test {
             .set_label_area_size(LabelAreaPosition::Right, 20)
             .build_cartesian_3d(0..10, 0..10, 0..10)
             .expect("Create chart");
-        
+
         chart.with_projection(|mut pb| {
             pb.yaw = 0.5;
             pb.pitch = 0.5;
@@ -946,7 +951,6 @@ mod test {
 
         chart.configure_axes().draw().expect("Drawing axes");
 
-
         chart
             .draw_series(std::iter::once(Circle::new((5, 5, 5), 5, &RED)))
             .expect("Drawing error");

src/coord/ranged3d/cartesian3d.rs

@@ -5,6 +5,7 @@ use plotters_backend::BackendCoord;
 
 use std::ops::Range;
 
+/// A 3D cartesian coordinate system
 pub struct Cartesian3d<X: Ranged, Y: Ranged, Z: Ranged> {
     pub(crate) logic_x: X,
     pub(crate) logic_y: Y,
@@ -53,6 +54,7 @@ impl<X: Ranged, Y: Ranged, Z: Ranged> Cartesian3d<X, Y, Z> {
             projection: Self::create_projection(actual_x, actual_y, build_projection_matrix),
         }
     }
+    /// Set the projection matrix
     pub fn set_projection<F: FnOnce(ProjectionMatrixBuilder) -> ProjectionMatrix>(
         &mut self,
         actual_x: Range<i32>,
@@ -63,6 +65,7 @@ impl<X: Ranged, Y: Ranged, Z: Ranged> Cartesian3d<X, Y, Z> {
         self
     }
 
+    /// Create a new coordinate
     pub fn new<SX: Into<X>, SY: Into<Y>, SZ: Into<Z>>(
         logic_x: SX,
         logic_y: SY,
@@ -73,10 +76,12 @@ impl<X: Ranged, Y: Ranged, Z: Ranged> Cartesian3d<X, Y, Z> {
             pb.into_matrix()
         })
     }
+    /// Get the projection matrix
     pub fn projection(&self) -> &ProjectionMatrix {
         &self.projection
     }
 
+    /// Do not project, only transform the guest coordinate system
     pub fn map_3d(&self, x: &X::ValueType, y: &Y::ValueType, z: &Z::ValueType) -> (i32, i32, i32) {
         (
             self.logic_x.map(x, (0, self.coord_size.0)),
@@ -85,6 +90,7 @@ impl<X: Ranged, Y: Ranged, Z: Ranged> Cartesian3d<X, Y, Z> {
         )
     }
 
+    /// Get the depth of the projection
     pub fn projected_depth(&self, x: &X::ValueType, y: &Y::ValueType, z: &Z::ValueType) -> i32 {
         self.projection.projected_depth(self.map_3d(x, y, z))
     }

src/coord/ranged3d/projection.rs

@@ -1,6 +1,7 @@
 use std::f64::consts::PI;
 use std::ops::Mul;
 
+/// The projection matrix which is used to project the 3D space to the 2D display panel
 #[derive(Clone, Debug, Copy)]
 pub struct ProjectionMatrix([[f64; 4]; 4]);
 
@@ -68,6 +69,7 @@ impl Mul<(f64, f64, f64)> for ProjectionMatrix {
 }
 
 impl ProjectionMatrix {
+    /// Returns the identity matrix
     pub fn one() -> Self {
         ProjectionMatrix([
             [1.0, 0.0, 0.0, 0.0],
@@ -76,9 +78,11 @@ impl ProjectionMatrix {
             [0.0, 0.0, 0.0, 1.0],
         ])
     }
+    /// Returns the zero maxtrix
     pub fn zero() -> Self {
         ProjectionMatrix([[0.0; 4]; 4])
     }
+    /// Returns the matrix which shift the coordinate
     pub fn shift(x: f64, y: f64, z: f64) -> Self {
         ProjectionMatrix([
             [1.0, 0.0, 0.0, x],
@@ -87,6 +91,7 @@ impl ProjectionMatrix {
             [0.0, 0.0, 0.0, 1.0],
         ])
     }
+    /// Returns the matrix which rotates the coordinate
     pub fn rotate(x: f64, y: f64, z: f64) -> Self {
         let (c, b, a) = (x, y, z);
         ProjectionMatrix([
@@ -106,6 +111,7 @@ impl ProjectionMatrix {
             [0.0, 0.0, 0.0, 1.0],
         ])
     }
+    /// Returns the matrix that applies a scale factor
     pub fn scale(factor: f64) -> Self {
         ProjectionMatrix([
             [1.0, 0.0, 0.0, 0.0],
@@ -114,6 +120,7 @@ impl ProjectionMatrix {
             [0.0, 0.0, 0.0, 1.0 / factor],
         ])
     }
+    /// Normalize the matrix, this will make the metric unit to 1
     pub fn normalize(&mut self) {
         if self.0[3][3] > 1e-20 {
             for r in 0..4 {
@@ -124,12 +131,14 @@ impl ProjectionMatrix {
         }
     }
 
+    /// Get the distance of the point in guest coordinate from the screen in pixels
     pub fn projected_depth(&self, (x, y, z): (i32, i32, i32)) -> i32 {
         let r = &self.0[2];
         (r[0] * x as f64 + r[1] * y as f64 + r[2] * z as f64 + r[3]) as i32
     }
 }
 
+/// The helper struct to build a projection matrix
 #[derive(Copy, Clone)]
 pub struct ProjectionMatrixBuilder {
     pub yaw: f64,
@@ -150,12 +159,15 @@ impl ProjectionMatrixBuilder {
         }
     }
 
+    /// Set the pivot point, which means the 3D coordinate "before" should be mapped into
+    /// the 2D coordinatet "after"
     pub fn set_pivot(&mut self, before: (i32, i32, i32), after: (i32, i32)) -> &mut Self {
         self.pivot_before = before;
         self.pivot_after = after;
         self
     }
 
+    /// Build the matrix based on the configuration
     pub fn into_matrix(self) -> ProjectionMatrix {
         let mut ret = if self.pivot_before == (0, 0, 0) {
             ProjectionMatrix::default()

src/series/surface.rs

@@ -1,5 +1,11 @@
 use crate::element::Polygon;
 use crate::style::ShapeStyle;
+/// The surface series.
+///
+/// Currently the surface is representing any surface in form
+/// y = f(x,z)
+///
+/// TODO: make this more general
 pub struct SurfaceSeries<X, Y, Z> {
     x_data: Vec<X>,
     y_data: Vec<Y>,