svg_path - v0.4.0

svg_path

Core SVG path data structures and constructors.

This module models paths as a list of subpaths, and subpaths as continuous segment lists. Use svg_path/parse and svg_path/serialize when working directly with SVG path data strings.

Types

BoundingBox

</>

An axis-aligned bounding box.

pub type BoundingBox {
  BoundingBox(min: vec2.Vec2(Float), max: vec2.Vec2(Float))
}

Constructors

CrossingOptions

</>

Options for detecting scalar zero crossings along a segment.

pub type CrossingOptions {
  CrossingOptions(
    samples: Int,
    tolerance: Float,
    max_iterations: Int,
  )
}

Constructors 

  • CrossingOptions(
  samples: Int,
  tolerance: Float,
  max_iterations: Int,
)

EndpointPolicy

</>

How construction and editing helpers reconcile segment endpoints.

pub type EndpointPolicy {
  Strict
  Wiggle
  Bridge
  WiggleThenBridge
}

Constructors 

  • Strict

    Endpoints must already match exactly.

  • Wiggle

    Move nearby endpoints together within the default wiggle tolerance.

  • Bridge

    Keep endpoints unchanged and insert a straight line if needed.

  • WiggleThenBridge

    Try Wiggle; if that fails, use Bridge.

Error

</>

Errors returned by path construction and editing helpers.

pub type Error {
  AlreadyClosed
  ClosedEmptySubpath
  Discontinuous(
    previous_index: Int,
    next_index: Int,
    expected: vec2.Vec2(Float),
    got: vec2.Vec2(Float),
    distance: Float,
  )
  EmptySubpath
  EmptyPath
  EmptySubpaths
  DegenerateArc
  CannotMapArcNonlinearly
  IncompatibleHorizontalWiggle(
    previous_end: vec2.Vec2(Float),
    next_start: vec2.Vec2(Float),
  )
  IncompatibleVerticalWiggle(
    previous_end: vec2.Vec2(Float),
    next_start: vec2.Vec2(Float),
  )
  InvalidSplice(start: Int, delete: Int, length: Int)
  InvalidCrossingSamples(samples: Int)
  InvalidCrossingTolerance(tolerance: Float)
  InvalidCrossingMaxIterations(max_iterations: Int)
  CrossingMaxIterationsReached(estimate: Float, value: Float)
  MultipleNonemptySubpaths
  NotCloseEnough(
    expected: vec2.Vec2(Float),
    got: vec2.Vec2(Float),
    tolerance: Float,
  )
  SplitOutsideSegment
}

Constructors 

  • AlreadyClosed

    The subpath is already closed and cannot accept more segments.

  • ClosedEmptySubpath

    An operation would produce a closed subpath with no segments.

    Empty open subpaths are valid, but this package does not represent a closed empty subpath.

  • Discontinuous(
  previous_index: Int,
  next_index: Int,
  expected: vec2.Vec2(Float),
  got: vec2.Vec2(Float),
  distance: Float,
)

    A segment starts somewhere other than the previous segment’s end point.

    previous_index is the segment whose end point was expected. next_index is the segment whose start point did not match. distance is the distance between expected and got.

  • EmptySubpath

    The operation requires a non-empty subpath.

  • EmptyPath

    The operation requires a path with at least one subpath.

  • EmptySubpaths

    The operation requires a path with at least one non-empty subpath.

  • DegenerateArc

    The arc cannot be converted to center-parameter form.

  • CannotMapArcNonlinearly

    Nonlinear point mapping cannot preserve an SVG arc segment.

  • IncompatibleHorizontalWiggle(
  previous_end: vec2.Vec2(Float),
  next_start: vec2.Vec2(Float),
)

    A wiggle operation could not reconcile two horizontal line segments.

  • IncompatibleVerticalWiggle(
  previous_end: vec2.Vec2(Float),
  next_start: vec2.Vec2(Float),
)

    A wiggle operation could not reconcile two vertical line segments.

  • InvalidSplice(start: Int, delete: Int, length: Int)

    A splice was requested with invalid bounds.

    This is returned when start is negative, delete is negative, or start is greater than the subpath length.

  • InvalidCrossingSamples(samples: Int)

    The number of crossing scan samples must be greater than zero.

  • InvalidCrossingTolerance(tolerance: Float)

    The crossing tolerance must be greater than zero.

  • InvalidCrossingMaxIterations(max_iterations: Int)

    The crossing bisection iteration limit must be greater than zero.

  • CrossingMaxIterationsReached(estimate: Float, value: Float)

    A bracketed crossing could not be refined within the iteration limit.

  • MultipleNonemptySubpaths

    The path contains more than one non-empty subpath.

  • NotCloseEnough(
  expected: vec2.Vec2(Float),
  got: vec2.Vec2(Float),
  tolerance: Float,
)

    Two points were too far apart for a wiggle operation to merge them.

  • SplitOutsideSegment

    The requested split point is outside the segment’s 0.0..1.0 parameter range.

