Add v2 microridge model: weights, plans, and provenance record

2D nnU-Net (Dataset502_MicroridgeField, nnUNetTrainer_100epochs, fold 0)
segmenting background / cell_region / cell_membrane / microridge.

Frozen test over 3 unseen fields: cell_region Dice 0.944, microridge Dice
0.877, cell_membrane boundary F1 0.659.

The checkpoint is unmodified so registry.json's checkpoint_sha256 verifies.

README.md

@@ -1,3 +1,163 @@
 ---
 license: cc-by-nc-sa-4.0
+library_name: nnunetv2
+pipeline_tag: image-segmentation
+tags:
+  - biology
+  - microscopy
+  - cell-segmentation
+  - microridge
+  - nnunet
+  - zebrafish
 ---
+
+# MicroridgeVectorAI — v2
+
+A 2D nnU-Net that segments **actin microridges**, **cell regions** and **cell
+membranes** in projected single-channel microscopy of epithelial tissue.
+
+Companion application: <https://github.com/LBK888/MicroridgeVectorAI> (CellVector,
+AGPL-3.0). The model runs standalone with nnU-Net v2 alone — CellVector is not
+required.
+
+| | |
+|---|---|
+| Model id | `8f1dbd06-6ec8-4c22-8e26-412cfee26ea9` |
+| Task | 2D semantic segmentation, 4 classes |
+| Architecture | nnU-Net v2 PlainConvUNet, 8 stages, patch 512x512 |
+| Trainer / folds | `nnUNetTrainer_100epochs`, fold 0 |
+| Input | single-channel 2D image, any size |
+| Snapshot hash | `dbe134f83c52b8ecae6cb62182310205496497ec297406ed8a2c912b60ba8cc9` |
+
+Labels: `0` background, `1` cell_region, `2` cell_membrane, `3` microridge.
+
+## Scores
+
+Frozen test — 36 tiles from **3 fields the model never saw**. Splits are grouped
+by source field, so no tile of a training field appears in the test set.
+
+| Metric | Value |
+|---|---|
+| cell_region Dice | 0.944 |
+| cell_membrane Dice | 0.471 |
+| cell_membrane boundary F1 (1 px tolerance) | 0.659 |
+| microridge Dice | 0.877 |
+| microridge precision / recall | 0.911 / 0.855 |
+| microridge skeleton length error | 0.100 |
+
+nnU-Net's own fold-0 validation (89 tiles): cell_region 0.964, cell_membrane
+0.495, microridge 0.912.
+
+**Reading the membrane number.** A Dice of 0.47 on a 3-pixel line covering ~1%
+of the frame is not the same failure as 0.47 on a region class: thin-structure
+Dice collapses when a prediction is offset by a pixel even where it follows the
+right path. The boundary F1 of 0.659, which allows one pixel of tolerance, is
+the more informative figure, and the gap between them says the membrane is
+mostly in the right place but not pixel-exact.
+
+## Limitations
+
+- **Cell contours derived from the label map merge.** Reconstructing cells as
+  the connected components of `label in (1, 3)` yields a single blob, because
+  the predicted membrane is thin and not perfectly closed. Use the predicted
+  membrane (class 2) for cell geometry, or split the region with a watershed
+  seeded inside cells. Do not expect instance-separated cells out of the box.
+- **The ground truth was not human-reviewed.** Labels were imported from
+  published raster masks and corrected only for import artifacts, not by an
+  expert. Treat this model as a proposal generator to be corrected, which is how
+  the companion application uses it.
+- **Trained on 13 fields.** Train and validation loss diverge (-0.755 vs
+  -0.629), which is what a small number of independent acquisitions looks like.
+  More fields will help more than more epochs.
+- **One fold, not an ensemble.** Only fold 0 was trained.
+- Validated on zebrafish periderm-style epithelial microridge imagery. Behaviour
+  on other tissue, magnification or modality is unknown.
+
+## Training data
+
+Wide-field frames cut into 477 tiles of at most 512x512 from 19 fields, keeping
+only regions whose raster truth is trustworthy. Uneven illumination leaves part
+of such a frame too dark for the upstream segmentation to resolve anything, and
+that failure is silent — the skeleton mask is empty while the cell mask still
+looks complete. Blocks were kept only where skeleton density cleared both an
+absolute floor and a share of the frame's own 90th percentile, **and** at least
+95% of the block was attributed to a cell. 68.3% of the field pixels survived.
+
+Labels were rasterized from vector geometry with a 3 px membrane and a 5 px
+microridge stroke.
+
+## Files
+
+```text
+registry.json                                   provenance record, metrics, checksums
+nnUNet_results/Dataset502_MicroridgeField/
+└─ nnUNetTrainer_100epochs__nnUNetPlans__2d/
+   ├─ dataset.json                              channel names and label map
+   ├─ plans.json                                preprocessing and architecture
+   └─ fold_0/checkpoint_final.pth               weights
+```
+
+Those three files under the trainer folder are the complete inference set. The
+directory names encode the configuration — nnU-Net parses
+`Dataset<ID>_<name>/<trainer>__<plans>__<configuration>` — so do not rename them.
+
+The checkpoint is shipped unmodified so the `checkpoint_sha256` in
+`registry.json` verifies. About half of it is optimizer state; stripping to
+`network_weights`, `init_args`, `trainer_name` and
+`inference_allowed_mirroring_axes` halves the size but invalidates that
+checksum.
+
+## Usage
+
+```bash
+pip install nnunetv2 huggingface_hub
+hf download leobk/MicroridgeVectorAI --local-dir microridge-model
+```
+
+```python
+import torch, numpy as np, tifffile
+from nnunetv2.inference.predict_from_raw_data import nnUNetPredictor
+
+MODEL = ("microridge-model/nnUNet_results/Dataset502_MicroridgeField"
+         "/nnUNetTrainer_100epochs__nnUNetPlans__2d")
+
+predictor = nnUNetPredictor(device=torch.device("cuda"))
+predictor.initialize_from_trained_model_folder(
+    MODEL, use_folds=(0,), checkpoint_name="checkpoint_final.pth"
+)
+
+image = tifffile.imread("frame.tif").astype("float32")
+segmentation = predictor.predict_single_npy_array(
+    image[None, None], {"spacing": (999.0, 1.0, 1.0)}, None, None, False
+)
+```
+
+No nnU-Net environment variables are needed for this path. Roughly 13 s for a
+512x512 tile on an RTX 4080 SUPER.
+
+### Reimplementing the pipeline
+
+The network takes `(1, 1, H, W)` and returns 4 logit channels, and exports to
+TorchScript. If you drive it yourself, reproduce all of:
+
+- **Normalization** — z-score using *each image's own* mean and standard
+  deviation (`use_mask_for_norm=False`). No dataset statistics;
+  `foreground_intensity_properties_per_channel` in `plans.json` is for CT
+  normalization and unused here.
+- **Sliding window** — 512x512 patches, step 0.5, Gaussian-weighted overlap.
+- **Test-time augmentation** — mirroring over axes `(0, 1)`.
+- **Output** — argmax over the 4 channels.
+
+Skipping the normalization or the Gaussian window degrades results noticeably
+and without any error.
+
+## Licensing note
+
+These weights are released under **CC BY-NC-SA 4.0**: attribution required,
+**non-commercial use only**, derivatives under the same terms. Note that this
+differs from the companion application's code licence (AGPL-3.0) — the code and
+the weights are covered separately.
+
+The weights were trained on third-party imagery; if that source data carries its
+own terms, they may constrain redistribution of this model independently of this
+label.

