3D Scatter Plot

Renders 3D point data using orthographic projection with a depth-sorted painter's algorithm. Points are projected onto a 2D canvas with a matplotlib-style open-box wireframe, back-pane fills, and grid lines on all three back walls. Supports z-colormap coloring, depth shading, per-point colors and sizes, and six marker shapes.

Import path: kuva::plot::scatter3d::Scatter3DPlot

Basic usage

Pass (x, y, z) tuples via with_data():

#![allow(unused)]
fn main() {
use kuva::plot::scatter3d::Scatter3DPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let scatter = Scatter3DPlot::new()
    .with_data(vec![(1.0, 2.0, 3.0), (4.0, 5.0, 6.0), (7.0, 8.0, 9.0)])
    .with_color("steelblue")
    .with_x_label("X")
    .with_y_label("Y")
    .with_z_label("Z");

let plots = vec![Plot::Scatter3D(scatter)];
let layout = Layout::auto_from_plots(&plots).with_title("3D Scatter");

let scene = render_multiple(plots, layout);
let svg = SvgBackend.render_scene(&scene);
std::fs::write("scatter3d.svg", svg).unwrap();
}

Z-colormap

Color points by their Z value using a colormap. A colorbar is rendered automatically alongside the plot:

#![allow(unused)]
fn main() {
use kuva::plot::scatter3d::Scatter3DPlot;
use kuva::plot::heatmap::ColorMap;
let scatter = Scatter3DPlot::new()
    .with_data(vec![(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)])
    .with_z_colormap(ColorMap::Viridis)
    .with_z_label("Z");   // also labels the colorbar
}

Available colormaps: Viridis, Inferno, Grayscale, Custom.

Custom view angles

Adjust the camera position with azimuth and elevation. Enable with_depth_shade() to fade distant points as an additional depth cue:

#![allow(unused)]
fn main() {
use kuva::plot::scatter3d::Scatter3DPlot;
let scatter = Scatter3DPlot::new()
    .with_data(vec![(1.0, 2.0, 3.0)])
    .with_azimuth(-120.0)
    .with_elevation(20.0)
    .with_depth_shade();
}

Alternatively, pass a View3D struct directly:

#![allow(unused)]
fn main() {
use kuva::plot::scatter3d::Scatter3DPlot;
use kuva::plot::plot3d::View3D;
let scatter = Scatter3DPlot::new()
    .with_data(vec![(1.0, 2.0, 3.0)])
    .with_view(View3D { azimuth: -120.0, elevation: 20.0 });
}

Per-point colors and sizes

#![allow(unused)]
fn main() {
use kuva::plot::scatter3d::Scatter3DPlot;
let data = vec![(0.0, 0.0, 0.0), (1.0, 1.0, 1.0), (2.0, 2.0, 2.0)];
let scatter = Scatter3DPlot::new()
    .with_data(data)
    .with_colors(vec!["crimson", "steelblue", "seagreen"])
    .with_sizes(vec![4.0, 6.0, 8.0]);
}

Builder reference

CLI

# Basic
kuva scatter3d data.tsv --x x --y y --z z \
    --title "3D Scatter" --x-label "X" --y-label "Y" --z-label "Z"

# Group colors with legend
kuva scatter3d data.tsv --x x --y y --z z --color-by group

# Z colormap with depth shading
kuva scatter3d data.tsv --x x --y y --z z \
    --z-color viridis --depth-shade

# Custom view, no grid
kuva scatter3d data.tsv --x x --y y --z z \
    --azimuth -120 --elevation 20 --no-grid --no-box

CLI flags