svg_path/offset

Path offset construction.

This module follows the same basic model as svgpathsio: lines and circular arcs are offset exactly, while other curves are offset by fitted cubic Beziers. Cubic approximations are checked by sampling the true normal extrusion of the source curve and measuring its distance to the proposed offset. If the error is too large, the source curve is split and each half is offset recursively.

Subpath and path offsets create a provisional one-sided offset walk by connecting adjacent segment offsets with the requested join style. The public trimmed offset splits that walk at self-intersections, removes sections that lie inside the forbidden distance tube around the original subpath, then keeps the remaining sections in provisional traversal order. Because trimming can split an offset or remove it entirely, subpath and path offsets return Path.

The *_untrimmed helpers expose the provisional offset walk directly. It is useful for debugging, drawing raw construction geometry, or implementing a different trimming policy.

subpath_band and path_band construct two signed offset walks and trim them together. They do not add caps or bridges. subpath_stroke and path_stroke add endpoint caps for open subpaths. Closed strokes use the same capless per-subpath band construction.

Types

Cap

</>

Cap style used at open stroke endpoints.

pub type Cap {
  Butt
  Square
  RoundCap
}

Constructors

```
Butt
```
End the stroke exactly at the endpoint.
```
Square
```
Extend the stroke by half its width beyond the endpoint.
```
RoundCap
```
Add a semicircular endpoint cap.

Error

</>

Errors returned by offset helpers.

pub type Error {
  PathError(svg_path.Error)
  InvalidTolerance(tolerance: Float)
  InvalidSamples(samples: Int)
  InvalidMaxDepth(max_depth: Int)
  InvalidMiterLimit(miter_limit: Float)
  InvalidStalledOffsetDiameter(diameter: Float)
  InvalidStrokeWidth(width: Float)
  DegenerateTangent(t: Float)
  MaxDepthReached(error: Float)
  NonFinite
}

Constructors

```
PathError(svg_path.Error)
```
An underlying path operation failed.
```
InvalidTolerance(tolerance: Float)
```
The offset tolerance must be greater than zero.
```
InvalidSamples(samples: Int)
```
The number of divergence samples must be greater than zero.
```
InvalidMaxDepth(max_depth: Int)
```
The recursive subdivision limit must be greater than zero.
```
InvalidMiterLimit(miter_limit: Float)
```
The miter limit must be greater than zero.
```
InvalidStalledOffsetDiameter(diameter: Float)
```
The stalled offset diameter must be non-negative.
```
InvalidStrokeWidth(width: Float)
```
Stroke width must be greater than zero.
```
DegenerateTangent(t: Float)
```
A segment tangent was too small to define a stable normal direction.
```
MaxDepthReached(error: Float)
```
Refinement could not produce an offset within the requested tolerance.
```
NonFinite
```
A calculation produced a non-finite coordinate.

FittingOptions

</>

Cubic fitting controls used by the recursive offset builders.

tolerance bounds the sampled geometric error of a fitted offset curve, samples controls the number of check samples, and max_depth limits recursive subdivision.

pub type FittingOptions {
  FittingOptions(tolerance: Float, samples: Int, max_depth: Int)
}

Constructors

FittingOptions(tolerance: Float, samples: Int, max_depth: Int)

Join

</>

Join style used when offsetting adjacent subpath segments.

This covers the common SVG stroke-linejoin values bevel, miter, and round. SVG 2 also describes miter-clip and arcs; those are not exposed here yet.

pub type Join {
  Bevel
  Miter(miter_limit: Float)
  Round
}

Constructors

```
Bevel
```
Connect adjacent offset segments with a straight line.
```
Miter(miter_limit: Float)
```
Extend the offset tangents toward their intersection when the miter stays within miter_limit; otherwise fall back to Bevel.
```
Round
```
Connect adjacent offset segments with a circular SVG arc.

Options

</>

Options for offset construction.

fitting controls offset approximation, trimming controls projection and root-finding used while pruning, and stalled_offset_diameter decides when the stalled-run builder treats an offset piece as too small to keep as an ordinary independently fitted segment.

pub type Options {
  Options(
    fitting: FittingOptions,
    trimming: svg_path.DistanceOptions,
    stalled_offset_diameter: Float,
    join: Join,
  )
}

Constructors

Options(
  fitting: FittingOptions,
  trimming: svg_path.DistanceOptions,
  stalled_offset_diameter: Float,
  join: Join,
)

Values

default_options

</>

pub fn default_options() -> Options

Return default options for offset construction.

path

</>