Path

</>

An SVG path, made of zero or more subpaths.

pub type Path {
  Path(subpaths: List(Subpath))
}

Constructors

Point

</>

A 2D point.

This is a vec.Vec2(Float), so its coordinates are available as .x and .y.

pub type Point =
  vec2.Vec2(Float)

Segment

</>

A single SVG path segment.

pub type Segment {
  Line(start: vec2.Vec2(Float), end: vec2.Vec2(Float))
  QuadraticBezier(
    start: vec2.Vec2(Float),
    control: vec2.Vec2(Float),
    end: vec2.Vec2(Float),
  )
  CubicBezier(
    start: vec2.Vec2(Float),
    control1: vec2.Vec2(Float),
    control2: vec2.Vec2(Float),
    end: vec2.Vec2(Float),
  )
  Arc(
    start: vec2.Vec2(Float),
    radius: vec2.Vec2(Float),
    x_axis_rotation: Float,
    large_arc: Bool,
    sweep: Bool,
    end: vec2.Vec2(Float),
  )
}

Constructors

Subpath

opaque </>

A continuous sequence of path segments, optionally closed.

The constructor is opaque so that subpaths cannot be created in an invalid discontinuous state. Use subpath, empty_subpath, append_segment, or their _with variants to build values.

pub opaque type Subpath

Values

append_segment

</> 
pub fn append_segment(
  subpath: Subpath,
  segment: Segment,
) -> Result(Subpath, Error)

Append a segment to an open subpath.

The new segment must start exactly at the current end point.

append_segment_with

</> 
pub fn append_segment_with(
  subpath: Subpath,
  segment: Segment,
  policy endpoint_policy: EndpointPolicy,
) -> Result(Subpath, Error)

Append a segment to an open subpath using the given endpoint policy.

append_subpath

</> 
pub fn append_subpath(path: Path, subpath: Subpath) -> Path

Append a subpath to the end of a path.

arc

</> 
pub fn arc(
  start start: vec2.Vec2(Float),
  radius radius: vec2.Vec2(Float),
  x_axis_rotation x_axis_rotation: Float,
  large_arc large_arc: Bool,
  sweep sweep: Bool,
  end end: vec2.Vec2(Float),
) -> Segment

Create an elliptical arc segment.

arc_from_center_data

</> 
pub fn arc_from_center_data(
  data: ellipse.CenterArcData,
) -> Segment

Create an elliptical arc segment from center-parameter arc data.

arc_from_endpoint_data

</> 
pub fn arc_from_endpoint_data(
  data: ellipse.EndpointArcData,
) -> Segment

Create an elliptical arc segment from endpoint-parameter arc data.

as_subpath

</> 
pub fn as_subpath(path: Path) -> Result(Subpath, Error)

Convert a path with zero or one non-empty subpaths into a subpath.

Empty subpaths are ignored. If more than one non-empty subpath is present, this returns MultipleNonemptySubpaths.

assert_append_segment

</> 
pub fn assert_append_segment(
  subpath: Subpath,
  segment: Segment,
) -> Subpath

Append a segment to an open subpath, panicking if invalid.

assert_append_segment_with

</> 
pub fn assert_append_segment_with(
  subpath: Subpath,
  segment: Segment,
  policy endpoint_policy: EndpointPolicy,
) -> Subpath

Append a segment with an endpoint policy, panicking if invalid.

assert_join

</> 
pub fn assert_join(subpaths: List(Subpath)) -> Subpath

Join open subpaths, panicking if invalid.

assert_join_with

