[](https://navis-org.github.io/skeletor/) [](https://github.com/navis-org/skeletor/actions/workflows/test-package.yml) [](https://zenodo.org/badge/latestdoi/153085435)
# Skeletor
Unlike its [namesake](https://en.wikipedia.org/wiki/Skeletor), this Python 3
library does not (yet) seek to conquer Eternia but to turn meshes into skeletons.
_Heads-up: skeletor `1.0.0` introduced some breaking changes and major reorganizations._
_Please see the [changelog](https://github.com/navis-org/skeletor/blob/master/NEWS.md)_
_for details._
## Install
```bash
pip3 install skeletor
```
For the dev version:
```bash
pip3 install git+https://github.com/navis-org/skeletor@master
```
#### Dependencies
Automatically installed with `pip`:
- `networkx`
- `numpy`
- `pandas`
- `scipy`
- `scikit-learn`
- `trimesh`
- `tqdm`
- `python-igraph`
- `ncollpyde`
Optional because not strictly required for the core functions but highly recommended:
- [pyglet](https://pypi.org/project/pyglet/) is required by trimesh to preview meshes/skeletons in 3D: `pip3 install pyglet`
- [fastremap](https://github.com/seung-lab/fastremap) for sizeable speed-ups with some methods: `pip3 install fastremap`
## Documentation
Please see the [documentation](https://navis-org.github.io/skeletor/) for details.
The change log can be found [here](https://github.com/navis-org/skeletor/blob/master/NEWS.md).
## Quickstart
For the impatient a quick example:
```Python
>>> import skeletor as sk
>>> mesh = sk.example_mesh()
>>> # To load and use your own mesh instead of the example mesh:
>>> # import trimesh as tm
>>> # mesh = tm.Trimesh(vertices, faces) # or...
>>> # mesh = tm.load_mesh('mesh.obj')
>>> fixed = sk.pre.fix_mesh(mesh, remove_disconnected=5, inplace=False)
>>> skel = sk.skeletonize.by_wavefront(fixed, waves=1, step_size=1)
>>> skel
<Skeleton(vertices=(1258, 3), edges=(1194, 2), method=wavefront)>
```
All skeletonization methods return a `Skeleton` object. These are just
convenient objects to represent and inspect the results.
```Python
>>> # location of vertices (nodes)
>>> skel.vertices
array([[16744, 36720, 26407],
...,
[22076, 23217, 24472]])
>>> # child -> parent edges
>>> skel.edges
array([[ 64, 31],
...,
[1257, 1252]])
>>> # Mapping for mesh to skeleton vertex indices
>>> skel.mesh_map
array([ 157, 158, 1062, ..., 525, 474, 547])
>>> # SWC table
>>> skel.swc.head()
node_id parent_id x y z radius
0 0 -1 16744.005859 36720.058594 26407.902344 0.000000
1 1 -1 5602.751953 22266.756510 15799.991211 7.542587
2 2 -1 16442.666667 14999.978516 10887.916016 5.333333
>>> # Save SWC file
>>> skel.save_swc('skeleton.swc')
```
If you installed `pyglet` (see above) you can also use `trimesh`'s plotting
capabilities to inspect the results:
```Python
>>> skel.show(mesh=True)
```
## Benchmarks
[Benchmarks](https://github.com/navis-org/skeletor/blob/master/benchmarks/skeletor_benchmark.ipynb)
were run on a 2018 MacBook Pro (2.2 GHz Core i7, 32Gb memory) with optional
`fastremap` dependency installed. Note some of these functions (e.g.
contraction and TEASAR/vertex cluster skeletonization) can vary a lot in
speed based on parameterization.
## Contributing
Pull requests are always welcome!
## References & Acknowledgments
Mesh contraction and the edge collapse approach are based on this paper:
`[1] Au OK, Tai CL, Chu HK, Cohen-Or D, Lee TY. Skeleton extraction by mesh contraction. ACM Transactions on Graphics (TOG). 2008 Aug 1;27(3):44.`
The abstract and the paper can be found [here](http://visgraph.cse.ust.hk/projects/skeleton/).
Also see [this](https://www.youtube.com/watch?v=-H7n59YQCRM&feature=youtu.be) YouTube video.
Some of the code in skeletor was modified from the
[Py_BL_MeshSkeletonization](https://github.com/aalavandhaann/Py_BL_MeshSkeletonization)
addon for Blender 3D created by #0K Srinivasan Ramachandran and published under GPL3.
The mesh TEASAR approach was adapted from the implementation in
[meshparty](https://github.com/sdorkenw/MeshParty) by Sven Dorkenwald, Casey
Schneider-Mizell and Forrest Collman.
Raw data
{
"_id": null,
"home_page": "https://github.com/navis-org/skeletor",
"name": "skeletor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "mesh skeletonization mesh contraction skeleton extraction",
"author": "Philipp Schlegel",
"author_email": "pms70@cam.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/30/1b/a17a7b68c691c0e80ec2935012eaa3a1aa90953ee00e9681e235a4f6d449/skeletor-1.3.0.tar.gz",
"platform": null,
"description": "[](https://navis-org.github.io/skeletor/) [](https://github.com/navis-org/skeletor/actions/workflows/test-package.yml) [](https://zenodo.org/badge/latestdoi/153085435)\n\n# Skeletor\nUnlike its [namesake](https://en.wikipedia.org/wiki/Skeletor), this Python 3\nlibrary does not (yet) seek to conquer Eternia but to turn meshes into skeletons.\n\n_Heads-up: skeletor `1.0.0` introduced some breaking changes and major reorganizations._\n_Please see the [changelog](https://github.com/navis-org/skeletor/blob/master/NEWS.md)_\n_for details._\n\n## Install\n```bash\npip3 install skeletor\n```\n\nFor the dev version:\n```bash\npip3 install git+https://github.com/navis-org/skeletor@master\n```\n\n#### Dependencies\nAutomatically installed with `pip`:\n- `networkx`\n- `numpy`\n- `pandas`\n- `scipy`\n- `scikit-learn`\n- `trimesh`\n- `tqdm`\n- `python-igraph`\n- `ncollpyde`\n\nOptional because not strictly required for the core functions but highly recommended:\n- [pyglet](https://pypi.org/project/pyglet/) is required by trimesh to preview meshes/skeletons in 3D: `pip3 install pyglet`\n- [fastremap](https://github.com/seung-lab/fastremap) for sizeable speed-ups with some methods: `pip3 install fastremap`\n\n## Documentation\nPlease see the [documentation](https://navis-org.github.io/skeletor/) for details.\n\nThe change log can be found [here](https://github.com/navis-org/skeletor/blob/master/NEWS.md).\n\n## Quickstart\nFor the impatient a quick example:\n\n```Python\n>>> import skeletor as sk\n>>> mesh = sk.example_mesh()\n>>> # To load and use your own mesh instead of the example mesh:\n>>> # import trimesh as tm\n>>> # mesh = tm.Trimesh(vertices, faces) # or...\n>>> # mesh = tm.load_mesh('mesh.obj')\n>>> fixed = sk.pre.fix_mesh(mesh, remove_disconnected=5, inplace=False)\n>>> skel = sk.skeletonize.by_wavefront(fixed, waves=1, step_size=1)\n>>> skel\n<Skeleton(vertices=(1258, 3), edges=(1194, 2), method=wavefront)>\n```\n\nAll skeletonization methods return a `Skeleton` object. These are just\nconvenient objects to represent and inspect the results.\n\n```Python\n>>> # location of vertices (nodes)\n>>> skel.vertices\narray([[16744, 36720, 26407],\n ...,\n [22076, 23217, 24472]])\n>>> # child -> parent edges\n>>> skel.edges\narray([[ 64, 31],\n ...,\n [1257, 1252]])\n>>> # Mapping for mesh to skeleton vertex indices\n>>> skel.mesh_map\narray([ 157, 158, 1062, ..., 525, 474, 547])\n>>> # SWC table\n>>> skel.swc.head()\n node_id parent_id x y z radius\n0 0 -1 16744.005859 36720.058594 26407.902344 0.000000\n1 1 -1 5602.751953 22266.756510 15799.991211 7.542587\n2 2 -1 16442.666667 14999.978516 10887.916016 5.333333\n>>> # Save SWC file\n>>> skel.save_swc('skeleton.swc')\n```\n\nIf you installed `pyglet` (see above) you can also use `trimesh`'s plotting\ncapabilities to inspect the results:\n\n```Python\n>>> skel.show(mesh=True)\n```\n\n\n\n## Benchmarks\n\n\n[Benchmarks](https://github.com/navis-org/skeletor/blob/master/benchmarks/skeletor_benchmark.ipynb)\nwere run on a 2018 MacBook Pro (2.2 GHz Core i7, 32Gb memory) with optional\n`fastremap` dependency installed. Note some of these functions (e.g.\ncontraction and TEASAR/vertex cluster skeletonization) can vary a lot in\nspeed based on parameterization.\n\n## Contributing\nPull requests are always welcome!\n\n## References & Acknowledgments\nMesh contraction and the edge collapse approach are based on this paper:\n`[1] Au OK, Tai CL, Chu HK, Cohen-Or D, Lee TY. Skeleton extraction by mesh contraction. ACM Transactions on Graphics (TOG). 2008 Aug 1;27(3):44.`\nThe abstract and the paper can be found [here](http://visgraph.cse.ust.hk/projects/skeleton/).\nAlso see [this](https://www.youtube.com/watch?v=-H7n59YQCRM&feature=youtu.be) YouTube video.\n\nSome of the code in skeletor was modified from the\n[Py_BL_MeshSkeletonization](https://github.com/aalavandhaann/Py_BL_MeshSkeletonization)\naddon for Blender 3D created by #0K Srinivasan Ramachandran and published under GPL3.\n\nThe mesh TEASAR approach was adapted from the implementation in\n[meshparty](https://github.com/sdorkenw/MeshParty) by Sven Dorkenwald, Casey\nSchneider-Mizell and Forrest Collman.\n",
"bugtrack_url": null,
"license": "GNU GPL V3",
"summary": "Python 3 library to extract skeletons from 3D meshes",
"version": "1.3.0",
"project_urls": {
"Changelog": "https://github.com/navis-org/skeletor/blob/master/NEWS.md",
"Documentation": "https://navis-org.github.io/skeletor/",
"Homepage": "https://github.com/navis-org/skeletor",
"Source": "https://github.com/navis-org/skeletor"
},
"split_keywords": [
"mesh",
"skeletonization",
"mesh",
"contraction",
"skeleton",
"extraction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b1ed40161048c0423790fa028c1385f3c88b02aed615ec64ac14cbc7617f921c",
"md5": "0f918f7a7365023011f05f97b724d0a9",
"sha256": "e36dee67d37e5bb214a4906809199a207cf55848ddb8050a5e34e224488f2080"
},
"downloads": -1,
"filename": "skeletor-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f918f7a7365023011f05f97b724d0a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 208605,
"upload_time": "2024-04-07T14:08:31",
"upload_time_iso_8601": "2024-04-07T14:08:31.239607Z",
"url": "https://files.pythonhosted.org/packages/b1/ed/40161048c0423790fa028c1385f3c88b02aed615ec64ac14cbc7617f921c/skeletor-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "301ba17a7b68c691c0e80ec2935012eaa3a1aa90953ee00e9681e235a4f6d449",
"md5": "d79e50c7e5141e3cdb5960743e36ed97",
"sha256": "71fe15a40593589d5174019326515e739ee3ddb97323eca00b60f5aea0f78157"
},
"downloads": -1,
"filename": "skeletor-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "d79e50c7e5141e3cdb5960743e36ed97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 194363,
"upload_time": "2024-04-07T14:08:32",
"upload_time_iso_8601": "2024-04-07T14:08:32.651115Z",
"url": "https://files.pythonhosted.org/packages/30/1b/a17a7b68c691c0e80ec2935012eaa3a1aa90953ee00e9681e235a4f6d449/skeletor-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-07 14:08:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "navis-org",
"github_project": "skeletor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.16.0"
]
]
},
{
"name": "trimesh",
"specs": [
[
">=",
"2.38.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.50.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"0.24.2"
]
]
},
{
"name": "networkx",
"specs": [
[
">=",
"2.4"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"0.23"
]
]
},
{
"name": "igraph",
"specs": [
[
">=",
"0.8"
]
]
},
{
"name": "ncollpyde",
"specs": [
[
">=",
"0.14.0"
]
]
}
],
"lcname": "skeletor"
}
JSON
