Struct lyon_algorithms::measure::PathMeasurements

pub struct PathMeasurements { /* private fields */ }

An acceleration structure for sampling distances along a specific path.

Building the path measurements can be an expensive operation depending on the complexity of the measured path, so it is usually a good idea to cache and reuse it whenever possible.

Queries on path measurements are made via a sampler object (see PathSampler) which can be configured to measure real distance or normalized ones (values between 0 and 1 with zero indicating the start of the path and 1 indicating the end).

Differences with the PathWalker

The walker module provides a similar functionality via the PathWalker. The main differences are:

• The path walker does all of its computation on the fly without storing any information for later use.
• PathMeasurements stores potentially large amounts of data to speed up sample queries.
• The cost of creating PathMeasurements is similar to that of walking the entire path once.
• Once the PathMeasurements have been created, random samples on the path are much faster than path walking.
• The PathWalker does not handle normalized distances since the length of the path cannot be known without traversing the entire path at least once.

Prefer PathMeasurements over PathWalker if the measurements can be cached and reused for a large number of queries.

Example

use lyon_algorithms::{
    math::point,
    path::Path,
    length::approximate_length,
    measure::{PathMeasurements, SampleType},
};

let mut path = Path::builder();
path.begin(point(0.0, 0.0));
path.quadratic_bezier_to(point(1.0, 1.0), point(2.0, 0.0));
path.end(false);
let path = path.build();

// Build the acceleration structure.
let measurements = PathMeasurements::from_path(&path, 1e-3);
let mut sampler = measurements.create_sampler(&path, SampleType::Normalized);

let sample  = sampler.sample(0.5);
println!("Mid-point position: {:?}, tangent: {:?}", sample.position(), sample.tangent());

let mut second_half = Path::builder();
sampler.split_range(0.5..1.0, &mut second_half);
let second_half = second_half.build();
assert!((sampler.length() / 2.0 - approximate_length(&second_half, 1e-3)).abs() < 1e-3);

Implementations

impl PathMeasurements

pub fn empty() -> Self

Create empty path measurements.

The measurements cannot be used until it has been initialized.

pub fn from_path(path: &Path, tolerance: f32) -> Self

Create path measurements initialized with a Path.

pub fn from_path_slice(path: &PathSlice<'_>, tolerance: f32) -> Self

Create path measurements initialized with a PathSlice.

pub fn from_iter<Iter, PS>(path: Iter, positions: &PS, tolerance: f32) -> Selfwhere Iter: IntoIterator<Item = IdEvent>, PS: PositionStore,

Create path measurements initialized with a generic iterator and position store.

pub fn initialize<Iter, PS>( &mut self, path: Iter, position_store: &PS, tolerance: f32 )where Iter: IntoIterator<Item = IdEvent>, PS: PositionStore,

Initialize the path measurements with a path.

pub fn initialize_with_path(&mut self, path: &Path, tolerance: f32)

Initialize the path measurements with a path.

pub fn initialize_with_path_slice( &mut self, path: PathSlice<'_>, tolerance: f32 )

Initialize the path measurements with a path.

pub fn length(&self) -> f32

Returns the approximate length of the path.

pub fn create_sampler<'l, PS: PositionStore>( &'l self, positions: &'l PS, ty: SampleType ) -> PathSampler<'l, PS, ()>

Create an object that can perform fast sample queries on a path using the cached measurements.

The returned sampler does not compute interpolated attributes.

pub fn create_sampler_with_attributes<'l, PS, AS>( &'l self, positions: &'l PS, attributes: &'l AS, ty: SampleType ) -> PathSampler<'l, PS, AS>where PS: PositionStore, AS: AttributeStore,

Create an object that can perform fast sample queries on a path using the cached measurements.

The returned sampler computes interpolated attributes.