Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

What Works (Implemented)

StageModuleStatus
0: Data acquisitionmesh.rs, draco.rs, shard*.rs, volume.rsWorking for standard formats; SyConn format skipped
1: Morphologymorphology.rsVoxel-based volume/SA/sphericity working
1: Skeletonskeleton.rsTEASAR with chamfer DT + Dijkstra; bottleneck at ~2h/8.5K neurons
2: Voxel contactvoxel_contact.rsO(n) single pass working
2: Synapse-awaresynapse_aware.rs26-neighborhood voting working for songbird
3: Geometrygeometry.rsChamfer DT, SDF gradients, Laplace-Beltrami curvature — implemented but never called from pipeline
4: Scoringscoring.rsLogistic regression with 5 features; coefficients are literature priors
5: Assignmentassign.rsWeighted decision score (curvature + diameter + swelling) — uses dummy morphologies
6: Process classifyprocess.rsLogistic regression on skeleton features — skeleton not wired into pipeline
7: Cell typecelltype.rsRule-based per species — GMM not implemented
8: Graphgraph.rspetgraph-based; Erdos-Renyi null model (incorrect)
9: Outputpipeline.rsParquet + 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

FileLinesKey finding
Original design proposal1438 at audit timeSection 19 records the original open questions
crates/tools/etl/src/neuroglancer/pipeline.rs505score_and_assign at L267: zero curvature, dummy morphologies
crates/tools/etl/src/neuroglancer/geometry.rs397contact_normals(), voxel_curvature() exist but unused in pipeline
crates/tools/etl/src/neuroglancer/assign.rs339estimate_local_morphology() returns ::default() — stub only
crates/tools/etl/src/neuroglancer/scoring.rs239Logistic regression; no uncertainty, no GB tree alternative
crates/tools/etl/src/neuroglancer/skeleton.rs577HashMap-based Dijkstra — 100x slower than optimized C++ dijkstra3d
crates/tools/etl/src/neuroglancer/contact.rs394Mesh contact uses stride-100 vertex sampling, no parry3d BVH integrated
crates/tools/etl/src/neuroglancer/graph.rs396Null model is Erdos-Renyi; degree-preserving rewiring absent
crates/tools/etl/src/neuroglancer/celltype.rs133GMM not implemented; rule-based only
crates/tools/etl/src/neuroglancer/process.rs211Skeleton features extracted but never called from pipeline
crates/tools/etl/src/mesh_connectomics/mod.rs808Main 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():

  1. Call geometry::contact_normals() for each contact to get real normals
  2. Call geometry::voxel_curvature() for each contact site
  3. Build real LocalMorphology from skeleton diameter profile + curvature field
  4. 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:

  1. Build BVH over all neuron meshes
  2. Query close pairs within cleft_threshold_nm
  3. Compute per-vertex normals and curvature from mesh topology
  4. 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 edt C++ library (Meyer’s flooding algorithm, O(V) with near-optimal constant)
  • dijkstra3d specialized 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:

  1. Rust equivalent: Replace HashMap-based Dijkstra with a priority queue on a flat array. Use BinaryHeap for frontier. Replace HashSet<(u64,u64,u64)> with a bit-packed flat array for O(1) membership. This matches dijkstra3d’s approach.
  2. FFI to C++ edt + dijkstra3d: Maximum speed but adds build complexity.
  3. 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:

  1. Create a null distribution by rewiring edges while preserving in/out degree
  2. Repeat 100-1000 rewiring iterations
  3. Compute C_rand and L_rand from the rewired ensemble
  4. 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:

  1. Score candidates with current model
  2. Sample highest-uncertainty candidates for “human review”
  3. Retrain scoring coefficients on reviewed data
  4. 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 sz workgroups, 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:

  1. Downsample volume 4-8×
  2. Detect contacts at coarse resolution
  3. Only read full-resolution chunks for regions with contacts
  4. Already specified in design Section 19.2

Risks and Constraints

RiskImpactMitigation
Changing scoring coefficients retroactively affects all existing ETL resultsMediumVersion the scoring model; store model version in pipeline_report.json
GPU code requires Vulkan-capable hardwareLowKeep CPU fallback; make GPU optional via feature flag
SyConn mesh format may never be decodableMediumContinue using separate SyConn ETL for songbird; document format spec
Kimimaro-style optimizations add C++ build depsMediumPrefer pure-Rust optimization first; FFI is backup
MICrONS ground truth may not be available in pipeline contextLowThe validation setup exists; need to wire it into the scoring module
Changing null model changes validation thresholdsLowDocument comparison with both old and new models during transition

Candidate Next Steps

Phase 1 — Fix Pipeline Core (1-2 sessions)

  1. Wire geometry into score_and_assign — call contact_normals() and voxel_curvature() from pipeline
  2. Build real LocalMorphology from skeleton diameter data
  3. Wire process classification into assignment
  4. Implement degree-preserving rewiring null model

Phase 2 — Algorithm Upgrades (2-3 sessions)

  1. Optimize TEASAR: flat-array Dijkstra + BinaryHeap + bit-packed membership flags
  2. Implement multi-synapse watershed splitting
  3. Implement GMM cell type classifier
  4. Add conformal prediction uncertainty

Phase 3 — Performance (2-3 sessions)

  1. Rayon-parallel per-neuron skeletonization
  2. GPU-accelerated distance transform via wgpu compute shaders
  3. Multi-resolution contact detection pre-filter

Phase 4 — ML Integration (ongoing)

  1. MICrONS validation pipeline: feature extraction → Python training → coefficient export
  2. Embed CatBoost/XGBoost model for synapse scoring
  3. Active learning loop for continuous improvement

Open Decisions For The User

  1. Priority: Start with Phase 1 (fix broken geometry flow) which is the highest-impact change, or go straight to Phase 2 (algorithm upgrades)?
  2. ML approach: Logistic regression refinements via Python (lower risk, proven) or embed a Rust-native GB tree model (bleeding edge)?
  3. GPU path: Start with Rayon parallelization (simpler, works everywhere) or invest in wgpu compute shaders (faster, hardware-dependent)?
  4. Skeleton optimization: Pure-Rust optimization of the current Dijkstra (safe, no deps) or bind to edt/dijkstra3d C++ libraries (max speed, build complexity)?
  5. Scope: Should mesh-based contact detection (parry3d BVH integration) be a priority, or is voxel contact + geometry sufficient for the immediate dataset targets?