The Vesuvius 2025 Surface Detection task requires segmenting thin papyrus surfaces from 3D CT volumes of ancient scrolls. The competition metric is:
\nLB = 0.30 × TopoScore + 0.35 × SurfaceDice + 0.35 × VOI
\nThis means topology matters as much as pixel overlap. A model that gets good Dice but merges or splits surface sheets will score poorly on Betti matching and VOI. This insight drove every design decision — from the loss function to the post-processing.
\nCustom 3D U-Net with 6 encoder/decoder stages designed specifically for thin surface detection in CT volumes.
\nFeature channels: [32, 64, 128, 256, 320, 320]
\nResidual blocks per stage: [1, 2, 3, 4, 6, 6]
HybridConv3d — Instead of standard 3×3×3 convolutions, I decouple XY and Z processing: Conv3d(kernel=(1,3,3)) for in-plane features and Conv3d(kernel=(3,1,1)) for cross-slice features, then concatenate. CT data is anisotropic — in-plane resolution typically differs from slice spacing — so decoupled processing respects the data geometry.
MultiScaleResBlock — Res2Net-style blocks where the channel dimension is split into groups that process hierarchically. Each group receives input from the previous group, building multi-scale receptive fields within a single residual block. Applied at every encoder and decoder stage.
\nAttentionBlock (stages 2–5) — Combined channel attention (squeeze-excitation via AdaptiveAvgPool3d) and spatial attention (7×7 conv on concatenated mean+max pooled features). Helps the model focus on surface regions while suppressing irrelevant background.
SurfaceRefinementBlock (decoder stage 0) — This was critical for performance. At the highest resolution decoder stage, an edge convolution branch computes |conv(x)| to detect edges, concatenates with original features, and refines through two conv-norm-activation layers. Surfaces in the Vesuvius data can be 1–2 voxels thick, so having dedicated edge-aware processing at full resolution made a noticeable difference.
Other details:
\nGroupNorm throughout (stable with small batch size 4, unlike BatchNorm)LeakyReLU(0.01) activationConvTranspose3d upsamplingThe competition metric penalizes topological errors (Betti matching, VOI), so I designed the loss function with topology preservation as a first-class objective. All 5 losses are active from epoch 0.
\n| Loss | \nWeight | \nPurpose | \n
|---|---|---|
| Dice | \n0.25 | \nCore overlap signal for segmentation | \n
| BCE | \n0.10 | \nPer-voxel calibration, prevents over-confident predictions | \n
| clDice | \n0.30 | \nCenterline Dice — penalizes breaks in thin surface sheets | \n
| Surface | \n0.15 | \nDistance-weighted boundary loss — forces sharper edges | \n
| Topology | \n0.20 | \nLaplacian-based loss — preserves connected components | \n
clDice (centerline Dice) — Computes soft skeletonization via iterative min-pooling at half resolution (for speed), then evaluates Dice on the skeleton. A break in a 1-voxel-thick surface sheet destroys the skeleton connectivity, so clDice directly optimizes the topological continuity that TopoScore measures. This loss received the highest weight (0.30) because it was the most effective at improving topology.
\nSurface Loss — Computes GPU-approximate signed distance maps via iterative morphological dilation (5 iterations), then weights prediction errors by distance to the ground truth boundary. This forces the model to get surface boundaries right rather than just filling interiors.
\nTopology Loss — Applies a discrete 3D Laplacian kernel to both prediction and target, then penalizes the difference. The Laplacian highlights topological features (holes, tunnels, component boundaries) — exactly the features that Betti matching and VOI measure. Uses exponential weighting to focus on boundary regions.
\nDeep Supervision — During training, auxiliary Dice loss heads at 3 intermediate decoder resolutions (weights: 0.5, 0.25, 0.125) help gradient flow to deeper layers.
\n| Setting | \nValue | \n
|---|---|
| Folds | \n3-fold StratifiedKFold (stratified on scroll_id, seed=42) | \n
| Data | \n786 valid volumes across 6 scrolls | \n
| Patch size | \n192 × 192 × 192 | \n
| Batch size | \n4 | \n
| Optimizer | \nAdamW (lr=3e-4, weight_decay=1e-2) | \n
| LR warmup | \n5 epochs linear warmup | \n
| LR schedule | \nCosineAnnealingLR (T_max=795, eta_min=1e-6) | \n
| Precision | \nbfloat16 | \n
| Grad clipping | \nmax_norm=1.0 | \n
| Epochs | \n800 per fold | \n
| Validation | \nEvery 5 epochs, patch-based Dice | \n
All augmentations run on GPU in bfloat16 using pure PyTorch operations:
\nAll spatial augmentations use F.grid_sample for batched GPU processing. Labels use nearest-neighbor interpolation to preserve discrete values.
\n\nKey insight: Mild augmentation was critical. Heavy elastic deformation or affine transforms break 1–2 voxel thick surfaces, destroying the topology the model needs to learn.
\n
Used the fold 0 best checkpoint (epoch 249, best Dice 0.5711) for submission.
\nnn.DataParallel across 2× Tesla T4 (15.6 GB each)The key insight: every morphological operation is wrapped in a topology-safety check. Before and after each operation, we count 3D connected components (26-connectivity). If the operation would reduce the component count (i.e., merge separate surface sheets), it is reverted. This is cheap to compute and prevents post-processing from destroying the topology the model learned.
\n\n\nCritical design choice: 2D slicewise, not 3D. All morphology is done slice-by-slice independently. 3D morphological operations with 3D structuring elements are too aggressive and destroy 1-voxel-thick surfaces. 2D slicewise processing is much gentler and preserves thin structures.
\n
|conv(x)| edge detection branch gives the model an explicit edge signal to refine.F.grid_sample eliminates CPU bottleneck. Training speed limited only by forward/backward pass.| Stage | \nHardware | \nTime | \n
|---|---|---|
| Training (per fold) | \nNVIDIA H100 80GB | \n800 epochs, ~10–15 min/epoch | \n
| Inference (per volume) | \n2× Tesla T4 (DataParallel) | \n~2–3 min with flip TTA | \n
Training was done on Vast.ai with H100 GPU. Inference runs on 2× T4 within the competition runtime limits.
\nBoth notebooks are fully self-contained single-file implementations. No external repositories or custom packages required.
\n| Notebook | \nWhat it does | \n
|---|---|
| Training | \nFull TopoPreservingUNet3D architecture + 5-loss stack + GPU augmentations + 3-fold stratified CV + checkpoint management | \n
| Inference | \nModel loading + sliding window inference with Gaussian blending + 3-axis flip TTA + topology-safe 2D post-processing + TIFF submission | \n
Dependencies: PyTorch, NumPy, SciPy, scikit-image, tifffile, pandas
\nThanks for reading!
", "messages": [ { "id": 3414979, "postDate": "2026-02-28T02:47:08.400Z", "content": "The Vesuvius 2025 Surface Detection task requires segmenting thin papyrus surfaces from 3D CT volumes of ancient scrolls. The competition metric is:
\nLB = 0.30 × TopoScore + 0.35 × SurfaceDice + 0.35 × VOI
\nThis means topology matters as much as pixel overlap. A model that gets good Dice but merges or splits surface sheets will score poorly on Betti matching and VOI. This insight drove every design decision — from the loss function to the post-processing.
\nCustom 3D U-Net with 6 encoder/decoder stages designed specifically for thin surface detection in CT volumes.
\nFeature channels: [32, 64, 128, 256, 320, 320]
\nResidual blocks per stage: [1, 2, 3, 4, 6, 6]
HybridConv3d — Instead of standard 3×3×3 convolutions, I decouple XY and Z processing: Conv3d(kernel=(1,3,3)) for in-plane features and Conv3d(kernel=(3,1,1)) for cross-slice features, then concatenate. CT data is anisotropic — in-plane resolution typically differs from slice spacing — so decoupled processing respects the data geometry.
MultiScaleResBlock — Res2Net-style blocks where the channel dimension is split into groups that process hierarchically. Each group receives input from the previous group, building multi-scale receptive fields within a single residual block. Applied at every encoder and decoder stage.
\nAttentionBlock (stages 2–5) — Combined channel attention (squeeze-excitation via AdaptiveAvgPool3d) and spatial attention (7×7 conv on concatenated mean+max pooled features). Helps the model focus on surface regions while suppressing irrelevant background.
SurfaceRefinementBlock (decoder stage 0) — This was critical for performance. At the highest resolution decoder stage, an edge convolution branch computes |conv(x)| to detect edges, concatenates with original features, and refines through two conv-norm-activation layers. Surfaces in the Vesuvius data can be 1–2 voxels thick, so having dedicated edge-aware processing at full resolution made a noticeable difference.
Other details:
\nGroupNorm throughout (stable with small batch size 4, unlike BatchNorm)LeakyReLU(0.01) activationConvTranspose3d upsamplingThe competition metric penalizes topological errors (Betti matching, VOI), so I designed the loss function with topology preservation as a first-class objective. All 5 losses are active from epoch 0.
\n| Loss | \nWeight | \nPurpose | \n
|---|---|---|
| Dice | \n0.25 | \nCore overlap signal for segmentation | \n
| BCE | \n0.10 | \nPer-voxel calibration, prevents over-confident predictions | \n
| clDice | \n0.30 | \nCenterline Dice — penalizes breaks in thin surface sheets | \n
| Surface | \n0.15 | \nDistance-weighted boundary loss — forces sharper edges | \n
| Topology | \n0.20 | \nLaplacian-based loss — preserves connected components | \n
clDice (centerline Dice) — Computes soft skeletonization via iterative min-pooling at half resolution (for speed), then evaluates Dice on the skeleton. A break in a 1-voxel-thick surface sheet destroys the skeleton connectivity, so clDice directly optimizes the topological continuity that TopoScore measures. This loss received the highest weight (0.30) because it was the most effective at improving topology.
\nSurface Loss — Computes GPU-approximate signed distance maps via iterative morphological dilation (5 iterations), then weights prediction errors by distance to the ground truth boundary. This forces the model to get surface boundaries right rather than just filling interiors.
\nTopology Loss — Applies a discrete 3D Laplacian kernel to both prediction and target, then penalizes the difference. The Laplacian highlights topological features (holes, tunnels, component boundaries) — exactly the features that Betti matching and VOI measure. Uses exponential weighting to focus on boundary regions.
\nDeep Supervision — During training, auxiliary Dice loss heads at 3 intermediate decoder resolutions (weights: 0.5, 0.25, 0.125) help gradient flow to deeper layers.
\n| Setting | \nValue | \n
|---|---|
| Folds | \n3-fold StratifiedKFold (stratified on scroll_id, seed=42) | \n
| Data | \n786 valid volumes across 6 scrolls | \n
| Patch size | \n192 × 192 × 192 | \n
| Batch size | \n4 | \n
| Optimizer | \nAdamW (lr=3e-4, weight_decay=1e-2) | \n
| LR warmup | \n5 epochs linear warmup | \n
| LR schedule | \nCosineAnnealingLR (T_max=795, eta_min=1e-6) | \n
| Precision | \nbfloat16 | \n
| Grad clipping | \nmax_norm=1.0 | \n
| Epochs | \n800 per fold | \n
| Validation | \nEvery 5 epochs, patch-based Dice | \n
All augmentations run on GPU in bfloat16 using pure PyTorch operations:
\nAll spatial augmentations use F.grid_sample for batched GPU processing. Labels use nearest-neighbor interpolation to preserve discrete values.
\n\nKey insight: Mild augmentation was critical. Heavy elastic deformation or affine transforms break 1–2 voxel thick surfaces, destroying the topology the model needs to learn.
\n
Used the fold 0 best checkpoint (epoch 249, best Dice 0.5711) for submission.
\nnn.DataParallel across 2× Tesla T4 (15.6 GB each)The key insight: every morphological operation is wrapped in a topology-safety check. Before and after each operation, we count 3D connected components (26-connectivity). If the operation would reduce the component count (i.e., merge separate surface sheets), it is reverted. This is cheap to compute and prevents post-processing from destroying the topology the model learned.
\n\n\nCritical design choice: 2D slicewise, not 3D. All morphology is done slice-by-slice independently. 3D morphological operations with 3D structuring elements are too aggressive and destroy 1-voxel-thick surfaces. 2D slicewise processing is much gentler and preserves thin structures.
\n
|conv(x)| edge detection branch gives the model an explicit edge signal to refine.F.grid_sample eliminates CPU bottleneck. Training speed limited only by forward/backward pass.| Stage | \nHardware | \nTime | \n
|---|---|---|
| Training (per fold) | \nNVIDIA H100 80GB | \n800 epochs, ~10–15 min/epoch | \n
| Inference (per volume) | \n2× Tesla T4 (DataParallel) | \n~2–3 min with flip TTA | \n
Training was done on Vast.ai with H100 GPU. Inference runs on 2× T4 within the competition runtime limits.
\nBoth notebooks are fully self-contained single-file implementations. No external repositories or custom packages required.
\n| Notebook | \nWhat it does | \n
|---|---|
| Training | \nFull TopoPreservingUNet3D architecture + 5-loss stack + GPU augmentations + 3-fold stratified CV + checkpoint management | \n
| Inference | \nModel loading + sliding window inference with Gaussian blending + 3-axis flip TTA + topology-safe 2D post-processing + TIFF submission | \n
Dependencies: PyTorch, NumPy, SciPy, scikit-image, tifffile, pandas
\nThanks for reading!
", "rawMarkdown": "## 1. Problem Understanding\n\nThe Vesuvius 2025 Surface Detection task requires segmenting thin papyrus surfaces from 3D CT volumes of ancient scrolls. The competition metric is:\n\n**LB = 0.30 × TopoScore + 0.35 × SurfaceDice + 0.35 × VOI**\n\nThis means **topology matters as much as pixel overlap**. A model that gets good Dice but merges or splits surface sheets will score poorly on Betti matching and VOI. This insight drove every design decision — from the loss function to the post-processing.\n\n---\n\n## 2. Architecture: TopoPreservingUNet3D (~10M params)\n\nCustom 3D U-Net with 6 encoder/decoder stages designed specifically for thin surface detection in CT volumes.\n\n**Feature channels:** `[32, 64, 128, 256, 320, 320]` \n**Residual blocks per stage:** `[1, 2, 3, 4, 6, 6]`\n\n### Key Design Choices\n\n**HybridConv3d** — Instead of standard `3×3×3` convolutions, I decouple XY and Z processing: `Conv3d(kernel=(1,3,3))` for in-plane features and `Conv3d(kernel=(3,1,1))` for cross-slice features, then concatenate. CT data is anisotropic — in-plane resolution typically differs from slice spacing — so decoupled processing respects the data geometry.\n\n**MultiScaleResBlock** — Res2Net-style blocks where the channel dimension is split into groups that process hierarchically. Each group receives input from the previous group, building multi-scale receptive fields within a single residual block. Applied at every encoder and decoder stage.\n\n**AttentionBlock (stages 2–5)** — Combined channel attention (squeeze-excitation via `AdaptiveAvgPool3d`) and spatial attention (`7×7` conv on concatenated mean+max pooled features). Helps the model focus on surface regions while suppressing irrelevant background.\n\n**SurfaceRefinementBlock (decoder stage 0)** — This was critical for performance. At the highest resolution decoder stage, an edge convolution branch computes `|conv(x)|` to detect edges, concatenates with original features, and refines through two conv-norm-activation layers. Surfaces in the Vesuvius data can be **1–2 voxels thick**, so having dedicated edge-aware processing at full resolution made a noticeable difference.\n\n**Other details:**\n- `GroupNorm` throughout (stable with small batch size 4, unlike `BatchNorm`)\n- `LeakyReLU(0.01)` activation\n- Strided convolution downsampling (learnable, instead of max-pool)\n- `ConvTranspose3d` upsampling\n- Deep supervision heads at 3 decoder levels during training\n\n---\n\n## 3. Loss Function: 5-Component Topology-Aware Stack\n\nThe competition metric penalizes topological errors (Betti matching, VOI), so I designed the loss function with topology preservation as a first-class objective. All 5 losses are active from epoch 0.\n\n| Loss | Weight | Purpose |\n|:-----|:------:|:--------|\n| **Dice** | 0.25 | Core overlap signal for segmentation |\n| **BCE** | 0.10 | Per-voxel calibration, prevents over-confident predictions |\n| **clDice** | 0.30 | Centerline Dice — penalizes breaks in thin surface sheets |\n| **Surface** | 0.15 | Distance-weighted boundary loss — forces sharper edges |\n| **Topology** | 0.20 | Laplacian-based loss — preserves connected components |\n\n### How each loss works\n\n**clDice (centerline Dice)** — Computes soft skeletonization via iterative min-pooling at half resolution (for speed), then evaluates Dice on the skeleton. A break in a 1-voxel-thick surface sheet destroys the skeleton connectivity, so clDice directly optimizes the topological continuity that TopoScore measures. This loss received the highest weight (0.30) because it was the most effective at improving topology.\n\n**Surface Loss** — Computes GPU-approximate signed distance maps via iterative morphological dilation (5 iterations), then weights prediction errors by distance to the ground truth boundary. This forces the model to get surface boundaries right rather than just filling interiors.\n\n**Topology Loss** — Applies a discrete 3D Laplacian kernel to both prediction and target, then penalizes the difference. The Laplacian highlights topological features (holes, tunnels, component boundaries) — exactly the features that Betti matching and VOI measure. Uses exponential weighting to focus on boundary regions.\n\n**Deep Supervision** — During training, auxiliary Dice loss heads at 3 intermediate decoder resolutions (weights: 0.5, 0.25, 0.125) help gradient flow to deeper layers.\n\n---\n\n## 4. Training Details\n\n| Setting | Value |\n|:--------|:------|\n| **Folds** | 3-fold StratifiedKFold (stratified on `scroll_id`, seed=42) |\n| **Data** | 786 valid volumes across 6 scrolls |\n| **Patch size** | 192 × 192 × 192 |\n| **Batch size** | 4 |\n| **Optimizer** | AdamW (lr=3e-4, weight\\_decay=1e-2) |\n| **LR warmup** | 5 epochs linear warmup |\n| **LR schedule** | CosineAnnealingLR (T\\_max=795, eta\\_min=1e-6) |\n| **Precision** | bfloat16 |\n| **Grad clipping** | max\\_norm=1.0 |\n| **Epochs** | 800 per fold |\n| **Validation** | Every 5 epochs, patch-based Dice |\n\n### Data Preprocessing\n\n- **Robust Z-score normalization**: Percentile clipping (0.5th – 99.5th percentile) followed by Z-score. Standard medical imaging approach (used by nnU-Net, MONAI). Handles CT artifacts and outlier voxels before computing mean/std.\n- **Foreground oversampling**: 60% of patches centered on foreground voxels — important because surfaces are sparse (often <10% of volume).\n\n### GPU Augmentations (all on GPU, no CPU bottleneck)\n\nAll augmentations run on GPU in bfloat16 using pure PyTorch operations:\n\n- **Random 3D flips** (all axes) + **90° rotations** in HW plane\n- **Elastic deformation**: Low-res random displacement upsampled with trilinear interpolation (σ=2.0 — intentionally mild to avoid breaking thin surfaces)\n- **Affine scaling**: Uniform(0.9, 1.1)\n- **Gaussian noise**: σ=0.05\n- **Contrast/brightness jitter**\n- **Random cuboid occlusion**: Up to 3 small cubes zeroed out per sample\n\nAll spatial augmentations use `F.grid_sample` for batched GPU processing. Labels use nearest-neighbor interpolation to preserve discrete values.\n\n> **Key insight:** Mild augmentation was critical. Heavy elastic deformation or affine transforms break 1–2 voxel thick surfaces, destroying the topology the model needs to learn.\n\n---\n\n## 5. Inference Pipeline\n\n### Single Model Inference\n\nUsed the fold 0 best checkpoint (epoch 249, best Dice 0.5711) for submission.\n\n### Sliding Window Inference (SWI)\n\n1. Load test volume as float32 TIFF\n2. Normalize with identical percentile clipping (0.5–99.5%) + Z-score as training\n3. Pad volume if smaller than patch size (reflect padding)\n4. Generate overlapping 192×192×192 patch positions with **50% overlap**\n5. Create 3D Gaussian weight kernel (σ = 0.125 × patch\\_size) for smooth blending at patch boundaries\n6. Process patches in batches of 2 (one per T4 GPU)\n7. Accumulate weighted predictions and normalize by weight sum\n\n### Test-Time Augmentation (TTA)\n\n- **Flip TTA**: Original + flip along Z, Y, X axes = **4 forward passes**\n- Predictions averaged in probability space before thresholding\n\n### Multi-GPU Setup\n\n- `nn.DataParallel` across 2× Tesla T4 (15.6 GB each)\n- Batch size 2 (1 patch per GPU) for 192³ patches\n- float16 inference for speed\n\n---\n\n## 6. Post-Processing (Topology-Safe)\n\nThe key insight: every morphological operation is wrapped in a **topology-safety check**. Before and after each operation, we count 3D connected components (26-connectivity). If the operation would **reduce** the component count (i.e., merge separate surface sheets), it is **reverted**. This is cheap to compute and prevents post-processing from destroying the topology the model learned.\n\n### Pipeline\n\n1. **Fixed threshold at 0.5** — standard sigmoid midpoint\n2. **Remove small components** (<50 voxels) — noise cleanup using 26-connectivity labeling\n3. **2D slicewise closing** (4-connectivity, 1 iteration, topology-safe) — fills small gaps within each slice\n4. **2D slicewise hole filling** (all 3 axes, topology-safe) — fills enclosed holes per-slice\n5. **2D slicewise opening** (4-connectivity, 1 iteration, topology-safe) — removes small protrusions\n6. **Final small component removal** — second cleanup pass\n\n> **Critical design choice: 2D slicewise, not 3D.** All morphology is done slice-by-slice independently. 3D morphological operations with 3D structuring elements are too aggressive and destroy 1-voxel-thick surfaces. 2D slicewise processing is much gentler and preserves thin structures.\n\n---\n\n## 7. What Worked ✅\n\n1. **Topology-aware loss stack** — clDice(0.30) + Topology(0.20) directly optimize what the competition metric measures. Without them, the model learns decent Dice but poor Betti matching and VOI scores.\n2. **HybridConv3d** — Decoupled XY/Z convolutions respect CT anisotropy. More effective than isotropic 3×3×3 convolutions when in-plane and cross-slice resolutions differ.\n3. **SurfaceRefinementBlock** — Edge-aware processing at full decoder resolution is essential for 1–2 voxel thick surfaces. The `|conv(x)|` edge detection branch gives the model an explicit edge signal to refine.\n4. **2D slicewise post-processing** — Much gentler than 3D morphology. Thin surface structures survive.\n5. **Topology-safe operation guard** — Simple component-count check before/after each morphological operation prevents accidental merging of separate sheets.\n6. **GPU augmentations** — All augmentations on GPU with `F.grid_sample` eliminates CPU bottleneck. Training speed limited only by forward/backward pass.\n7. **bfloat16 training** — Same quality as float32, 2× memory savings, no GradScaler complexity.\n8. **Foreground oversampling (60%)** — Critical when surfaces are <10% of volume. Without it, the model sees mostly background patches.\n\n---\n\n## 8. What Didn't Work ❌\n\n1. **Frangi vesselness filter** in post-processing — Designed for tubular structures, not sheets. Reduced mean prediction confidence from 0.118 to 0.089, hurting overall score.\n2. **Adaptive thresholding** (e.g., 0.30) — Created too many false positive regions. The fixed 0.5 threshold was consistently better.\n3. **3D morphological operations** — Too aggressive for 1-voxel-thick surfaces. Switching to 2D slicewise processing was a critical improvement.\n4. **Heavy augmentation** — Strong elastic deformation (σ > 5) or large affine transforms broke thin surface topology during training, making the model worse at preserving connectivity.\n\n---\n\n## 9. Hardware & Runtime\n\n| Stage | Hardware | Time |\n|:------|:---------|:-----|\n| Training (per fold) | NVIDIA H100 80GB | 800 epochs, ~10–15 min/epoch |\n| Inference (per volume) | 2× Tesla T4 (DataParallel) | ~2–3 min with flip TTA |\n\nTraining was done on Vast.ai with H100 GPU. Inference runs on 2× T4 within the competition runtime limits.\n\n---\n\n## 10. Code\n\nBoth notebooks are fully self-contained single-file implementations. No external repositories or custom packages required.\n\n| Notebook | What it does |\n|:---------|:-------------|\n| **Training** | Full `TopoPreservingUNet3D` architecture + 5-loss stack + GPU augmentations + 3-fold stratified CV + checkpoint management |\n| **Inference** | Model loading + sliding window inference with Gaussian blending + 3-axis flip TTA + topology-safe 2D post-processing + TIFF submission |\n\n**Dependencies:** PyTorch, NumPy, SciPy, scikit-image, tifffile, pandas\n\n---\n\n*Thanks for reading!*\n", "votes": 5 } ], "comments": [], "raw_markdown_by_id": { "3414979": "## 1. Problem Understanding\n\nThe Vesuvius 2025 Surface Detection task requires segmenting thin papyrus surfaces from 3D CT volumes of ancient scrolls. The competition metric is:\n\n**LB = 0.30 × TopoScore + 0.35 × SurfaceDice + 0.35 × VOI**\n\nThis means **topology matters as much as pixel overlap**. A model that gets good Dice but merges or splits surface sheets will score poorly on Betti matching and VOI. This insight drove every design decision — from the loss function to the post-processing.\n\n---\n\n## 2. Architecture: TopoPreservingUNet3D (~10M params)\n\nCustom 3D U-Net with 6 encoder/decoder stages designed specifically for thin surface detection in CT volumes.\n\n**Feature channels:** `[32, 64, 128, 256, 320, 320]` \n**Residual blocks per stage:** `[1, 2, 3, 4, 6, 6]`\n\n### Key Design Choices\n\n**HybridConv3d** — Instead of standard `3×3×3` convolutions, I decouple XY and Z processing: `Conv3d(kernel=(1,3,3))` for in-plane features and `Conv3d(kernel=(3,1,1))` for cross-slice features, then concatenate. CT data is anisotropic — in-plane resolution typically differs from slice spacing — so decoupled processing respects the data geometry.\n\n**MultiScaleResBlock** — Res2Net-style blocks where the channel dimension is split into groups that process hierarchically. Each group receives input from the previous group, building multi-scale receptive fields within a single residual block. Applied at every encoder and decoder stage.\n\n**AttentionBlock (stages 2–5)** — Combined channel attention (squeeze-excitation via `AdaptiveAvgPool3d`) and spatial attention (`7×7` conv on concatenated mean+max pooled features). Helps the model focus on surface regions while suppressing irrelevant background.\n\n**SurfaceRefinementBlock (decoder stage 0)** — This was critical for performance. At the highest resolution decoder stage, an edge convolution branch computes `|conv(x)|` to detect edges, concatenates with original features, and refines through two conv-norm-activation layers. Surfaces in the Vesuvius data can be **1–2 voxels thick**, so having dedicated edge-aware processing at full resolution made a noticeable difference.\n\n**Other details:**\n- `GroupNorm` throughout (stable with small batch size 4, unlike `BatchNorm`)\n- `LeakyReLU(0.01)` activation\n- Strided convolution downsampling (learnable, instead of max-pool)\n- `ConvTranspose3d` upsampling\n- Deep supervision heads at 3 decoder levels during training\n\n---\n\n## 3. Loss Function: 5-Component Topology-Aware Stack\n\nThe competition metric penalizes topological errors (Betti matching, VOI), so I designed the loss function with topology preservation as a first-class objective. All 5 losses are active from epoch 0.\n\n| Loss | Weight | Purpose |\n|:-----|:------:|:--------|\n| **Dice** | 0.25 | Core overlap signal for segmentation |\n| **BCE** | 0.10 | Per-voxel calibration, prevents over-confident predictions |\n| **clDice** | 0.30 | Centerline Dice — penalizes breaks in thin surface sheets |\n| **Surface** | 0.15 | Distance-weighted boundary loss — forces sharper edges |\n| **Topology** | 0.20 | Laplacian-based loss — preserves connected components |\n\n### How each loss works\n\n**clDice (centerline Dice)** — Computes soft skeletonization via iterative min-pooling at half resolution (for speed), then evaluates Dice on the skeleton. A break in a 1-voxel-thick surface sheet destroys the skeleton connectivity, so clDice directly optimizes the topological continuity that TopoScore measures. This loss received the highest weight (0.30) because it was the most effective at improving topology.\n\n**Surface Loss** — Computes GPU-approximate signed distance maps via iterative morphological dilation (5 iterations), then weights prediction errors by distance to the ground truth boundary. This forces the model to get surface boundaries right rather than just filling interiors.\n\n**Topology Loss** — Applies a discrete 3D Laplacian kernel to both prediction and target, then penalizes the difference. The Laplacian highlights topological features (holes, tunnels, component boundaries) — exactly the features that Betti matching and VOI measure. Uses exponential weighting to focus on boundary regions.\n\n**Deep Supervision** — During training, auxiliary Dice loss heads at 3 intermediate decoder resolutions (weights: 0.5, 0.25, 0.125) help gradient flow to deeper layers.\n\n---\n\n## 4. Training Details\n\n| Setting | Value |\n|:--------|:------|\n| **Folds** | 3-fold StratifiedKFold (stratified on `scroll_id`, seed=42) |\n| **Data** | 786 valid volumes across 6 scrolls |\n| **Patch size** | 192 × 192 × 192 |\n| **Batch size** | 4 |\n| **Optimizer** | AdamW (lr=3e-4, weight\\_decay=1e-2) |\n| **LR warmup** | 5 epochs linear warmup |\n| **LR schedule** | CosineAnnealingLR (T\\_max=795, eta\\_min=1e-6) |\n| **Precision** | bfloat16 |\n| **Grad clipping** | max\\_norm=1.0 |\n| **Epochs** | 800 per fold |\n| **Validation** | Every 5 epochs, patch-based Dice |\n\n### Data Preprocessing\n\n- **Robust Z-score normalization**: Percentile clipping (0.5th – 99.5th percentile) followed by Z-score. Standard medical imaging approach (used by nnU-Net, MONAI). Handles CT artifacts and outlier voxels before computing mean/std.\n- **Foreground oversampling**: 60% of patches centered on foreground voxels — important because surfaces are sparse (often <10% of volume).\n\n### GPU Augmentations (all on GPU, no CPU bottleneck)\n\nAll augmentations run on GPU in bfloat16 using pure PyTorch operations:\n\n- **Random 3D flips** (all axes) + **90° rotations** in HW plane\n- **Elastic deformation**: Low-res random displacement upsampled with trilinear interpolation (σ=2.0 — intentionally mild to avoid breaking thin surfaces)\n- **Affine scaling**: Uniform(0.9, 1.1)\n- **Gaussian noise**: σ=0.05\n- **Contrast/brightness jitter**\n- **Random cuboid occlusion**: Up to 3 small cubes zeroed out per sample\n\nAll spatial augmentations use `F.grid_sample` for batched GPU processing. Labels use nearest-neighbor interpolation to preserve discrete values.\n\n> **Key insight:** Mild augmentation was critical. Heavy elastic deformation or affine transforms break 1–2 voxel thick surfaces, destroying the topology the model needs to learn.\n\n---\n\n## 5. Inference Pipeline\n\n### Single Model Inference\n\nUsed the fold 0 best checkpoint (epoch 249, best Dice 0.5711) for submission.\n\n### Sliding Window Inference (SWI)\n\n1. Load test volume as float32 TIFF\n2. Normalize with identical percentile clipping (0.5–99.5%) + Z-score as training\n3. Pad volume if smaller than patch size (reflect padding)\n4. Generate overlapping 192×192×192 patch positions with **50% overlap**\n5. Create 3D Gaussian weight kernel (σ = 0.125 × patch\\_size) for smooth blending at patch boundaries\n6. Process patches in batches of 2 (one per T4 GPU)\n7. Accumulate weighted predictions and normalize by weight sum\n\n### Test-Time Augmentation (TTA)\n\n- **Flip TTA**: Original + flip along Z, Y, X axes = **4 forward passes**\n- Predictions averaged in probability space before thresholding\n\n### Multi-GPU Setup\n\n- `nn.DataParallel` across 2× Tesla T4 (15.6 GB each)\n- Batch size 2 (1 patch per GPU) for 192³ patches\n- float16 inference for speed\n\n---\n\n## 6. Post-Processing (Topology-Safe)\n\nThe key insight: every morphological operation is wrapped in a **topology-safety check**. Before and after each operation, we count 3D connected components (26-connectivity). If the operation would **reduce** the component count (i.e., merge separate surface sheets), it is **reverted**. This is cheap to compute and prevents post-processing from destroying the topology the model learned.\n\n### Pipeline\n\n1. **Fixed threshold at 0.5** — standard sigmoid midpoint\n2. **Remove small components** (<50 voxels) — noise cleanup using 26-connectivity labeling\n3. **2D slicewise closing** (4-connectivity, 1 iteration, topology-safe) — fills small gaps within each slice\n4. **2D slicewise hole filling** (all 3 axes, topology-safe) — fills enclosed holes per-slice\n5. **2D slicewise opening** (4-connectivity, 1 iteration, topology-safe) — removes small protrusions\n6. **Final small component removal** — second cleanup pass\n\n> **Critical design choice: 2D slicewise, not 3D.** All morphology is done slice-by-slice independently. 3D morphological operations with 3D structuring elements are too aggressive and destroy 1-voxel-thick surfaces. 2D slicewise processing is much gentler and preserves thin structures.\n\n---\n\n## 7. What Worked ✅\n\n1. **Topology-aware loss stack** — clDice(0.30) + Topology(0.20) directly optimize what the competition metric measures. Without them, the model learns decent Dice but poor Betti matching and VOI scores.\n2. **HybridConv3d** — Decoupled XY/Z convolutions respect CT anisotropy. More effective than isotropic 3×3×3 convolutions when in-plane and cross-slice resolutions differ.\n3. **SurfaceRefinementBlock** — Edge-aware processing at full decoder resolution is essential for 1–2 voxel thick surfaces. The `|conv(x)|` edge detection branch gives the model an explicit edge signal to refine.\n4. **2D slicewise post-processing** — Much gentler than 3D morphology. Thin surface structures survive.\n5. **Topology-safe operation guard** — Simple component-count check before/after each morphological operation prevents accidental merging of separate sheets.\n6. **GPU augmentations** — All augmentations on GPU with `F.grid_sample` eliminates CPU bottleneck. Training speed limited only by forward/backward pass.\n7. **bfloat16 training** — Same quality as float32, 2× memory savings, no GradScaler complexity.\n8. **Foreground oversampling (60%)** — Critical when surfaces are <10% of volume. Without it, the model sees mostly background patches.\n\n---\n\n## 8. What Didn't Work ❌\n\n1. **Frangi vesselness filter** in post-processing — Designed for tubular structures, not sheets. Reduced mean prediction confidence from 0.118 to 0.089, hurting overall score.\n2. **Adaptive thresholding** (e.g., 0.30) — Created too many false positive regions. The fixed 0.5 threshold was consistently better.\n3. **3D morphological operations** — Too aggressive for 1-voxel-thick surfaces. Switching to 2D slicewise processing was a critical improvement.\n4. **Heavy augmentation** — Strong elastic deformation (σ > 5) or large affine transforms broke thin surface topology during training, making the model worse at preserving connectivity.\n\n---\n\n## 9. Hardware & Runtime\n\n| Stage | Hardware | Time |\n|:------|:---------|:-----|\n| Training (per fold) | NVIDIA H100 80GB | 800 epochs, ~10–15 min/epoch |\n| Inference (per volume) | 2× Tesla T4 (DataParallel) | ~2–3 min with flip TTA |\n\nTraining was done on Vast.ai with H100 GPU. Inference runs on 2× T4 within the competition runtime limits.\n\n---\n\n## 10. Code\n\nBoth notebooks are fully self-contained single-file implementations. No external repositories or custom packages required.\n\n| Notebook | What it does |\n|:---------|:-------------|\n| **Training** | Full `TopoPreservingUNet3D` architecture + 5-loss stack + GPU augmentations + 3-fold stratified CV + checkpoint management |\n| **Inference** | Model loading + sliding window inference with Gaussian blending + 3-axis flip TTA + topology-safe 2D post-processing + TIFF submission |\n\n**Dependencies:** PyTorch, NumPy, SciPy, scikit-image, tifffile, pandas\n\n---\n\n*Thanks for reading!*\n" } }