</> 
pub fn assert_join_with(
  subpaths: List(Subpath),
  policy endpoint_policy: EndpointPolicy,
) -> Subpath

Join open subpaths with an endpoint policy, panicking if invalid.

assert_set_closed

</> 
pub fn assert_set_closed(
  subpath: Subpath,
  closed closed: Bool,
) -> Subpath

Set a subpath’s semantic closed state, panicking if invalid.

assert_set_closed_with

</> 
pub fn assert_set_closed_with(
  subpath: Subpath,
  closed closed: Bool,
  policy endpoint_policy: EndpointPolicy,
) -> Subpath

Set a subpath’s semantic closed state with an endpoint policy, panicking if invalid.

assert_splice

</> 
pub fn assert_splice(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
) -> Subpath

Replace a range of segments, panicking if the splice is invalid.

assert_splice_with

</> 
pub fn assert_splice_with(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
  policy endpoint_policy: EndpointPolicy,
) -> Subpath

Replace a range of segments with an endpoint policy, panicking if invalid.

assert_subpath

</> 
pub fn assert_subpath(segments: List(Segment)) -> Subpath

Create an open subpath from a continuous list of segments, panicking if the segments are invalid.

This is useful for hand-authored paths where invalid continuity would be a programmer error. Use subpath when you want to handle construction errors.

assert_subpath_with

</> 
pub fn assert_subpath_with(
  segments: List(Segment),
  policy endpoint_policy: EndpointPolicy,
) -> Subpath

Create an open subpath with an endpoint policy, panicking if construction fails.

clean_subpath

</> 
pub fn clean_subpath(subpath: Subpath) -> Subpath

Remove zero-length line segments from a subpath.

If the subpath contains only one zero-length line, it is preserved so the subpath does not become empty.

cubic_bezier

</> 
pub fn cubic_bezier(
  start start: vec2.Vec2(Float),
  control1 control1: vec2.Vec2(Float),
  control2 control2: vec2.Vec2(Float),
  end end: vec2.Vec2(Float),
) -> Segment

Create a cubic Bezier segment.

default_crossing_options

</> 
pub fn default_crossing_options() -> CrossingOptions

Return the default options for segment crossing detection.

empty_path

</> 
pub fn empty_path() -> Path

Create an empty path.

empty_subpath

</> 
pub fn empty_subpath() -> Subpath

Create an empty open subpath.

end

</> 
pub fn end(subpath: Subpath) -> Result(vec2.Vec2(Float), Error)

Return the end point of a non-empty subpath.

from_subpath

</> 
pub fn from_subpath(subpath: Subpath) -> Path

Create a path containing a single subpath.

is_closed

</> 
pub fn is_closed(subpath: Subpath) -> Bool

Check whether a subpath is closed.

join

</> 
pub fn join(subpaths: List(Subpath)) -> Result(Subpath, Error)

Join open subpaths into one open subpath.

Each subpath’s end point must exactly match the next subpath’s start point. Empty open subpaths are treated as identity values.

join_with

</> 
pub fn join_with(
  subpaths: List(Subpath),
  policy endpoint_policy: EndpointPolicy,
) -> Result(Subpath, Error)

Join open subpaths using the given endpoint policy.

line

</> 
pub fn line(
  start start: vec2.Vec2(Float),
  end end: vec2.Vec2(Float),
) -> Segment

Create a straight line segment.

map_path_points

</> 
pub fn map_path_points(
  path: Path,
  with f: fn(vec2.Vec2(Float)) -> vec2.Vec2(Float),
) -> Result(Path, Error)

Map the defining points of every segment in a path.

Each subpath’s closed state is preserved. For nonlinear functions, this maps endpoints and control points, not the exact image of every point on each rendered curve. If any segment is an arc, this returns CannotMapArcNonlinearly.

map_segment_points

</> 
pub fn map_segment_points(
  segment: Segment,
  with f: fn(vec2.Vec2(Float)) -> vec2.Vec2(Float),
) -> Result(Segment, Error)

Map the defining points of a segment.

Lines, quadratic Beziers, and cubic Beziers are mapped by applying f to their endpoints and control points. For nonlinear functions, this is not the exact image of every point on the rendered curve. Arc segments return CannotMapArcNonlinearly because an arbitrary nonlinear mapping does not generally preserve SVG arc parameters.

