mesh-skeleton 1.0.0

Extract connected skeletal graphs (centerlines) from 3D meshes

Mesh Skeleton

Extract connected skeletal graphs from 3D meshes. Unlike point-cloud skeletons, this tool preserves full connectivity as a NetworkX graph — enabling direct path traversal, branch analysis, and navigation.

Installation

pip install mesh-skeleton

Or from source:

git clone https://github.com/iamsalvatore/mesh-skeleton.git
cd mesh-skeleton
pip install -e .

Quick Start

Command Line

python -m mesh_skeleton input_mesh.obj                          # basic extraction
python -m mesh_skeleton input_mesh.stl -o skeleton.ply -r 256   # custom resolution
python -m mesh_skeleton input_mesh.obj --no_viz                 # skip visualization

Python API

import trimesh
from mesh_skeleton import SkeletonExtractor

mesh = trimesh.load('model.obj')
extractor = SkeletonExtractor(mesh, voxel_resolution=256)
skeleton_coords = extractor.extract_skeleton()

# Access the graph
G = extractor.skeleton_graph        # NetworkX graph
endpoints = extractor.endpoints      # degree-1 nodes
junctions = extractor.junctions      # degree-3+ nodes
main_path = extractor.main_path      # longest path indices

# Custom path between two world-space points
centerline = extractor.get_ordered_centerline(start_point=[0,0,0], end_point=[1,1,1])

# Save PLY + JSON
extractor.save_skeleton(skeleton_coords, 'skeleton.ply')

How It Works

1. Interior fill — watertight meshes use ray-cast containment (mesh.contains); non-watertight meshes use surface voxelization + morphological closing + exterior flood-fill
2. Skeletonization — topological thinning via scikit-image
3. Graph construction — 26-connected voxel neighbors linked via KDTree
4. Connectivity enforcement — disconnected components bridged with interpolated edges
5. Path analysis — endpoints, junctions, main centerline (double-BFS), and non-overlapping branch segments (edge-walking)

GPU Acceleration

When PyTorch with CUDA is available, voxelization and morphological operations run on GPU automatically. No code changes needed — falls back to CPU transparently.

Output Files

skeleton.ply

PLY with vertex positions and edge connectivity.

skeleton_graph.json

{
  "vertices": [[x, y, z], ...],
  "edges": [[v1, v2], ...],
  "endpoints": [0, 5, ...],
  "junctions": [12, 34, ...],
  "main_path": [0, 1, 2, ...],
  "branch_paths": [[12, 13, 14], ...]
}

CLI Arguments

Argument	Default	Description
input_mesh	required	Input mesh file (OBJ, STL, PLY, etc.)
-o, --output	skeleton.ply	Output file path
-r, --resolution	256	Voxel grid resolution (128=fast, 256=balanced, 512=detailed)
--no_viz	off	Skip matplotlib visualization

Resolution Guide

Resolution	Use case	Notes
128	Quick preview	Fast, coarse detail
256	Production	Balanced quality and speed
512	High detail	Slower, fine structures preserved

Troubleshooting

Empty skeleton — verify mesh has valid geometry and consistent normals. Try increasing resolution.

Many disconnected components — components <10 voxels are pruned; larger ones are bridged automatically within mesh_scale * 0.1 distance. Check if mesh is watertight.

Slow processing — the bottleneck is skeletonize (CPU-bound). Reduce resolution for faster results.

License

MIT — see LICENSE.