IronLAB¶

IronLAB is a Rust library and application for building scientific figures, exploring them interactively then exporting them for publication.

IronLAB features:

• A desktop viewer. A fast, native application with figure browser (so you can find what you're looking for among hundreds of figures) and property editor (so you can edit what it looks like before exporting).

• Web embeds. Figures can be embedded live in a web page. Check out the gallery to see this in action!

• Publication-quality PDF export. A figure is exported as a PDF. That PDF is the exact size you need. It contains exactly what you're seeing (WYSIWYG). The fonts are the exact size you need. Figures, including all text and symbols, look identical wherever they're viewed. (Yes, figures can also be exported as pngs!).

• Embedded LaTeX mathematics. Any label, tick, or title may contain a LaTeX expression, which IronLAB typesets itself using the awesome latex-rust project: no TeX installation is needed to build, view, embed or export a figure.

• Smart vector/raster export. All exports contain entirely vector graphics - no more screenshots (finally!!!). If the contents get too large (complex surfaces or images could result in massive PDF files), individual objects are rasterised at 600dpi (retaining vectorised axes, labels and everything else).

• Language clients. (COMING SOON!) Write figures from a wide variety of languages like python, MATLAB, C++, julia and more. Reach out on github to request a client if it's not there yet, we'll build them only in response to demand.

At the core¶

IronLAB is built on a unified data model that describes the contents and arrangement of a figure. This is a tree of nodes (like the figure, its axes and their contents).

These nodes are strictly defined by Rust types. Other languages can read and write figures through .proto files generated from the types. Figures are held in binary form using Protocol Buffers (lowest memory, fastest), or as JSON (less efficient, but user-readable).

This yields us the following benefits: - Anyone (now or at any time in the future) can build or read an IronLAB figure, even without using IronLAB at all - it's a completely public, open data model - Every node has a stable identifier, and every property that affects the drawing is stored in the model, so a saved figure reopens exactly as it was built, whatever the platform. - Property changes may be recorded as a changelist, meaning it is possible to 'undo/redo' any manipulation of the view.

A minimal example¶

The IronLAB API takes inspriation from MATLAB, plotly, matplotlib and GNU/Octave plots. The equivalent functions page lists every plotting function beside its MATLAB, matplotlib and Plotly counterparts.

The following program plots two curves with LaTeX legend entries and axis labels, exports the figure to PDF and opens it in the viewer.

use ironlab::prelude::*;

fn main() -> Result<(), ironlab::Error> {
    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);

    fig.export_pdf("trigonometric.pdf")?;
    fig.show()
}

The getting started guide explains each step and every supported plot type.

Map of the documentation¶

• Guides explain how to use IronLAB.
  • Getting started covers building figures with the Rust API, saving and loading them, exporting PDF for LaTeX documents and PNG for slides and web pages, and opening the viewer.
  • Using the viewer describes the viewer's tools, gestures and keyboard shortcuts, and how to edit a figure live in its property editor.
  • Embedding figures in a web page explains how a publication or a site carries a live figure, with the bundle, the element, its API and its theming.
• Gallery shows every example figure live in the page, with the exact source code that produced it.
• Reference describes the system precisely.
  • Equivalent functions maps the plotting functions of MATLAB, matplotlib and Plotly to IronLAB's.
  • Figure schema explains every entity of the figure model, its Protocol Buffers and JSON encodings, and the rules for versioning it.
  • Architecture describes the crates, how a figure becomes pixels or a PDF page, and how text is resolved.
• Architecture decisions records the significant design decisions and the reasons for them.
• Background contains the discussion from which the design emerged.
• Conventions describe how the project is developed: branching, commits and versioning and pull requests. The contributing guide sets out how contributions are licensed.