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.
```rust
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.
```rust
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.
```rust
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.
```rust
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
```rust
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](LICENSE) file for complete licensing details.