plotters-ternary 0.1.0

Publication-quality ternary diagrams, contours, filled bands, and scalar maps for Plotters
Documentation
# Scientific marker kernel

## Purpose and boundary

The scientific-marker extension adds portable marker geometry beneath
`TernaryPointSeries`; it does not change ternary coordinates, interpolation,
viewports, or Plotters' legend system. The crate keeps using
`TernaryChart::draw_series`, which returns Plotters' native `SeriesAnno`, and
callers configure legends through the normal `configure_series_labels` path.

The core marker model is independent of a concrete Plotters backend until a
`MarkerElement<Coord>` is drawn. It uses Plotters colour and `ShapeStyle` types
for interoperability, but has no bitmap-quality or `image` dependency.

## Public model

```rust
use plotters::prelude::*;
use plotters_ternary::{MarkerShape, MarkerStyle, TernaryPoint, TernaryPointSeries};

let style = MarkerStyle::solid(
    MarkerShape::Diamond,
    RGBColor(225, 95, 50),
    BLACK.stroke_width(2),
)?;
let points = TernaryPointSeries::new([TernaryPoint::new(0.2, 0.3, 0.5)])
    .size(9)
    .marker_style(style);
# Ok::<(), plotters_ternary::MarkerError>(())
```

`MarkerGeometry` stores a validated `MarkerShape` and optional extra rotation.
`MarkerStyle` contains a geometry, a `MarkerFill`, and one optional outer
`ShapeStyle`. `MarkerFill` is `Empty`, `Solid { color }`, or `Partitioned`.
`MarkerSlice` stores finite positive relative weights and an `RGBAColor`.
Constructor colours implement Plotters' `Color` trait and are converted to
RGBA immediately.

The compatibility path remains unchanged:

```rust
# use plotters::prelude::*;
# use plotters_ternary::{MarkerShape, TernaryPoint, TernaryPointSeries};
let points = TernaryPointSeries::new([TernaryPoint::new(0.2, 0.3, 0.5)])
    .size(6)
    .style(RED.filled())
    .marker(MarkerShape::Circle);
```

`MarkerShape::Triangle` is retained as the historical spelling for
`TriangleUp`. `Plus` is the orthogonal `+`; `Cross` is the diagonal `×`.
Fillable shapes are circle/ellipse, square/rectangle/rounded square, diamond,
the four triangle directions, regular polygons, and stars. `Plus`, `Cross`,
and `Asterisk` are intentionally stroke-only and reject non-empty fills.
Convenience constructors cover pentagons, hexagons, octagons, and 4/5/6/8
point stars.

## Centre and tessellation contract

Every outline is generated in local floating-point coordinates and normalized
to a centred `[-1, 1] × [-1, 1]` bounding box. A `MarkerElement` anchor is
always that visual centre, both in a plot and in a legend. The requested size
is the backend-pixel half-extent. This prevents circles, triangles, stars, and
stroke-only symbols from shifting when mixed in a native Plotters legend.

Circles and ellipses use a fixed 32-vertex closed outline. The fixed bounded
policy means the exact same logical polygon topology reaches PNG and SVG;
bitmap supersampling only changes the rasterisation of that geometry.

## Fills and partitions

`MarkerPartition::Radial` accepts one to four slices. Angles begin at
`start_angle_deg`; `0°` points right and positive angles rotate
counter-clockwise in ordinary mathematical space (visually toward the top in
backend pixel coordinates). `SweepDirection` selects positive or negative
sweep. Slices follow source-vector order and their positive finite weights are
normalized internally.

`Horizontal`, `Vertical`, `DiagonalForward`, and `DiagonalBackward` require
exactly two slices. Their first slice is respectively upper, left, the
upper/right side of `/`, and the upper/left side of `\`. `Quadrants` requires
four slices in upper-right, lower-right, lower-left, upper-left order before
the supplied counter-clockwise rotation.

Radial fills are built by intersecting wedge half-planes with a fan of the
outer marker polygon. Linear and quadrant fills use the same reusable convex
half-plane clipping. Concave stars are decomposed into centre-to-outline fans,
so each partition remains inside the visible star. Draw order is always:

```text
partition fills -> optional divider segments -> one common outer edge
```

The outer edge is never redrawn per partition. Empty markers require an edge;
solid and partitioned markers may deliberately omit one. `MarkerStyle::fact_sage`
creates the common same-colour fill-and-edge form.

## Per-point phase combinations

A uniform `marker_style` is the common case. For experiment-specific phase
mixtures, `point_style_provider` receives `(original_source_index,
normalized_abc_composition)` and returns a complete `MarkerStyle`:

```rust
# use plotters::prelude::*;
# use plotters_ternary::{MarkerShape, MarkerStyle, TernaryPoint, TernaryPointSeries};
let points = TernaryPointSeries::new([
    TernaryPoint::new(0.2, 0.3, 0.5),
    TernaryPoint::new(0.3, 0.4, 0.3),
])
.marker_style(MarkerStyle::solid(MarkerShape::Circle, RED, BLACK)?)
.point_style_provider(|index, _composition| {
    if index == 0 {
        MarkerStyle::solid(MarkerShape::Diamond, BLUE, BLACK).unwrap()
    } else {
        MarkerStyle::solid(MarkerShape::Circle, GREEN, BLACK).unwrap()
    }
});
# Ok::<(), plotters_ternary::MarkerError>(())
```

The callback is stored directly in the series generic parameter rather than a
boxed `'static` trait object. It is evaluated during drawing, preserves source
indexes after centre clipping, and does not require a separate Plotters series
for every phase combination.

## Legend, PNG and SVG behaviour

`MarkerElement<(i32, i32)>` is a concrete ordinary Plotters element, so a
legend can use it directly in `SeriesAnno::legend`. The examples adapt the
callback anchor through one shared fixed-width symbol slot: all line and
marker symbols use the same centre and label start. This remains example
layout infrastructure, not a ternary-specific legend API.

The example PNG helper's optional supersampled geometry pass calls
`MarkerStyle::scaled` and scales marker half-size, edge widths, and dividers.
Its final-resolution text pass is unchanged. SVG receives the same unscaled
local polygon geometry in the vector `ternary-geometry` group and never
contains raster marker images.

## Validation and deferred work

Regular polygons, stars, and asterisks accept 3 through 16 sides/points/arms.
Stars require `0 < inner_ratio < 1`; ellipses and rectangles require a finite
positive aspect ratio; rounded-square corner ratio is finite in `0..=0.5`;
all rotations are finite. Partitions reject empty input, more than four
slices, incorrect fixed partition counts, and non-finite or non-positive
weights. `MarkerError` is nested by `SeriesError::Marker` with an optional
source index.

Marker-bounds clipping remains deferred: `MarkerClipMode::Centre` clips only
the anchor, while `None` is the documented unrestricted escape hatch. General
phase-region polygons, annotations, and contour work remain separate future
milestones.

## Permanent gallery

`examples/custom_markers.rs` writes:

- `examples/output/png/custom_markers.png`;
- `examples/output/svg/custom_markers.svg`.

It includes all built-in scientific shape families, empty and solid forms,
independent fill/edge colours, all supported split modes, equal and weighted
radial sectors, four experimental phase combinations selected through the
per-point style callback, and native Plotters legend rows.