Crate tumo_path

Expand description

A crate for vector path operations.

This crate provides a complete toolkit for working with vector paths, including path construction, transformation, manipulation, and rendering.

The crate’s design philosophy treats paths as data streams, where all operations are implemented as type transformations on these streams. For example, converting curves to straight lines is a transformation from Iterator<Item = PathCmd> to Iterator<Item = LinearCmd>. This approach enables flexible composition of operations - you can chain dash transformations, stroke operations, and linearization in any order, with the sequence determining the processing pipeline.

§Features

std: Enables the standard library for enhanced functionality
libm: Provides mathematical functions via the libm library

§Constructing Paths

Path construction is built around the PathCore trait, which serves as the fundamental interface for path building operations. The trait defines six essential methods:

current: Retrieves the current endpoint of the path
move_to: Moves to a specified point without drawing
line_to: Draws a straight line to the specified point
quadratic_to: Draws a quadratic Bézier curve to the specified point
cubic_to: Draws a cubic Bézier curve to the specified point
close: Closes the current path segment

Building upon PathCore, several extension traits provide enhanced functionality:

PathRelative: Enables relative path construction operations
PathExtend: Advanced curve operations including arcs and connections
PathGeometry: Basic geometric shapes like circles, ellipses, and rectangles
PathCanvas: Web Canvas-compatible methods such as arc and arcTo
PathSvg: SVG-compatible path operations including arc commands

Any type implementing PathCore automatically gains these extension traits, allowing for seamless path construction using the full feature set.

Additionally, SVG path format support is provided through the SvgCore trait, enabling parsing of SVG path data strings.

use tumo_path::*;

// Basic path construction
let mut path = Path::default();
path.move_to((10.0, 10.0));
path.line_to((50.0, 10.0));
path.cubic_to((80.0, 10.0), (80.0, 50.0), (50.0, 50.0));
path.close();

// Using geometric shapes
let mut path = Path::default();
path.add_rect((20.0, 20.0), 60.0, 60.0);     // Rectangle
path.add_circle((50.0, 50.0), 30.0);         // Circle
path.add_ellipse((70.0, 70.0), (20.0, 10.0)); // Ellipse
path.add_round_rect((10.0, 10.0), 80.0, 80.0, 20.0, 20.0);
path.add_pie((50.0, 50.0), (30.0, 30.0), Angle::ZERO, Angle::FRAC_PI_2);

// Parse SVG path string
let mut path = Path::default();
path.svg_path_str("M10,10 L50,10 L50,50 Z").unwrap();

§Manipulating Paths

Path manipulation is centered around iterator-based operations. The crate defines two primary path command structures:

PathCmd: Complete path commands supporting all operations including lines, quadratic and cubic Bézier curves, and path closure
LinearCmd: Simplified commands containing only straight lines and closure operations

The crate provides iterator extensions for advanced operations:

PathCmdFlow: Extends Iterator<Item = PathCmd> with curve operations including linearization, dashing, and rasterization
LinearCmdFlow: Extends Iterator<Item = LinearCmd> primarily for tessellation operations

Conversion between command types is straightforward: Iterator<Item = PathCmd> can be converted to Iterator<Item = LinearCmd> using the linearize method.

use tumo_path::*;

// Create a path with curves
let mut path = Path::default();
path.add_circle((50.0, 50.0), 40.0);

// Linearize curves to straight lines
path.iter().linearize(0.1);

// Apply transformations
path.iter()
    .translate(10.0, 10.0)
    .rotate(Angle::FRAC_PI_2)
    .scale(2.0, 2.0);

// Apply dash pattern
let dash = Dash::new(&[5.0, 3.0], 0.0).unwrap();
path.iter().dash(dash, 0.1);

// Compute bounding box
let mut bounds = Bounds::default();
path.iter().bounds(&mut bounds);

// Calculate path length
path.iter().length();

// Convert to SVG string
path.iter().svgstr();

§Rasterizing Paths

Paths can be converted to grayscale images through the rasterization process. First rasterize the path into a VecStorage container, then render to a Mask bitmap using fill rules (non-zero or even-odd).

To stroke a path, first apply the stroke method on PathCmdFlow followed by the rastive method, then render the storage to a mask.

use tumo_path::*;

// Create a path
let mut path = Path::default();
path.add_circle((50.0, 50.0), 40.0);

// Rasterize to storage
let mut storage = VecStorage::new((0, 0).into(), (100, 100).into());
path.iter().rastive(&mut storage);

// Render to mask using non-zero fill rule
let mut mask = Mask::new(0, 0, 100, 100);
storage.non_zero(&mut mask);

// Stroke and rasterize
let mut stroker = Stroker::new(Stroke::default().thickness(5.0));
path.iter().stroke(&mut stroker).rastive(&mut storage);
storage.even_odd(&mut mask);

§Tessellating Paths

The crate implements two distinct tessellation algorithms:

Traper: Utilizes scanline algorithms optimized for fill operations
Striper: Constructs triangle strips along paths, ideal for stroke operations

The Mesh type provides a convenient container for storing tessellation results.

use tumo_path::*;

// Create a path
let mut path = Path::default();
path.add_circle((50.0, 50.0), 40.0);

