skeliner

A lightweight skeletonizer that converts neuron meshes into biophysical‑modelling‑ready morphologies. It extracts an acyclic center‑line skeleton, estimates per‑node radii, detects the soma, and bridges small gaps. It also provides robust contact‑site mapping between pairs of cells using both skeletons and meshes.

Features

• Mesh Preprocessing

  • remove mesh anomolies such as parallel faces due to chunk merging failures, gaps (broken neurites), fusions (wrong connections)
  • find and classify soma, organelles, neurites and fragments that should be descarded

• Mesh → SWC skeletons

  • Center‑line, acyclic skeleton.
  • Per‑node radii with multiple estimators (median/mean/trim) and an automatic recommendation.
  • Ellipsoidal soma detection near the soma centroid.
  • Bridges disconnected mesh components back to the soma (gap‑closing) and prunes tiny peri‑soma artefacts.
  • SWC and NPZ export with metadata;

• Pairwise contact sites (two cells)

  • Skeleton‑based seeding: fast KD‑tree search finds node↔node proximity pairs with tolerance; returns contact midpoints and per‑node loci.
  • Mesh‑based patches: around seeds, projects to both meshes and extracts touching triangle patches; returns per‑site areas on A/B and their mean, plus compact AABBs for downstream use.
  • Optional skeleton‑only approximation of contact sites/areas when meshes are unavailable.

• I/O, visualization, diagnostics and post-processing

  • Read/write SWC and compact NPZ; load meshes via trimesh.
  • 2D projections and 3D viewers for meshes, skeletons, and contact patches.
  • Various diagnostics and post-processing tools.

Installation

pip install skeliner

or from source:

git clone https://github.com/berenslab/skeliner.git

# with uv
uv sync --all-extras

# or not
pip install -e "skeliner[dev]"

Quickstart

Skeletonize a mesh and save SWC

import skeliner as sk

mesh = sk.io.load_mesh("cellA.obj")  # or trimesh.load_mesh directly
skel = sk.skeletonize(mesh, unit="nm", verbose=True)

# Choose the recommended radius column (median/mean/trim)
print("Recommended radius:", skel.recommend_radius())

# Save SWC (e.g. convert nm → µm on write)
skel.to_swc("cellA.swc", scale=1e-3)
# Also persist a compact NPZ for fast reload
skel.to_npz("cellA.npz")

Calibrate skeleton radii

The quick skeletonization process often yields biased radius estimates, for two reasons:

1. The raw radius estimators compute the distance to the node center, which is biased too be too low for cylindrical segments.
2. The mesh may have internal strucutre, typically from mitochondria or other organelles, which reduces the apparent radius.

Problem (1) is adressed by using the distance to the midline rather than the center point.
Problem (2) is adressed using ray‑casting to remove inner vertices of the mesh. This is computationally expensive, so per default it is only done for nodes that have many vertices. This can be controlled via the min_verts_q_outer parameter.

You can use sk.post.calibrate_radii to improve it:

import skeliner as sk

mesh = sk.io.load_mesh("cellA.obj")  # or trimesh.load_mesh directly
skel = sk.skeletonize(mesh, unit="nm", verbose=True)

# Calibrate radii against the mesh (takes a few minutes)
sk.post.calibrate_radii(
    skel=skel,
    mesh=mesh,
    min_n_outer=20,
    min_frac_outer=0.33,
    min_verts_q_outer=80.,  # Set to 0 to check all nodes for internal structure, set to 100 to skip this step
    rays_num_outer=30,
    rays_thresh_outer=0.2,
    verbose=True,
    aggregate='trim',
    store_key="calibrated",
)

Mesh preprocessing

It's highly recommended to run the auto mesh preprocessing pipeline before skeletonization, as the raw mesh full of artifacts that might bias the geodedic binning.

import skeliner as sk

mesh = sk.io.load_mesh("cellA.obj")  # or trimesh.load_mesh directly
mesh, components = sk.preprocess(mesh, compact=True, verbose=True)
skel_preproc = sk.skeletonize(mesh=mesh, components=components, verbose=True)

But it will of course take longer time to produce the skeleton.

Find contact sites between two cells (skeleton + mesh)

import skeliner as sk

meshA = sk.io.load_mesh("cellA.obj")
meshB = sk.io.load_mesh("cellB.obj")
A = sk.skeletonize(meshA)
B = sk.skeletonize(meshB)

# 1) skeleton-based seeds (delta in the same unit as the skeletons/meshes)
seeds = pair.find_contact_seeds(A, B, exclude_soma=True)
print("seed count:", seeds.n)

# 2) mesh-based contact patches around the seed midpoints
sites = pair.map_contact_sites(meshA, meshB, seeds.pos, unit="nm^2")
print("contact patches:", len(sites.faces_A))
print("mean areas (mesh units^2):", sites.area_mean)

# Optional: visualize patches
# sk.plot.view_contacts(meshA, meshB, sites, sides="A")

See example notebooks for more usage.