Struct kurbo::BezPath

pub struct BezPath(_);

A Bézier path.

These docs assume basic familiarity with Bézier curves; for an introduction, see Pomax’s wonderful A Primer on Bézier Curves.

This path can contain lines, quadratics (QuadBez) and cubics (CubicBez), and may contain multiple subpaths.

Elements and Segments

A Bézier path can be represented in terms of either ‘elements’ (PathEl) or ‘segments’ (PathSeg). Elements map closely to how Béziers are generally used in PostScript-style drawing APIs; they can be thought of as instructions for drawing the path. Segments more directly describe the path itself, with each segment being an independent line or curve.

These different representations are useful in different contexts. For tasks like drawing, elements are a natural fit, but when doing hit-testing or subdividing, we need to have access to the segments.

Conceptually, a BezPath contains zero or more subpaths. Each subpath always begins with a MoveTo, then has zero or more LineTo, QuadTo, and CurveTo elements, and optionally ends with a ClosePath.

Internally, a BezPath is a list of PathEls; as such it implements FromIterator<PathEl> and Extend<PathEl>:

use kurbo::{BezPath, Rect, Shape, Vec2};
let accuracy = 0.1;
let rect = Rect::from_origin_size((0., 0.,), (10., 10.));
// these are equivalent
let path1 = rect.to_path(accuracy);
let path2: BezPath = rect.path_elements(accuracy).collect();

// extend a path with another path:
let mut path = rect.to_path(accuracy);
let shifted_rect = rect + Vec2::new(5.0, 10.0);
path.extend(shifted_rect.to_path(accuracy));

You can iterate the elements of a BezPath with the iter method, and the segments with the segments method:

use kurbo::{BezPath, Line, PathEl, PathSeg, Point, Rect, Shape};
let accuracy = 0.1;
let rect = Rect::from_origin_size((0., 0.,), (10., 10.));
// these are equivalent
let path = rect.to_path(accuracy);
let first_el = PathEl::MoveTo(Point::ZERO);
let first_seg = PathSeg::Line(Line::new((0., 0.), (10., 0.)));
assert_eq!(path.iter().next(), Some(first_el));
assert_eq!(path.segments().next(), Some(first_seg));

In addition, if you have some other type that implements Iterator<Item=PathEl>, you can adapt that to an iterator of segments with the segments free function.

Advanced functionality

In addition to the basic API, there are several useful pieces of advanced functionality available on BezPath:

• flatten does Bézier flattening, converting a curve to a series of line segments
• intersect_line computes intersections of a path with a line, useful for things like subdividing

Implementations

impl BezPath

pub fn new() -> BezPath

Create a new path.

pub fn from_vec(v: Vec<PathEl>) -> BezPath

Create a path from a vector of path elements.

BezPath also implements FromIterator<PathEl>, so it works with collect:

// a very contrived example:
use kurbo::{BezPath, PathEl};

let path = BezPath::new();
let as_vec: Vec<PathEl> = path.into_iter().collect();
let back_to_path: BezPath = as_vec.into_iter().collect();

pub fn pop(&mut self) -> Option<PathEl>

Removes the last PathEl from the path and returns it, or None if the path is empty.

pub fn push(&mut self, el: PathEl)

Push a generic path element onto the path.

pub fn move_to<P: Into<Point>>(&mut self, p: P)

Push a “move to” element onto the path.

pub fn line_to<P: Into<Point>>(&mut self, p: P)

Push a “line to” element onto the path.

Will panic with a debug assert when the current subpath does not start with move_to.

pub fn quad_to<P: Into<Point>>(&mut self, p1: P, p2: P)

Push a “quad to” element onto the path.

Will panic with a debug assert when the current subpath does not start with move_to.

pub fn curve_to<P: Into<Point>>(&mut self, p1: P, p2: P, p3: P)

Push a “curve to” element onto the path.

Will panic with a debug assert when the current subpath does not start with move_to.

pub fn close_path(&mut self)

Push a “close path” element onto the path.

Will panic with a debug assert when the current subpath does not start with move_to.

pub fn elements(&self) -> &[PathEl]

Get the path elements.

pub fn elements_mut(&mut self) -> &mut [PathEl]

Get the path elements (mut version).

pub fn iter(&self) -> impl Iterator<Item = PathEl> + Clone + '_

Returns an iterator over the path’s elements.

pub fn segments(&self) -> impl Iterator<Item = PathSeg> + Clone + '_

Iterate over the path segments.

pub fn truncate(&mut self, len: usize)

Shorten the path, keeping the first len elements.

pub fn flatten(&self, tolerance: f64, callback: impl FnMut(PathEl))

Flatten the path, invoking the callback repeatedly.

Flattening is the action of approximating a curve with a succession of line segments.

The tolerance value controls the maximum distance between the curved input segments and their polyline approximations. (In technical terms, this is the Hausdorff distance). The algorithm attempts to bound this distance between by tolerance but this is not absolutely guaranteed. The appropriate value depends on the use, but for antialiased rendering, a value of 0.25 has been determined to give good results. The number of segments tends to scale as the inverse square root of tolerance.

The callback will be called in order with each element of the generated path. Because the result is made of polylines, these will be straight-line path elements only, no curves.