pub fn path(
  path: svg_path.Path,
  distance distance: Float,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path by a signed distance.

path_band

</>

pub fn path_band(
  path: svg_path.Path,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path at two signed distances and trim each pair of sides together.

path_band_untrimmed

</>

pub fn path_band_untrimmed(
  path: svg_path.Path,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path at two signed distances without trimming any side.

path_band_untrimmed_with

</>

pub fn path_band_untrimmed_with(
  path path: svg_path.Path,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
  options options: Options,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path at two signed distances without trimming any side, using explicit options.

path_band_with

</>

pub fn path_band_with(
  path path: svg_path.Path,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
  options options: Options,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path at two signed distances using explicit options.

path_stroke

</>

pub fn path_stroke(
  path: svg_path.Path,
  width width: Float,
) -> Result(svg_path.Path, Error)

Stroke every subpath in a path with the default butt cap.

path_stroke_with

</>

pub fn path_stroke_with(
  path path: svg_path.Path,
  width width: Float,
  cap cap: Cap,
  options options: Options,
) -> Result(svg_path.Path, Error)

Stroke every subpath in a path using explicit cap and offset options.

path_untrimmed

</>

pub fn path_untrimmed(
  path: svg_path.Path,
  distance distance: Float,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path without trimming self-intersections.

path_untrimmed_with

</>

pub fn path_untrimmed_with(
  path path: svg_path.Path,
  distance distance: Float,
  options options: Options,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path without trimming self-intersections using explicit options.

path_with

</>

pub fn path_with(
  path path: svg_path.Path,
  distance distance: Float,
  options options: Options,
) -> Result(svg_path.Path, Error)

Offset every subpath in a path by a signed distance using explicit options.

segment

</>

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

Offset one segment by a signed distance.

Positive distances offset to the right of the segment direction. For a line from (0, 0) to (10, 0), distance: 2.0 returns a line from (0, -2) to (10, -2).

Curves return an open subpath because the result may need several pieces to stay within tolerance. Circular arcs offset to circular arcs; non-circular arcs and Beziers use cubic fitting.

segment_with

</>

pub fn segment_with(
  segment segment: svg_path.Segment,
  distance distance: Float,
  options options: Options,
) -> Result(svg_path.Subpath, Error)

Offset one segment by a signed distance using explicit options.

subpath

</>

pub fn subpath(
  subpath: svg_path.Subpath,
  distance distance: Float,
) -> Result(svg_path.Path, Error)

Offset a subpath by a signed distance.

Positive distances offset to the right of the subpath direction. Adjacent offset segments are connected using default_options().join. The result is a path because trimming self-intersections can split the offset into multiple subpaths or remove it entirely.

The provisional offset is split at self-intersections. Each section is sampled at global section-length parameters 0.1, 0.2, ..., 0.9; sections with fewer than five samples at least abs(distance) - options.fitting.tolerance from the original subpath are removed.

subpath_band

</>

pub fn subpath_band(
  subpath: svg_path.Subpath,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
) -> Result(svg_path.Path, Error)

Offset a subpath at two signed distances and trim the two sides together.

No caps, bridges, or fill-rule interpretation are added. The two provisional offset walks are split at their own self-intersections and at intersections with each other, then each section is tested against the original subpath’s distance tube. This supports ordinary capless stroke sides, one-sided bands, and asymmetric bands such as two positive offsets.

subpath_band_untrimmed

</>

pub fn subpath_band_untrimmed(
  subpath: svg_path.Subpath,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
) -> Result(svg_path.Path, Error)

Offset a subpath at two signed distances without trimming either side.

This returns the two provisional offset walks in one path, with the distance_a side first and the distance_b side second. No caps, bridges, pairwise trimming, self-intersection pruning, or fill-rule interpretation are added.

subpath_band_untrimmed_with

</>

pub fn subpath_band_untrimmed_with(
  subpath subpath: svg_path.Subpath,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
  options options: Options,
) -> Result(svg_path.Path, Error)

Offset a subpath at two signed distances without trimming either side, using explicit options.

subpath_band_with

</>

pub fn subpath_band_with(
  subpath subpath: svg_path.Subpath,
  distance_a distance_a: Float,
  distance_b distance_b: Float,
  options options: Options,
) -> Result(svg_path.Path, Error)

Offset a subpath at two signed distances using explicit options.

subpath_offset_map

</>

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

Build a local coordinate map around a subpath.

The returned function interprets its input point as local path coordinates: x is true arc length along the source subpath, and y is signed offset from that point. Positive offsets use this module’s usual convention: to the right of the subpath direction.

Open subpaths reject x values outside 0.0..subpath_length. Closed subpaths wrap x modulo the subpath length. Empty and zero-length subpaths cannot define a stable normal direction and return an error.

subpath_offset_map_with

</>

pub fn subpath_offset_map_with(
  subpath: svg_path.Subpath,
  options options: svg_path.LengthOptions,
) -> Result(
  fn(svg_path.Point) -> Result(svg_path.Point, Error),
  Error,
)

Build a local coordinate map around a subpath using explicit length options.

subpath_stroke

</>

pub fn subpath_stroke(
  subpath: svg_path.Subpath,
  width width: Float,
) -> Result(svg_path.Path, Error)

Stroke a subpath with the default butt cap.

Open subpaths build one closed provisional stroke boundary from the two offset sides and endpoint caps, then keep sections that separate points inside the intended stroke from points outside it. Closed subpaths use the same capless construction as subpath_band.

subpath_stroke_with

</>

pub fn subpath_stroke_with(
  subpath subpath: svg_path.Subpath,
  width width: Float,
  cap cap: Cap,
  options options: Options,
) -> Result(svg_path.Path, Error)

Stroke a subpath using explicit cap and offset options.

subpath_untrimmed

</>

pub fn subpath_untrimmed(
  subpath: svg_path.Subpath,
  distance distance: Float,
) -> Result(svg_path.Subpath, Error)

Offset a subpath without trimming self-intersections.

This returns the provisional one-sided offset walk. Adjacent segment offsets are connected with default_options().join; the result may self-intersect or contain sections that a trimmed offset would remove.

subpath_untrimmed_with

</>

pub fn subpath_untrimmed_with(
  subpath subpath: svg_path.Subpath,
  distance distance: Float,
  options options: Options,
) -> Result(svg_path.Subpath, Error)

Offset a subpath without trimming self-intersections using explicit options.

subpath_with

</>

pub fn subpath_with(
  subpath subpath: svg_path.Subpath,
  distance distance: Float,
  options options: Options,
) -> Result(svg_path.Path, Error)

Offset a subpath by a signed distance using explicit options.