Crate path_kit 

path-kit

基于 Skia PathOps 和 PathKit 的 Rust 路径运算库，提供 safe 的 API 封装。 A Rust path operations library based on Skia PathOps and PathKit with safe API wrappers.

功能 / Features

• 路径构建：Path、PathBuilder；线段、二次/三次贝塞尔、矩形、椭圆、圆、圆角矩形、RRect Path construction: Path, PathBuilder; lines, quad/cubic bezier, rect, oval, circle, round rect, RRect
• 路径布尔运算：并集、交集、差集、异或 Path boolean operations: union, intersect, difference, xor
• 路径简化、包围盒：simplify, path.tight_bounds, pathops_tight_bounds Path simplification and tight bounds computation
• 路径变换：Path::transform、Path::transformed、Matrix（SkMatrix） Affine/perspective transform via Path::transform, Path::transformed, Matrix
• 路径迭代：按动词遍历 Move/Line/Quad/Cubic/Close Path iteration over verbs and points
• 描边：将路径转为描边轮廓 Stroke: convert path to stroked outline

线程安全 / Thread safety

当前未保证 Send / Sync，请勿跨线程共享 Path、Matrix、RRect、StrokeRec、Paint 等封装 C++ 的类型。 Send / Sync are not guaranteed; do not share Path, Matrix, RRect, StrokeRec, Paint, or other C++-backed handles across threads.

文档 / Documentation

• docs.rs/path-kit：托管 API 参考与 rustdoc。 Hosted API reference and rustdoc.
• CHANGELOG.md：版本变更记录。 Version history in the repo.
• 本地：cargo doc --open。 Locally: run cargo doc --open.

类型概览 / Types

类型	说明 · Description
Path	路径 · Path
PathBuilder	路径构建器（SkPathBuilder，snapshot / detach）· Path builder (SkPathBuilder, snapshot / detach)
Rect	矩形 · Axis-aligned rectangle
RRect	圆角矩形（四角独立半径）· Rounded rect (per-corner radii)
Point	二维点 · 2D point
Matrix / ScaleToFit / matrix_type / coeff	3×3 矩阵（SkMatrix）、缩放适配、类型位、系数下标 · 3×3 transform, scale-to-fit, type bits, coeff indices
Direction	绘制方向 Cw/Ccw · Fill direction clockwise / counter-clockwise
RectCorner	矩形起始角 · Starting corner when adding a rect
PathOp	布尔运算类型 · Path boolean operation kind
PathFillType	填充规则（winding / even-odd / inverse 等）· Fill rule variants
PathVerb / PathVerbItem	路径动词枚举 / 迭代项 · Path verb enum / iterator items
PathMeasure	长度、位置与切线、分段提取 · Length, pos/tan, segment extraction
OpBuilder	批量布尔运算（SkOpBuilder）· Batch boolean ops (SkOpBuilder)
path_op / simplify / pathops_tight_bounds	两路径布尔、简化、pathops 紧包围盒 · Binary op, simplify, pathops tight bounds
StrokeRec / StrokeStyle	描边参数与样式快照 · Stroke parameters and style snapshot
StrokeCap	线端 Butt/Round/Square · Stroke end cap
StrokeJoin	转角 Miter/Round/Bevel · Stroke corner join
Paint	绘图参数（Style、Stroke 等）· Paint / stroke parameters (SkPaint)
PaintStyle	填充/描边样式 · Fill / stroke / stroke-and-fill
CornerPathEffect / DashPathEffect	圆角 / 虚线效果 · Corner / dash path effects
RRectType	圆角矩形类型（SkRRect::Type）· RRect classification

示例 / Examples

路径布尔运算 / Path boolean ops

use path_kit::{Path, Rect, Direction, RectCorner, PathOp, path_op, OpBuilder};

let mut path1 = Path::new();
path1.add_rect(&Rect::new(0.0, 0.0, 100.0, 100.0), Direction::Cw, RectCorner::UpperLeft);

let mut path2 = Path::new();
path2.add_rect(&Rect::new(50.0, 50.0, 150.0, 150.0), Direction::Cw, RectCorner::UpperLeft);

let union = path_op(&path1, &path2, PathOp::Union).unwrap();

// 批量运算 / Batch operations (use add_ref to avoid clone when reusing paths)
let result = OpBuilder::new()
    .add_ref(&path1, PathOp::Union)
    .add_ref(&path2, PathOp::Union)
    .resolve()
    .unwrap();