This algorithm is based on the blog post Flattening quadratic Béziers but with some refinements. For one, there is a more careful approximation at cusps. For two, the algorithm is extended to work with cubic Béziers as well, by first subdividing into quadratics and then computing the subdivision of each quadratic. However, as a clever trick, these quadratics are subdivided fractionally, and their endpoints are not included.

TODO: write a paper explaining this in more detail.

Note: the flatten function provides the same functionality but works with slices and other PathEl iterators.

pub fn get_seg(&self, ix: usize) -> Option<PathSeg>

Get the segment at the given element index.

If you need to access all segments, segments provides a better API. This is intended for random access of specific elements, for clients that require this specifically.

note: This returns the segment that ends at the provided element index. In effect this means it is 1-indexed: since no segment ends at the first element (which is presumed to be a MoveTo) get_seg(0) will always return None.

pub fn is_empty(&self) -> bool

Returns true if the path contains no segments.

pub fn apply_affine(&mut self, affine: Affine)

Apply an affine transform to the path.

pub fn is_finite(&self) -> bool

Is this path finite?

pub fn is_nan(&self) -> bool

Is this path NaN?

impl BezPath

pub fn from_path_segments(segments: impl Iterator<Item = PathSeg>) -> BezPath

Create a BezPath with segments corresponding to the sequence of PathSegs

pub fn to_svg(&self) -> String

Convert the path to an SVG path string representation.

The current implementation doesn’t take any special care to produce a short string (reducing precision, using relative movement).

pub fn write_to<W: Write>(&self, writer: W) -> Result<()>

Write the SVG representation of this path to the provided buffer.

pub fn from_svg(data: &str) -> Result<BezPath, SvgParseError>

Try to parse a bezier path from an SVG path element.

This is implemented on a best-effort basis, intended for cases where the user controls the source of paths, and is not intended as a replacement for a general, robust SVG parser.

Trait Implementations

impl Clone for BezPath

fn clone(&self) -> BezPath

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BezPath

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BezPath

fn default() -> BezPath

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for BezPath

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Extend<PathEl> for BezPath

fn extend<I: IntoIterator<Item = PathEl>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl FromIterator<PathEl> for BezPath

fn from_iter<T: IntoIterator<Item = PathEl>>(iter: T) -> Self

Creates a value from an iterator.

impl<'a> IntoIterator for &'a BezPath

Allow iteration over references to BezPath.

Note: the semantics are slightly different from simply iterating over the slice, as it returns PathEl items, rather than references.

type Item = PathEl

The type of the elements being iterated over.

type IntoIter = Cloned<Iter<'a, PathEl>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for BezPath

type Item = PathEl

The type of the elements being iterated over.

type IntoIter = IntoIter<PathEl, Global>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl JsonSchema for BezPath

fn schema_name() -> String

The name of the generated JSON Schema.

fn json_schema(gen: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl<'a> Mul<&'a BezPath> for Affine

type Output = BezPath

The resulting type after applying the * operator.

fn mul(self, other: &BezPath) -> BezPath

Performs the * operation.

impl<'a> Mul<&'a BezPath> for TranslateScale

type Output = BezPath

The resulting type after applying the * operator.

fn mul(self, other: &BezPath) -> BezPath

Performs the * operation.

impl Mul<BezPath> for Affine

type Output = BezPath

The resulting type after applying the * operator.

fn mul(self, other: BezPath) -> BezPath

Performs the * operation.

impl Mul<BezPath> for TranslateScale

type Output = BezPath

The resulting type after applying the * operator.

fn mul(self, other: BezPath) -> BezPath

Performs the * operation.

impl PartialEq<BezPath> for BezPath

fn eq(&self, other: &BezPath) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for BezPath

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Shape for BezPath

fn area(&self) -> f64

Signed area.

fn winding(&self, pt: Point) -> i32

Winding number of point.

type PathElementsIter<'iter> = Copied<Iter<'iter, PathEl>>

The iterator returned by the path_elements method.

fn path_elements(&self, _tolerance: f64) -> Self::PathElementsIter<'_>

Returns an iterator over this shape expressed as PathEls; that is, as Bézier path elements.

fn to_path(&self, _tolerance: f64) -> BezPath

Convert to a Bézier path.

fn into_path(self, _tolerance: f64) -> BezPath

Convert into a Bézier path.

fn perimeter(&self, accuracy: f64) -> f64

Total length of perimeter.

fn bounding_box(&self) -> Rect

The smallest rectangle that encloses the shape.

fn as_path_slice(&self) -> Option<&[PathEl]>

If the shape is stored as a slice of path elements, make that available.

fn path_segments(&self, tolerance: f64) -> Segments<Self::PathElementsIter<'_>>

Returns an iterator over this shape expressed as Bézier path segments (PathSegs).

fn contains(&self, pt: Point) -> bool

Returns true if the Point is inside this shape.

fn as_line(&self) -> Option<Line>

If the shape is a line, make it available.

fn as_rect(&self) -> Option<Rect>

If the shape is a rectangle, make it available.

fn as_rounded_rect(&self) -> Option<RoundedRect>

If the shape is a rounded rectangle, make it available.

fn as_circle(&self) -> Option<Circle>

If the shape is a circle, make it available.

impl StructuralPartialEq for BezPath