Struct SvgDocument 

pub struct SvgDocument { /* private fields */ }

Represents an SVG document with a specified width and height. It contains clip paths, styles, layers, and symbols that can be used to create SVG graphics. Although you can directly manipulate the SVG document, it is recommended to use higher level objects in this library such as Chart struct for creating scaled charts with x and y axis.

The SvgDocument struct is the main entry point for creating SVG documents in this library.

A SVG-global style sheet can be set using the scss field, which is a string containing SCSS styles. The styles are compiled to CSS using the grass crate when the SVG document is rendered. This allows for flexible styling of SVG elements using SCSS syntax, and verified the validity of the SCSS parameters before rendering. You can append additional SCSS styles using the append_scss method.

Any css file is also a valid SCSS file, so you can use any CSS file as a stylesheet.

The style sheet is embedded in the SVG document as a <style> element, which is the most convenient way to handle SVG images with styles.

You don’t have to use a global style, you can set styles for individual elements using the StyleAttr parameter in all the plot element and plot functions.

Implementations

impl SvgDocument

pub fn new() -> Self

Creates a new SvgDocument with default settings only, without any nodes, symbols, or plots.

Examples found in repository

examples/sine_curve.rs (line 27)

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pi = std::f64::consts::PI;
    let pi2 = 2.0 * pi;

    const N: i32 = 100;
    let sin: Vec<(f64, f64)> = (0..N)
        .map(|i| {
            let x = i as f64 * pi2 / (N as f64 - 1.0);
            (x, x.sin())
        })
        .collect();

    let chart = XYChart::new((600, 300), (..pi2, -1.1..1.1))
        .x_labels(1.0, 10, None)
        .y_labels(0.5, 10, None)
        .x_axis_description("x", None)
        .y_axis_description("sin(x)", None)
        .plot_grid(0.2, 0.1, class("fine-grid"))
        .plot_grid(1.0, 0.5, class("grid"))
        .plot_poly_line(sin, class("curve"))
        .plot_poly_line(vec![(0.0, 0.0), (pi2, 0.0)], class("base-line"));

    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(chart))
        .save("docs/img/sine_curve.svg")
}

examples/xy_gamut_plots.rs (line 45)

pub fn make_plot(space: RgbSpace) -> Result<(), Box<dyn std::error::Error>> {
    let observer = Observer::Cie1931; // Use the CIE 1931 observer
                                      // let space = RgbSpace::DisplayP3; // Use the sRGB color space

    // Create an XYChromaticity chart with the specified observer and ranges
    let xy_chromaticity = XYChromaticity::new((775, 875), (-0.025..=0.75, 0.0..=0.875))
        .ticks(0.01, 0.01, 5, class("fine-grid"))
        .ticks(0.1, 0.1, 10, class("grid"))
        .x_labels(0.1, 10, None)
        .x_axis_description(&format!("{} x", observer.name()), None)
        .y_labels(0.1, 10, class("y-labels"))
        .y_axis_description(&format!("{} y", observer.name()), None)
        .plot_spectral_locus(class("spectral-locus"))
        .plot_spectral_locus_ticks(440..=650, 10, 15, class("spectral-locus-ticks"))
        .plot_spectral_locus_ticks(460..=630, 1, 7, class("spectral-locus-ticks"))
        .plot_spectral_locus_labels(460..=620, 10, 3, class("spectral-locus-labels"))
        .plot_rgb_gamut(space, None)
        .plot_planckian_locus(class("planckian"))
        .plot_planckian_locus_ticks((1500..=7500).step_by(100), 7, class("planckian-ticks-fine"))
        .plot_planckian_locus_ticks(PLANCKIAN_LABELS_AT.to_vec(), 15, class("planckian-ticks"))
        .plot_planckian_locus_labels(PLANCKIAN_LABELS_AT.to_vec(), 18, class("planckian-labels"))
        .plot_grid(0.01, 0.01, class("fine-grid"))
        .plot_grid(0.1, 0.1, class("grid"));

    // create the plot
    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(xy_chromaticity))
        .save(format!("docs/img/{}_gamut.svg", space.as_ref().to_lowercase()).as_str())?;
    Ok(())
}

pub fn append_scss(self, css: &str) -> Self

Appends SCSS styles to the document’s stylesheet. This method allows you to add additional styles to the existing SCSS content. The styles are compiled to CSS when the document is rendered.

Most covenient is to use a separate SCSS file and include it using the append_scss method using include_str! macro, which reads the file at compile time. The SCSS styles are compiled to CSS using the grass crate when the SVG document is rendered, and embedded in the resulting SVG document as a <style> element.

Using a seperate SCSS file allows you to keep your styles organized and maintainable, and also allows you to edit the styles in a lanaguate aware editor with syntax highlighting and autocompletion.

Example

// The file in the include_str! macro is just an example, and gives a compile error if the file does not exist.
use colorimetry_plot::svgdoc::SvgDocument;

// Create a new SVG document and append SCSS styles from a file
let svg_doc = SvgDocument::new()
    .append_scss(include_str!("path/to/your/styles.scss"));

Examples found in repository

examples/sine_curve.rs (line 28)

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pi = std::f64::consts::PI;
    let pi2 = 2.0 * pi;

    const N: i32 = 100;
    let sin: Vec<(f64, f64)> = (0..N)
        .map(|i| {
            let x = i as f64 * pi2 / (N as f64 - 1.0);
            (x, x.sin())
        })
        .collect();

    let chart = XYChart::new((600, 300), (..pi2, -1.1..1.1))
        .x_labels(1.0, 10, None)
        .y_labels(0.5, 10, None)
        .x_axis_description("x", None)
        .y_axis_description("sin(x)", None)
        .plot_grid(0.2, 0.1, class("fine-grid"))
        .plot_grid(1.0, 0.5, class("grid"))
        .plot_poly_line(sin, class("curve"))
        .plot_poly_line(vec![(0.0, 0.0), (pi2, 0.0)], class("base-line"));

    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(chart))
        .save("docs/img/sine_curve.svg")
}

examples/xy_gamut_plots.rs (line 46)

pub fn make_plot(space: RgbSpace) -> Result<(), Box<dyn std::error::Error>> {
    let observer = Observer::Cie1931; // Use the CIE 1931 observer
                                      // let space = RgbSpace::DisplayP3; // Use the sRGB color space

    // Create an XYChromaticity chart with the specified observer and ranges
    let xy_chromaticity = XYChromaticity::new((775, 875), (-0.025..=0.75, 0.0..=0.875))
        .ticks(0.01, 0.01, 5, class("fine-grid"))
        .ticks(0.1, 0.1, 10, class("grid"))
        .x_labels(0.1, 10, None)
        .x_axis_description(&format!("{} x", observer.name()), None)
        .y_labels(0.1, 10, class("y-labels"))
        .y_axis_description(&format!("{} y", observer.name()), None)
        .plot_spectral_locus(class("spectral-locus"))
        .plot_spectral_locus_ticks(440..=650, 10, 15, class("spectral-locus-ticks"))
        .plot_spectral_locus_ticks(460..=630, 1, 7, class("spectral-locus-ticks"))
        .plot_spectral_locus_labels(460..=620, 10, 3, class("spectral-locus-labels"))
        .plot_rgb_gamut(space, None)
        .plot_planckian_locus(class("planckian"))
        .plot_planckian_locus_ticks((1500..=7500).step_by(100), 7, class("planckian-ticks-fine"))
        .plot_planckian_locus_ticks(PLANCKIAN_LABELS_AT.to_vec(), 15, class("planckian-ticks"))
        .plot_planckian_locus_labels(PLANCKIAN_LABELS_AT.to_vec(), 18, class("planckian-labels"))
        .plot_grid(0.01, 0.01, class("fine-grid"))
        .plot_grid(0.1, 0.1, class("grid"));

    // create the plot
    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(xy_chromaticity))
        .save(format!("docs/img/{}_gamut.svg", space.as_ref().to_lowercase()).as_str())?;
    Ok(())
}

pub fn set_margin(self, margin: u32) -> Self

Sets the margin for the SVG document. The margin is applied to the width and height of the document when calculating the size of sub plots. The default margin is 50 pixels.

pub fn set_width(self, width: u32) -> Self

Sets the width of the SVG document. If not set, the width will be calculated based on the size of the sub plots and the margin. If the width is larger than the maximum allowed size, an error will be printed and the program will exit. The width is set in pixels.

pub fn set_height(self, height: u32) -> Self

Sets the height of the SVG document. If not set, the height will be calculated based on the size of the sub plots and the margin. If the height is larger than the maximum allowed size, an error will be printed and the program will exit. The height is set in pixels.

pub fn add_clip_path(self, id: String, path: &Path) -> Self

Adds a path to the SVG document as a clip path with the specified ID.

pub fn add_symbol(self, symbol: impl Into<Symbol>) -> Self

Adds a symbol to the SVG document.

pub fn add_node(self, node: impl Into<Box<dyn Node>>) -> Self

Adds a node to the SVG document, typically used for headers, footers, or other SVG elements. They will be added to the SVG document as-is, without any transformations or scaling, and placed in front of any other content, into a layer with the id “front”.

pub fn add_plot(self, svg_sub: Box<dyn Rendable>) -> Self

Adds a sub plot to the SVG document. The sub plot must implement the Rendable trait, which allows it to be rendered as an SVG element. The sub plot will be positioned based on the document’s flow, which is calculated by the flow method. If the sub plot is larger than the document size, an error will be printed and the program will exit.

Examples found in repository

examples/sine_curve.rs (line 29)

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pi = std::f64::consts::PI;
    let pi2 = 2.0 * pi;

    const N: i32 = 100;
    let sin: Vec<(f64, f64)> = (0..N)
        .map(|i| {
            let x = i as f64 * pi2 / (N as f64 - 1.0);
            (x, x.sin())
        })
        .collect();

    let chart = XYChart::new((600, 300), (..pi2, -1.1..1.1))
        .x_labels(1.0, 10, None)
        .y_labels(0.5, 10, None)
        .x_axis_description("x", None)
        .y_axis_description("sin(x)", None)
        .plot_grid(0.2, 0.1, class("fine-grid"))
        .plot_grid(1.0, 0.5, class("grid"))
        .plot_poly_line(sin, class("curve"))
        .plot_poly_line(vec![(0.0, 0.0), (pi2, 0.0)], class("base-line"));

    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(chart))
        .save("docs/img/sine_curve.svg")
}

examples/xy_gamut_plots.rs (line 47)

pub fn make_plot(space: RgbSpace) -> Result<(), Box<dyn std::error::Error>> {
    let observer = Observer::Cie1931; // Use the CIE 1931 observer
                                      // let space = RgbSpace::DisplayP3; // Use the sRGB color space

    // Create an XYChromaticity chart with the specified observer and ranges
    let xy_chromaticity = XYChromaticity::new((775, 875), (-0.025..=0.75, 0.0..=0.875))
        .ticks(0.01, 0.01, 5, class("fine-grid"))
        .ticks(0.1, 0.1, 10, class("grid"))
        .x_labels(0.1, 10, None)
        .x_axis_description(&format!("{} x", observer.name()), None)
        .y_labels(0.1, 10, class("y-labels"))
        .y_axis_description(&format!("{} y", observer.name()), None)
        .plot_spectral_locus(class("spectral-locus"))
        .plot_spectral_locus_ticks(440..=650, 10, 15, class("spectral-locus-ticks"))
        .plot_spectral_locus_ticks(460..=630, 1, 7, class("spectral-locus-ticks"))
        .plot_spectral_locus_labels(460..=620, 10, 3, class("spectral-locus-labels"))
        .plot_rgb_gamut(space, None)
        .plot_planckian_locus(class("planckian"))
        .plot_planckian_locus_ticks((1500..=7500).step_by(100), 7, class("planckian-ticks-fine"))
        .plot_planckian_locus_ticks(PLANCKIAN_LABELS_AT.to_vec(), 15, class("planckian-ticks"))
        .plot_planckian_locus_labels(PLANCKIAN_LABELS_AT.to_vec(), 18, class("planckian-labels"))
        .plot_grid(0.01, 0.01, class("fine-grid"))
        .plot_grid(0.1, 0.1, class("grid"));

    // create the plot
    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(xy_chromaticity))
        .save(format!("docs/img/{}_gamut.svg", space.as_ref().to_lowercase()).as_str())?;
    Ok(())
}

pub fn flow(&self) -> Vec<(u32, u32)>

Calculates the positions of the sub plots on the document. The positions are calculated based on the document’s width and height, and the size of the sub plots. If there is only one sub plot, it will be centered in the document. If there are multiple sub plots, the flow is not yet implemented and will return todo!(). The sub plots will not be scaled, but positioned based on the document’s flow. If the sub plot is larger than the document size, an error will be printed and the program will exit.

