Skip to main content

StrokeOutline

StrokeOutline converts finite 2D centerlines into sampled, explicitly closed contours with constant or variable stroke width. It is a pre-1.0 geometry library extracted from InkGrammar. PlanarCurve owns the neutral line and Bézier types; StrokeOutline owns sampling, stroke expansion, and output contours.

StrokeOutline is not a complete SVG/CSS stroker or a general polygon offset/Boolean engine.

Requirements and installation

Python >=3.10. Install the core package with:

python -m pip install strokeoutline

SVG path parsing is optional and requires FontTools:

python -m pip install 'strokeoutline[svg]'

Quick start

from strokeoutline import outline, path_from_polyline

path = path_from_polyline([(0, 0), (10, 0), (15, 5)])
result = outline(path, width=4.0)

print(result.bounds)  # (min_x, min_y, max_x, max_y)

Width is the full stroke diameter, not the radius. OutlineResult is immutable. Its contours and points are tuples, each output contour repeats its first point at the end, and aggregate bounds are None only when there are no contours.

Width profiles

outline() accepts a positive real scalar, a piecewise-linear iterable of (u, width) knots spanning 0..1, or a callable returning a finite positive width. Boolean widths and knots are rejected. Piecewise knots are sampled at their specified progress positions. Callable results are memoized within one outline() call. Callbacks should be deterministic and sufficiently continuous to satisfy the sampling tolerance.

The compatibility default is segment-index progress, restarted for each independent subpath:

u = (segment_index + local_segment_parameter) / segment_count

It is not physical distance. An implicit closing segment participates in the segment count of a closed subpath. To opt into normalized physical arc length, set OutlineConfig(width_parameterization="arclength").

outline_disc(center, diameter) evaluates a width profile at u == 0.5, since a point has no path progression.

Caps and joins

Open-path caps default to "round"; "square" extends by half the endpoint width along the analytic endpoint tangent, and "butt" ends at the centerline endpoint. Caps do not apply to closed paths.

The default join is "legacy", preserving the sampled bisector behavior. It is not a standard miter or bevel join. Opt-in join="miter", "bevel", or "round" selects explicit sampled join construction. miter_limit is a positive ratio, defaulting to 4.0; over-limit miters fall back to bevel geometry.

Sampling and numerical limits

OutlineConfig controls centerline deviation, width interpolation error, tangent-angle change, subdivision depth, caps, joins, and width parameterization. Subdivision is iterative. If tolerances cannot be met, the depth limit is exceeded, or floating-point subdivision makes no progress, StrokeOutline raises SubdivisionLimitError, not RecursionError.

Coordinates and widths may use any consistent units. There is no fixed pixel or font-unit scale. Exact zero-length geometry is rejected; finite precision still affects extremely small features relative to large coordinate translations.

The output is sampled, not an analytic offset. StrokeOutline does not perform Boolean cleanup or guarantee simple topology for arbitrary self-intersections, cusps, or very large offsets.

Composition, PlanarCurve, and SVG

combine_outlines() concatenates contours in order and recomputes bounds. It does not perform a Boolean union. planarcurve.CubicPath can be passed directly to outline(); PlanarCurve remains the semantic owner of its geometry types, which StrokeOutline also re-exports as a convenience.

The optional strokeoutline.svg adapter parses path geometry through FontTools. Regression-tested commands include relative coordinates, horizontal/vertical lines, smooth cubic/quadratic commands, arcs converted to cubic segments, and close paths. SVG parsing is not rendering and does not imply complete CSS/SVG stroke semantics.

Examples and documentation

The examples guide lists seven runnable scripts, their optional dependencies, and their semantic invariants. Importing an example has no output or filesystem side effects.

The Sphinx documentation contains the user guide, concepts, API reference, SVG details, and limitations.

Development

python -m pip install -e '.[dev]'
ruff format --check .
ruff check .
pytest
python docs/make.py html
python docs/make.py doctest
python -m build
python -m twine check dist/*

Metadata

Release files for strokeoutline 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for strokeoutline 0.1.1
File Size Uploaded Provenance Actions
strokeoutline-0.1.1.tar.gz 51.8 kB With provenance Details for strokeoutline-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for strokeoutline 0.1.1
File Interpreter ABI Platform Actions
strokeoutline-0.1.1-py3-none-any.whl Python 3 none any Details for strokeoutline-0.1.1-py3-none-any.whl

Total release size: 73.8 kB

Release files / strokeoutline-0.1.1.tar.gz

Download URL strokeoutline-0.1.1.tar.gz
Size 51.8 kB
Tags Source
SHA-256 checksum
How to use checksums
2ae7940d64ab398e1d92202286557ce566065ec2be28952d7e4811d4bd080f29
BLAKE2b-256 checksum
How to use checksums
f9c23163c7800112cf1997009205a481d95d5d559287878dd1f72e95c5c29014
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / strokeoutline-0.1.1-py3-none-any.whl

Download URL strokeoutline-0.1.1-py3-none-any.whl
Size 22.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5d17bda2093bc2075a897d1e59db29c99c0afa2cca09378474bd42f1f8e45987
BLAKE2b-256 checksum
How to use checksums
b8cb1f815ef0c40fe13a4e8886fc8742d3aeb3df24a93500671d2cfc72845744
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for strokeoutline 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for strokeoutline-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page