Struct Figure 

pub struct Figure { /* private fields */ }

A figure is the top-level container for one or more axes (subplots).

The figure owns all axes, holds the overall dimensions, an optional super-title, and the visual theme. It implements the rendering pipeline described in ARCHITECTURE.md:

1. Fill figure background.
2. Draw suptitle if set.
3. Compute subplot layout rectangles.
4. For each axes: delegate rendering with its allocated rectangle and theme.

Ownership model (ADR-003)

Figure owns Vec<Axes> directly – no Rc, no RefCell. add_subplot returns &mut Axes, and the borrow checker enforces single-axes mutation at compile time.

Examples

use plotkit_core::figure::Figure;

let mut fig = Figure::new();
let ax = fig.add_subplot(1, 1, 1);
// ax.plot(...)?;

Implementations

impl Figure

pub fn new() -> Figure

Creates a new figure with default dimensions (800 x 600 pixels).

pub fn with_size(width: u32, height: u32) -> Figure

Creates a new figure with the specified dimensions in pixels.

pub fn width(&self) -> u32

Returns the figure width in pixels.

pub fn height(&self) -> u32

Returns the figure height in pixels.

pub fn add_subplot( &mut self, nrows: usize, ncols: usize, index: usize, ) -> &mut Axes

Adds a subplot and returns a mutable reference to it.

Uses 1-based indexing in matplotlib style: (nrows, ncols, index). The index counts across rows first (row-major), starting at 1.

If a subplot already exists at the given index, the existing axes is returned without creating a duplicate. Otherwise a new Axes is created, appended to the figure’s axes list, and returned.

Panics

Panics if nrows, ncols, or index is zero, or if index exceeds nrows * ncols.

Examples

use plotkit_core::figure::Figure;

let mut fig = Figure::new();
let ax = fig.add_subplot(2, 2, 1); // top-left of a 2x2 grid

pub fn suptitle(&mut self, title: &str) -> &mut Figure

Sets the overall figure title (super-title), displayed above all subplots.

Returns &mut Self for builder-style chaining.

pub fn set_theme(&mut self, theme: Theme) -> &mut Figure

Sets the visual theme for the entire figure.

The theme is inherited by all axes during rendering unless an individual axes has its own override.

Returns &mut Self for builder-style chaining.

pub fn theme(&self) -> &Theme

Returns a reference to the figure’s theme.

pub fn axes_mut(&mut self, index: usize) -> Option<&mut Axes>

Returns mutable access to the axes at index (0-based).

Returns None if index is out of bounds.

pub fn axes(&self, index: usize) -> Option<&Axes>

Returns a shared reference to the axes at index (0-based).

Returns None if index is out of bounds.

pub fn num_axes(&self) -> usize

Returns the number of axes (subplots) in this figure.

pub fn subplots(nrows: usize, ncols: usize) -> Figure

Creates a new figure with an nrows × ncols subplot grid.

Axes are added in row-major order (index 0 = top-left). Access them via fig.axes_mut(index) where index goes from 0 to nrows*ncols - 1.

Panics

Panics if nrows or ncols is zero.

pub fn subplots_with_size( nrows: usize, ncols: usize, width: u32, height: u32, ) -> Figure

Creates a new figure with an nrows × ncols subplot grid and custom size.

Panics

Panics if nrows or ncols is zero.

pub fn axes_grid( &mut self, row: usize, col: usize, ncols: usize, ) -> Option<&mut Axes>

2D indexing into the subplot grid.

Returns axes_mut(row * ncols + col), or None if out of bounds.

pub fn twinx(&mut self, parent_index: usize) -> &mut Axes

Creates a twin axes that shares the x-axis of the axes at parent_index but has an independent y-axis drawn on the right side.

Panics

Panics if parent_index is out of bounds or if the parent already has a twin.

pub fn twiny(&mut self, parent_index: usize) -> &mut Axes

Creates a twin axes that shares the y-axis of the axes at parent_index but has an independent x-axis drawn on the top side.

Panics

Panics if parent_index is out of bounds or if the parent already has a twin.

pub fn twin_of(&self, parent_index: usize) -> Option<usize>

Returns the twin axes index for a given parent axes index, if one exists.

pub fn render(&self, renderer: &mut impl Renderer)

Renders the figure using the given renderer.

This is the core rendering pipeline (per ARCHITECTURE.md):

1. Fill figure background with the theme’s figure_background color.
2. Draw suptitle if one has been set.
3. Compute the subplot grid layout, producing one Rect per axes.
4. For each axes, delegate to Axes::render with its assigned rectangle and the figure theme.

pub fn render_to<R>(&self, renderer: R) -> Vec<u8>

where R: Renderer,

Renders the figure using the given renderer and returns the encoded output bytes (PNG, SVG, PDF, etc., depending on the renderer).

This convenience method calls render and then Renderer::finalize to produce the final byte output.

pub fn save_with<R>( &self, renderer: R, path: impl AsRef<Path>, ) -> Result<(), PlotError>

where R: Renderer,

Saves the figure to a file using the provided renderer.

The renderer determines the output format. The encoded bytes are written to path atomically via std::fs::write.

Trait Implementations

impl Debug for Figure

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Figure

fn default() -> Figure

Returns the “default value” for a type.

impl FigureExt for Figure

fn save(&self, path: impl AsRef<Path>) -> Result<()>

Saves the figure to a file. Format determined by extension.

fn to_png_bytes(&self) -> Result<Vec<u8>>

Renders to PNG bytes.

fn to_svg_string(&self) -> Result<String>

Renders to SVG string.