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 *;
use *;
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 |
|---|---|---|
![]() |
![]() |
![]() |
Contours and labels
| Coloured contours | Tangent labels | Curved labels |
|---|---|---|
![]() |
![]() |
![]() |
Filled bands and scalar maps
| Filled bands | Scalar map | Transparent hole over a map |
|---|---|---|
![]() |
![]() |
![]() |
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
.build;
mesh.draw_background?; // minor and major grids
chart.draw_series?;
chart.draw_series?;
mesh.draw_foreground?; // joined physical boundary and ticks
mesh.draw_text?; // 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.








