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.