map_subpath_points

</> 
pub fn map_subpath_points(
  subpath: Subpath,
  with f: fn(vec2.Vec2(Float)) -> vec2.Vec2(Float),
) -> Result(Subpath, Error)

Map the defining points of every segment in a subpath.

The subpath’s closed state is preserved. For nonlinear functions, this maps endpoints and control points, not the exact image of every point on each rendered curve. If any segment is an arc, this returns CannotMapArcNonlinearly.

path

</> 
pub fn path(subpaths: List(Subpath)) -> Path

Create a path from a list of subpaths.

path_arcs_to_cubic_beziers

</> 
pub fn path_arcs_to_cubic_beziers(path: Path) -> Path

Convert every arc in a path to cubic Bezier curves.

This applies subpath_arcs_to_cubic_beziers to each subpath.

path_bounding_box

</> 
pub fn path_bounding_box(
  path: Path,
) -> Result(BoundingBox, Error)

Return the exact axis-aligned bounding box of all non-empty subpaths.

path_end

</> 
pub fn path_end(path: Path) -> Result(vec2.Vec2(Float), Error)

Return the end point of the last non-empty subpath in a path.

path_start

</> 
pub fn path_start(path: Path) -> Result(vec2.Vec2(Float), Error)

Return the start point of the first non-empty subpath in a path.

path_to_cubic_beziers

</> 
pub fn path_to_cubic_beziers(path: Path) -> Path

Convert every segment in a path to cubic Bezier curves.

This applies subpath_to_cubic_beziers to each subpath.

point

</> 
pub fn point(x: Float, y: Float) -> vec2.Vec2(Float)

Create a point from x and y coordinates.

quadratic_bezier

</> 
pub fn quadratic_bezier(
  start start: vec2.Vec2(Float),
  control control: vec2.Vec2(Float),
  end end: vec2.Vec2(Float),
) -> Segment

Create a quadratic Bezier segment.

reverse_path

</> 
pub fn reverse_path(path: Path) -> Path

Reverse the traversal direction of a path.

This reverses each subpath and reverses the path’s subpath order.

reverse_segment

</> 
pub fn reverse_segment(segment: Segment) -> Segment

Reverse the traversal direction of a segment.

reverse_subpath

</> 
pub fn reverse_subpath(subpath: Subpath) -> Subpath

Reverse the traversal direction of every segment in a subpath.

The subpath’s closed state is preserved.

segment_arcs_to_cubic_beziers

</> 
pub fn segment_arcs_to_cubic_beziers(
  segment: Segment,
) -> List(Segment)

Convert an arc segment to cubic Bezier curves, preserving other segments.

Non-arc segments are returned unchanged as a single-item list. An arc may become several cubic Bezier segments.

segment_bounding_box

</> 
pub fn segment_bounding_box(
  segment: Segment,
) -> Result(BoundingBox, Error)

Return a segment’s exact axis-aligned bounding box.

segment_crossings

</> 
pub fn segment_crossings(
  segment: Segment,
  where f: fn(vec2.Vec2(Float)) -> Float,
) -> Result(List(Float), Error)

Find scalar sign-change crossings along a segment using default options.

This samples t in 0.0..1.0, detects sign changes of f(segment_point(t)), and refines each bracket with bisection. It finds crossings visible at the configured sampling resolution; tangent roots and pairs of crossings inside one sample window may be missed.

segment_crossings_with

</> 
pub fn segment_crossings_with(
  segment: Segment,
  where f: fn(vec2.Vec2(Float)) -> Float,
  options options: CrossingOptions,
) -> Result(List(Float), Error)

Find scalar sign-change crossings along a segment using explicit options.

segment_derivative

</> 
pub fn segment_derivative(
  segment: Segment,
  at t: Float,
) -> Result(vec2.Vec2(Float), Error)

Return a segment’s derivative with respect to parameter t.

t is not clamped.

segment_end

</> 
pub fn segment_end(segment: Segment) -> vec2.Vec2(Float)

Return the end point of a segment.

segment_point

</> 
pub fn segment_point(
  segment: Segment,
  at t: Float,
) -> Result(vec2.Vec2(Float), Error)

Evaluate a segment at parameter t.

t is not clamped. Values outside 0.0..1.0 extrapolate along the same segment.

segment_start