矩阵与路径变换 / Matrix and path transform

use path_kit::{Matrix, Path};

let mut path = Path::new();
path.move_to(0.0, 0.0).line_to(100.0, 0.0).line_to(100.0, 100.0).close();

let mut m = Matrix::identity();
m.pre_translate(10.0, 5.0).pre_scale(2.0, 2.0);
path.transform(&m);

// Or keep the original: `let out = path.transformed(&m);`

PathBuilder · 增量构建 / Incremental path build

use path_kit::PathBuilder;

let mut b = PathBuilder::new();
b.move_to(0.0, 0.0).line_to(50.0, 40.0).line_to(0.0, 40.0).close();
let _copy = b.snapshot(); // builder unchanged
let _owned = b.detach(); // builder reset; geometry moved into `Path`

圆角矩形 RRect / Rounded rect with per-corner radii

use path_kit::{Path, Rect, RRect, Radii, Direction, RectCorner};

// 统一圆角 / Uniform radii
let rr = RRect::from_rect_xy(&Rect::new(0.0, 0.0, 100.0, 50.0), 10.0, 10.0);
let mut path = Path::new();
path.add_rrect(&rr, Direction::Cw);

// 四角独立半径 / Per-corner radii
let radii = [
    Radii { x: 10.0, y: 10.0 },
    Radii { x: 20.0, y: 10.0 },
    Radii { x: 10.0, y: 20.0 },
    Radii { x: 5.0, y: 5.0 },
];
let rr2 = RRect::from_rect_radii(&Rect::new(0.0, 0.0, 80.0, 60.0), &radii);
path.add_rrect(&rr2, Direction::Ccw);

路径迭代 / Path iteration

use path_kit::{Path, PathVerbItem};

let mut path = Path::new();
path.move_to(0.0, 0.0).line_to(100.0, 0.0).line_to(100.0, 100.0).close();

for item in path.iter(false) {
    match item {
        PathVerbItem::Move(p) => println!("Move to {:?}", p),
        PathVerbItem::Line(from, to) => println!("Line {:?} -> {:?}", from, to),
        PathVerbItem::Quad(c, to) => println!("Quad {:?} -> {:?}", c, to),
        PathVerbItem::Cubic(c1, c2, to) => println!("Cubic -> {:?}", to),
        PathVerbItem::Close => println!("Close"),
        _ => {}
    }
}

描边 / Stroke

use path_kit::{Path, StrokeRec};

let rec = StrokeRec::new_stroke(4.0, false);
let mut path = Path::new();
path.move_to(0.0, 0.0).line_to(100.0, 0.0);
let stroked = rec.apply_to_path(&path).unwrap();

Paint · 描边转填充轮廓 / Stroke to fill outline (get_fill_path)

use path_kit::{Paint, PaintStyle, Path};

let mut paint = Paint::new();
paint.set_style(PaintStyle::Stroke);
paint.set_stroke_width(4.0);
let mut path = Path::new();
path.move_to(0.0, 0.0).line_to(100.0, 0.0);
let stroked_as_fill = paint.get_fill_path(&path).unwrap();
assert!(stroked_as_fill.count_verbs() >= path.count_verbs());

路径测量 / Path measure

use path_kit::{Path, PathMeasure};

let mut path = Path::new();
path.move_to(0.0, 0.0).line_to(100.0, 0.0);
let mut measure = PathMeasure::from_path(&path, false, 1.0);
let len = measure.length();           // ~100
let (pos, tan) = measure.pos_tan(50.0).unwrap();  // position & tangent at midpoint
let mut segment = Path::new();
measure.get_segment(25.0, 75.0, &mut segment, true);  // extract sub-path

路径简化与包围盒 / Simplify and bounds

use path_kit::{Path, simplify, pathops_tight_bounds};

let mut path = Path::new();
path.move_to(0.0, 0.0)
    .line_to(100.0, 0.0)
    .line_to(100.0, 100.0)
    .line_to(50.0, 50.0)
    .line_to(0.0, 100.0)
    .close();

let simplified = simplify(&path).unwrap();
let bounds = pathops_tight_bounds(&path).unwrap();  // or path.tight_bounds() for infallible

Modules

coeff

