Skip to content

Commit 8169188

Browse files
jonaspleyerjonaspleyer
committed
increase documentation and correctly format
1 parent 573c751 commit 8169188

File tree

2 files changed

+78
-39
lines changed

2 files changed

+78
-39
lines changed

‎plotters/src/style/colors/colormaps.rs

Lines changed: 73 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,34 @@
1-
use crate::style::{HSLColor,RGBAColor,RGBColor};
1+
use crate::style::{HSLColor, RGBAColor, RGBColor};
22

3-
use num_traits::{Float,ToPrimitive,FromPrimitive};
3+
use num_traits::{Float, FromPrimitive, ToPrimitive};
44

5-
pub trait ColorMap<ColorType: crate::prelude::Color, FloatType=f32>
5+
/// Converts scalar values to colors.
6+
pub trait ColorMap<ColorType: crate::prelude::Color, FloatType = f32>
67
where
78
FloatType: Float,
89
{
10+
/// Takes a scalar value 0.0 <= h <= 1.0 and returns the corresponding color.
11+
/// Typically color-scales are named according to which color-type they return.
12+
/// To use upper and lower bounds with ths function see [get_color_normalized](ColorMap::get_color_normalized).
913
fn get_color(&self, h: FloatType) -> ColorType {
1014
self.get_color_normalized(h, FloatType::zero(), FloatType::one())
1115
}
1216

17+
/// A slight abstraction over [get_color](ColorMap::get_color) function where lower and upper bound can be specified.
1318
fn get_color_normalized(&self, h: FloatType, min: FloatType, max: FloatType) -> ColorType;
1419
}
1520

16-
1721
/// This struct is used to dynamically construct colormaps by giving it a slice of colors.
1822
/// It can then be used when being intantiated, but not with associated functions.
1923
/// ```
2024
/// use plotters::prelude::{BLACK,BLUE,WHITE,DerivedColorMap,ColorMap};
21-
///
25+
///
2226
/// let derived_colormap = DerivedColorMap::new(
2327
/// &[BLACK,
2428
/// BLUE,
2529
/// WHITE]
2630
/// );
27-
///
31+
///
2832
/// assert_eq!(derived_colormap.get_color(0.0), BLACK);
2933
/// assert_eq!(derived_colormap.get_color(0.5), BLUE);
3034
/// assert_eq!(derived_colormap.get_color(1.0), WHITE);
@@ -33,20 +37,22 @@ pub struct DerivedColorMap<ColorType> {
3337
colors: Vec<ColorType>,
3438
}
3539

36-
3740
impl<ColorType: crate::style::Color + Clone> DerivedColorMap<ColorType> {
41+
/// This function lets the user define a new colormap by simply specifying colors in the correct order.
42+
/// For calculation of the color values, the colors will be spaced evenly apart.
3843
pub fn new(colors: &[ColorType]) -> Self {
39-
DerivedColorMap { colors: colors.iter().map(|color| color.clone()).collect::<Vec<_>>() }
44+
DerivedColorMap {
45+
colors: colors.iter().map(|color| color.clone()).collect::<Vec<_>>(),
46+
}
4047
}
4148
}
4249