nnUNet_results/Dataset502_MicroridgeField/nnUNetTrainer_100epochs__nnUNetPlans__2d/dataset.json

@@ -0,0 +1,14 @@
+{
+    "channel_names": {
+        "0": "actin_microridge"
+    },
+    "file_ending": ".tif",
+    "labels": {
+        "background": 0,
+        "cell_membrane": 2,
+        "cell_region": 1,
+        "microridge": 3
+    },
+    "numTraining": 441,
+    "overwrite_image_reader_writer": "NaturalImage2DIO"
+}

nnUNet_results/Dataset502_MicroridgeField/nnUNetTrainer_100epochs__nnUNetPlans__2d/fold_0/checkpoint_final.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0e9e440280e99deffcd772cfde6e59aaa6e0f3578f59662a12246226692dbdde
+size 370825919

nnUNet_results/Dataset502_MicroridgeField/nnUNetTrainer_100epochs__nnUNetPlans__2d/plans.json

@@ -0,0 +1,207 @@
+{
+    "dataset_name": "Dataset502_MicroridgeField",
+    "plans_name": "nnUNetPlans",
+    "original_median_spacing_after_transp": [
+        999.0,
+        1.0,
+        1.0
+    ],
+    "original_median_shape_after_transp": [
+        1,
+        512,
+        491
+    ],
+    "image_reader_writer": "NaturalImage2DIO",
+    "transpose_forward": [
+        0,
+        1,
+        2
+    ],
+    "transpose_backward": [
+        0,
+        1,
+        2
+    ],
+    "configurations": {
+        "2d": {
+            "data_identifier": "nnUNetPlans_2d",
+            "preprocessor_name": "DefaultPreprocessor",
+            "batch_size": 12,
+            "patch_size": [
+                512,
+                512
+            ],
+            "median_image_size_in_voxels": [
+                512.0,
+                491.0
+            ],
+            "spacing": [
+                1.0,
+                1.0
+            ],
+            "normalization_schemes": [
+                "ZScoreNormalization"
+            ],
+            "use_mask_for_norm": [
+                false
+            ],
+            "resampling_fn_data": "resample_data_or_seg_to_shape",
+            "resampling_fn_seg": "resample_data_or_seg_to_shape",
+            "resampling_fn_data_kwargs": {
+                "is_seg": false,
+                "order": 3,
+                "order_z": 0,
+                "force_separate_z": null
+            },
+            "resampling_fn_seg_kwargs": {
+                "is_seg": true,
+                "order": 1,
+                "order_z": 0,
+                "force_separate_z": null
+            },
+            "resampling_fn_probabilities": "resample_data_or_seg_to_shape",
+            "resampling_fn_probabilities_kwargs": {
+                "is_seg": false,
+                "order": 1,
+                "order_z": 0,
+                "force_separate_z": null
+            },
+            "architecture": {
+                "network_class_name": "dynamic_network_architectures.architectures.unet.PlainConvUNet",
+                "arch_kwargs": {
+                    "n_stages": 8,
+                    "features_per_stage": [
+                        32,
+                        64,
+                        128,
+                        256,
+                        512,
+                        512,
+                        512,
+                        512
+                    ],
+                    "conv_op": "torch.nn.modules.conv.Conv2d",
+                    "kernel_sizes": [
+                        [
+                            3,
+                            3
+                        ],
+                        [
+                            3,
+                            3
+                        ],
+                        [
+                            3,
+                            3
+                        ],
+                        [
+                            3,
+                            3
+                        ],
+                        [
+                            3,
+                            3
+                        ],
+                        [
+                            3,
+                            3
+                        ],
+                        [
+                            3,
+                            3
+                        ],
+                        [
+                            3,
+                            3
+                        ]
+                    ],
+                    "strides": [
+                        [
+                            1,
+                            1
+                        ],
+                        [
+                            2,
+                            2
+                        ],
+                        [
+                            2,
+                            2
+                        ],
+                        [
+                            2,
+                            2
+                        ],
+                        [
+                            2,
+                            2
+                        ],
+                        [
+                            2,
+                            2
+                        ],
+                        [
+                            2,
+                            2
+                        ],
+                        [
+                            2,
+                            2
+                        ]
+                    ],
+                    "n_conv_per_stage": [
+                        2,
+                        2,
+                        2,
+                        2,
+                        2,
+                        2,
+                        2,
+                        2
+                    ],
+                    "n_conv_per_stage_decoder": [
+                        2,
+                        2,
+                        2,
+                        2,
+                        2,
+                        2,
+                        2
+                    ],
+                    "conv_bias": true,
+                    "norm_op": "torch.nn.modules.instancenorm.InstanceNorm2d",
+                    "norm_op_kwargs": {
+                        "eps": 1e-05,
+                        "affine": true
+                    },
+                    "dropout_op": null,
+                    "dropout_op_kwargs": null,
+                    "nonlin": "torch.nn.LeakyReLU",
+                    "nonlin_kwargs": {
+                        "inplace": true
+                    }
+                },
+                "_kw_requires_import": [
+                    "conv_op",
+                    "norm_op",
+                    "dropout_op",
+                    "nonlin"
+                ]
+            },
+            "batch_dice": true
+        }
+    },
+    "experiment_planner_used": "ExperimentPlanner",
+    "label_manager": "LabelManager",
+    "foreground_intensity_properties_per_channel": {
+        "0": {
+            "max": 18781.0,
+            "mean": 540.381103515625,
+            "median": 382.0,
+            "min": 104.0,
+            "percentile_00_5": 116.0,
+            "percentile_99_5": 2714.0,
+            "std": 473.2962646484375
+        }
+    }
+}

