ironlab

A MATLAB-flavoured Rust API for building, viewing and exporting scientific figures.

A figure is built by placing axes in a grid of tiles and adding plots to them with functions named after their MATLAB equivalents: plot, scatter, contour, quiver, surf and their relatives. Each plotting function returns a handle whose chained setters change the properties of the new plot, in the way that MATLAB's name–value arguments do. The figure can then be shown in the interactive viewer, saved as a .fig file or as JSON, or exported to a single-page PDF whose page is exactly the size of the figure, with fonts embedded and text that can be selected and searched. Labels may contain LaTeX mathematics, which IronLAB typesets itself, so no TeX installation is needed.

Where this crate sits

IronLAB is a Cargo workspace, and this crate is its facade. It writes directly to the retained figure model of ironlab-ir, and depends on ironlab-text for typesetting, ironlab-scene for layout and geometry, ironlab-pdf for export and ironlab-viewer for the interactive window. This is the crate to depend on: the others are useful directly only when a particular layer is needed on its own.

Usage

cargo add ironlab

use ironlab::prelude::*;

let x = linspace(0.0, 2.0 * std::f64::consts::PI, 200);
let sin: Vec<f64> = x.iter().map(|x| x.sin()).collect();
let cos: Vec<f64> = x.iter().map(|x| x.cos()).collect();

let mut fig = Figure::new().size_mm(120.0, 80.0).title("Trigonometric functions");
let mut ax = fig.axes(0, 0);
ax.plot(&x, &sin).display_name("$\\sin x$");
ax.plot(&x, &cos).display_name("$\\cos x$").dash(Dash::Dashed);
ax.xlabel("$x$").ylabel("$f(x)$").legend(LegendLocation::NorthEast);

assert!(fig.validate().is_valid());

Builder calls never panic because of inconsistent input, such as arrays of different lengths or a tile outside the layout. Such problems are reported by Figure::validate, and are checked again before a figure is exported or shown.

Documentation

The documentation site is at ironlab.org. It covers getting started, using the viewer and the architecture, and the gallery shows every figure IronLAB can draw, each with the code that produced it and the PDF it exports to. The source is at github.com/thclark/ironlab.

IronLAB is moving quickly and breaking changes are expected. Pin to an exact version.

Licence

This crate is licensed under the GNU Affero General Public License, either version 3 or (at your option) any later version (AGPL-3.0-or-later).