43-
4450
macro_rules! calculate_new_color_value(
4551
($relative_difference:expr, $colors:expr, $index_upper:expr, $index_lower:expr, RGBColor) => {
4652
RGBColor(
4753
// These equations are a very complicated way of writing a simple linear extrapolation with lots of casting between numerical values
4854
// In principle every cast should be safe which is why we choose to unwrap
49-
// (1.0 - r) * color_value_1 + r * color_value_2
55+
// (1.0 - r) * color_value_1 + r * color_value_2
5056
((FloatType::one() - $relative_difference) * FloatType::from_u8($colors[$index_upper].0).unwrap() + $relative_difference * FloatType::from_u8($colors[$index_lower].0).unwrap()).round().to_u8().unwrap(),
5157
((FloatType::one() - $relative_difference) * FloatType::from_u8($colors[$index_upper].1).unwrap() + $relative_difference * FloatType::from_u8($colors[$index_lower].1).unwrap()).round().to_u8().unwrap(),
5258
((FloatType::one() - $relative_difference) * FloatType::from_u8($colors[$index_upper].2).unwrap() + $relative_difference * FloatType::from_u8($colors[$index_lower].2).unwrap()).round().to_u8().unwrap()
@@ -56,7 +62,7 @@ macro_rules! calculate_new_color_value(
5662
RGBAColor(
5763
// These equations are a very complicated way of writing a simple linear extrapolation with lots of casting between numerical values
5864
// In principle every cast should be safe which is why we choose to unwrap
59-
// (1.0 - r) * color_value_1 + r * color_value_2
65+
// (1.0 - r) * color_value_1 + r * color_value_2
6066
((FloatType::one() - $relative_difference) * FloatType::from_u8($colors[$index_upper].0).unwrap() + $relative_difference * FloatType::from_u8($colors[$index_lower].0).unwrap()).round().to_u8().unwrap(),
6167
((FloatType::one() - $relative_difference) * FloatType::from_u8($colors[$index_upper].1).unwrap() + $relative_difference * FloatType::from_u8($colors[$index_lower].1).unwrap()).round().to_u8().unwrap(),
6268
((FloatType::one() - $relative_difference) * FloatType::from_u8($colors[$index_upper].2).unwrap() + $relative_difference * FloatType::from_u8($colors[$index_lower].2).unwrap()).round().to_u8().unwrap(),
@@ -67,7 +73,7 @@ macro_rules! calculate_new_color_value(
6773
HSLColor(
6874
// These equations are a very complicated way of writing a simple linear extrapolation with lots of casting between numerical values
6975
// In principle every cast should be safe which is why we choose to unwrap
70-
// (1.0 - r) * color_value_1 + r * color_value_2
76+
// (1.0 - r) * color_value_1 + r * color_value_2
7177
((FloatType::one() - $relative_difference) * FloatType::from_f64($colors[$index_upper].0).unwrap() + $relative_difference * FloatType::from_f64($colors[$index_lower].0).unwrap()).to_f64().unwrap(),
7278
((FloatType::one() - $relative_difference) * FloatType::from_f64($colors[$index_upper].1).unwrap() + $relative_difference * FloatType::from_f64($colors[$index_lower].1).unwrap()).to_f64().unwrap(),
7379
((FloatType::one() - $relative_difference) * FloatType::from_f64($colors[$index_upper].2).unwrap() + $relative_difference * FloatType::from_f64($colors[$index_lower].2).unwrap()).to_f64().unwrap(),
@@ -113,22 +119,26 @@ macro_rules! implement_color_scale_for_derived_color_map{
113119
self.colors.len()
114120
);
115121
// Interpolate the final color linearly
116-
calculate_new_color_value!(relative_difference, self.colors, index_upper, index_lower, $color_type)
122+
calculate_new_color_value!(
123+
relative_difference,
124+
self.colors,
125+
index_upper,
126+
index_lower,
127+
$color_type
128+
)
117129
}
118130
}
119131
)+
120132
}
121133
}
122134

123-
implement_color_scale_for_derived_ColorMap!{RGBAColor, RGBColor, HSLColor}
124-
135+
implement_color_scale_for_derived_color_map! {RGBAColor, RGBColor, HSLColor}
125136

126137
macro_rules! count {
127138
() => (0usize);
128139
($x:tt $($xs:tt)* ) => (1usize + count!($($xs)*));
129140
}
130141

131-
132142
macro_rules! define_colors_from_list_of_values_or_directly{
133143
($color_type:ident, $(($($color_value:expr),+)),+) => {
134144
[$($color_type($($color_value),+)),+]
@@ -160,28 +170,49 @@ macro_rules! implement_linear_interpolation_color_map {
160170
Self::COLORS.len()
161171
);
162172
// Interpolate the final color linearly
163-
calculate_new_color_value!(relative_difference, Self::COLORS, index_upper, index_lower, $color_type)
173+
calculate_new_color_value!(
174+
relative_difference,
175+
Self::COLORS,
176+
index_upper,
177+
index_lower,
178+
$color_type
179+
)
164180
}
165181
}
166182

167183
impl $color_scale_name {
168-
pub fn get_color<FloatType: std::fmt::Debug + Float + FromPrimitive + ToPrimitive>(h: FloatType) -> $color_type {
184+
#[doc = "Get color value from `"]
185+
#[doc = stringify!($color_scale_name)]
186+
#[doc = "` by supplying a parameter 0.0 <= h <= 1.0"]
187+
pub fn get_color<FloatType: std::fmt::Debug + Float + FromPrimitive + ToPrimitive>(
188+
h: FloatType,
189+
) -> $color_type {
169190
let color_scale = $color_scale_name {};
170191
color_scale.get_color(h)
171192
}
172193

173-
pub fn get_color_normalized<FloatType: std::fmt::Debug + Float + FromPrimitive + ToPrimitive>(h: FloatType, min: FloatType, max: FloatType) -> $color_type {
194+
#[doc = "Get color value from `"]
195+
#[doc = stringify!($color_scale_name)]
196+
#[doc = "` by supplying lower and upper bounds min, max and a parameter h where min <= h <= max"]
197+
pub fn get_color_normalized<
198+
FloatType: std::fmt::Debug + Float + FromPrimitive + ToPrimitive,
199+
>(
200+
h: FloatType,
201+
min: FloatType,
202+
max: FloatType,
203+
) -> $color_type {
174204
let color_scale = $color_scale_name {};
175205
color_scale.get_color_normalized(h, min, max)
176206
}
177207
}
178-
}
208+
};
179209
}
180210

181-
182211
#[macro_export]
212+
/// Macro to create a new colormap with evenly spaced colors at compile-time.
183213
macro_rules! define_linear_interpolation_color_map{
184-
($color_scale_name:ident, $color_type:ident, $(($($color_value:expr),+)),*) => {
214+
($color_scale_name:ident, $color_type:ident, $doc:expr, $(($($color_value:expr),+)),*) => {
215+
#[doc = $doc]
185216
pub struct $color_scale_name {}
186217

187218
impl $color_scale_name {
@@ -192,7 +223,8 @@ macro_rules! define_linear_interpolation_color_map{
192223

193224
implement_linear_interpolation_color_map!{$color_scale_name, $color_type}
194225
};
195-
($color_scale_name:ident, $color_type:ident, $($color_complete:tt),+) => {
226+
($color_scale_name:ident, $color_type:ident, $doc:expr, $($color_complete:tt),+) => {
227+
#[doc = $doc]
196228
pub struct $color_scale_name {}
197229

198230
impl $color_scale_name {
@@ -203,10 +235,12 @@ macro_rules! define_linear_interpolation_color_map{
203235
}
204236
}
205237

206-
207-
define_linear_interpolation_color_map!{
238+
define_linear_interpolation_color_map! {
208239
ViridisRGBA,
209240
RGBAColor,
241+
"A colormap optimized for visually impaired people (RGBA format).
242+
It is currently the default colormap also used by [matplotlib](https://matplotlib.org/stable/tutorials/colors/colormaps.html).
243+
Read more in this [paper](https://doi.org/10.1371/journal.pone.0199239)",
210244
( 68, 1, 84, 1.0),
211245
( 70, 50, 127, 1.0),
212246
( 54, 92, 141, 1.0),
@@ -217,10 +251,12 @@ define_linear_interpolation_color_map!{
217251
(254, 232, 37, 1.0)
218252
}
219253

220-
221-
define_linear_interpolation_color_map!{
254+
define_linear_interpolation_color_map! {
222255
ViridisRGB,
223256
RGBColor,
257+
"A colormap optimized for visually impaired people (RGB Format).
258+
It is currently the default colormap also used by [matplotlib](https://matplotlib.org/stable/tutorials/colors/colormaps.html).
259+
Read more in this [paper](https://doi.org/10.1371/journal.pone.0199239)",
224260
( 68, 1, 84),
225261
( 70, 50, 127),
226262
( 54, 92, 141),
@@ -231,44 +267,44 @@ define_linear_interpolation_color_map!{
231267
(254, 232, 37)
232268
}
233269

234-
235-
define_linear_interpolation_color_map!{
270+
define_linear_interpolation_color_map! {
236271
BlackWhite,
237272
RGBColor,
273+
"Simple chromatic colormap from black to white.",
238274
( 0, 0, 0),
239275
(255, 255, 255)
240276
}
241277

242-
243-
define_linear_interpolation_color_map!{
278+
define_linear_interpolation_color_map! {
244279
MandelbrotHSL,
245280
HSLColor,
281+
"Colormap created to replace the one used in the mandelbrot example.",
246282
(0.0, 1.0, 0.5),
247283
(1.0, 1.0, 0.5)
248284
}
249285

250-
251-
define_linear_interpolation_color_map!{
286+
define_linear_interpolation_color_map! {
252287
VulcanoHSL,
253288
HSLColor,
289+
"A vulcanic colormap that display red/orange and black colors",
254290
(2.0/3.0, 1.0, 0.7),
255291
( 0.0, 1.0, 0.7)
256292
}
257293

258-
259294
use super::full_palette::*;
260-
define_linear_interpolation_color_map!{
295+
define_linear_interpolation_color_map! {
261296
Bone,
262297
RGBColor,
298+
"Dark colormap going from black over blue to white.",
263299
BLACK,
264300
BLUE,
265301
WHITE
266302
}
267303

268-
269-
define_linear_interpolation_color_map!{
304+
define_linear_interpolation_color_map! {
270305
Copper,
271306
RGBColor,
307+
"Friendly black to brown colormap.",
272308
BLACK,
273309
BROWN,
274310
ORANGE

‎plotters/src/style/colors/mod.rs

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,10 @@ define_color!(CYAN, 0, 255, 255, "Cyan");
5656
define_color!(MAGENTA, 255, 0, 255, "Magenta");
5757
define_color!(TRANSPARENT, 0, 0, 0, 0.0, "Transparent");
5858

59-
#[cfg(feature = "full_palette")]
60-
pub mod full_palette;
6159
#[cfg(feature = "colormaps")]
60+
/// Colormaps can be used to simply go from a scalar value to a color value which will be more/less
61+
/// intense corresponding to the value of the supplied scalar.
62+
/// These colormaps can also be defined by the user and be used with lower and upper bounds.
6263
pub mod colormaps;
64+
#[cfg(feature = "full_palette")]
65+
pub mod full_palette;

0 commit comments

Comments
 (0)