xref: /external/rust/crates/plotters/src/chart/builder.rs

use super::context::ChartContext;

use crate::coord::cartesian::{Cartesian2d, Cartesian3d};
use crate::coord::ranged1d::AsRangedCoord;
use crate::coord::Shift;

use crate::drawing::{DrawingArea, DrawingAreaErrorKind};
use crate::style::{IntoTextStyle, SizeDesc, TextStyle};

use plotters_backend::DrawingBackend;

/**
Specifies one of the four label positions around the figure.

This is used to configure the label area size with function
[`ChartBuilder::set_label_area_size()`].

# Example

```
use plotters::prelude::*;
let drawing_area = SVGBackend::new("label_area_position.svg", (300, 200)).into_drawing_area();
drawing_area.fill(&WHITE).unwrap();
let mut chart_builder = ChartBuilder::on(&drawing_area);
chart_builder.set_label_area_size(LabelAreaPosition::Bottom, 60).set_label_area_size(LabelAreaPosition::Left, 35);
let mut chart_context = chart_builder.build_cartesian_2d(0.0..4.0, 0.0..3.0).unwrap();
chart_context.configure_mesh().x_desc("Spacious X label area").y_desc("Narrow Y label area").draw().unwrap();
```

The result is a chart with a spacious X label area and a narrow Y label area:

![](https://cdn.jsdelivr.net/gh/facorread/plotters-doc-data@9ca6541/apidoc/label_area_position.svg)

# See also

[`ChartBuilder::set_left_and_bottom_label_area_size()`]
*/
#[derive(Copy, Clone)]
pub enum LabelAreaPosition {
    /// Top of the figure
    Top = 0,
    /// Bottom of the figure
    Bottom = 1,
    /// Left side of the figure
    Left = 2,
    /// Right side of the figure
    Right = 3,
}

/**
The helper object to create a chart context, which is used for the high-level figure drawing.

With the help of this object, we can convert a basic drawing area into a chart context, which
allows the high-level charting API being used on the drawing area.

See [`ChartBuilder::on()`] for more information and examples.
*/
pub struct ChartBuilder<'a, 'b, DB: DrawingBackend> {
    label_area_size: [u32; 4], // [upper, lower, left, right]
    overlap_plotting_area: [bool; 4],
    root_area: &'a DrawingArea<DB, Shift>,
    title: Option<(String, TextStyle<'b>)>,
    margin: [u32; 4],
}

impl<'a, 'b, DB: DrawingBackend> ChartBuilder<'a, 'b, DB> {
    /**
    Create a chart builder on the given drawing area

    - `root`: The root drawing area
    - Returns: The chart builder object

    # Example

    ```
    use plotters::prelude::*;
    let drawing_area = SVGBackend::new("chart_builder_on.svg", (300, 200)).into_drawing_area();
    drawing_area.fill(&WHITE).unwrap();
    let mut chart_builder = ChartBuilder::on(&drawing_area);
    chart_builder.margin(5).set_left_and_bottom_label_area_size(35)
    .caption("Figure title or caption", ("Calibri", 20, FontStyle::Italic, &RED).into_text_style(&drawing_area));
    let mut chart_context = chart_builder.build_cartesian_2d(0.0..3.8, 0.0..2.8).unwrap();
    chart_context.configure_mesh().draw().unwrap();
    ```
    The result is a chart with customized margins, label area sizes, and title:

    ![](https://cdn.jsdelivr.net/gh/facorread/plotters-doc-data@42ecf52/apidoc/chart_builder_on.svg)

    */
    pub fn on(root: &'a DrawingArea<DB, Shift>) -> Self {
        Self {
            label_area_size: [0; 4],
            root_area: root,
            title: None,
            margin: [0; 4],
            overlap_plotting_area: [false; 4],
        }
    }

