Skip to main content

SkeletonPaths

SkeletonPaths converts binary image masks or precomputed skeletons into compact topology graphs and ranked candidate paths.

It is deliberately domain-neutral: it exposes geometry, topology, candidate routes, ranking, and ambiguity without claiming that a selected path is the true drawing or pen direction.

Install

pip install skeletonpaths

For development:

python -m pip install -e ".[dev]"

Quick start

import numpy as np
from skeletonpaths import graph_from_skeleton, select_path

skeleton = np.zeros((9, 9), dtype=bool)
skeleton[4, 1:8] = True

graph = graph_from_skeleton(skeleton, min_spur_length=0.0)
path = select_path(graph, path_kind="open", expected_cycles=0)

print(graph.endpoint_count)  # 2
print(path.xy)

From a binary mask, use graph_from_mask(mask); scikit-image performs the skeletonization step.

graph_from_mask derives radius from the binary mask with a distance transform unless a radius map is supplied. Its min_component_area option filters small connected components and defaults to 0, which keeps every component. graph_from_skeleton expects an already-thinned image and does not derive radius automatically.

Coordinate contract

Input arrays use image indexing [row, column]. Public geometry uses (x=column, y=row).

MVP API

  • graph_from_mask(...)
  • graph_from_skeleton(...)
  • prune_spurs(...)
  • prepare_topology_paths(...)
  • rank_paths(...)
  • select_path(...)
  • PathScore, PathSearchLimitError, SkeletonNode, SkeletonEdge, SkeletonGraph, SkeletonPath

Compatibility names from the extracted InkGrammar implementation are also exported: build_skeleton_graph, rank_topology_paths, and select_topology_path.

The initial path kinds are "open", "loop", and "open-with-loop".

Path ranking and ambiguity

With candidate_xy, route ranking uses symmetric guide distance first, endpoint orientation to break geometric ties, measured confidence next, then expected-length error, sampled turning cost, and edge IDs for deterministic tie-breaking. Without a guide, measured confidence leads. PathScore reports these measurements in pixel units, confidence, and squared radians for turning cost.

expected_cycles constrains each candidate route, not the whole graph's cycle count. SkeletonGraph.cycle_count remains a graph-level diagnostic. Topology enumeration is bounded by max_paths (default 10_000); exceeding the limit raises PathSearchLimitError.

Skeleton topology is undirected. A selected orientation follows candidate geometry and endpoint constraints, but does not establish physical drawing direction. SkeletonPath.ambiguous reports competing routes, while orientation_ambiguous reports uncertainty between orientations of the same route. Neither flag changes measured confidence.

Versioning

The package version is derived from Git tags with setuptools-scm; there is no hard-coded package version. Tag releases as, for example, v0.1.0.

Outside a Git checkout, source builds use the configured development fallback version.

Development

pytest
python -m build
python -m twine check dist/*

License

Apache-2.0.

Metadata

Release files for skeletonpaths 0.1.0

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

Source distribution (sdist)

Source distribution for skeletonpaths 0.1.0
File Size Uploaded Provenance Actions
skeletonpaths-0.1.0.tar.gz 31.4 kB Without provenance Details for skeletonpaths-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 50.1 kB

Release files / skeletonpaths-0.1.0.tar.gz

Download URL skeletonpaths-0.1.0.tar.gz
Size 31.4 kB
Tags Source
SHA-256 checksum
How to use checksums
0de7ecd908db46d2494dbbe61b9af1eb247533a4414032faad6d2aa796636e41
BLAKE2b-256 checksum
How to use checksums
098a7c7aa6a28e9f180866c9a718759befb04885b83dd782069bb40f0a60a364
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / skeletonpaths-0.1.0-py3-none-any.whl

Download URL skeletonpaths-0.1.0-py3-none-any.whl
Size 18.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
293235d8abc333e38f0d85ab2e0e52683151a1c9416c4202857c40c3ad8b89c9
BLAKE2b-256 checksum
How to use checksums
d590ea53cdb6bdebb8db3fb1e1eaa09815e2eb5dbe55f518159c231bd3fc5ee2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for skeletonpaths 0.1.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

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