Mesh2Connectomics Improvements Research Dossier
Historical research snapshot, not a current implementation audit. Several gaps described below were subsequently addressed; consult the remaining validation gates. Proposed algorithms and speedups are not validated results.
Goal And Trigger
Investigate the current mesh-to-connectomics heuristics in the SynDB codebase and identify bleeding-edge improvements. The pipeline extracts connectome graphs from public 3D EM segmentation volumes (songbird, MICrONS, fly) by detecting neuron contacts, scoring synapses, assigning pre/post direction, classifying cell types, and building validated graphs.
Current Reality
The pipeline exists in two places:
- Design: Original mathematical design proposal
- Implementation:
crates/tools/etl/src/neuroglancer/(9 modules, ~3000 lines)
What Works (Implemented)
| Stage | Module | Status |
|---|---|---|
| 0: Data acquisition | mesh.rs, draco.rs, shard*.rs, volume.rs | Working for standard formats; SyConn format skipped |
| 1: Morphology | morphology.rs | Voxel-based volume/SA/sphericity working |
| 1: Skeleton | skeleton.rs | TEASAR with chamfer DT + Dijkstra; bottleneck at ~2h/8.5K neurons |
| 2: Voxel contact | voxel_contact.rs | O(n) single pass working |
| 2: Synapse-aware | synapse_aware.rs | 26-neighborhood voting working for songbird |
| 3: Geometry | geometry.rs | Chamfer DT, SDF gradients, Laplace-Beltrami curvature — implemented but never called from pipeline |
| 4: Scoring | scoring.rs | Logistic regression with 5 features; coefficients are literature priors |
| 5: Assignment | assign.rs | Weighted decision score (curvature + diameter + swelling) — uses dummy morphologies |
| 6: Process classify | process.rs | Logistic regression on skeleton features — skeleton not wired into pipeline |
| 7: Cell type | celltype.rs | Rule-based per species — GMM not implemented |
| 8: Graph | graph.rs | petgraph-based; Erdos-Renyi null model (incorrect) |
| 9: Output | pipeline.rs | Parquet + JSON output working |
Critical Gap: Geometry data does not flow
pipeline.rs:score_and_assign() passes mean_curvature: 0.0 to scoring and LocalMorphology::default() to assignment. The geometry functions in geometry.rs (contact_normals, voxel_curvature) exist but are never called. This means:
- Normal alignment scores are hardcoded to 0.5 for voxel contacts
- Curvature scores are computed from zero (always max)
- Pre/post assignment uses default morphology (axon-like: 300nm diameter, slight convexity, rating 1.5)
- Process-based assignment is not wired (the design’s strongest signal)
Evidence Inventory
| File | Lines | Key finding |
|---|---|---|
| Original design proposal | 1438 at audit time | Section 19 records the original open questions |
crates/tools/etl/src/neuroglancer/pipeline.rs | 505 | score_and_assign at L267: zero curvature, dummy morphologies |
crates/tools/etl/src/neuroglancer/geometry.rs | 397 | contact_normals(), voxel_curvature() exist but unused in pipeline |
crates/tools/etl/src/neuroglancer/assign.rs | 339 | estimate_local_morphology() returns ::default() — stub only |
crates/tools/etl/src/neuroglancer/scoring.rs | 239 | Logistic regression; no uncertainty, no GB tree alternative |
crates/tools/etl/src/neuroglancer/skeleton.rs | 577 | HashMap-based Dijkstra — 100x slower than optimized C++ dijkstra3d |
crates/tools/etl/src/neuroglancer/contact.rs | 394 | Mesh contact uses stride-100 vertex sampling, no parry3d BVH integrated |
crates/tools/etl/src/neuroglancer/graph.rs | 396 | Null model is Erdos-Renyi; degree-preserving rewiring absent |
crates/tools/etl/src/neuroglancer/celltype.rs | 133 | GMM not implemented; rule-based only |
crates/tools/etl/src/neuroglancer/process.rs | 211 | Skeleton features extracted but never called from pipeline |
crates/tools/etl/src/mesh_connectomics/mod.rs | 808 | Main ETL entry point; SyConn format undecodable, mesh contact not integrated |
Improvement Opportunities
Tier 1: Fix Broken Core Functionality (Highest Impact)
1.1 Wire Geometry into Scoring and Assignment
Problem: The most basic pipeline function — using actual geometry to score synapses — is broken. score_contact receives mean_curvature: 0.0 and voxel contacts get normal_alignment: 0.5 (a guess). Assignment gets LocalMorphology::default() — no real curvature, diameter, or swelling data.
Fix: In pipeline.rs:score_and_assign():
- Call
geometry::contact_normals()for each contact to get real normals - Call
geometry::voxel_curvature()for each contact site - Build real
LocalMorphologyfrom skeleton diameter profile + curvature field - This single change makes the entire scoring and assignment pipeline data-driven
Bleeding-edge alternative: Replace the logistic regression with a gradient-boosted tree (CatBoost/XGBoost) trained on MICrONS ground truth. The design document already mentions this (Section 16.2). XGBoost handles non-linear feature interactions that logistic regression cannot model. Implement via rust-xgboost bindings or export features + train in Python, then embed the model.
1.2 Complete Mesh-Based Contact Detection
Problem: ContactMode::MeshBVH and Hybrid both fall through to detect_voxel_candidates() at pipeline.rs L131-133. The parry3d BVH pipeline from contact.rs and the design doc Section 6.3 is not integrated.
Fix: Wire parry3d::Qbvh-based global scene from design doc Section 14.5:
- Build BVH over all neuron meshes
- Query close pairs within
cleft_threshold_nm - Compute per-vertex normals and curvature from mesh topology
- Estimate contact area from overlapping surface patches
Bleeding edge: Replace stride-sampled vertex distance (current detect_mesh_contact at contact.rs L162) with GPU-based point cloud distance using WGPU compute shaders.
1.3 Implement Multi-Synapse Splitting
Problem: Large contact regions (>2× typical PSD area) may contain multiple adjacent synapses. The design specifies watershed splitting on the curvature field (Section 8.5) but this is not implemented.
Fix: When contact area > 2× AREA_TYPICAL, apply watershed segmentation on the curvature field to identify individual synapse centers. Each sub-region becomes its own synapse record.
1.4 Wire Process Classification into Assignment
Problem: The design’s strongest signal for pre/post assignment is process type (axon→dendrite), but score_and_assign never calls process classification. The pipeline computes NeuronMorphology but doesn’t run skeletonization or process classification during scoring.
Fix: After Stage 1 morphology, run skeleton extraction → process classification → use result in assignment. Add a process_cache: HashMap<u64, ProcessType> parameter to score_and_assign.
1.5 Implement GMM Cell Type Classifier
Problem: Only rule-based classification exists. The GMM from design Section 11.2 would handle continuous morphometric features properly.
Fix: Implement Gaussian Mixture Model on the feature vector (log volume, log SA, log cable length, n_branches, mean diameter, sphericity, Sholl features). Use EM algorithm; initialize with known cell type means when available. For Rust, mixer crate or implement using ndarray.
Tier 2: Modernization (Bleeding Edge Improvements)
2.1 Upgrade TEASAR Skeletonization
Current: HashMap-based Dijkstra with O(V log V) per neuron using HashSet/HashMap for frontier management. The extract_path function creates new HashMaps for each path extraction, causing allocator pressure.
State-of-the-art: Kimimaro (Seung Lab production skeletonizer):
- Multi-label single-pass EDT via
edtC++ library (Meyer’s flooding algorithm, O(V) with near-optimal constant) dijkstra3dspecialized for 3D images (Dijkstra directly on voxel grid, no graph construction)- Process all labels in parallel via
rayon+ shared memory - ~94 seconds for 512³ with 2124 labels on M3 MacBook
Options:
- Rust equivalent: Replace HashMap-based Dijkstra with a priority queue on a flat array. Use
BinaryHeapfor frontier. ReplaceHashSet<(u64,u64,u64)>with a bit-packed flat array for O(1) membership. This matches dijkstra3d’s approach. - FFI to C++
edt+dijkstra3d: Maximum speed but adds build complexity. - WGSL compute shader: GPU-based distance transform. The chamfer DT is embarrassingly parallel.
2.2 Replace Erdos-Renyi Null Model with Degree-Preserving Rewiring
Current: small_world_index compares clustering coefficient to p = E/(N*(N-1)) — an Erdos-Renyi model that doesn’t preserve degree distribution. This is known to produce biased small-world estimates (Betzel et al. 2025).
Fix: Implement the configuration model:
- Create a null distribution by rewiring edges while preserving in/out degree
- Repeat 100-1000 rewiring iterations
- Compute C_rand and L_rand from the rewired ensemble
- Use these for small-world index computation
2.3 Add Uncertainty-Aware Scoring
Current: Binary threshold at 0.5. No uncertainty quantification.
Bleeding edge: Conformal prediction — distribution-free uncertainty sets that are valid under minimal assumptions. For each synapse, produce both a point prediction and a prediction set guaranteed to contain the true label with probability 1-α. This lets us flag low-confidence predictions for human review.
Alternatively, Monte Carlo dropout at inference time: run the logistic regression (or GB tree ensemble) multiple times with stochastic components to estimate prediction variance.
2.4 Add Active Learning Loop
Current: Static coefficients from literature priors.
Bleeding edge: When MICrONS ground truth is available:
- Score candidates with current model
- Sample highest-uncertainty candidates for “human review”
- Retrain scoring coefficients on reviewed data
- Repeat until convergence
This is already noted in the design doc Section 19.3. Implement as a Python validation script that exports Rust-extracted features, trains in scikit-learn/XGBoost, exports coefficients back to Rust.
Tier 3: Performance (GPU / Parallel)
3.1 GPU-Accelerated Distance Transform
The chamfer distance transform (geometry.rs, skeleton.rs) is the bottleneck. The 3-pass 26-neighbor propagation is highly parallelizable.
Option A: WGSL compute shader via wgpu:
- Forward pass: dispatch
szworkgroups, each processing xy-plane - Backward pass: same in reverse
- Third pass: dispatch full grid
- Estimated 10-50× speedup vs. CPU
Option B: Rayon parallel pass with tiling (lower effort):
- Divide volume into 3D tiles
- Process tiles independently with overlap borders
- Merge at tile boundaries
3.2 Parallel Per-Neuron Skeletonization
Current: Serial per-neuron processing. With 8.5K neurons, this dominates runtime.
Fix: Use rayon::par_iter() over segment IDs. Each skeleton extraction is independent. With 32 cores, estimated 20× speedup on the skeletonization stage.
3.3 Multi-Resolution Contact Detection
For very large volumes (whole mouse brain), implement coarse-to-fine:
- Downsample volume 4-8×
- Detect contacts at coarse resolution
- Only read full-resolution chunks for regions with contacts
- Already specified in design Section 19.2
Risks and Constraints
| Risk | Impact | Mitigation |
|---|---|---|
| Changing scoring coefficients retroactively affects all existing ETL results | Medium | Version the scoring model; store model version in pipeline_report.json |
| GPU code requires Vulkan-capable hardware | Low | Keep CPU fallback; make GPU optional via feature flag |
| SyConn mesh format may never be decodable | Medium | Continue using separate SyConn ETL for songbird; document format spec |
| Kimimaro-style optimizations add C++ build deps | Medium | Prefer pure-Rust optimization first; FFI is backup |
| MICrONS ground truth may not be available in pipeline context | Low | The validation setup exists; need to wire it into the scoring module |
| Changing null model changes validation thresholds | Low | Document comparison with both old and new models during transition |
Candidate Next Steps
Phase 1 — Fix Pipeline Core (1-2 sessions)
- Wire geometry into
score_and_assign— callcontact_normals()andvoxel_curvature()from pipeline - Build real
LocalMorphologyfrom skeleton diameter data - Wire process classification into assignment
- Implement degree-preserving rewiring null model
Phase 2 — Algorithm Upgrades (2-3 sessions)
- Optimize TEASAR: flat-array Dijkstra + BinaryHeap + bit-packed membership flags
- Implement multi-synapse watershed splitting
- Implement GMM cell type classifier
- Add conformal prediction uncertainty
Phase 3 — Performance (2-3 sessions)
- Rayon-parallel per-neuron skeletonization
- GPU-accelerated distance transform via wgpu compute shaders
- Multi-resolution contact detection pre-filter
Phase 4 — ML Integration (ongoing)
- MICrONS validation pipeline: feature extraction → Python training → coefficient export
- Embed CatBoost/XGBoost model for synapse scoring
- Active learning loop for continuous improvement
Open Decisions For The User
- Priority: Start with Phase 1 (fix broken geometry flow) which is the highest-impact change, or go straight to Phase 2 (algorithm upgrades)?
- ML approach: Logistic regression refinements via Python (lower risk, proven) or embed a Rust-native GB tree model (bleeding edge)?
- GPU path: Start with Rayon parallelization (simpler, works everywhere) or invest in wgpu compute shaders (faster, hardware-dependent)?
- Skeleton optimization: Pure-Rust optimization of the current Dijkstra (safe, no deps) or bind to edt/dijkstra3d C++ libraries (max speed, build complexity)?
- Scope: Should mesh-based contact detection (parry3d BVH integration) be a priority, or is voxel contact + geometry sufficient for the immediate dataset targets?