// Fill using Non-Zero rule
let mut mesh = Mesh::default();
path.iter()
    .linearize(0.1)
    .iter()
    .non_zero(&mut Traper::default(), &mut mesh);

// Fill using Even-Odd rule
let mut mesh = Mesh::default();
path.iter()
    .linearize(0.1)
    .iter()
    .even_odd(&mut Traper::default(), &mut mesh);

§Complete Example

use tumo_path::*;

fn main() {
    // Create a path with multiple shapes
    let mut path = Path::default();
    path.add_rect((10.0, 10.0), 80.0, 80.0);
    path.add_circle((50.0, 50.0), 30.0);

    // Rasterize the path
    let mut storage = VecStorage::new((0, 0).into(), (120, 120).into());
    path.iter()
        .rotate(Angle::FRAC_PI_2)
        .translate(10.0, 10.0)
        .rastive(&mut storage);

    // Render to mask
    let mut mask = Mask::new(0, 0, 120, 120);
    storage.non_zero(&mut mask);

    // Convert to SVG
    let svg = path.iter().svgstr();

    // Tessellate for GPU rendering
    let mut mesh = Mesh::default();
    path.iter()
        .linearize(0.1)
        .iter()
        .non_zero(&mut Traper::default(), &mut mesh);

    println!("Generated {} vertices and {} triangles",
             mesh.vertices.len(), mesh.indices.len() / 3);
}

§License

This project is licensed under the MIT license. See the LICENSE file for complete licensing details.

Structs§

Angle
ArrayPath: A path that stores its data in arrays.
ArrayPathIter
ArrayStorage
Bounds: Axis-aligned bounding box.
BoundsBuilder
Boundser
Cell: Represents a cell in the rasterization grid.
Celler
Cubic
CurveDasher
CurveLinearizer: A utility struct for converting curves to linear segments through recursive subdivision.
Dash
Dasher
FixedPath
FixedPoint
Line
LineCmder
LineIter
LinearCloser
LinearCmdPather
Linearizer
Liner
Mask
MaskHit
MaskSlice
Mesh
NumListParser
Path: A PathCore implementation that stores its data in vectors.
PathCloser
PathIter: An iterator over path commands reconstructed from separate verb and point slices.
PathSlice: A structure that represents a slice of path data using separate arrays for verbs and points.
PathTransformer
Point
Quadratic
Reader
SegmentCmder
Segmenter
Span
Striper
Stroke: Configuration for stroke operations.
Stroker
StrokerIter
SvgBundle
SvgFill
SvgFillAttr
SvgLinearFmt
SvgMeshFmt
SvgParser
SvgPathCmdPathCmder
SvgPathFmt
SvgPathParser
SvgPiece
SvgStroke
SvgStrokeAttr
SvgTagParser
SvgTransformParser
Transform
Traper: Converts a sequence of line path commands to a sequence of trapezoids. The line path commands should define a set of closed contours.
VecStorage

Enums§

Cap: Defines cap styles for stroke operations.
Dashing
FillRule: Defines fill rules for path rendering.
Join: Defines join styles for stroke operations.
LineCmd
LinearCmd: Represents linear path commands for simplified path operations.
PathCmd: Represents complete path commands including curves.
PathVerb: Represents path verbs for vector graphics operations.
Segment
SegmentCmd
SvgElement
SvgError
SvgPathCmd
SvgPathError
SvgPathToken
SvgToken
SvgTransform

Traits§

Curve: A trait for working with parametric curves in vector graphics. Provides methods for evaluating, splitting, and manipulating curves.
FixedCore: A Path Build trait for fixed-point.
LinearCmdFlow: A trait for flowing linear commands through various transformations and operations. Provides methods for converting to paths, applying fills, transformations, and other operations.
Maskive: A trait for mask-based rendering operations.
MeshTransform: A trait for applying geometric transformations to meshes.
Meshive: A trait for mesh-based geometric operations.
PathAppliable: Trait for objects that can be applied to a path. Defines how to apply path commands to a path builder.
PathApply: Trait for applying path commands to a path object. Provides methods for applying path operations and iterating over path commands.
PathCanvas: Trait for canvas-style path operations that extend basic path functionality. Provides methods similar to HTML5 Canvas API for drawing arcs and curves.
PathCmdFlow: A trait for flowing path commands through various transformations and operations. Provides methods for closing paths, segmenting, transforming, dashing, and other path operations.
PathCore: Core trait for building path objects in vector graphics.
PathExtend: Trait for extending path functionality with advanced geometric operations. Provides methods for drawing arcs, curves, and connecting points with various shapes.
PathGeometry: Trait for adding geometric shapes to a path. Provides methods for drawing common geometric figures like rectangles, ellipses, arcs, etc.
PathRelative: Trait for adding relative path operations to a path object. Provides methods that interpret coordinates relative to the current position.
PathSvg: Trait for SVG path operations that extend basic path functionality. Provides methods for drawing SVG-style arcs according to SVG specification.
PathTransform: A trait for transforming path commands and linear commands with geometric transformations.
Rastive: A trait for rasterization operations.
SvgCore: A trait for SVG path operations.

Crate tumo_path

Crate tumo_path Copy item path

§Features

§Constructing Paths

§Manipulating Paths

§Rasterizing Paths

§Tessellating Paths

§Complete Example

§License

Structs§

Enums§

Traits§

Crate tumo_path