ironlab 0.6.0

MATLAB-flavoured Rust API for building, viewing and exporting scientific figures.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

//! 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`](AxesMut::plot),
//! [`scatter`](AxesMut::scatter), [`contour`](AxesMut::contour),
//! [`quiver`](AxesMut::quiver), [`surf`](AxesMut::surf), [`image`](AxesMut::image)
//! and their relatives (MATLAB's `imagesc` is [`mapped_image`](AxesMut::mapped_image)).
//! Each plotting function returns a handle whose chained setters change the properties
//! of the new plot, in the way that MATLAB 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 PDF.
//!
//! Every call writes directly to the retained figure IR of the [`ir`] crate, which is
//! the single source of truth for what is drawn. 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 the figure is exported or shown.
//!
//! # Example
//!
//! ```
//! 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());
//! ```
//!
//! Showing and exporting a figure:
//!
//! ```no_run
//! use ironlab::prelude::*;
//!
//! # fn main() -> Result<(), ironlab::Error> {
//! let x = linspace(-1.5, 1.5, 61);
//! let y = linspace(-1.5, 1.5, 61);
//! let z = Matrix::from_fn(y.len(), x.len(), |row, col| x[col].powi(2) - y[row].powi(2));
//!
//! let mut fig = Figure::new().title("A saddle");
//! fig.axes(0, 0).surf(&x, &y, &z);
//! fig.export_pdf("saddle.pdf")?;
//! fig.show()?;
//! # Ok(())
//! # }
//! ```

mod artists;
mod axes;
mod color;
mod error;
mod figure;
mod grid;
mod matrix;
mod pixels;

pub use ironlab_ir as ir;

pub use artists::{
    ContourMut, ImageMut, IndexedImageMut, LineMut, MappedImageMut, QuiverMut, ScatterMut,
    SurfaceMut,
};
pub use axes::AxesMut;
pub use color::IntoColorSpec;
pub use error::Error;
pub use figure::Figure;
pub use grid::GridCoords;
pub use matrix::{Matrix, linspace, logspace, meshgrid};
pub use pixels::{ByteMatrix, ImageValues, Pixels};

/// The coordinate dimension of an axes, used to link axes and set limits.
pub use ironlab_ir::Dimension as Dim;

/// The shape of the markers drawn at data points.
pub use ironlab_ir::MarkerShape as Marker;

/// The dash pattern of a line.
pub use ironlab_ir::DashStyle as Dash;

/// The name of a colormap.
pub use ironlab_ir::ColormapName as Colormap;

/// The plane of an axes in which an image lies, with its offset along the third axis.
pub use ironlab_ir::ImagePlane;

/// What a colour-indexed or colour-mapped image draws for a pixel it cannot colour.
pub use ironlab_ir::OutOfRange;

pub use ironlab_ir::{
    Color, ColorSpec, Interpreter, LegendLocation, NodeId, Parameter, Scale, Text, ValidationReport,
};

/// How a dense artist is drawn when the figure is exported, and at what resolution it is
/// rasterised. See [`Figure::export_pdf_with`].
pub use ironlab_pdf::{RasterOptions, RasterPolicy};

/// The types and functions needed to build figures, for glob import.
///
/// ```
/// use ironlab::prelude::*;
/// ```
pub mod prelude {
    pub use crate::AxesMut;
    pub use crate::{
        ByteMatrix, Color, ColorSpec, Colormap, ContourMut, Dash, Dim, Error, Figure, GridCoords,
        ImageMut, ImagePlane, ImageValues, IndexedImageMut, IntoColorSpec, LegendLocation, LineMut,
        MappedImageMut, Marker, Matrix, NodeId, OutOfRange, Parameter, Pixels, QuiverMut,
        RasterOptions, RasterPolicy, Scale, ScatterMut, SurfaceMut, Text, linspace, logspace,
        meshgrid,
    };
}