sampling 0.3.1

use std::{borrow::*, convert::From, fmt, io::Write, path::Path};

#[cfg(feature = "serde_support")]
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
/// For labeling the gnuplot plots axis
pub enum Labels {
    /// construct the labels
    FromValues {
        /// minimum value for axis labels
        min: f64,
        /// maximum value for axis labels
        max: f64,
        ///number of tics, should be at least 2
        tics: usize,
    },
    /// use labels
    FromStrings {
        /// this are the labels
        labels: Vec<String>,
    },
}
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
/// For labeling the gnuplot plots axis
pub struct GnuplotAxis {
    labels: Labels,
    rotation: f32,
}

impl GnuplotAxis {
    /// Set the rotation value.
    /// Tics will be displayed rotated to the right by the requested amount
    pub fn set_rotation(&mut self, rotation_degrees: f32) {
        self.rotation = rotation_degrees;
    }

    pub(crate) fn write_tics<W: Write>(
        &self,
        mut w: W,
        num_bins: usize,
        axis: &str,
    ) -> std::io::Result<()> {
        match &self.labels {
            Labels::FromValues { min, max, tics } => {
                if min.is_nan() || max.is_nan() || *tics < 2 || num_bins < 2 {
                    Ok(())
                } else {
                    let t_m1 = tics - 1;
                    let difference = (max - min) / t_m1 as f64;

                    let bin_dif = (num_bins - 1) as f64 / t_m1 as f64;
                    write!(w, "set {}tics ( ", axis)?;
                    for i in 0..t_m1 {
                        let val = min + i as f64 * difference;
                        let pos = i as f64 * bin_dif;
                        write!(w, "\"{:#}\" {:e}, ", val, pos)?;
                    }
                    writeln!(
                        w,
                        "\"{:#}\" {:e} ) rotate by {} right",
                        max,
                        num_bins - 1,
                        self.rotation
                    )
                }
            }
            Labels::FromStrings { labels } => {
                let tics = labels.len();
                match tics {
                    0 => Ok(()),
                    1 => {
                        writeln!(w, "set {}tics ( \"{}\" 0 )", axis, labels[0])
                    }
                    _ => {
                        write!(w, "set {}tics ( ", axis)?;
                        let t_m1 = tics - 1;
                        let bin_dif = (num_bins - 1) as f64 / t_m1 as f64;
                        for (i, lab) in labels.iter().enumerate() {
                            let pos = i as f64 * bin_dif;
                            write!(w, "\"{}\" {:e}, ", lab, pos)?;
                        }
                        writeln!(w, " ) rotate by {} right", self.rotation)
                    }
                }
            }
        }
    }

    /// Create new GnuplotAxis::FromValues
    pub fn new(min: f64, max: f64, tics: usize) -> Self {
        let labels = Labels::FromValues { min, max, tics };
        Self {
            labels,
            rotation: 0.0,
        }
    }

    /// Create new GnuplotAxis::Labels
    /// - Vector contains labels used for axis
    pub fn from_labels(labels: Vec<String>) -> Self {
        let labels = Labels::FromStrings { labels };
        Self {
            labels,
            rotation: 0.0,
        }
    }

    /// Similar to `from_labels`
    /// * Slice of slice is converted to Vector of Strings and `Self::from_labels(vec)` is called
    pub fn from_slice(labels: &[&str]) -> Self {
        let vec = labels.iter().map(|&s| s.into()).collect();

        Self::from_labels(vec)
    }
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
/// # Settings for gnuplot
/// * implements default
/// * implements builder pattern for itself
/// # **Safety**
///
/// **These gnuplot options are not meant for production!**
/// If you allow arbitrary user input for this, the resulting gnuplot scripts can contain
/// **arbitrary system calls!**
///
/// Thus calling the resulting gnuplot scripts is not safe, if you have not sanitized the inputs!
///
/// This is not an issue if you only create scripts for yourself, i.e., if you are your own user.
pub struct GnuplotSettings {
    /// x label for gnuplot
    pub x_label: String,
    /// how to format the labels of the x axis?
    pub x_axis: Option<GnuplotAxis>,
    /// y label for gnuplot
    pub y_label: String,
    /// how to format the labels of the y axis?
    pub y_axis: Option<GnuplotAxis>,
    /// title for gnuplot
    pub title: String,
    /// which terminal to use for gnuplot
    pub terminal: GnuplotTerminal,

