MedMLX
/

segresnet-renal-cect-mlx

@@ -2,76 +2,121 @@
 license: apache-2.0
 library_name: mlx
 tags:
-- medical-imaging
 - apple-silicon
 - research
 language:
 - en
 ---
-# MONAI renalStructures_CECT_segmentation (SegResNet, 3-phase CECT)
-Native MLX package: [segresnet-mlx](https://github.com/MedMLX/segresnet-mlx.git).
-Evaluated revision: `0503a9a3ad1c1c4f2fa0abd033b31c223763b43f` plus the retained [renal correction](segresnet-mlx-renal-fix.patch).
-This card describes the one configuration evaluated in the MedMLX paper. It is research software; the single-case comparison does not estimate clinical accuracy.
-## Source and checkpoint
-Original publisher: MONAI.
-Original implementation: [https://huggingface.co/MONAI/renalStructures_CECT_segmentation](https://huggingface.co/MONAI/renalStructures_CECT_segmentation).
-Source revision or version: `8ccbcd9573c004dc435d1913c0459ccd1a110ed1`.
-Original checkpoint: https://huggingface.co/MONAI/renalStructures_CECT_segmentation/resolve/8ccbcd9573c004dc435d1913c0459ccd1a110ed1/models/model.pt
-Conversion: segresnet_mlx.convert_checkpoint(spec=BUNDLES['renalStructures_CECT_segmentation'].spec).
-Conversion changes tensor layout or storage as specified by the native package; it does not retrain the model.
-## Recorded example
-CPTAC-CCRCC (TCIA), patient C3L-01458, CC BY 4.0; CPTAC-CCRCC (TCIA), patient C3L-01458, CC BY 4.0; CPTAC-CCRCC (TCIA), patient C3L-01458, CC BY 4.0
 ```python
 from segresnet_mlx.medmlx import run
-# Replace file and directory names with your locally obtained inputs and weights.
-kwargs = {
-    "bundle": "renalStructures_CECT_segmentation",
-    "arterial_path": "arterial.nii.gz",
-    "venous_path": "venous.nii.gz",
-    "excretory_path": "excretory.nii.gz",
-    "weights_path": "segresnet-renal-cect.safetensors",
-    "output_dir": "mlx-final",
-    "overwrite": False
-}
-result = run(**kwargs)
 print(result["outputs"])
 ```
 Native result: **success**. Original-code comparison: **pass**, `minimum per-label mask Dice` = `1.0`.
 Corrected October 12 native path matches all 85,089,840 raw FP32 logits and all 5,935,600 exported mask voxels in a fresh MONAI CPU comparison. The unchanged tolerance is rtol=atol=1e-4. Tumor anatomical correctness is unverified.
-The complete [native run](native-run.json) and [original-code comparison](reference-comparison.json) retain commands, geometry, precision, and output-specific checks. Use the [replay harness](https://github.com/MedMLX/Med-MLX/blob/main/benchmarks/README.md) to substitute local paths. The package README documents installation and conversion.
-## Distribution terms
-Upstream code: **Apache-2.0**. Weights: **Apache-2.0**.
-Converted weights are hosted in this repository.
-Corrected October 12 native path matches all 85,089,840 raw FP32 logits and all 5,935,600 exported mask voxels in a fresh MONAI CPU comparison. The unchanged tolerance is rtol=atol=1e-4. Tumor anatomical correctness is unverified. Converted weights may retain the identified upstream license and required notices; the accompanying notices describe the redistribution terms.
-Full [upstream license](LICENSE) accompanies any weight distribution.
-Required notices:
-- Retain the applicable license, copyright and attribution notices; identify the upstream checkpoint, authors, and MLX conversion changes.
-- Include Apache-2.0, retain applicable upstream NOTICE content, and mark modifications.
-Review sources:
-- https://huggingface.co/MONAI/renalStructures_CECT_segmentation
-- https://huggingface.co/MONAI/renalStructures_CECT_segmentation/resolve/8ccbcd9573c004dc435d1913c0459ccd1a110ed1/models/model.pt
-- https://huggingface.co/MONAI/renalStructures_CECT_segmentation/blob/8ccbcd9573c004dc435d1913c0459ccd1a110ed1/LICENSE
-## Packaged files
-- `segresnet-renal-cect.safetensors`

 license: apache-2.0
 library_name: mlx
 tags:
+- mlx
+- native-mlx
 - apple-silicon
+- medical-imaging
+- ct
+- kidney
+- segmentation
 - research
 language:
 - en
+inference: false
+pipeline_tag: image-segmentation
+base_model: MONAI/renalStructures_CECT_segmentation
 ---
+# SegResNet Renal CECT Segmentation
+Native MLX port of [MONAI renal structures CECT segmentation](https://huggingface.co/MONAI/renalStructures_CECT_segmentation).
+Segment renal structures from three-phase contrast-enhanced CT locally on Apple Silicon.
+- Arterial, venous and excretory CT inputs
+- Five renal structure labels
+- Converted MONAI SegResNet checkpoint included
+MLX implementation by [MedMLX](https://github.com/MedMLX).
+[GitHub](https://github.com/MedMLX/segresnet-mlx) · [Usage](https://github.com/MedMLX/segresnet-mlx#quick-start) · [Upstream](https://huggingface.co/MONAI/renalStructures_CECT_segmentation)
+**Requires the companion `segresnet-mlx` runtime.** Follow the quick start below.
+## Requirements
+Apple Silicon Mac with Metal GPU access, Python 3.12 and [uv](https://docs.astral.sh/uv/).
+The weights are included here; checkpoint conversion is not needed.
+## Quick start
+```bash
+uv venv --python 3.12
+source .venv/bin/activate
+uv pip install "segresnet-mlx @ git+https://github.com/MedMLX/segresnet-mlx.git" huggingface_hub
+hf download MedMLX/segresnet-renal-cect-mlx --local-dir models
+```
+Authenticate with `hf auth login` if repository access is required.
+Run this example in the same environment, replacing the input paths with your own:
 ```python
 from segresnet_mlx.medmlx import run
+result = run(
+    bundle='renalStructures_CECT_segmentation',
+    arterial_path='arterial.nii.gz',
+    venous_path='venous.nii.gz',
+    excretory_path='excretory.nii.gz',
+    weights_path='models/segresnet-renal-cect.safetensors',
+    output_dir='outputs',
+)
 print(result["outputs"])
 ```
+## Input and output
+Input is three 3D NIfTI CT volumes on the same voxel grid: arterial, venous
+and excretory phases, in that order.
+Output is `renalStructures_CECT_segmentation_mask.nii.gz` on the input grid.
+Labels: 0 background, 1 artery, 2 vein, 3 ureter, 4 neoplasm, 5 parenchyma.
+## Technical details
 Native result: **success**. Original-code comparison: **pass**, `minimum per-label mask Dice` = `1.0`.
 Corrected October 12 native path matches all 85,089,840 raw FP32 logits and all 5,935,600 exported mask voxels in a fresh MONAI CPU comparison. The unchanged tolerance is rtol=atol=1e-4. Tumor anatomical correctness is unverified.
+These are recorded results for one configuration, not a new benchmark or an
+estimate of clinical accuracy. The [native run](https://huggingface.co/MedMLX/segresnet-renal-cect-mlx/blob/main/native-run.json)
+and [original-code comparison](https://huggingface.co/MedMLX/segresnet-renal-cect-mlx/blob/main/reference-comparison.json)
+retain the commands, precision, geometry and output checks.
+<details>
+<summary>Checkpoint provenance and recorded configuration</summary>
+Recorded configuration: **MONAI renalStructures_CECT_segmentation (SegResNet, 3-phase CECT)**.
+Evaluated package revision: `0503a9a3ad1c1c4f2fa0abd033b31c223763b43f` plus the retained [renal correction](segresnet-mlx-renal-fix.patch).
+Recorded input: CPTAC-CCRCC (TCIA), patient C3L-01458, CC BY 4.0.
+Original publisher: MONAI.
+Original implementation: [upstream source](https://huggingface.co/MONAI/renalStructures_CECT_segmentation).
+Source revision or version: `8ccbcd9573c004dc435d1913c0459ccd1a110ed1`.
+Original checkpoint: [pinned checkpoint](https://huggingface.co/MONAI/renalStructures_CECT_segmentation/resolve/8ccbcd9573c004dc435d1913c0459ccd1a110ed1/models/model.pt).
+Weights were converted with the companion MLX package, without retraining.
+Conversion changes tensor layout or storage as required by that implementation.
+The [replay harness](https://github.com/MedMLX/Med-MLX/blob/main/benchmarks/README.md)
+describes how to reproduce the recorded configuration with local paths.
+</details>
+## Intended use
+Research and education. Outputs require human review and are not intended for
+clinical diagnosis or treatment decisions.
+## License
+Weights: **Apache-2.0** ([license](https://huggingface.co/MedMLX/segresnet-renal-cect-mlx/blob/main/LICENSE)).
+Upstream code: **Apache-2.0**. MLX port code:
+[Apache-2.0](https://github.com/MedMLX/segresnet-mlx/blob/main/LICENSE).
+Retain the [attribution and notices](https://huggingface.co/MedMLX/segresnet-renal-cect-mlx/blob/main/NOTICE) when redistributing
+the bundle or a conversion:
+- Retain the applicable license, copyright and attribution notices; identify the upstream checkpoint, authors, and MLX conversion changes.
+- Include Apache-2.0, retain applicable upstream NOTICE content, and mark modifications.