Crate lyon_path_iterator

Lyon path builder

Tools to iterate over path objects.

Overview

This crate provides a collection of traits to extend the Iterator trait with information about the state of the cursor moving along the path. This is useful because the way some events are described require to have information about the previous events. For example the event LinTo gives the next position and it is generally useful to have access to the current position in order to make something out of it. Likewise, Some Svg events are given in relative coordinates and/or are expressed in a way that the first control point is deduced from the position of the previous control point.

All of this extra information is conveniently exposed in the PathState struct that can be accessed by PathIterator, SvgIterator and FlattenedIterator.

The PathStateIter<Iter> adapter automatically implements PathIterator for any Iter that implements Iterator<PathEvent>

This crate provides adapters between these iterator types. For example iterating over a sequence of SVG events can be automatically translated into iterating over simpler path events which express all positions with absolute coordinates, among other things.

The trait FlattenedIterator is what some of the tessellation algorithms of the lyon_tessellation crate take as input.

Examples

extern crate lyon_path_iterator;
use lyon_path_iterator::*;
use math::{point, vec2};

fn main() {
    let events = vec![
        SvgEvent::MoveTo(point(1.0, 1.0)),
        SvgEvent::RelativeQuadraticTo(vec2(4.0, 5.0), vec2(-1.0, 4.0)),
        SvgEvent::SmoothCubicTo(point(3.0, 1.0), point(10.0, -3.0)),
        SvgEvent::Close,
    ];

    // A simple std::iter::Iterator<SvgEvent>,
    let simple_iter = events.iter().cloned();

    // Make it a SvgIterator (keeps tracks of the path state).
    let svg_path_iter = PathStateSvgIter::new(simple_iter);

    // Make it a PathIterator (iterates on simpler PathEvents).
    let path_iter = svg_path_iter.path_iter();
    // Equivalent to:
    // let path_iter = SvgToPathIter::new(svg_path_iter);

    // Make it an iterator over even simpler primitives: FlattenedEvent,
    // which do not contain any curve. To do so we approximate each curve
    // linear segments according to a tolerance threashold which controls
    // the tradeoff between fidelity of the approximation and amount of
    // generated events. Let's use a tolerance threshold of 0.01.
    // The beauty of this approach is that the flattening happens lazily
    // while iterating with no memory allocation.
    let flattened_iter = path_iter.flattened(0.01);
    // equivalent to:
    // let flattened = FlatteningIter::new(0.01, path_iter);

    for evt in flattened_iter {
        match evt {
            FlattenedEvent::MoveTo(p) => { println!(" - move to {:?}", p); }
            FlattenedEvent::LineTo(p) => { println!(" - line to {:?}", p); }
            FlattenedEvent::Close => { println!(" - close"); }
        }
    }
}

An equivalent (but shorter) version of the above code takes advantage of the fact you can get a flattening iterator directly from an SvgIterator:

extern crate lyon_path_iterator;
use lyon_path_iterator::*;
use math::{point, vec2};

fn main() {
    let events = vec![
        SvgEvent::MoveTo(point(1.0, 1.0)),
        SvgEvent::RelativeQuadraticTo(vec2(4.0, 5.0), vec2(-1.0, 4.0)),
        SvgEvent::SmoothCubicTo(point(3.0, 1.0), point(10.0, -3.0)),
        SvgEvent::Close,
    ];

    for evt in PathStateSvgIter::new(events.iter().cloned()).flattened(0.01) {
        // ...
    }
}

Reexports

pub use core::*;

Structs

FlatteningIter	An iterator that consumes an PathIterator and yields FlattenedEvents.
PathStateIter	An adapater iterator that implements PathIterator on top of an Iterator.
PathStateSvgIter	An adapater iterator that implements SvgIterator on top of an Iterator.
SegmentIterator	Consumes an iterator of path events and yields segments.
SvgToPathIter

Enums

Segment

Convenience for algorithms which prefer to iterate over segments directly rather than path events.

Traits

FlattenedIterator	An extension to the common Iterator interface, that adds information which is useful when chaining path-specific iterators.
PathIterator	An extension to the common Iterator interface, that adds information which is useful when chaining path-specific iterators.
SvgIterator	An extension to the common Iterator interface, that adds information which is useful when chaining path-specific iterators.