    /// Color palette for heatmap
    pub palette: GnuplotPalette,

    /// Define the cb range if this option is set
    pub cb_range: Option<(f64, f64)>,

    /// # Size of the terminal
    /// * Anything gnuplot accepts (e.g. "2cm, 2.9cm") is acceptable
    /// # Note
    /// the code does not check, if your input for `size` makes any sense
    pub size: String,
}

impl GnuplotSettings {
    /// # Builder pattern - set size of terminal
    /// * Anything gnuplot accepts (e.g. "2cm, 2.9cm") is acceptable
    /// # Note
    /// the code does not check, if your input for `size` makes any sense
    pub fn size<S: Into<String>>(&'_ mut self, size: S) -> &'_ mut Self {
        self.size = size.into();
        self
    }

    /// # Builder pattern - set cb_range
    pub fn cb_range(&'_ mut self, range_start: f64, range_end: f64) -> &'_ mut Self {
        self.cb_range = Some((range_start, range_end));
        self
    }

    /// # Builder pattern - remove cb_range
    pub fn remove_cb_range(&'_ mut self) -> &'_ mut Self {
        self.cb_range = None;
        self
    }

    /// # Builder pattern - set x_label
    pub fn x_label<S: Into<String>>(&'_ mut self, x_label: S) -> &'_ mut Self {
        self.x_label = x_label.into();
        self
    }

    pub(crate) fn write_label<W: Write>(&self, mut writer: W) -> std::io::Result<()> {
        if !self.x_label.is_empty() {
            writeln!(writer, "set xlabel \"{}\"", self.x_label)?;
        }
        if !self.y_label.is_empty() {
            writeln!(writer, "set ylabel \"{}\"", self.y_label)
        } else {
            Ok(())
        }
    }

    /// # Builder pattern - set y_label
    pub fn y_label<S: Into<String>>(&'_ mut self, y_label: S) -> &'_ mut Self {
        self.y_label = y_label.into();
        self
    }

    /// # Builder pattern - set title
    pub fn title<S: Into<String>>(&'_ mut self, title: S) -> &'_ mut Self {
        self.title = title.into();
        self
    }

    /// # currently set title
    pub fn get_title(&self) -> &str {
        &self.title
    }

    /// # Builder pattern - set terminal
    pub fn terminal(&'_ mut self, terminal: GnuplotTerminal) -> &'_ mut Self {
        self.terminal = terminal;
        self
    }

    pub(crate) fn write_terminal<W: Write>(&self, writer: W) -> std::io::Result<()> {
        self.terminal.write_terminal(writer, &self.size)
    }

    /// # Builder pattern - set color palette
    pub fn palette(&'_ mut self, palette: GnuplotPalette) -> &'_ mut Self {
        self.palette = palette;
        self
    }

    /// Create new, default, GnuplotSettings
    pub fn new() -> Self {
        Self::default()
    }

    /// Set x_axis - See GnuplotAxis or try it out
    pub fn x_axis(&'_ mut self, axis: GnuplotAxis) -> &'_ mut Self {
        self.x_axis = Some(axis);
        self
    }

    /// Remove x_axis
    pub fn remove_x_axis(&'_ mut self) -> &'_ mut Self {
        self.x_axis = None;
        self
    }

    /// Set y_axis - See GnuplotAxis or try it out
    pub fn y_axis(&'_ mut self, axis: GnuplotAxis) -> &'_ mut Self {
        self.y_axis = Some(axis);
        self
    }

    /// Remove y_axis
    pub fn remove_y_axis(&'_ mut self) -> &'_ mut Self {
        self.y_axis = None;
        self
    }

    pub(crate) fn write_axis<W: Write>(
        &self,
        mut w: W,
        num_bins_x: usize,
        num_bins_y: usize,
    ) -> std::io::Result<()> {
        if let Some(ax) = self.x_axis.as_ref() {
            ax.write_tics(&mut w, num_bins_x, "x")?;
        }
        if let Some(ax) = self.y_axis.as_ref() {
            ax.write_tics(w, num_bins_y, "y")?;
        }
        Ok(())
    }

    pub(crate) fn write_heatmap_helper1<W>(
        &self,
        mut writer: W,
        x_len: usize,
        y_len: usize,
    ) -> std::io::Result<()>
    where
        W: Write,
    {
        self.write_terminal(&mut writer)?;

        self.write_label(&mut writer)?;

        writeln!(writer, "set xrange[-0.5:{}]", x_len as f64 - 0.5)?;
        writeln!(writer, "set yrange[-0.5:{}]", y_len as f64 - 0.5)?;
        if let Some((range_start, range_end)) = self.cb_range {
            writeln!(writer, "set cbrange [{range_start:e}:{range_end:e}]")?;
        }
        if !self.title.is_empty() {
            writeln!(writer, "set title '{}'", self.title)?;
        }

        self.write_axis(&mut writer, x_len, y_len)?;

        self.palette.write_palette(&mut writer)?;
        writeln!(writer, "set view map")?;

        writeln!(
            writer,
            "set rmargin screen 0.8125\nset lmargin screen 0.175"
        )
    }

    /// # Write a heatmap with the given gnuplot Settings
    /// * `closure` has to write the heatmap. It must write `y_len` rows with `x_len` values each, where the latter values are separated by a space.
    ///   This data will be used for the heatmap.
    /// * `x_len`: The number of entries in each column, that you promise the `closure` will write
    /// * `y_len`: The number of columns you promise that the `closure` will write
    /// # **Safety**
    ///
    /// **These gnuplot options are not meant for production!**
    /// If you allow arbitrary user input for the gnuplot settings, the resulting gnuplot scripts can contain
    /// **arbitrary system calls!**
    ///
    /// Thus calling the resulting gnuplot scripts is not safe, if you have not sanitized the inputs!
    ///
    /// This is not an issue if you only create scripts for yourself, i.e., if you are your own user.
    pub fn write_heatmap<F, W>(
        &self,
        mut writer: W,
        closure: F,
        x_len: usize,
        y_len: usize,
    ) -> std::io::Result<()>
    where
        W: Write,
        F: FnOnce(&mut W) -> std::io::Result<()>,
    {
        self.write_heatmap_helper1(&mut writer, x_len, y_len)?;
        writeln!(writer, "$data << EOD")?;
        closure(&mut writer)?;

        writeln!(writer, "EOD")?;

        writeln!(
            writer,
            "splot $data matrix with image t \"{}\" ",
            &self.title
        )?;

        self.terminal.finish(&mut writer)
    }

    /// Same as write_heatmap but it assumes that the heatmap
    /// matrix is available in the file "heatmap"
    /// # **Safety**
    ///
    /// **These gnuplot options are not meant for production!**
    /// If you allow arbitrary user input for the gnuplot settings, the resulting gnuplot scripts can contain
    /// **arbitrary system calls!**
    ///
    /// Thus calling the resulting gnuplot scripts is not safe, if you have not sanitized the inputs!
    ///
    /// This is not an issue if you only create scripts for yourself, i.e., if you are your own user.
    pub fn write_heatmap_external_matrix<W, P>(
        &self,
        mut writer: W,
        matrix_width: usize,
        matrix_height: usize,
        matrix_path: P,
    ) -> std::io::Result<()>
    where
        W: Write,
        P: AsRef<Path>,
    {
        self.write_heatmap_helper1(&mut writer, matrix_width, matrix_height)?;

        writeln!(
            writer,
            "splot \"{}\" matrix with image t \"{}\" ",
            matrix_path.as_ref().to_string_lossy(),
            &self.title
        )?;

        self.terminal.finish(&mut writer)
    }
}

impl Default for GnuplotSettings {
    fn default() -> Self {
        Self {
            x_label: "".to_owned(),
            y_label: "".to_owned(),
            title: "".to_owned(),
            terminal: GnuplotTerminal::Empty,
            palette: GnuplotPalette::PresetHSV,
            x_axis: None,
            y_axis: None,
            size: "7.4cm, 5cm".into(),
            cb_range: None,
        }
    }
}

#[derive(Debug, Clone, Copy)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
/// Implements color palett from <https://arxiv.org/abs/1108.5083>
///
/// What's so good about this palett? It is monotonically increasing in perceived brightness.
/// That means, it is well suited for being printed in black and white.
///
/// ```
/// use sampling::heatmap::*;
/// let mut params = CubeHelixParameter::default();
/// params.rotation(1.3)
///         .gamma(1.1)
///         .start_color(0.3)
///         .reverse(true);
/// ```
pub struct CubeHelixParameter {
    hue: f32,      // hue intensity, valid values 0 <= hue <= 1
    r: f32,        // rotation in color space. Typical values: -1.5 <= r <= 1.5
    s: f32,        // starting color, valid values 0 <= s <= 1
    gamma: f32,    // gamma < 1 emphasises low intensity values, gamma > 1 high intensity ones
    low: f32,      // lowest value for grayscale. 0 <= low < 1 and low < high
    high: f32,     // highest value for grayscale. 0< high <= 1 and low < high
    reverse: bool, // reverse cbrange?
}

fn valid(v: f32) -> bool {
    (0.0..=1.0).contains(&v)
}

impl CubeHelixParameter {
    /// # Builder pattern - set start color
    /// Will panic if the following is false: 0.0 <= s <= 1.0
    pub fn start_color(&mut self, s: f32) -> &mut Self {
        if valid(s) {
            self.s = s;
            return self;
        }
        panic!("Invalid value for starting color! The following has to be true: 0.0 <= s <= 1.0 - you used: s={}", s)
    }

    /// # Builder pattern - set gamma
    ///
    /// |gamma| < 1 emphasises low intensity values, |gamma| > 1 high intensity ones
    ///
    /// gamma has to be finite - will panic otherwise
    pub fn gamma(&mut self, gamma: f32) -> &mut Self {
        if gamma.is_finite() {
            self.gamma = gamma.abs();
            return self;
        }
        panic!("Gamma has to be finite. You used: {}", gamma)
    }

    /// # Builder pattern - set reverse
    /// reverse: Reverse the cbrange?
    pub fn reverse(&mut self, reverse: bool) -> &mut Self {
        self.reverse = reverse;
        self
    }

    /// # Builder pattern - set low and high value
    /// default: low = 0.0, high = 1.0
    ///
    /// Maps grayscale range from [0.0, 1.0] -> [low, high].
    /// These are the brightness values used for calculating the palette later on.
    ///
    /// # Safety
    /// will panic if
    /// * `low` >= `high`
    /// * `low` < 0
    /// * `low` >= 1
    /// * `high` <= 0
    /// * `high` > 1
    pub fn low_high(&mut self, low: f32, high: f32) -> &mut Self {
        if low < high && valid(low) && valid(high) {
            self.low = low;
            self.high = high;
            return self;
        }
        panic!("Invalid values of low and high. The following has to be true: 0.0 <= low < high <= 1.0. You used: low {} high {}", low, high)
    }

    /// #Set hue intensity. Builder pattern
    /// Valid values are 0.0 <= hue <= 1.0.
    /// **Important** Will panic on invalid hue values!
    pub fn hue(&mut self, hue: f32) -> &mut Self {
        if valid(hue) {
            self.hue = hue;
        } else {
            panic!(
                "Invalid hue value! Hue value has to be 0.0 <= hue <= 1.0, you used {}",
                hue
            )
        }
        self
    }

    /// #Set rotation. Builder pattern
    /// Rotation in color space. The higher the value, the quicker the colors will change in the palett.
    ///
    /// Normally the range used is -1.5 <= rotation <= 1.5. Invalid values are Nan, or ±Infinity
    /// **Important** Will panic on invalid rotation values!
    pub fn rotation(&mut self, rotation: f32) -> &mut Self {
        if rotation.is_finite() {
            self.r = rotation;
        } else {
            panic!(
                "Invalid rotation value! Rotation value has to be finite, you used {}",
                rotation
            )
        }
        self
    }

    /// Calculate color from gray value.
    /// Gray value should be in the interval [0.0,1.0].
    ///
    /// Will return `[red, green, blue]`, where red, green and blue are in [0.0, 1.0],
    /// will return \[0,0,0\] for NAN gray value.
    pub fn rgb_from_gray(&self, gray: f32) -> [f32; 3] {
        if gray.is_nan() {
            return [0.0, 0.0, 0.0];
        }
        let mut lambda = gray.clamp(0.0, 1.0);
        if self.reverse {
            lambda = 1.0 - lambda;
        }
        lambda = self.low + (self.high - self.low) * lambda; // map [0,1] -> [low, high]
        let lg = lambda.powf(self.gamma);
        let phi = 2.0 * (self.s / 3.0 + self.r * lambda) * std::f32::consts::PI;
        let a = self.hue * lg * (1.0 - lg) * 0.5;

        let (s_phi, c_phi) = phi.sin_cos();

        [
            a * (-0.14861 * c_phi + 1.78277 * s_phi) + lg, // red
            lg + a * (-0.29227 * c_phi - 0.90649 * s_phi), // green
            lg + a * c_phi * 1.97294,                      // blue
        ]
    }

    /// * Calculate color from gray value.
    /// * Gray value should be in the interval [0.0,1.0].
    /// * will return `ColorRgb::new(0,0,0)` for NAN gray value
    ///
    /// will return corresponding (approximate) [`ColorRgb`](crate::heatmap::ColorRGB)
    pub fn approximate_color_rgb(&self, gray: f32) -> ColorRGB {
        let color = self.rgb_from_gray(gray);
        let color = color.map(|val| (val * 255.0).clamp(0.0, 255.0).floor() as u8);

        ColorRGB::new_from_array(&color)
    }

    /// Converts `self` into the corresponding enum of [`GnuplotPallet`](crate::heatmap::GnuplotPalette)
    pub fn into_gnuplot_palette(self) -> GnuplotPalette {
        self.into()
    }
}

impl Default for CubeHelixParameter {
    fn default() -> Self {
        Self {
            hue: 1.0,
            r: 1.2,
            low: 0.0,
            high: 1.0,
            reverse: false,
            gamma: 1.0,
            s: 0.1,
        }
    }
}

/// # RGB value
/// * stores a color in RGB space
/// * default color is black `[0,0,0]`
#[derive(Debug, Clone, Copy)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
pub struct ColorRGB {
    /// The red part
    pub red: u8,
    /// The green part
    pub green: u8,
    /// The blue part
    pub blue: u8,
}

impl Default for ColorRGB {
    fn default() -> Self {
        Self::new(0, 0, 0)
    }
}

impl ColorRGB {
    /// # Create a new color
    pub fn new(red: u8, green: u8, blue: u8) -> Self {
        Self { red, green, blue }
    }

    /// # Create color from an array
    /// * `color[0]` -> red
    /// * `color[1]` -> green
    /// * `color[2]` -> blue
    pub fn new_from_array(color: &[u8; 3]) -> Self {
        Self {
            red: color[0],
            green: color[1],
            blue: color[2],
        }
    }

    /// # convert color to array,
    /// will return `[red, green, blue]`
    pub fn to_array(&self) -> [u8; 3] {
        [self.red, self.green, self.blue]
    }

    /// # Turn into hex representation
    /// ```
    /// use sampling::heatmap::ColorRGB;
    ///
    /// let color = ColorRGB::new(0,0,0);
    /// let hex = color.to_hex();
    /// assert_eq!(&hex, "#000000");
    ///
    /// let color = ColorRGB::new_from_array(&[255,255,255]);
    /// let hex = color.to_hex();
    /// assert_eq!(&hex, "#FFFFFF");
    /// ```
    pub fn to_hex(&self) -> String {
        let mut s = String::new();
        self.fmt_hex(&mut s).unwrap();
        s
    }

    /// # Write hex representation to a fmt writer
    /// * similar to [`to_hex`](crate::heatmap::ColorRGB::to_hex), but writes to fmt writer instead
    pub fn fmt_hex<W: fmt::Write>(&self, mut writer: W) -> Result<(), fmt::Error> {
        write!(
            writer,
            "#{:02X?}{:02X?}{:02X?}",
            self.red, self.green, self.blue
        )
    }

    /// # Write hex representation to a io writer
    /// * similar to [`to_hex`](crate::heatmap::ColorRGB::to_hex), but writes to io writer instead
    pub fn write_hex<W: Write>(&self, mut writer: W) -> Result<(), std::io::Error> {
        write!(
            writer,
            "#{:02X?}{:02X?}{:02X?}",
            self.red, self.green, self.blue
        )
    }
}

/// # A color palette in RGB space
/// * used for [GnuplotPalette](crate::heatmap::GnuplotPalette)
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
pub struct PaletteRGB {
    colors: Vec<ColorRGB>,
}

impl PaletteRGB {
    /// # Initialize Palette
    /// Note: Palette needs at least two colors,
    /// therefore `None` will be returned if the
    /// `colors` has a length less than 2
    pub fn new(colors: Vec<ColorRGB>) -> Option<Self> {
        if colors.len() < 2 {
            return None;
        }
        Some(Self { colors })
    }

    /// # add a color to the palette
    pub fn add_color(&mut self, color: ColorRGB) {
        self.colors.push(color)
    }

    /// # write string to define this palette in gnuplot to fmt writer
    pub fn fmt_palette<W: fmt::Write>(&self, mut writer: W) -> Result<(), fmt::Error> {
        write!(writer, "set palette defined ( 0 \"")?;
        self.colors[0].fmt_hex(&mut writer)?;
        write!(writer, "\"")?;

        for (color, index) in self.colors.iter().skip(1).zip(1..) {
            write!(writer, ", {} \"", index)?;
            color.fmt_hex(&mut writer)?;
            write!(writer, "\"")?;
        }
        write!(writer, " )")
    }

    /// # write string to define this palette in gnuplot to io writer
    pub fn write_palette<W: std::io::Write>(&self, mut writer: W) -> Result<(), std::io::Error> {
        write!(writer, "set palette defined ( 0 \"")?;
        self.colors[0].write_hex(&mut writer)?;
        write!(writer, "\"")?;

        for (color, index) in self.colors.iter().skip(1).zip(1..) {
            write!(writer, ", {} \"", index)?;
            color.write_hex(&mut writer)?;
            write!(writer, "\"")?;
        }
        write!(writer, " )")
    }

    /// Converts `self` into the corresponding enum of [`GnuplotPallet`](crate::heatmap::GnuplotPalette)
    pub fn into_gnuplot_palette(self) -> GnuplotPalette {
        self.into()
    }
}

/// # Defines gnuplot point
/// * Note that most of the fields are public and
///   can be accessed directly
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
pub struct GnuplotPointSettings {
    /// Color of the point
    pub color: ColorRGB,
    size: f32,
    /// should the point have a frame?
    pub frame: bool,
    /// Which color should the frame be?
    pub frame_color: ColorRGB,
    /// Entry for legend
    legend: String,
}

impl GnuplotPointSettings {
    /// Create a new instance of GnuplotPointSettings
    /// - same as GnuplotPointSettings::default()
    pub fn new() -> Self {
        Self::default()
    }

    /// # Choose the color for the point
    /// * default color is blue
    pub fn color(&mut self, color: ColorRGB) -> &mut Self {
        self.color = color;
        self
    }

    /// # Choose the size of the point
    /// * size has to be finite
    /// * size has to be >= 0.0
    ///
    /// Otherwise the old size will be silently kept
    pub fn size(&mut self, size: f32) -> &mut Self {
        if size.is_finite() && size >= 0.0 {
            self.size = size;
        }
        self
    }

    /// # Get the point size
    /// Note: allmost all other fields are public!
    pub fn get_size(&self) -> f32 {
        self.size
    }

    /// Should there be a frame around the point ?
    /// This is good for better visibility if you do not know the color
    /// of the background, or the background color changes
    pub fn frame(&mut self, active: bool) -> &mut Self {
        self.frame = active;
        self
    }

    /// # Which color should the frame have?
    /// *default color is black
    pub fn frame_color(&mut self, color: ColorRGB) -> &mut Self {
        self.frame_color = color;
        self
    }

    /// # Change the legend entry
    /// * This will be the title of the legend for this point(s)
    /// * will be set to "Invalid character encountered" if it contains a " or newline character
    pub fn legend<S: Into<String>>(&mut self, legend: S) -> &mut Self {
        let s = legend.into();
        if s.contains('\"') || s.contains('\n') {
            self.legend = "Invalid character encountered".to_owned();
            self
        } else {
            self.legend = s;
            self
        }
    }

    /// # Get entry for legend
    /// This will be the title of the legend for this point(s)
    pub fn get_legend(&self) -> &str {
        &self.legend
    }

    #[allow(dead_code)]
    pub(crate) fn frame_size(&self) -> f32 {
        let size = self.size * 1.14;
        if size < 0.01 {
            0.01
        } else {
            size
        }
    }
}

impl Default for GnuplotPointSettings {
    fn default() -> Self {
        Self {
            color: ColorRGB::new(0, 0, 255),
            size: 0.5,
            frame: true,
            frame_color: ColorRGB::default(),
            legend: "".into(),
        }
    }
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
/// defines presets for different color palettes
pub enum GnuplotPalette {
    /// Use preset HSV palette
    PresetHSV,
    /// Use preset RGB palette, i.e., the
    /// default palette of gnuplot
    PresetRGB,
    /// Use a CubeHelix palette
    ///
    /// What makes this palette special is,
    /// that, if it is converted to black and white,
    /// it will be monotonically increasing in perceived brightness
    /// (or monotonically decreasing, if you reverse the palette),
    /// which is nice for heatmaps
    ///
    /// For more info see [`CubeHelixParameter`](crate::heatmap::CubeHelixParameter)
    CubeHelix(CubeHelixParameter),
    /// Define a palette in RGB space
    RGB(PaletteRGB),
}

impl From<PaletteRGB> for GnuplotPalette {
    fn from(palette: PaletteRGB) -> Self {
        GnuplotPalette::RGB(palette)
    }
}

impl From<CubeHelixParameter> for GnuplotPalette {
    fn from(parameter: CubeHelixParameter) -> Self {
        GnuplotPalette::CubeHelix(parameter)
    }
}

impl GnuplotPalette {
    pub(crate) fn write_palette<W: Write>(&self, mut writer: W) -> std::io::Result<()> {
        match self {
            Self::PresetHSV => {
                writeln!(writer, "set palette model HSV")?;
                writeln!(
                    writer,
                    "set palette negative defined  ( 0 0 1 0, 2.8 0.4 0.6 0.8, 5.5 0.83 0 1 )"
                )
            }
            Self::PresetRGB => Ok(()),
            Self::CubeHelix(helix) => {
                writeln!(writer, "# Parameter for color palett")?;
                writeln!(
                    writer,
                    "hue={}     # hue intensity, valid values 0 <= hue <= 1",
                    helix.hue
                )?;
                writeln!(
                    writer,
                    "r={}       # rotation in color space. Typical values: -1.5 <= r <= 1.5",
                    helix.r
                )?;
                writeln!(
                    writer,
                    "s={}       # starting color, valid values 0 <= s <= 1",
                    helix.s
                )?;
                writeln!(writer, "gamma={}   # gamma < 1 emphasizes low intensity values, gamma > 1 high intensity ones", helix.gamma)?;
                writeln!(
                    writer,
                    "low={}     # lowest value for grayscale. 0 <= low < 1 and low < high",
                    helix.low
                )?;
                writeln!(
                    writer,
                    "high={}    # highest value for grayscale. 0< high <= 1 and low < high",
                    helix.high
                )?;
                let s = if helix.reverse { "1" } else { "0" };
                writeln!(
                    writer,
                    "reverse={}   # set to 1 for reverse cbrange, set to 0 for original cbrange",
                    s
                )?;
                writeln!(
                    writer,
                    "\n\nlg(lambda)=lambda**gamma
phi(lambda)=2.0 * (s/3.0 + r * lambda) * pi
a(lambda)=hue*lg(lambda)*(1.0-lg(lambda)) * 0.5

red(lambda)=a(lambda)*(-0.14861*cos(phi(lambda)) + 1.78277 * sin(phi(lambda))) + lg(lambda)
green(lambda)=lg(lambda) + a(lambda)*(-0.29227 * cos(phi(lambda)) - 0.90649 * sin(phi(lambda)))
blue(lambda)=lg(lambda) + a(lambda) * cos(phi(lambda)) * 1.97294

rev(x)=reverse?1-x:x    # reverse grayscale

map(x)=low+(high-low)*rev(x)

set palette functions red(map(gray)), green(map(gray)), blue(map(gray))\n"
                )
            }
            Self::RGB(palette) => {
                palette.write_palette(&mut writer)?;
                writeln!(writer)
            }
        }
    }
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde_support", derive(Serialize, Deserialize))]
/// # Options for choosing gnuplot Terminal
pub enum GnuplotTerminal {
    /// # Use EpsLatex as terminal in gnuplot
    /// * The String here is the output name, i.e., the filepath of the output of gnuplot (without the .tex)
    ///   Only alphanumeric characters, space and underscore are allowed,
    ///   all other characters will be ignored
    /// * the created gnuplot script assumes, you have `latexmk` installed
    /// * if you do not have latexmk, you can still use this, but you have to manually edit the
    ///   gnuplot scrip later on
    /// * gnuplot script will create `.tex` file and `.pdf` file created from the tex file
    ///
    /// ## WARNING
    /// The created gnuplot script will contain a system call to latexmk, such that a pdf file is generated from a tex file
    /// without the need for calling latexmk afterwards.
    EpsLatex(String),
    /// # Use pdf as gnuplot terminal
    /// * gnuplot script will create a `.pdf` file
    /// * The String here is the output name, i.e., the filepath of the output of gnuplot (without the .pdf)
    PDF(String),
    /// # Does not specify a terminal
    Empty,
}

fn get_valid_filename(name: &str) -> String {
    name.chars()
        .filter(|c| c.is_alphabetic() || *c == ' ' || *c == '_')
        .take(255)
        .collect()
}

impl GnuplotTerminal {
    pub(crate) fn write_terminal<W: Write>(
        &self,
        mut writer: W,
        size: &str,
    ) -> std::io::Result<()> {
        writeln!(writer, "reset session")?;
        writeln!(writer, "set encoding utf8")?;

        let size = if size.is_empty() {
            size.to_owned()
        } else {
            format!(" size {}", size)
        };

        match self {
            Self::EpsLatex(name) => {
                let name = get_valid_filename(name);
                writeln!(writer, "set t epslatex 9 standalone color{} header \"\\\\usepackage{{amsmath}}\\n\"\nset font \",9\"", size)?;
                writeln!(writer, "set output \"{name}.tex\"")
            }
            Self::PDF(name) => {
                let name = get_valid_filename(name);
                writeln!(writer, "set t pdf {}", size)?;
                writeln!(writer, "set output \"{name}.pdf\"")
            }
            Self::Empty => Ok(()),
        }
    }

    pub(crate) fn finish<W: Write>(&self, mut w: W) -> std::io::Result<()> {
        match self {
            Self::EpsLatex(name) => {
                let name = get_valid_filename(name);
                writeln!(w, "set output")?;
                write!(w, "system('latexmk {name}.tex")?;
                writeln!(w, " -pdf -f')")
            }
            Self::PDF(_) => {
                writeln!(w, "set output")
            }
            _ => Ok(()),
        }
    }
}