Module lyon_path::iterator

Tools to iterate over paths.

Lyon path iterators

Overview

This module 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 PathIter<Iter> adapter automatically implements PathIterator for any Iter that implements Iterator<PathEvent>

This module 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 PathIterator is what some of the tessellation algorithms of the lyon_tessellation crate take as input.

Examples

extern crate lyon_path;
use lyon_path::iterator::*;
use lyon_path::math::{point, vector};
use lyon_path::{PathEvent, SvgEvent, FlattenedEvent};

fn main() {
    let events = vec![
        SvgEvent::MoveTo(point(1.0, 1.0)),
        SvgEvent::RelativeQuadraticTo(vector(4.0, 5.0), vector(-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 = SvgPathIter::new(simple_iter);

    // Make it a PathIterator (iterates on simpler PathEvents).
    let path_iter = svg_path_iter.path_events();
    // Equivalent to:
    // let path_iter = PathEvents::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 threshold 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 = Flattened::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;
use lyon_path::iterator::*;
use lyon_path::math::{point, vector};
use lyon_path::SvgEvent;

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

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

Structs

Flattened	An iterator that consumes an PathIterator and yields FlattenedEvents.
FromPolyline	An iterator that consumes an iterator of Points and produces FlattenedEvents.
PathEvents
PathIter	An adapater iterator that implements PathIterator on top of an Iterator<Item=PathEvent>.
SvgPathIter	An adapater iterator that implements SvgIterator on top of an Iterator<Item=SvgEvent>.
Transformed	Applies a 2D transform to a path iterator and yields the resulting path iterator.

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.
QuadraticPathIterator	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.