Repository navigation
feat(feature): ShapeTools shape measures on a smoothed mesh (total |K|, shape index, curvedness, fractal dimension) - #62
Draft
alxndrkalinin wants to merge 2 commits into
Conversation
Adds Total Absolute Gaussian Curvature, Avg Shape Index and Avg Curvedness, the ShapeTools shape measures, chosen by how well they separate shape states rather than by parity: - Any average of Gaussian curvature is fixed by Gauss-Bonnet, so the shape signal is in where K is negative. The integral of |K| over 4 pi is 1 for every convex body and grows with saddle regions (grooves, waists, the necks of lobes); unitless. - Shape index (Koenderink) and curvedness come from per-vertex principal curvatures computed as in LONI ShapeTools (Meyer et al. angle defect and edge-based mean curvature over the mixed Voronoi area), averaged over the surface by area rather than by vertex, so the result does not depend on how the mesher distributes vertices. Per-vertex curvature on a voxel staircase measures the staircase, so these are computed on a mesh of the mask blurred at curvature_sigma (default twice the coarsest spacing, isotropic in physical units), a new option of extract_features, extract_surface_features and mask2mesh (sigma). Nothing is blurred unless one of them is requested, and an object too small to survive the blur gets NaN for them with a warning. On synthetic nuclei with random size, axes, rotation, sub-voxel position and boundary noise (3 seeds x 2 noise levels, 30 per class), total |K| separated folded from smooth ellipsoids with AUC 1.00 and lobulated with 0.82 at rotation CV 0.000, against 0.53-0.64 for every average of K (including the 2021 ball measure and the ShapeTools vertex mean), and shape index and curvedness added 0.02-0.06 cross-validated AUC on top of Solidity, Sphericity and mean curvature. On analytic shapes: ball total |K| 1.000, torus 2.04 (exact 2), unit change rescales curvedness by 10 and leaves the rest unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011hEQ1TZJUbmhYKcC14RYHT
Completes the ShapeTools shape list with the LONI GSA fractal dimension, whose module sampled the mesh at triangle counts between a minimum and a maximum: the smoothed mesh is simplified by quadric error metrics to six face counts from a sixteenth of its own up to all of it, and D = 2 + 2 * slope of log area against log face count (about 2 for a smooth surface; 2.005 on a voxelized ball). On the synthetic nuclei it is weak on its own (AUC 0.59-0.66) and adds signal only in some settings (+0.05 cross-validated AUC for folded nuclei at high boundary noise, -0.03 for lobulated at low noise); box counting on the mask boundary added nothing and was not kept. Decimation needs fast-simplification, now in the mesh extra (>=0.1.9: 0.1.7 does not import under NumPy 2). Without it the feature raises a RuntimeError naming the package. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011hEQ1TZJUbmhYKcC14RYHT
Contributor
Reviewer's GuideThe PR adds four optional ShapeTools-inspired mesh descriptors, computes curvature-based measures on a physically scaled Gaussian-smoothed mask, estimates fractal dimension through QEM decimation, and covers the new behavior with extensive feature and validation tests. Sequence diagram for smoothed mesh feature extractionsequenceDiagram
participant Caller
participant Extract as extract_surface_features
participant Smooth as _smooth_mask2mesh
participant Features as extract_mesh_features
participant Mesh as trimesh
Caller->>Extract: extract_surface_features(mask, spacing, features, curvature_sigma)
Extract->>Extract: _curvature_sigma(spacing, curvature_sigma)
Extract->>Smooth: _smooth_mask2mesh(mask, spacing, sigma)
Smooth-->>Extract: smooth_mesh
Extract->>Features: extract_mesh_features(mesh, features, smooth_mesh)
Features->>Mesh: compute curvature features on smooth_mesh
Features->>Mesh: compute other features on mesh
Features-->>Caller: feature values
Flow diagram for optional smoothed curvature featuresflowchart TD
A["extract_surface_features"] --> B{"Any smoothed feature requested?"}
B -->|No| C["Extract all requested features from raw mesh"]
B -->|Yes| D["Resolve curvature_sigma"]
D --> E["Blur mask in physical units"]
E --> F{"Mask reaches 0.5 level?"}
F -->|No| G["Warn and return NaN for four smoothed features"]
G --> H["Compute remaining features on raw mesh"]
F -->|Yes| I["Generate smoothed mesh"]
I --> J["Compute curvature features on smoothed mesh"]
J --> K["Compute other features on raw mesh"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
5 tasks done
There was a problem hiding this comment.
🟡 Changes recommended
Closed meshes with fewer than 64 faces generate invalid decimation targets, which can cause fractal-dimension extraction to fail even with the default feature set.
1 open issue
What changed in this PR
Adds ShapeTools-inspired measures to cubic’s mesh feature extraction, building on #61 while preserving raw-mesh measurements for existing features.
Changes:
- Adds total absolute Gaussian curvature, area-weighted shape index and curvedness, and fractal dimension.
- Introduces configurable, physical-scale smoothing with warnings and NaN results for objects that vanish under blur.
- Adds the simplification dependency and tests for the new measurements and smoothing behavior.
| File | Description |
|---|---|
uv.lock |
Locks fast-simplification and includes it in the mesh and all extras. |
tests/feature/test_mesh.py |
Tests new measures, scaling, rotation, smoothing, and dependency handling. |
pyproject.toml |
Adds fast-simplification to the mesh extra. |
cubic/feature/mesh.py |
Implements the new measures and smoothed-mesh APIs. |
Review effort: Balanced
| raise RuntimeError( | ||
| "Fractal Dimension needs fast-simplification. Install with 'cubic[mesh]'" | ||
| ) | ||
| n_faces = len(mesh.faces) |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Stacked on #61 (base
fix/mesh-features); retarget tomainonce #61 merges.Summary
Adds the LONI ShapeTools shape measures to
cubic.feature.mesh. Each one is formulated to separate cell states as well as possible, rather than to match ShapeTools exactly.fast-simplification, which is now in themeshextra (>=0.1.9; 0.1.7 doesn't import under NumPy 2).Per-vertex curvature on a voxel staircase measures the staircase. So these four are computed on a mesh of the mask blurred at
curvature_sigma, a new parameter ofextract_features/extract_surface_features(sigmaonmask2mesh).Evidence (synthetic)
The synthetic nuclei are smooth ellipsoids, folded ones (a waist groove), lobulated ones and wrinkled ones. Each gets a random size, axis ratios, rotation, sub-voxel position and smooth boundary noise. Runs: 3 seeds × 2 noise levels, 30 nuclei per class.
On top of Solidity + Sphericity + mean curvature (5-fold CV logistic regression), shape index, curvedness and total |K| add 0.02–0.06 AUC in the cases not already at ceiling. Fractal dimension is mixed: +0.05 on folded nuclei at high noise, −0.03 on lobulated at low noise.
On analytic shapes:
Real data
The test data are nuclear masks only, from three published cell-state comparisons:
Voxel sizes come from the Zeiss metadata of each slide or tile series, because the tile names aren't reliable: NHA day 5 is labelled 80 nm in XY but is 87.86 nm. Three PROLIF slides ship no metadata. They are given 0.1318 × 0.1318 × 0.3152 µm, which all 14 slides with metadata state. Their median volumes, 388–503 µm³, bracket the 447 µm³ of slide 157, the one PROLIF slide with metadata.
Validation. Each slide holds a single class, so a classifier can learn the slide instead of the cell state. The folds therefore hold out whole groups:
AUC is computed within each test fold. Δ is the paired difference to the baseline on the same folds. The baseline is the 18 size/shape features from #61. Every cell reads logistic regression / gradient boosting.
The four features carry signal, but the baseline already has most of it. On their own they reach 0.59–0.64 AUC on fibroblasts and VPA, yet they add at most 0.03 to the baseline. The only gain that holds across folds is Fractal Dimension with logistic regression on VPA: 22 of 25 tile folds and 3 of 3 days.
PC3 shape stays near chance across slides with every feature set and blur (0.36–0.61 AUC). Nucleus-level cross-validation reports 0.74 → 0.83 there, and that comes from slide identity. For example, EMT slide 179 alone has a median total |K| of 1.27, against 1.44–1.59 on the other five slides.
The 2021 ball measure of Gaussian curvature adds nothing consistent either. On PC3 its direction flips between slide pairs: its AUC is 0.06 on 171 vs 168 and 0.95 on 172 vs 179.
Blur. For Δ with all four features, 1× the coarsest spacing does better than the 2× default on VPA:
With fold sd of Δ up to 0.03 and only 3 day folds, the default stays at 2×.
Against LONI Mask2Mesh. Mask2Mesh is the iterative Laplace–Beltrami surface reconstruction in the 2018 pipeline, run with the 2018 parameters. The comparison uses 15 nuclei per class per dataset. Masks were downsampled 3× in x and y so that Mask2Mesh finishes, and both methods mesh the same downsampled mask. The table gives the Spearman ρ of each feature against Mask2Mesh, per dataset (PC3 / VPA / fibroblast):
Test plan
tests/feature/test_mesh.py: 38 passed with the locked versions, 38 with the floor versions (trimesh 4.6.12, fast-simplification 0.1.9), and 36 passed + 2 skipped without fast-simplificationruff check .,ruff format --check .,mypy --ignore-missing-imports cubic/🤖 Generated with Claude Code
https://claude.ai/code/session_011hEQ1TZJUbmhYKcC14RYHT
Summary by Sourcery
Add ShapeTools-inspired curvature and fractal-dimension measures to mesh feature extraction with scale-aware smoothing.
New Features:
Enhancements:
Build:
Documentation:
Tests: