Struct SurfacePlot 

pub struct SurfacePlot { /* private fields */ }

A structure representing a 3-D surface plot.

The SurfacePlot struct is designed to build and customize 3-dimensional surface visualizations. It supports fine-grained control over the color mapping of z values, interactive color bars, lighting effects that enhance depth perception, and global opacity settings. Layout elements such as the plot title and axis labels can also be configured through the builder API, allowing you to embed the surface seamlessly in complex dashboards.

Arguments

• data – A reference to the DataFrame that supplies the data. It must contain three numeric columns whose names are given by x, y and z.
• x – The column name to be used for the x-axis coordinates. Each distinct x value becomes a row in the underlying z grid.
• y – The column name to be used for the y-axis coordinates. Each distinct y value becomes a column in the z grid.
• z – The column name that provides the z-axis heights. These values are mapped to colors according to color_scale / reverse_scale.
• color_bar – An optional Reference to a ColorBar describing the appearance of the color legend (length, tick formatting, border, etc.).
• color_scale – An optional Palette that defines the color gradient (e.g. Viridis, Cividis).
• reverse_scale – An optional bool indicating whether the chosen color_scale should run in the opposite direction.
• show_scale – An optional bool that toggles the visibility of the color bar. Useful when you have multiple surfaces that share an external legend.
• lighting – An optional Reference to a Lighting struct that specifies ambient, diffuse, specular components, roughness, fresnel and light position. Leaving it None applies Plotly’s default Phong shading.
• opacity – An optional f64 in [0.0, 1.0] that sets the global transparency of the surface (1 = opaque, 0 = fully transparent).
• facet – An optional string slice specifying the column name to create faceted subplots (one surface per category).
• facet_config – An optional reference to a FacetConfig struct for customizing facet layout (ncol, nrow, gap sizes, etc.).
• plot_title – An optional Text that customizes the title (content, font, size, alignment).
• legend – An optional reference to a Legend struct for legend customization.

Example

use ndarray::Array;
use plotlars::{ColorBar, Lighting, Palette, Plot, SurfacePlot, Text};
use polars::prelude::*;
use std::iter;

let n: usize = 100;
let (x_base, _): (Vec<f64>, Option<usize>) = Array::linspace(-10.0, 10.0, n).into_raw_vec_and_offset();
let (y_base, _): (Vec<f64>, Option<usize>) = Array::linspace(-10.0, 10.0, n).into_raw_vec_and_offset();

let x = x_base
    .iter()
    .flat_map(|&xi| iter::repeat_n(xi, n))
    .collect::<Vec<_>>();

let y = y_base
    .iter()
    .cycle()
    .take(n * n)
    .cloned()
    .collect::<Vec<_>>();

let z = x_base
    .iter()
    .flat_map(|i| {
        y_base
            .iter()
            .map(|j| 1.0 / (j * j + 5.0) * j.sin() + 1.0 / (i * i + 5.0) * i.cos())
            .collect::<Vec<_>>()
    })
    .collect::<Vec<_>>();

let dataset = df![
        "x" => &x,
        "y" => &y,
        "z" => &z,
    ]
    .unwrap();

SurfacePlot::builder()
    .data(&dataset)
    .x("x")
    .y("y")
    .z("z")
    .plot_title(
        Text::from("Surface Plot")
            .font("Arial")
            .size(18),
    )
    .color_bar(
        &ColorBar::new()
            .border_width(1),
    )
    .color_scale(Palette::Cividis)
    .reverse_scale(true)
    .opacity(0.5)
    .build()
    .plot();

Implementations

impl SurfacePlot

pub fn builder<'f1, 'f2, 'f3, 'f4, 'f5, 'f6, 'f7, 'f8, 'f9>() -> SurfacePlotBuilder<'f1, 'f2, 'f3, 'f4, 'f5, 'f6, 'f7, 'f8, 'f9>

Examples found in repository

examples/surfaceplot.rs (line 42)

fn main() {
    let n: usize = 100;
    let (x_base, _): (Vec<f64>, Option<usize>) =
        Array::linspace(-10.0, 10.0, n).into_raw_vec_and_offset();
    let (y_base, _): (Vec<f64>, Option<usize>) =
        Array::linspace(-10.0, 10.0, n).into_raw_vec_and_offset();

    let x = x_base
        .iter()
        .flat_map(|&xi| iter::repeat_n(xi, n))
        .collect::<Vec<_>>();

    let y = y_base
        .iter()
        .cycle()
        .take(n * n)
        .cloned()
        .collect::<Vec<_>>();

    let z = x_base
        .iter()
        .flat_map(|i| {
            y_base
                .iter()
                .map(|j| 1.0 / (j * j + 5.0) * j.sin() + 1.0 / (i * i + 5.0) * i.cos())
                .collect::<Vec<_>>()
        })
        .collect::<Vec<_>>();

    let dataset = df![
        "x" => &x,
        "y" => &y,
        "z" => &z,
    ]
    .unwrap();

    SurfacePlot::builder()
        .data(&dataset)
        .x("x")
        .y("y")
        .z("z")
        .plot_title(Text::from("Surface Plot").font("Arial").size(18))
        .color_bar(&ColorBar::new().border_width(1))
        .color_scale(Palette::Cividis)
        .reverse_scale(true)
        .opacity(0.5)
        .build()
        .plot();
}

examples/faceting.rs (line 653)

fn surfaceplot_example() {
    let n: usize = 50;
    let (x_base, _): (Vec<f64>, Option<usize>) =
        Array::linspace(-5., 5., n).into_raw_vec_and_offset();
    let (y_base, _): (Vec<f64>, Option<usize>) =
        Array::linspace(-5., 5., n).into_raw_vec_and_offset();

    let mut x_all = Vec::new();
    let mut y_all = Vec::new();
    let mut z_all = Vec::new();
    let mut category_all = Vec::new();

    type SurfaceFunction = Box<dyn Fn(f64, f64) -> f64>;
    let functions: Vec<(&str, SurfaceFunction)> = vec![
        (
            "Sine Wave",
            Box::new(|xi: f64, yj: f64| (xi * xi + yj * yj).sqrt().sin()),
        ),
        ("Saddle", Box::new(|xi: f64, yj: f64| xi * xi - yj * yj)),
        (
            "Gaussian",
            Box::new(|xi: f64, yj: f64| (-0.5 * (xi * xi + yj * yj)).exp()),
        ),
    ];

    for (name, func) in &functions {
        for &xi in x_base.iter() {
            for &yj in y_base.iter() {
                x_all.push(xi);
                y_all.push(yj);
                z_all.push(func(xi, yj));
                category_all.push(*name);
            }
        }
    }

    let dataset = df![
        "x" => &x_all,
        "y" => &y_all,
        "z" => &z_all,
        "function" => &category_all,
    ]
    .unwrap();

    SurfacePlot::builder()
        .data(&dataset)
        .x("x")
        .y("y")
        .z("z")
        .facet("function")
        .facet_config(&FacetConfig::new().cols(3).rows(1).h_gap(0.08).v_gap(0.12))
        .plot_title(
            Text::from("3D Mathematical Functions")
                .font("Arial")
                .size(20),
        )
        .color_scale(Palette::Viridis)
        .opacity(0.9)
        .build()
        .plot();
}

Trait Implementations

impl Clone for SurfacePlot

fn clone(&self) -> SurfacePlot

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Serialize for SurfacePlot

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl PlotHelper for SurfacePlot