plotters-ternary 0.1.0

Publication-quality ternary diagrams, contours, filled bands, and scalar maps for Plotters
Documentation

plotters-ternary

plotters-ternary adds scientific ternary composition diagrams to Plotters. A ternary diagram represents three-component compositions (a, b, c) satisfying a + b + c = 1 as a triangle. It is useful for phase diagrams, alloy systems, geochemistry, compositional chemistry, and any measurement defined on a three-part mixture.

The crate provides ternary projection, publication-oriented axes and grids, invisible mathematical viewports, lines, points, scientific markers, polygons, annotations, regular-grid contours, filled bands, scalar maps, contour labels, colour bars, PNG output, and native-vector SVG.

Numerical data and rendering are separate

The companion ternary-contours crate computes final semantic contour paths and filled-band regions from regular scalar fields. plotters-ternary projects those coordinates, clips them only for display, and hands ordinary Plotters elements to the selected backend. Numerical results remain independent of output dimensions, viewport choice, styles, legends, and PNG supersampling.

The same chart continues to use ordinary Plotters captions, styles, SeriesAnno, legends, and drawing backends.

Build a ternary chart

use plotters::prelude::*;
use plotters_ternary::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = BitMapBackend::new("ternary.png", (1000, 800)).into_drawing_area();
    root.fill(&WHITE)?;

    let mut chart = TernaryChartBuilder::on(&root)
        .caption("Three-component measurements", ("sans-serif", 32))
        .margin(60)
        .build()?;

    let mesh = chart.configure_mesh()
        .corner_a_name("A")
        .corner_b_name("B")
        .corner_c_name("C")
        .build();

    mesh.draw_background(&mut chart)?;
    chart.draw_series(TernaryLineSeries::new(
        [
            TernaryPoint::new(0.70, 0.20, 0.10),
            TernaryPoint::new(0.25, 0.50, 0.25),
        ],
        BLUE.stroke_width(2),
    ))?
    .label("Measured path")
    .legend(|(x, y)| PathElement::new([(x, y), (x + 20, y)], BLUE.stroke_width(2)));

    mesh.draw_foreground(&mut chart)?;
    mesh.draw_text(&mut chart)?;
    chart.configure_series_labels().draw()?;
    root.present()?;
    Ok(())
}

A TernaryViewport can crop a logical part of the triangle without becoming a Cartesian frame. Lines, points, polygons, annotations, and contour paths are mathematically clipped before Plotters draws them.

Add scalar data

Start with a RegularTernaryScalarField, then choose the representation that matches the scientific question.

Isolines

TernaryContourSeries draws selected scalar values as paths. Linear contours are the robust, piecewise-affine baseline. The optional cubic-alpha feature adds edge-derived cubic-alpha contours when smoother edge behaviour is useful. Use per-level styles, ordinary Plotters legends, or a ContourColorBar for dense keys.

Filled bands

TernaryContourBandSeries draws discrete intervals between ordered scalar breaks. Their geometry is exact for the piecewise-linear field. Bands can be disconnected and contain transparent holes that reveal the layer below. They are useful with a small number of scientifically meaningful intervals. Cubic-alpha filled bands are intentionally unavailable.

Scalar maps

TernaryScalarMapSeries covers the domain with colour. It evaluates the piecewise-linear field exactly, then approximates a smooth-looking gradient by flat-coloured microtriangles. More resolution reduces faceting but increases SVG primitive count and file size. It is not a rasterised SVG or a claim of continuous backend colour interpolation.

Visual goal API
Points or paths TernaryPointSeries / TernaryLineSeries
Selected scalar levels TernaryContourSeries
Discrete scalar intervals TernaryContourBandSeries
Continuous-looking colour field TernaryScalarMapSeries
Labels following contours ContourLabelConfig
Dense numerical key ContourColorBar

Contour labels and layer order

Contour labels are rendering-time placement decisions: they never change numerical contour coordinates. Tangent mode rotates one label to the local path direction. Curved mode positions characters along arc length. Repeated and manual placements are available, and placement checks endpoint clearance, curvature, viewport clearance, and collisions. Curved labels use per-character layout, not full text shaping.

A useful layer order is:

scalar map or filled bands
    -> mesh, if desired
    -> isolines
    -> contour labels
    -> annotations
    -> colour bars and legends

For publication output, SVG retains vector paths and searchable text. PNG examples use optional geometry-only supersampling; it is an output-quality technique, not numerical refinement.

Gallery

Basic charts, axes, and markers

Full chart Axes Scientific markers
Full triangle Custom axes Custom markers

Contours and labels

Coloured contours Tangent labels Curved labels
Contour colour bar Tangent labels Curved labels

Filled bands and scalar maps

Filled bands Scalar map Transparent hole over a map
Filled bands Scalar map Layered band hole

SVG counterparts live under examples/output/svg/.

Features

  • Default: charts, geometry, viewports, standard series, linear contours, filled bands, scalar maps, labels, legends, and SVG/PNG support.
  • cubic-alpha: cubic-alpha contour construction and adaptive topology. spline1d also supports the stable smooth-line series API.

Foreground triangle frame

The ternary simplex edge is the mathematical centreline of the visual frame. A boundary width is centred on that edge: half lies inside the simplex and half lies outside it. Lines, contours, polygon outlines, bands, and scalar-map microtriangles are still clipped to the mathematical domain; a foreground frame then masks their inner edge in the final rendering.

For publication figures with data, freeze the mesh and draw its phases around the series. This preserves Plotters-native annotations and legends while making the correct order explicit:

let mesh = chart.configure_mesh()
    .boundary_style(BLACK.stroke_width(8))
    .build();
mesh.draw_background(&mut chart)?; // minor and major grids
chart.draw_series(my_lines)?;
chart.draw_series(my_contours)?;
mesh.draw_foreground(&mut chart)?; // joined physical boundary and ticks
mesh.draw_text(&mut chart)?;       // labels at final text resolution

A complete triangle frame is emitted as deterministic filled miter-limited boundary strips, not as three independently round-capped strokes. In a cropped viewport only visible physical simplex-edge fragments are drawn; artificial rectangular viewport sides remain invisible and crop cuts use butt ends. The PNG geometry pass uses the same order at the supersampled resolution, while SVG keeps the frame and data as vector geometry. Markers retain their existing centre-clipping policy. In the recommended workflow they are data geometry, so the foreground frame masks their inner edge.

Limits and trade-offs

  • No cubic-alpha isobands.
  • No irregular or scattered-data triangulation.
  • No N-component grids.
  • Scalar-map SVG size grows with microtriangle resolution.
  • Curved labels use per-character placement rather than full text shaping.
  • PNG supersampling affects rendered geometry only, not coordinates or data.

More detailed material is available in the architecture notes and the numerical knowledge base. Contributions are welcome; see CONTRIBUTING.md. The crate is dual licensed under MIT or Apache-2.0.