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.
# 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.
# Rasterizing Paths
Paths can be converted to grayscale images through the rasterization process.
Paths are first rendered into containers implementing the `Rastive` trait, with
current implementations available for both `Vec` and `Array` types. The `Rastive`
containers provide various operations including grayscale image rendering and hit testing.
To stroke a path, first apply the `stroke` method on `PathCmdFlow` followed by
the `rasterize` method to generate the final image representation.
# 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
# License
This project is licensed under the MIT license.
See the [LICENSE](LICENSE) file for complete licensing details.