Release VesselBoost v2.0.2 pretrained weights (#1)

- Release VesselBoost v2.0.2 pretrained weights (d9a816e189b5c2e884bc5a786e2d8b3cb36b58fe)

.gitattributes

@@ -33,3 +33,12 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+BM_VB2_aug_all_ep2k_bat_10_0903 filter=lfs diff=lfs merge=lfs -text
+VB2_aug_intensity_ep2k_bat10_0903 filter=lfs diff=lfs merge=lfs -text
+VB2_aug_off_ep2k_bat10_0903 filter=lfs diff=lfs merge=lfs -text
+VB2_aug_random_ep2k_bat10_0903 filter=lfs diff=lfs merge=lfs -text
+VB2_aug_spatial_ep2k_bat10_0903 filter=lfs diff=lfs merge=lfs -text
+manual_0429 filter=lfs diff=lfs merge=lfs -text
+omelette1_0429 filter=lfs diff=lfs merge=lfs -text
+omelette2_0429 filter=lfs diff=lfs merge=lfs -text
+t2s_mod_ep1k2_0728 filter=lfs diff=lfs merge=lfs -text

BM_VB2_aug_all_ep2k_bat_10_0903

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

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marshall Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.sha256

@@ -0,0 +1,9 @@
+ff51c8e6c79947f13bf7c24ac2ae2242eb4b23b7739e62dc3f8344944bde28f1  BM_VB2_aug_all_ep2k_bat_10_0903
+73b3cabf38dcb4266507f375c67f7f6e1fa3e57747ff9ae5b9a2285175462ada  VB2_aug_intensity_ep2k_bat10_0903
+056849b426a669a7536d57b270803fa9a2dab69d9f8abbfcb865d028864db961  VB2_aug_off_ep2k_bat10_0903
+09b28d972172939f554f3884de9570f9584720b5c8fd225d620e812e48507461  VB2_aug_random_ep2k_bat10_0903
+a5bb099eaa70b1c61f948c5475002083b7637c118ed5525124dece20100de4d4  VB2_aug_spatial_ep2k_bat10_0903
+fb318efe161b0036f2af2585fb282dd92ab45c6f0258422154340f05a2b3ef80  manual_0429
+980cbbd4cdd85fc731cc5bc621b402ebcc1f0abba028ced4b6035bf92ebaa212  omelette1_0429
+d18245068d8a196d52d9cbaa841a0eff314c5673e5bef85af60bf482d28d1633  omelette2_0429
+794d8e333ae0b26578824debc375950a0637868deca3f16656dc81e0076951ad  t2s_mod_ep1k2_0728

README.md

@@ -1,3 +1,114 @@
 ---
 license: mit
+library_name: pytorch
+pipeline_tag: image-segmentation
+tags:
+  - medical-imaging
+  - mri
+  - tof-mra
+  - t2star
+  - vessel-segmentation
+  - brain-vasculature
+  - unet3d
+  - pytorch
 ---
+# VesselBoost pretrained weights
+
+## Model purpose
+
+VesselBoost segments small blood vessels in high-resolution human brain MRI. The primary models target time-of-flight magnetic resonance angiography (TOF-MRA). One checkpoint, `t2s_mod_ep1k2_0728`, provides experimental support for T2*-weighted MRI.
+
+These files are PyTorch state dictionaries for use with the VesselBoost inference, test-time adaptation, and boosting workflows. They are not standalone Hugging Face Transformers models or hosted inference endpoints.
+
+**Research use only. Not validated for clinical diagnosis, treatment planning, or other clinical decision-making.**
+
+## Architecture and release pin
+
+The checkpoints use the VesselBoost 3D U-Net with one input channel, one output channel, and 16 base filters. The network has four encoder stages, a bridge, four decoder stages with transposed-convolution upsampling and skip connections, and a final 1 x 1 x 1 convolution. Each convolutional block contains two 3 x 3 x 3 convolutions with batch normalization and ReLU activation.
+
+The corresponding source release is pinned to:
+
+- VesselBoost version: `2.0.2`
+- Git tag: [`v2.0.2`](https://github.com/KMarshallX/VesselBoost/tree/v2.0.2)
+- Git commit: [`1504b00c91777d5e2c271c1cab7f500078f08c69`](https://github.com/KMarshallX/VesselBoost/commit/1504b00c91777d5e2c271c1cab7f500078f08c69)
+
+See `config.json` for the machine-readable inference configuration.
+
+## Checkpoints
+
+Checkpoint names and extensions are preserved from the original release.
+
+| Checkpoint                            | MRI contrast     | Description                                                                                                                             |
+| ------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `BM_VB2_aug_all_ep2k_bat_10_0903`   | TOF-MRA          | Primary TOF-MRA checkpoint referenced by the VesselBoost documentation and tests; trained with the combined augmentation configuration. |
+| `VB2_aug_intensity_ep2k_bat10_0903` | TOF-MRA          | Augmentation ablation using the intensity augmentation configuration.                                                                   |
+| `VB2_aug_off_ep2k_bat10_0903`       | TOF-MRA          | Augmentation ablation with augmentation disabled.                                                                                       |
+| `VB2_aug_random_ep2k_bat10_0903`    | TOF-MRA          | Augmentation ablation using the random augmentation configuration.                                                                      |
+| `VB2_aug_spatial_ep2k_bat10_0903`   | TOF-MRA          | Augmentation ablation using the spatial augmentation configuration.                                                                     |
+| `manual_0429`                       | TOF-MRA          | Legacy checkpoint associated with the manual-label training run and used in VesselBoost v2.0.2 examples.                                |
+| `omelette1_0429`                    | TOF-MRA          | Legacy TOF-MRA checkpoint identified as Omelette variant 1.                                                                             |
+| `omelette2_0429`                    | TOF-MRA          | Legacy TOF-MRA checkpoint identified as Omelette variant 2.                                                                            |
+| `t2s_mod_ep1k2_0728`                | T2*-weighted MRI | Experimental T2*-weighted vessel-segmentation checkpoint. It has not received the same validation as the primary TOF-MRA model.         |
+
+The augmentation-specific checkpoints are included to preserve the original model set and support comparison or reproduction of augmentation experiments. For the standard TOF-MRA prediction workflow, use `manual_0429` or `BM_VB2_aug_all_ep2k_bat_10_0903` unless reproducing a specific legacy experiment.
+
+## Preprocessing and inference
+
+VesselBoost v2.0.2 performs the following inference operations:
+
+1. Load a single-channel NIfTI MRI volume.
+2. Resize each spatial dimension to at least 64 voxels and to a multiple of 64, using nearest-neighbor interpolation.
+3. Apply whole-volume z-score standardization: subtract the volume mean and divide by its standard deviation. A constant-valued volume is mapped to zeros.
+4. Divide the standardized image into non-overlapping `64 x 64 x 64` patches. The optional Gaussian-blending path uses overlapping patches.
+5. Apply the 3D U-Net and a sigmoid activation to obtain vessel probabilities.
+6. Threshold probabilities at the default value of `0.1`.
+7. Remove connected components smaller than `10` voxels using 26-connectivity.
+8. Resize the prediction back to the original image dimensions.
+
+VesselBoost preprocessing modes can optionally perform N4 bias-field correction, denoising, both operations, or neither. Use the same preprocessing choices used for validation when comparing results. Brain extraction is optional and requires separate SynthStrip weights; those third-party weights are not part of this model release.
+
+## Integrity verification
+
+SHA-256 checksums are provided in `MANIFEST.sha256`. From the directory containing the downloaded files, verify them with:
+
+```bash
+sha256sum --check MANIFEST.sha256
+```
+
+Load the checkpoints with the pinned VesselBoost source and map tensors to the intended device. When supported by the installed PyTorch version, use `weights_only=True` when loading these state dictionaries.
+
+## Known limitations and expected failure cases
+
+- The models were developed for research MRI data and may not generalize to unseen scanners, field strengths, acquisition protocols, resolutions, populations, pathologies, or non-brain anatomy.
+- The primary models target TOF-MRA. Applying them to other contrasts can produce unreliable results; T2* support is explicitly experimental.
+- Bright non-vascular structures, noise, motion, ringing, bias fields, susceptibility artifacts, and incomplete brain masking can cause false positives.
+- Low vessel contrast, slow or turbulent flow, signal dropout, very small vessels, severe pathology, and partial-volume effects can cause false negatives or disconnected vessels.
+- Z-score standardization is performed over the supplied volume. Large background regions, unexpected cropping, NaN or infinite intensities, and constant-valued images can change or invalidate the result.
+- Resizing and patch boundaries can alter fine structures. Gaussian blending may reduce patch-boundary artifacts but changes the inference procedure and should be reported.
+- The default probability threshold of `0.1` and component cutoff of `10` voxels may require validation for a new dataset. Tuning them on evaluation cases can bias reported performance.
+- Training labels for small vessels can be incomplete or imperfect. Predictions should not be interpreted as a complete representation of the cerebral vasculature.
+- Detailed provenance for `manual_0429`, `omelette1_0429`, and `omelette2_0429` training runs is documented in our ApertureNeuro journal article *VesselBoost: A Python Toolbox for Small Blood Vessel Segmentation in Human Magnetic Resonance Angiography Data*.
+
+## Resources and citation
+
+- Paper DOI: [10.52294/001c.123217](https://doi.org/10.52294/001c.123217)
+- Published article: [VesselBoost: A Python Toolbox for Small Blood Vessel Segmentation in Human Magnetic Resonance Angiography Data](https://apertureneuro.org/article/123217-vesselboost-a-python-toolbox-for-small-blood-vessel-segmentation-in-human-magnetic-resonance-angiography-data)
+- GitHub: [KMarshallX/VesselBoost](https://github.com/KMarshallX/VesselBoost)
+- OSF project and original model distribution: [osf.io/abk4p](https://osf.io/abk4p/)
+
+Please cite:
+
+```bibtex
+@article{xuVesselBoostPythonToolbox2024,
+  title = {VesselBoost: A Python Toolbox for Small Blood Vessel Segmentation in Human Magnetic Resonance Angiography Data},
+  author = {Xu, Marshall and Ribeiro, Fernanda L. and Barth, Markus and Bernier, Micha\"el and Bollmann, Steffen and Chatterjee, Soumick and Cognolato, Francesco and Gulban, Omer F. and Itkyal, Vaibhavi and Liu, Siyu and Mattern, Hendrik and Polimeni, Jonathan R. and Shaw, Thomas B. and Speck, Oliver and Bollmann, Saskia},
+  journal = {Aperture Neuro},
+  volume = {4},
+  year = {2024},
+  doi = {10.52294/001c.123217}
+}
+```
+
+## License
+
+The files in this model release are provided under the MIT License. See `LICENSE`.

VB2_aug_intensity_ep2k_bat10_0903

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

VB2_aug_off_ep2k_bat10_0903

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

VB2_aug_random_ep2k_bat10_0903

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

VB2_aug_spatial_ep2k_bat10_0903

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

config.json

@@ -0,0 +1,56 @@
+{
+  "model_type": "vesselboost-unet3d",
+  "framework": "pytorch",
+  "task": "image-segmentation",
+  "architecture": {
+    "class_name": "models.unet_3d.Unet",
+    "spatial_dimensions": 3,
+    "input_channels": 1,
+    "output_channels": 1,
+    "base_filters": 16,
+    "encoder_stages": 4,
+    "decoder_stages": 4,
+    "convolution_kernel_size": [3, 3, 3],
+    "output_kernel_size": [1, 1, 1],
+    "normalization": "batch_norm_3d",
+    "activation": "relu",
+    "output_activation": "sigmoid_at_inference"
+  },
+  "input": {
+    "format": "NIfTI",
+    "contrasts": [
+      "TOF-MRA",
+      "T2*-weighted MRI (experimental checkpoint only)"
+    ],
+    "patch_size": [64, 64, 64],
+    "default_patch_stride": [64, 64, 64]
+  },
+  "preprocessing": {
+    "resize_target": "each spatial dimension is at least 64 and a multiple of 64",
+    "resize_interpolation": "nearest_neighbor",
+    "intensity_transform": {
+      "name": "z_score_standardization",
+      "scope": "whole_volume",
+      "formula": "(x - mean(x)) / std(x)",
+      "constant_volume_result": "zeros"
+    },
+    "optional_operations": [
+      "N4 bias-field correction",
+      "denoising",
+      "brain extraction with separately distributed SynthStrip weights"
+    ]
+  },
+  "postprocessing": {
+    "probability_threshold": 0.1,
+    "connected_component_minimum_voxels": 10,
+    "connected_component_connectivity": 26,
+    "prediction_resize_interpolation": "nearest_neighbor"
+  },
+  "checkpoint_format": "PyTorch state_dict ZIP serialization",
+  "compatible_vesselboost": {
+    "version": "2.0.2",
+    "git_tag": "v2.0.2",
+    "git_commit": "1504b00c91777d5e2c271c1cab7f500078f08c69",
+    "source_url": "https://github.com/KMarshallX/VesselBoost/tree/v2.0.2"
+  }
+}

manual_0429

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

omelette1_0429

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

omelette2_0429

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

t2s_mod_ep1k2_0728

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