</> 
pub fn segment_start(segment: Segment) -> vec2.Vec2(Float)

Return the start point of a segment.

segment_to_cubic_beziers

</> 
pub fn segment_to_cubic_beziers(
  segment: Segment,
) -> List(Segment)

Convert a segment to one or more cubic Bezier curves.

Lines and quadratic Beziers are converted exactly. Cubic Beziers are returned unchanged. Arcs may become several cubic Bezier segments.

segments

</> 
pub fn segments(subpath: Subpath) -> List(Segment)

Return the segments in a subpath.

set_closed

</> 
pub fn set_closed(
  subpath: Subpath,
  closed closed: Bool,
) -> Result(Subpath, Error)

Set a subpath’s semantic closed state.

Setting closed to False only clears the semantic closed flag. Setting it to True requires the subpath’s end point to exactly match its start point.

set_closed_with

</> 
pub fn set_closed_with(
  subpath: Subpath,
  closed closed: Bool,
  policy endpoint_policy: EndpointPolicy,
) -> Result(Subpath, Error)

Set a subpath’s semantic closed state with an endpoint policy.

Setting closed to False only clears the semantic closed flag. Setting it to True uses the given endpoint policy to reconcile the subpath’s end point with its start point.

splice

</> 
pub fn splice(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
) -> Result(Subpath, Error)

Replace a range of segments in a subpath.

start is a zero-based segment index and delete is the number of segments to remove. If start + delete extends past the end of the subpath, everything from start onward is deleted. Negative start, negative delete, and start greater than the subpath length return InvalidSplice.

The edited subpath must remain continuous. Closed subpaths preserve their closed state; if the splice would make a closed subpath empty, ClosedEmptySubpath is returned.

splice_with

</> 
pub fn splice_with(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
  policy endpoint_policy: EndpointPolicy,
) -> Result(Subpath, Error)

Replace a range of segments in a subpath using the given endpoint policy.

split_segment

</> 
pub fn split_segment(
  segment: Segment,
  at t: Float,
) -> Result(#(Segment, Segment), Error)

Split a segment at parameter t.

t is not clamped. Values outside 0.0..1.0 extrapolate along the same segment.

split_segment_inside

</> 
pub fn split_segment_inside(
  segment: Segment,
  at t: Float,
) -> Result(#(Segment, Segment), Error)

Split a segment at parameter t, returning an error outside 0.0..1.0.

Values exactly at 0.0 or 1.0 are accepted and produce one zero-length segment.

start

</> 
pub fn start(subpath: Subpath) -> Result(vec2.Vec2(Float), Error)

Return the start point of a non-empty subpath.

subpath

</> 
pub fn subpath(segments: List(Segment)) -> Result(Subpath, Error)

Create an open subpath from a continuous list of segments.

Returns Discontinuous if any segment starts somewhere other than the previous segment’s end point. The error includes the two segment indices that failed to meet.

subpath_arcs_to_cubic_beziers

</> 
pub fn subpath_arcs_to_cubic_beziers(subpath: Subpath) -> Subpath

Convert every arc in a subpath to cubic Bezier curves.

Lines, quadratic Beziers, and cubic Beziers are preserved. Elliptical arcs are approximated with one or more cubic Beziers, split into chunks of at most a quarter turn. Degenerate arcs fall back to a straight-line cubic Bezier between their endpoints.

subpath_bounding_box

</> 
pub fn subpath_bounding_box(
  subpath: Subpath,
) -> Result(BoundingBox, Error)

Return a non-empty subpath’s exact axis-aligned bounding box.

subpath_to_cubic_beziers

</> 
pub fn subpath_to_cubic_beziers(subpath: Subpath) -> Subpath

Convert every segment in a subpath to cubic Bezier curves.

Lines and quadratic Beziers are converted exactly. Cubic Beziers are preserved. Elliptical arcs are approximated with one or more cubic Beziers, split into chunks of at most a quarter turn.

subpath_with

</> 
pub fn subpath_with(
  segments: List(Segment),
  policy endpoint_policy: EndpointPolicy,
) -> Result(Subpath, Error)

Create an open subpath using the given endpoint reconciliation policy.

subpaths

</> 
pub fn subpaths(path: Path) -> List(Subpath)

Return the subpaths in a path.

✨ Search Document