Returns

A vector of tuples containing the x and y positions of each sub plot in the document.

pub fn calculate_subplots_size_with_margin(&self) -> (u32, u32)

pub fn save(self, filename: &str) -> Result<(), Box<dyn Error>>

Examples found in repository

examples/sine_curve.rs (line 30)

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pi = std::f64::consts::PI;
    let pi2 = 2.0 * pi;

    const N: i32 = 100;
    let sin: Vec<(f64, f64)> = (0..N)
        .map(|i| {
            let x = i as f64 * pi2 / (N as f64 - 1.0);
            (x, x.sin())
        })
        .collect();

    let chart = XYChart::new((600, 300), (..pi2, -1.1..1.1))
        .x_labels(1.0, 10, None)
        .y_labels(0.5, 10, None)
        .x_axis_description("x", None)
        .y_axis_description("sin(x)", None)
        .plot_grid(0.2, 0.1, class("fine-grid"))
        .plot_grid(1.0, 0.5, class("grid"))
        .plot_poly_line(sin, class("curve"))
        .plot_poly_line(vec![(0.0, 0.0), (pi2, 0.0)], class("base-line"));

    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(chart))
        .save("docs/img/sine_curve.svg")
}

examples/xy_gamut_plots.rs (line 48)

pub fn make_plot(space: RgbSpace) -> Result<(), Box<dyn std::error::Error>> {
    let observer = Observer::Cie1931; // Use the CIE 1931 observer
                                      // let space = RgbSpace::DisplayP3; // Use the sRGB color space

    // Create an XYChromaticity chart with the specified observer and ranges
    let xy_chromaticity = XYChromaticity::new((775, 875), (-0.025..=0.75, 0.0..=0.875))
        .ticks(0.01, 0.01, 5, class("fine-grid"))
        .ticks(0.1, 0.1, 10, class("grid"))
        .x_labels(0.1, 10, None)
        .x_axis_description(&format!("{} x", observer.name()), None)
        .y_labels(0.1, 10, class("y-labels"))
        .y_axis_description(&format!("{} y", observer.name()), None)
        .plot_spectral_locus(class("spectral-locus"))
        .plot_spectral_locus_ticks(440..=650, 10, 15, class("spectral-locus-ticks"))
        .plot_spectral_locus_ticks(460..=630, 1, 7, class("spectral-locus-ticks"))
        .plot_spectral_locus_labels(460..=620, 10, 3, class("spectral-locus-labels"))
        .plot_rgb_gamut(space, None)
        .plot_planckian_locus(class("planckian"))
        .plot_planckian_locus_ticks((1500..=7500).step_by(100), 7, class("planckian-ticks-fine"))
        .plot_planckian_locus_ticks(PLANCKIAN_LABELS_AT.to_vec(), 15, class("planckian-ticks"))
        .plot_planckian_locus_labels(PLANCKIAN_LABELS_AT.to_vec(), 18, class("planckian-labels"))
        .plot_grid(0.01, 0.01, class("fine-grid"))
        .plot_grid(0.1, 0.1, class("grid"));

    // create the plot
    SvgDocument::new()
        .append_scss(STYLE)
        .add_plot(Box::new(xy_chromaticity))
        .save(format!("docs/img/{}_gamut.svg", space.as_ref().to_lowercase()).as_str())?;
    Ok(())
}

Trait Implementations

impl Default for SvgDocument

fn default() -> SvgDocument

Returns the “default value” for a type.

impl Rendable for SvgDocument

fn view_parameters(&self) -> ViewParameters

Returns the current view parameters for the object.

fn set_view_parameters(&mut self, _view_box: ViewParameters)

Sets the view parameters for the object.

fn render(&self) -> Document

Renders the object as an SVG element.

fn set_x(&mut self, x: i32)

Sets the x position of the view box (optional).

fn set_y(&mut self, y: i32)

Sets the y position of the view box (optional).

fn width(&self) -> u32

Returns the width of the view box (optional).

fn set_width(&mut self, width: u32)

Sets the width of the view box (optional).

fn height(&self) -> u32

Returns the height of the view box (optional).

fn set_height(&mut self, height: u32)

Sets the height of the view box (optional).

fn view_box(&mut self) -> (i32, i32, u32, u32)

fn set_view_box(&mut self, vx: i32, vy: i32, vw: u32, vh: u32)