SkMatrix 九个系数在 Matrix::mat 中的下标（kMScaleX … kMPersp2）。 Indices of the nine coeffs in Matrix::mat (kMScaleX …).

matrix_type

SkMatrix::TypeMask 中与类别相关的公开位，可与 | 组合；Matrix::get_type 的返回值可与此做位运算。 Public SkMatrix::TypeMask bits; combine with |; use with Matrix::get_type.

Structs

CornerPathEffect

圆角路径效果，将尖角变为圆角。 Corner path effect - rounds sharp corners.

DashPathEffect

虚线路径效果，将路径描边转为虚线。 Dash path effect for stroked paths (on/off intervals).

Direction

路径方向，与 pk::SkPathDirection 一致。 Path contour direction; matches pk::SkPathDirection.

Matrix

3×3 变换矩阵（列向量形式 p' = M * p），系数布局见模块说明。 3×3 transform (column vectors p' = M * p); layout described at module level.

OpBuilder

路径操作构建器，用于批量执行路径布尔运算。 Path operation builder, optimized for unioning/combining many paths.

Paint

绘图参数，控制路径的填充/描边及描边样式。 Paint - controls fill/stroke style and stroke parameters for path rendering.

PaintStyle

绘图样式，与 pk::SkPaint::Style 一致。 Paint style; matches pk::SkPaint::Style.

Path

路径的 safe 封装，底层为 C++ pk::SkPath。 Safe wrapper around pk::SkPath.

PathBuilder

可增量构建路径；完成后用 Self::snapshot 或 Self::detach 得到 Path。 Incremental path construction; finish with Self::snapshot or Self::detach into a Path.

PathFillType

填充规则低位，与 pk::SkPathFillType 一致。 Fill rule; matches pk::SkPathFillType.

PathIter

路径迭代器，按动词顺序遍历路径。Path iterator over verbs and points.

PathMeasure

路径测量器，用于获取路径长度、沿路径的位置和切线。 PathMeasure - measures path length and samples position/tangent along path.

PathOp

路径布尔运算，与 pk::SkPathOp 取值一致。 Path boolean op; matches pk::SkPathOp.

PathVerb

路径动词，与 pk::SkPath::Verb 一致。 Path verb, matches pk::SkPath::Verb. 路径动词，与 pk::SkPath::Verb 一致。 Path verb; matches pk::SkPath::Verb.

Point

二维点。A 2D point with x and y coordinates.

RRect

圆角矩形，支持四角独立半径。 Rounded rectangle with per-corner radii (each corner can have different x/y).

RRectType

圆角矩形分类，与 pk::SkRRect::Type 一致。 RRect specialization; matches pk::SkRRect::Type.

Radii

单角椭圆半径 (x, y)，与 SkRRect 每角 radii 一致。 Per-corner elliptical radii (x, y), matching SkRRect corner radii.

Rect

矩形，由 (left, top, right, bottom) 定义。 Rectangle defined by (left, top, right, bottom) coordinates.

RectCorner

矩形起始角，与 SkPath::addRect 角索引一致。 Rect start corner index for addRect.

StrokeCap

线端样式，与 pk::SkPaint::Cap / SkStrokeRec 一致。 Stroke cap; matches pk::SkPaint::Cap.

StrokeJoin

转角连接，与 pk::SkPaint::Join / SkStrokeRec 一致。 Stroke join; matches pk::SkPaint::Join.

StrokeRec

描边参数，描述如何将路径转为描边轮廓。 Stroke parameters - describes how to expand a path to a stroke outline.

Enums

PathVerbItem

单步迭代结果，含动词与关联点。Single iteration result with verb and points.

ScaleToFit

源矩形映射到目标矩形时的缩放/对齐策略，对应 SkMatrix::ScaleToFit。 Scale/align policy when mapping a source rect to a destination rect (SkMatrix::ScaleToFit).

StrokeStyle

描边样式快照，由 SkStrokeRec::getStyle 与宽度组合而成。 Stroke style snapshot from SkStrokeRec::getStyle plus width.

Functions

path_op

对两个路径执行布尔运算。Performs boolean operation on two paths.

pathops_tight_bounds

计算路径的紧密包围盒（pathops 实现）。Computes tight bounds using pathops algorithm.

simplify

简化路径，处理自相交等。Simplifies path (resolves self-intersections, etc.).