    /**
    Sets the size of the four margins of the chart.

    - `size`: The desired size of the four chart margins in backend units (pixels).

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn margin<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size.in_pixels(self.root_area).max(0) as u32;
        self.margin = [size, size, size, size];
        self
    }

    /**
    Sets the size of the top margin of the chart.

    - `size`: The desired size of the margin in backend units (pixels).

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn margin_top<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size.in_pixels(self.root_area).max(0) as u32;
        self.margin[0] = size;
        self
    }

    /**
    Sets the size of the bottom margin of the chart.

    - `size`: The desired size of the margin in backend units (pixels).

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn margin_bottom<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size.in_pixels(self.root_area).max(0) as u32;
        self.margin[1] = size;
        self
    }

    /**
    Sets the size of the left margin of the chart.

    - `size`: The desired size of the margin in backend units (pixels).

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn margin_left<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size.in_pixels(self.root_area).max(0) as u32;
        self.margin[2] = size;
        self
    }

    /**
    Sets the size of the right margin of the chart.

    - `size`: The desired size of the margin in backend units (pixels).

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn margin_right<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size.in_pixels(self.root_area).max(0) as u32;
        self.margin[3] = size;
        self
    }

    /**
    Sets the size of the four label areas of the chart.

    - `size`: The desired size of the four label areas in backend units (pixels).

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn set_all_label_area_size<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size.in_pixels(self.root_area);
        self.set_label_area_size(LabelAreaPosition::Top, size)
            .set_label_area_size(LabelAreaPosition::Bottom, size)
            .set_label_area_size(LabelAreaPosition::Left, size)
            .set_label_area_size(LabelAreaPosition::Right, size)
    }

    /**
    Sets the size of the left and bottom label areas of the chart.

    - `size`: The desired size of the left and bottom label areas in backend units (pixels).

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn set_left_and_bottom_label_area_size<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size.in_pixels(self.root_area);
        self.set_label_area_size(LabelAreaPosition::Left, size)
            .set_label_area_size(LabelAreaPosition::Bottom, size)
    }

    /**
    Sets the size of the X label area at the bottom of the chart.

    - `size`: The desired size of the X label area in backend units (pixels).
    If set to 0, the X label area is removed.

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn x_label_area_size<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        self.set_label_area_size(LabelAreaPosition::Bottom, size)
    }

    /**
    Sets the size of the Y label area to the left of the chart.

    - `size`: The desired size of the Y label area in backend units (pixels).
    If set to 0, the Y label area is removed.

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn y_label_area_size<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        self.set_label_area_size(LabelAreaPosition::Left, size)
    }

    /**
    Sets the size of the X label area at the top of the chart.

    - `size`: The desired size of the top X label area in backend units (pixels).
    If set to 0, the top X label area is removed.

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn top_x_label_area_size<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        self.set_label_area_size(LabelAreaPosition::Top, size)
    }

    /**
    Sets the size of the Y label area to the right of the chart.

    - `size`: The desired size of the Y label area in backend units (pixels).
    If set to 0, the Y label area to the right is removed.

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn right_y_label_area_size<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        self.set_label_area_size(LabelAreaPosition::Right, size)
    }

    /**
    Sets the size of a chart label area.

    - `pos`: The position of the desired label area to adjust
    - `size`: The desired size of the label area in backend units (pixels).
    If set to 0, the label area is removed.

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn set_label_area_size<S: SizeDesc>(
        &mut self,
        pos: LabelAreaPosition,
        size: S,
    ) -> &mut Self {
        let size = size.in_pixels(self.root_area);
        self.label_area_size[pos as usize] = size.unsigned_abs();
        self.overlap_plotting_area[pos as usize] = size < 0;
        self
    }

    /**
    Sets the title or caption of the chart.

    - `caption`: The caption of the chart
    - `style`: The text style

    The title or caption will be centered at the top of the drawing area.

    See [`ChartBuilder::on()`] for more information and examples.
    */
    pub fn caption<S: AsRef<str>, Style: IntoTextStyle<'b>>(
        &mut self,
        caption: S,
        style: Style,
    ) -> &mut Self {
        self.title = Some((
            caption.as_ref().to_string(),
            style.into_text_style(self.root_area),
        ));
        self
    }

