kurbo_se/lib.rs
1// Copyright 2026 the kurbo-se Authors
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3
4//! Stroke extensions for [kurbo]: stroke alignment (inside / center /
5//! outside), independent start and end caps, dash caps, and dashed aligned
6//! strokes. This is the feature set of Figma's stroke panel, produced as
7//! fill outlines on top of kurbo's public API.
8//!
9//! kurbo-se is not a fork. It depends on unmodified kurbo from crates.io
10//! and re-exports it as `kurbo_se::kurbo`, so the types are identical to
11//! the ones your renderer already consumes.
12//!
13//! # Output contract
14//!
15//! [`stroke_aligned`] returns a [`BezPath`](kurbo::BezPath) describing the
16//! stroke as a fill outline. Interpret it with the nonzero winding rule.
17//! The outline may self-overlap by design (inner joins, cusps, 180° turns);
18//! those overlaps cancel only under nonzero winding.
19//!
20//! # Conventions
21//!
22//! - Coordinates are Y-down, as in kurbo.
23//! - For a unit tangent `t̂`, the unit normal `n̂ = t̂.turn_90()` points to
24//! the right of the travel direction.
25//! - Positive signed area means clockwise winding in Y-down, matching
26//! [`kurbo::Shape::area`]. A positive-area subpath has its interior on
27//! the right of travel.
28//! - The stroke band at a path point `P` spans `[P − d_left·n̂, P + d_right·n̂]`
29//! with `d_left + d_right = width`. [`StrokeSide::Right`] means
30//! `(d_left, d_right) = (0, width)`: the left boundary is then the source
31//! path itself, exactly.
32//!
33//! # Alignment semantics
34//!
35//! For closed contours the aligned band is defined as a set, matching Figma
36//! (whose inside/outside strokes are a doubled centered stroke masked by
37//! the fill):
38//!
39//! ```text
40//! Inside(w) = { p ∈ F : dist(p, path) ≤ w }
41//! Outside(w) = { p ∉ F : dist(p, path) ≤ w }
42//! ```
43//!
44//! `F` is the filled region of the whole path under the nonzero rule.
45//! Centered strokes on closed simple contours follow the same model:
46//! `Center(w) = { p : dist(p, path) ≤ w/2 }`, built as the fill dilated by
47//! `w/2` minus the fill eroded by `w/2`.
48//!
49//! Two consequences:
50//!
51//! - An inside stroke never leaves the fill and an outside stroke never
52//! enters it, at any width. This includes dashed strokes: each dash is
53//! expanded and then masked by the fill.
54//! - A width beyond the local thickness saturates instead of folding over
55//! itself. The stroke fills the shape completely, as Figma renders it: a
56//! rectangle narrower than `2w`, a thin wedge, a small star, a circle
57//! stroked wider than its diameter.
58//!
59//! Per subpath kind:
60//!
61//! - Closed subpaths: `Inside` is the side of the filled region of the
62//! whole compound path. Holes stroke into the ring, not into the void.
63//! Winding direction of the input does not change what `Inside` means.
64//! Self-intersecting contours are split at their crossings, and each
65//! lobe resolves against the fill on its own.
66//! - Open subpaths: inside/outside is geometrically undefined there, so
67//! kurbo-se maps `Inside` to the right of travel and `Outside` to the
68//! left. Set [`StrokeStyle::side`] to pick a side explicitly. Open
69//! subpaths are banded independently of the closed contours' region
70//! construction: a nearby open subpath never prunes or masks a closed
71//! contour's band, and overlapping bands add under nonzero winding.
72//!
73//! # Quickstart
74//!
75//! ```
76//! use kurbo_se::{StrokeStyle, StrokeAlignment, stroke_aligned};
77//! use kurbo_se::kurbo::{Rect, Shape};
78//!
79//! let shape = Rect::new(0.0, 0.0, 100.0, 60.0);
80//! let style = StrokeStyle::new(8.0).with_alignment(StrokeAlignment::Inside);
81//! let outline = stroke_aligned(shape, &style, 0.1);
82//! // Fill `outline` with the nonzero rule. Inside alignment never escapes the shape:
83//! assert!(!outline.is_empty());
84//! assert!(shape.bounding_box().contains_rect(outline.bounding_box()));
85//! ```
86
87#![cfg_attr(not(feature = "std"), no_std)]
88#![cfg_attr(docsrs, feature(doc_cfg))]
89// From the Linebender lint set. These live here rather than in Cargo.toml's
90// [lints] table because they need cfg_attr or must not apply to tests.
91#![cfg_attr(not(test), warn(unused_crate_dependencies))]
92#![cfg_attr(target_pointer_width = "64", warn(clippy::trivially_copy_pass_by_ref))]
93#![warn(clippy::print_stdout, clippy::print_stderr)]
94
95#[cfg(not(any(feature = "std", feature = "libm")))]
96compile_error!("kurbo-se requires either the `std` or `libm` feature");
97
98// Suppress unused-crate warning when both std and libm are enabled.
99#[cfg(all(feature = "std", feature = "libm"))]
100use libm as _;
101
102extern crate alloc;
103
104pub use kurbo;
105
106mod broad;
107mod buckets;
108mod clip;
109mod ctx;
110mod dash;
111mod expand;
112mod math;
113mod normalize;
114mod orient;
115mod region;
116mod split;
117mod style;
118
119pub use ctx::{
120 AlignedStrokeCtx, StrokeAlignExt, SubpathInfo, analyze_subpaths, stroke_aligned,
121 stroke_aligned_with,
122};
123pub use style::{
124 DashStyle, StrokeAlignment, StrokeSide, StrokeStyle, miter_angle_to_limit, miter_limit_to_angle,
125};
126
127// Convenience re-exports of the kurbo types used in this crate's public API.
128pub use kurbo::{Cap, Dashes, Join};