svg_path/convex_hull

Convex hull helpers for paths, subpaths, segments, and points.

This module computes closed hulls. Lines, quadratic Beziers, and arcs have semantic hulls: the primitive itself plus the chord joining its endpoints, with tiny/point-like cases collapsed to lines. Cubic Beziers use a cubic-specific support/event solver.

Types

DirectionalExtent

</>

The supporting points and nonnegative width of a convex set in one unit direction supplied to a directional-support callback.

pub type DirectionalExtent {
  DirectionalExtent(
    lower_point: svg_path.Point,
    upper_point: svg_path.Point,
    width: Float,
  )
}

Constructors

DirectionalExtent(
  lower_point: svg_path.Point,
  upper_point: svg_path.Point,
  width: Float,
)

Error

</>

Errors returned by convex-hull construction.

pub type Error {
  PathError(svg_path.Error)
  ConstructionFailed
}

Constructors

```
PathError(svg_path.Error)
```
An underlying path operation failed.
```
ConstructionFailed
```
Hull construction failed because an internal invariant was not satisfied.

WidthExtremum

</>

A directional width extremum and the bounds established for its value.

center is the midpoint of the two support witnesses. For minimum width it is a representative point on the strip’s center line. For diameter it is the midpoint of the diameter witnesses; it is not generally the center of a minimum enclosing circle. converged reports whether the established bounds met the requested accuracy before the depth limit was reached.

pub type WidthExtremum {
  WidthExtremum(
    direction: svg_path.Point,
    lower_point: svg_path.Point,
    upper_point: svg_path.Point,
    center: svg_path.Point,
    width: Float,
    lower_bound: Float,
    upper_bound: Float,
    converged: Bool,
  )
}

Constructors

WidthExtremum(
  direction: svg_path.Point,
  lower_point: svg_path.Point,
  upper_point: svg_path.Point,
  center: svg_path.Point,
  width: Float,
  lower_bound: Float,
  upper_bound: Float,
  converged: Bool,
)

WidthSearchOptions

</>

Options for minimum-width and diameter searches.

pub type WidthSearchOptions {
  WidthSearchOptions(accuracy: Float, max_depth: Int)
}

Constructors

WidthSearchOptions(accuracy: Float, max_depth: Int)

Values

default_width_search_options

</>

pub fn default_width_search_options() -> WidthSearchOptions

Return the default options for directional width optimization.

diameter

</>

pub fn diameter(
  support: fn(svg_path.Point) -> DirectionalExtent,
  diameter_upper_bound diameter_upper_bound: Float,
) -> WidthExtremum

Find the diameter exposed by a directional support callback.

The callback receives a unit direction. diameter_upper_bound must bound the diameter of the represented convex set.

diameter_with

</>

pub fn diameter_with(
  support: fn(svg_path.Point) -> DirectionalExtent,
  diameter_upper_bound diameter_upper_bound: Float,
  options options: WidthSearchOptions,
) -> WidthExtremum

Find the diameter using explicit directional search options.

minimum_width

</>

pub fn minimum_width(
  support: fn(svg_path.Point) -> DirectionalExtent,
  diameter_upper_bound diameter_upper_bound: Float,
) -> WidthExtremum

Find the minimum directional width exposed by a support callback.

The callback receives a unit direction. diameter_upper_bound must bound the diameter of the represented convex set.

minimum_width_with

</>

pub fn minimum_width_with(
  support: fn(svg_path.Point) -> DirectionalExtent,
  diameter_upper_bound diameter_upper_bound: Float,
  options options: WidthSearchOptions,
) -> WidthExtremum

Find the minimum directional width using explicit search options.

path_diameter

</>

pub fn path_diameter(
  path: svg_path.Path,
) -> Result(WidthExtremum, Error)

Approximate a path’s diameter and return a realizing support pair.

path_diameter_with

</>

pub fn path_diameter_with(
  path: svg_path.Path,
  options options: WidthSearchOptions,
) -> Result(WidthExtremum, Error)

Approximate a path’s diameter using directional search options.

path_hull

</>

pub fn path_hull(
  path: svg_path.Path,
) -> Result(svg_path.Subpath, Error)

Compute the convex hull of a path.

Move-only subpaths are treated as single points at their starts. The result is a single closed subpath containing the hull of every subpath in the input path.

path_minimum_width

</>

pub fn path_minimum_width(
  path: svg_path.Path,
) -> Result(WidthExtremum, Error)

Approximate the minimum width of a path’s convex hull.

path_minimum_width_with

</>

pub fn path_minimum_width_with(
  path: svg_path.Path,
  options options: WidthSearchOptions,
) -> Result(WidthExtremum, Error)

Approximate the minimum width of a path’s convex hull using options.

points_hull

</>

pub fn points_hull(
  points: List(svg_path.Point),
) -> Result(svg_path.Subpath, Error)

Compute the convex hull of a list of points.

The result is a single closed subpath containing every input point.

segment_diameter

</>

pub fn segment_diameter(
  segment: svg_path.Segment,
) -> Result(WidthExtremum, Error)

Approximate a segment’s diameter and return a realizing support pair.

segment_diameter_with

</>

pub fn segment_diameter_with(
  segment: svg_path.Segment,
  options options: WidthSearchOptions,
) -> Result(WidthExtremum, Error)

Approximate a segment’s diameter using directional search options.

segment_hull

</>

pub fn segment_hull(
  segment: svg_path.Segment,
) -> Result(svg_path.Subpath, Error)

Return the closed convex hull boundary of one segment.

The returned subpath uses exact pieces of the input curve where they lie on the hull boundary and straight support chords between those pieces.

segment_minimum_width

</>

pub fn segment_minimum_width(
  segment: svg_path.Segment,
) -> Result(WidthExtremum, Error)

Approximate the minimum width of a segment’s convex hull.

segment_minimum_width_with

</>

pub fn segment_minimum_width_with(
  segment: svg_path.Segment,
  options options: WidthSearchOptions,
) -> Result(WidthExtremum, Error)

Approximate the minimum width of a segment’s convex hull using options.

subpath_diameter

</>

pub fn subpath_diameter(
  subpath: svg_path.Subpath,
) -> Result(WidthExtremum, Error)

Approximate a subpath’s diameter and return a realizing support pair.

subpath_diameter_with

</>

pub fn subpath_diameter_with(
  subpath: svg_path.Subpath,
  options options: WidthSearchOptions,
) -> Result(WidthExtremum, Error)

Approximate a subpath’s diameter using directional search options.

subpath_hull

</>

pub fn subpath_hull(
  subpath: svg_path.Subpath,
) -> Result(svg_path.Subpath, Error)

Compute the convex hull of a subpath.

The result is a closed subpath. Move-only subpaths are treated as a single point at their start. Otherwise each individual segment is first converted to its own convex hull, then those convex loops are unioned one at a time.

subpath_minimum_width

</>

pub fn subpath_minimum_width(
  subpath: svg_path.Subpath,
) -> Result(WidthExtremum, Error)

Approximate the minimum width of a subpath’s convex hull.

subpath_minimum_width_with

</>

pub fn subpath_minimum_width_with(
  subpath: svg_path.Subpath,
  options options: WidthSearchOptions,
) -> Result(WidthExtremum, Error)

Approximate the minimum width of a subpath’s convex hull using options.