    /// This function has been renamed to [`ChartBuilder::build_cartesian_2d()`] and is to be removed in the future.
    #[allow(clippy::type_complexity)]
    #[deprecated(
        note = "`build_ranged` has been renamed to `build_cartesian_2d` and is to be removed in the future."
    )]
    pub fn build_ranged<X: AsRangedCoord, Y: AsRangedCoord>(
        &mut self,
        x_spec: X,
        y_spec: Y,
    ) -> Result<
        ChartContext<'a, DB, Cartesian2d<X::CoordDescType, Y::CoordDescType>>,
        DrawingAreaErrorKind<DB::ErrorType>,
    > {
        self.build_cartesian_2d(x_spec, y_spec)
    }

    /**
    Builds a chart with a 2D Cartesian coordinate system.

    - `x_spec`: Specifies the X axis range and data properties
    - `y_spec`: Specifies the Y axis range and data properties
    - Returns: A `ChartContext` object, ready to visualize data.

    See [`ChartBuilder::on()`] and [`ChartContext::configure_mesh()`] for more information and examples.
    */
    #[allow(clippy::type_complexity)]
    pub fn build_cartesian_2d<X: AsRangedCoord, Y: AsRangedCoord>(
        &mut self,
        x_spec: X,
        y_spec: Y,
    ) -> Result<
        ChartContext<'a, DB, Cartesian2d<X::CoordDescType, Y::CoordDescType>>,
        DrawingAreaErrorKind<DB::ErrorType>,
    > {
        let mut label_areas = [None, None, None, None];

        let mut drawing_area = DrawingArea::clone(self.root_area);

        if *self.margin.iter().max().unwrap_or(&0) > 0 {
            drawing_area = drawing_area.margin(
                self.margin[0] as i32,
                self.margin[1] as i32,
                self.margin[2] as i32,
                self.margin[3] as i32,
            );
        }

        let (title_dx, title_dy) = if let Some((ref title, ref style)) = self.title {
            let (origin_dx, origin_dy) = drawing_area.get_base_pixel();
            drawing_area = drawing_area.titled(title, style.clone())?;
            let (current_dx, current_dy) = drawing_area.get_base_pixel();
            (current_dx - origin_dx, current_dy - origin_dy)
        } else {
            (0, 0)
        };

        let (w, h) = drawing_area.dim_in_pixel();

        let mut actual_drawing_area_pos = [0, h as i32, 0, w as i32];

        const DIR: [(i16, i16); 4] = [(0, -1), (0, 1), (-1, 0), (1, 0)];

        for (idx, (dx, dy)) in (0..4).map(|idx| (idx, DIR[idx])) {
            if self.overlap_plotting_area[idx] {
                continue;
            }

            let size = self.label_area_size[idx] as i32;

            let split_point = if dx + dy < 0 { size } else { -size };

            actual_drawing_area_pos[idx] += split_point;
        }

        // Now the root drawing area is to be split into
        //
        // +----------+------------------------------+------+
        // |    0     |    1 (Top Label Area)        |   2  |
        // +----------+------------------------------+------+
        // |    3     |                              |   5  |
        // |  Left    |       4 (Plotting Area)      | Right|
        // |  Labels  |                              | Label|
        // +----------+------------------------------+------+
        // |    6     |        7 (Bottom Labels)     |   8  |
        // +----------+------------------------------+------+

        let mut split: Vec<_> = drawing_area
            .split_by_breakpoints(
                &actual_drawing_area_pos[2..4],
                &actual_drawing_area_pos[0..2],
            )
            .into_iter()
            .map(Some)
            .collect();

        // Take out the plotting area
        std::mem::swap(&mut drawing_area, split[4].as_mut().unwrap());

        // Initialize the label areas - since the label area might be overlapping
        // with the plotting area, in this case, we need handle them differently
        for (src_idx, dst_idx) in [1, 7, 3, 5].iter().zip(0..4) {
            if !self.overlap_plotting_area[dst_idx] {
                let (h, w) = split[*src_idx].as_ref().unwrap().dim_in_pixel();
                if h > 0 && w > 0 {
                    std::mem::swap(&mut label_areas[dst_idx], &mut split[*src_idx]);
                }
            } else if self.label_area_size[dst_idx] != 0 {
                let size = self.label_area_size[dst_idx] as i32;
                let (dw, dh) = drawing_area.dim_in_pixel();
                let x0 = if DIR[dst_idx].0 > 0 {
                    dw as i32 - size
                } else {
                    0
                };
                let y0 = if DIR[dst_idx].1 > 0 {
                    dh as i32 - size
                } else {
                    0
                };
                let x1 = if DIR[dst_idx].0 >= 0 { dw as i32 } else { size };
                let y1 = if DIR[dst_idx].1 >= 0 { dh as i32 } else { size };

                label_areas[dst_idx] = Some(
                    drawing_area
                        .clone()
                        .shrink((x0, y0), ((x1 - x0), (y1 - y0))),
                );
            }
        }

        let mut pixel_range = drawing_area.get_pixel_range();
        pixel_range.0.end -= 1;
        pixel_range.1.end -= 1;
        pixel_range.1 = pixel_range.1.end..pixel_range.1.start;

        let mut x_label_area = [None, None];
        let mut y_label_area = [None, None];

        std::mem::swap(&mut x_label_area[0], &mut label_areas[0]);
        std::mem::swap(&mut x_label_area[1], &mut label_areas[1]);
        std::mem::swap(&mut y_label_area[0], &mut label_areas[2]);
        std::mem::swap(&mut y_label_area[1], &mut label_areas[3]);

        Ok(ChartContext {
            x_label_area,
            y_label_area,
            drawing_area: drawing_area.apply_coord_spec(Cartesian2d::new(
                x_spec,
                y_spec,
                pixel_range,
            )),
            series_anno: vec![],
            drawing_area_pos: (
                actual_drawing_area_pos[2] + title_dx + self.margin[2] as i32,
                actual_drawing_area_pos[0] + title_dy + self.margin[0] as i32,
            ),
        })
    }

    /**
    Builds a chart with a 3D Cartesian coordinate system.

    - `x_spec`: Specifies the X axis range and data properties
    - `y_spec`: Specifies the Y axis range and data properties
    - `z_sepc`: Specifies the Z axis range and data properties
    - Returns: A `ChartContext` object, ready to visualize data.

    See [`ChartBuilder::on()`] and [`ChartContext::configure_axes()`] for more information and examples.
    */
    #[allow(clippy::type_complexity)]
    pub fn build_cartesian_3d<X: AsRangedCoord, Y: AsRangedCoord, Z: AsRangedCoord>(
        &mut self,
        x_spec: X,
        y_spec: Y,
        z_spec: Z,
    ) -> Result<
        ChartContext<'a, DB, Cartesian3d<X::CoordDescType, Y::CoordDescType, Z::CoordDescType>>,
        DrawingAreaErrorKind<DB::ErrorType>,
    > {
        let mut drawing_area = DrawingArea::clone(self.root_area);

        if *self.margin.iter().max().unwrap_or(&0) > 0 {
            drawing_area = drawing_area.margin(
                self.margin[0] as i32,
                self.margin[1] as i32,
                self.margin[2] as i32,
                self.margin[3] as i32,
            );
        }

        let (title_dx, title_dy) = if let Some((ref title, ref style)) = self.title {
            let (origin_dx, origin_dy) = drawing_area.get_base_pixel();
            drawing_area = drawing_area.titled(title, style.clone())?;
            let (current_dx, current_dy) = drawing_area.get_base_pixel();
            (current_dx - origin_dx, current_dy - origin_dy)
        } else {
            (0, 0)
        };

        let pixel_range = drawing_area.get_pixel_range();

        Ok(ChartContext {
            x_label_area: [None, None],
            y_label_area: [None, None],
            drawing_area: drawing_area.apply_coord_spec(Cartesian3d::new(
                x_spec,
                y_spec,
                z_spec,
                pixel_range,
            )),
            series_anno: vec![],
            drawing_area_pos: (
                title_dx + self.margin[2] as i32,
                title_dy + self.margin[0] as i32,
            ),
        })
    }
}

