plotkit_core/charts/
scatter.rs

1//! Scatter chart builder methods.
2//!
3//! This module extends [`ScatterArtist`] with a fluent API for configuring
4//! scatter plot properties. Since [`Axes::scatter`] returns
5//! `Result<&mut ScatterArtist>`, these builder methods can be chained
6//! directly on the return value:
7//!
8//! ```ignore
9//! ax.scatter(&x, &y)?
10//!     .color(Color::TAB_ORANGE)
11//!     .marker(Marker::Diamond)
12//!     .size(8.0)
13//!     .label("Observations")
14//!     .alpha(0.7);
15//! ```
16
17use crate::artist::ScatterArtist;
18use crate::primitives::Color;
19use crate::theme::Marker;
20
21impl ScatterArtist {
22    /// Sets the marker color.
23    ///
24    /// Applies the given [`Color`] to every marker rendered by this artist,
25    /// unless per-point colors have been set via [`colors`](Self::colors).
26    ///
27    /// # Arguments
28    ///
29    /// * `color` - The [`Color`] to fill each marker with.
30    ///
31    /// # Examples
32    ///
33    /// ```ignore
34    /// artist.color(Color::TAB_RED);
35    /// ```
36    pub fn color(&mut self, color: Color) -> &mut Self {
37        self.color = color;
38        self
39    }
40
41    /// Sets the marker shape.
42    ///
43    /// The [`Marker`] enum defines the available shapes (circle, square,
44    /// triangle, diamond, plus, cross, star, point). The default is
45    /// [`Marker::Circle`].
46    ///
47    /// # Arguments
48    ///
49    /// * `marker` - The [`Marker`] variant to use for every data point.
50    ///
51    /// # Examples
52    ///
53    /// ```ignore
54    /// artist.marker(Marker::Triangle);
55    /// ```
56    pub fn marker(&mut self, marker: Marker) -> &mut Self {
57        self.marker = marker;
58        self
59    }
60
61    /// Sets the marker size in pixels.
62    ///
63    /// This controls the diameter of each marker glyph. Larger values
64    /// produce more prominent data points; smaller values suit dense
65    /// scatter plots.
66    ///
67    /// # Arguments
68    ///
69    /// * `size` - The marker diameter in device-independent pixels.
70    ///
71    /// # Examples
72    ///
73    /// ```ignore
74    /// artist.size(10.0);
75    /// ```
76    pub fn size(&mut self, size: f64) -> &mut Self {
77        self.size = size;
78        self
79    }
80
81    /// Sets the legend label for this scatter series.
82    ///
83    /// When a label is set, the scatter series will appear in the legend
84    /// if one is displayed on the axes. Pass an empty string or omit this
85    /// call to exclude the series from the legend.
86    ///
87    /// # Arguments
88    ///
89    /// * `label` - A string slice that will be stored as the legend entry.
90    ///
91    /// # Examples
92    ///
93    /// ```ignore
94    /// artist.label("Measurements");
95    /// ```
96    pub fn label(&mut self, label: &str) -> &mut Self {
97        self.label = Some(label.to_string());
98        self
99    }
100
101    /// Sets the opacity (0.0 = fully transparent, 1.0 = fully opaque).
102    ///
103    /// The value is clamped to the `[0.0, 1.0]` range. The default opacity
104    /// is determined by the active theme (typically `0.8`).
105    ///
106    /// # Arguments
107    ///
108    /// * `alpha` - The desired opacity level.
109    ///
110    /// # Examples
111    ///
112    /// ```ignore
113    /// artist.alpha(0.5); // 50% transparent
114    /// ```
115    pub fn alpha(&mut self, alpha: f64) -> &mut Self {
116        self.alpha = alpha.clamp(0.0, 1.0);
117        self
118    }
119
120    /// Sets per-point colors, overriding the single uniform color.
121    ///
122    /// When set, each data point is rendered with its corresponding color
123    /// from the vector. The length of `colors` must equal the number of
124    /// data points (`x.len()` and `y.len()`). This is commonly used to
125    /// map a third variable to a colormap.
126    ///
127    /// Calling [`color`](Self::color) after this method does not clear the
128    /// per-point colors; the per-point colors take precedence during
129    /// rendering.
130    ///
131    /// # Arguments
132    ///
133    /// * `colors` - A vector of [`Color`] values, one per data point.
134    ///
135    /// # Examples
136    ///
137    /// ```ignore
138    /// artist.colors(vec![Color::TAB_BLUE, Color::TAB_RED, Color::TAB_GREEN]);
139    /// ```
140    pub fn colors(&mut self, colors: Vec<Color>) -> &mut Self {
141        self.colors = Some(colors);
142        self
143    }
144}
plotkit_core/charts/scatter.rs

plotkit_core/charts/
scatter.rs