registry.json

@@ -0,0 +1,72 @@
+{
+  "models": [
+    {
+      "architecture": "plainconv",
+      "artifact_sha256": {
+        "dataset.json": "aa6242b569dc3fa70ee707db38970fd7e97fbfb45f48aa7f1a68a1c7a5a899cf",
+        "dataset_fingerprint.json": "9234acf421a087a276d8271f214cbddfdd97c1b71f4974e18a71fe44f680c7b9",
+        "fold_0/checkpoint_best.pth": "189e5d97d34dd8750bf279e47a78b8038ebb31d95b72ddcf0425f55c2785eb75",
+        "fold_0/checkpoint_final.pth": "0e9e440280e99deffcd772cfde6e59aaa6e0f3578f59662a12246226692dbdde",
+        "plans.json": "7e403e7cb95ad1efbf184de013d651595561f248bd885d461d5b0f8fa2e73874"
+      },
+      "augmentation_profile_hash": "6f738a972b6f7eba84ee6a2cd5cbd01f83dbed2afa9633439b89e76bb3a5a4dd",
+      "backend_id": "nnunetv2-local",
+      "backend_version": "2.8.1",
+      "benchmark_id": null,
+      "checkpoint_path": "fold_0/checkpoint_final.pth",
+      "checkpoint_sha256": "0e9e440280e99deffcd772cfde6e59aaa6e0f3578f59662a12246226692dbdde",
+      "configuration": {
+        "configuration": "2d",
+        "dataset_id": 502,
+        "dataset_name": "MicroridgeField",
+        "epochs": 100,
+        "executed_locally": true,
+        "fold": 0,
+        "membrane_width_px": 3,
+        "microridge_width_px": 5,
+        "plan_command": "nnUNetv2_plan_and_preprocess -d 502 -c 2d --verify_dataset_integrity",
+        "plans": "nnUNetPlans",
+        "source_data": "full view field tiles, trustworthy regions only",
+        "split_grouping": "specimen:field_frame_uri",
+        "torch_version": "2.12.1+cu130",
+        "train_command": "nnUNetv2_train 502 2d 0 -tr nnUNetTrainer_100epochs --npz",
+        "trainer": "nnUNetTrainer_100epochs",
+        "training_job_id": "0305ef07-38d7-41d3-bc44-a1e51a2c0d4f"
+      },
+      "created_at": "2026-08-31T10:00:21.285927Z",
+      "dataset_artifact_hash": "90178985de2ef8d24b5a7338b7e9fec83dfe6164e0558ef30d449d8e13439547",
+      "folds_completed": [
+        0
+      ],
+      "incomplete_provenance_fields": [],
+      "input_contract": "image/2d",
+      "label_contract": "cellvector.annotation/1.0.0",
+      "metrics": {
+        "frozen_test_cases": 36,
+        "frozen_test_cell_membrane_boundary_f1": 0.6589374464002449,
+        "frozen_test_cell_membrane_dice": 0.4708712201149024,
+        "frozen_test_cell_region_dice": 0.9438357584291484,
+        "frozen_test_cell_region_iou": 0.8940270075353971,
+        "frozen_test_microridge_dice": 0.8767592825579081,
+        "frozen_test_microridge_precision": 0.9106816936813859,
+        "frozen_test_microridge_recall": 0.8550323207264082,
+        "frozen_test_microridge_skeleton_length_error": 0.0997634178921583,
+        "nnunet_validation_dice_cell_membrane": 0.4954518160625487,
+        "nnunet_validation_dice_cell_region": 0.9644053946394331,
+        "nnunet_validation_dice_microridge": 0.9114529420774974
+      },
+      "model_id": "8f1dbd06-6ec8-4c22-8e26-412cfee26ea9",
+      "parent_model_id": null,
+      "provenance_status": "verified",
+      "selected_at": null,
+      "selection_actor": null,
+      "selection_reason": null,
+      "snapshot_hash": "dbe134f83c52b8ecae6cb62182310205496497ec297406ed8a2c912b60ba8cc9",
+      "software_smoke_test": false,
+      "status": "trained",
+      "training_job_id": "0305ef07-38d7-41d3-bc44-a1e51a2c0d4f",
+      "updated_at": "2026-08-31T10:00:21.285927Z"
+    }
+  ],
+  "schema_version": "1.0.0"
+}