#[cfg(test)]
mod test {
    use super::*;
    use crate::prelude::*;
    #[test]
    fn test_label_area_size() {
        let drawing_area = create_mocked_drawing_area(200, 200, |_| {});
        let mut chart = ChartBuilder::on(&drawing_area);

        chart
            .x_label_area_size(10)
            .y_label_area_size(20)
            .top_x_label_area_size(30)
            .right_y_label_area_size(40);
        assert_eq!(chart.label_area_size[1], 10);
        assert_eq!(chart.label_area_size[2], 20);
        assert_eq!(chart.label_area_size[0], 30);
        assert_eq!(chart.label_area_size[3], 40);

        chart.set_label_area_size(LabelAreaPosition::Left, 100);
        chart.set_label_area_size(LabelAreaPosition::Right, 200);
        chart.set_label_area_size(LabelAreaPosition::Top, 300);
        chart.set_label_area_size(LabelAreaPosition::Bottom, 400);

        assert_eq!(chart.label_area_size[0], 300);
        assert_eq!(chart.label_area_size[1], 400);
        assert_eq!(chart.label_area_size[2], 100);
        assert_eq!(chart.label_area_size[3], 200);
    }

    #[test]
    fn test_margin_configure() {
        let drawing_area = create_mocked_drawing_area(200, 200, |_| {});
        let mut chart = ChartBuilder::on(&drawing_area);

        chart.margin(5);
        assert_eq!(chart.margin[0], 5);
        assert_eq!(chart.margin[1], 5);
        assert_eq!(chart.margin[2], 5);
        assert_eq!(chart.margin[3], 5);

        chart.margin_top(10);
        chart.margin_bottom(11);
        chart.margin_left(12);
        chart.margin_right(13);
        assert_eq!(chart.margin[0], 10);
        assert_eq!(chart.margin[1], 11);
        assert_eq!(chart.margin[2], 12);
        assert_eq!(chart.margin[3], 13);
    }

    #[test]
    fn test_caption() {
        let drawing_area = create_mocked_drawing_area(200, 200, |_| {});
        let mut chart = ChartBuilder::on(&drawing_area);

        chart.caption("This is a test case", ("serif", 10));

        assert_eq!(chart.title.as_ref().unwrap().0, "This is a test case");
        assert_eq!(chart.title.as_ref().unwrap().1.font.get_name(), "serif");
        assert_eq!(chart.title.as_ref().unwrap().1.font.get_size(), 10.0);
        check_color(chart.title.as_ref().unwrap().1.color, BLACK.to_rgba());

        chart.caption("This is a test case", ("serif", 10));
        assert_eq!(chart.title.as_ref().unwrap().1.font.get_name(), "serif");
    }
}