MedMLX
/

vista3d-ct-mlx

@@ -2,77 +2,120 @@
 license: other
 library_name: mlx
 tags:
-- medical-imaging
 - apple-silicon
 - research
 language:
 - en
 license_name: nvidia-open-model
-license_link: LICENSE
 ---
-# NV-Segment-CT (VISTA-3D) automatic segment_all, weights afb51518
-Native MLX package: [nv-segment-ct-mlx](https://github.com/MedMLX/MLX-Segment-Ct.git).
-Evaluated revision: `d8969d90a299b0aebf62fce3a9afbf204734995b`.
-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: NVIDIA.
-Original implementation: [https://github.com/NVIDIA-Medtech/NV-Segment-CTMR](https://github.com/NVIDIA-Medtech/NV-Segment-CTMR).
-Source revision or version: `f9f5f51b589e5dc9c23c453cf5138398e4084056`.
-Original checkpoint: https://huggingface.co/nvidia/NV-Segment-CT/resolve/afb51518689f71e6abb367ee6301b2cd0225c66a/vista3d_pretrained_model/model.pt
-Conversion: README recipe: mlx_weights.convert_weights / mlx_correction_weights.convert_weights.
-Conversion changes tensor layout or storage as specified by the native package; it does not retrain the model.
-## Recorded example
-AMOS22 (validation) / amos_0008
 ```python
-from nv_segment_ct_mlx.medmlx import run
-# Replace file and directory names with your locally obtained inputs and weights.
-kwargs = {
-    "image_path": "image.nii.gz",
-    "weights_path": "vista3d",
-    "output_dir": "out",
-    "segment_all": True,
-    "overwrite": True
-}
-result = run(**kwargs)
 print(result["outputs"])
 ```
 Native result: **success**. Original-code comparison: **pass**, `minimum per-label mask Dice` = `1.0`.
 The demonstrated VISTA3D configuration uses NVIDIA NV-Segment-CT weights. Preserve that download origin; legacy MONAI weights have different terms.
-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: **LicenseRef-NVIDIA-Open-Model**.
-Converted weights are hosted in this repository.
-The demonstrated VISTA3D configuration uses NVIDIA NV-Segment-CT weights. Preserve that download origin; legacy MONAI weights have different terms. 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 the applicable NVIDIA Open Model Agreement and a Notice file containing: Licensed by NVIDIA Corporation under the NVIDIA Open Model License
-Review sources:
-- https://github.com/NVIDIA-Medtech/NV-Segment-CTMR
-- https://huggingface.co/nvidia/NV-Segment-CT/resolve/afb51518689f71e6abb367ee6301b2cd0225c66a/vista3d_pretrained_model/model.pt
-- https://huggingface.co/nvidia/NV-Segment-CT/blob/afb51518689f71e6abb367ee6301b2cd0225c66a/LICENSE
-## Packaged files
-- `automatic.safetensors`
-- `correction.safetensors`

 license: other
 library_name: mlx
 tags:
+- mlx
+- native-mlx
 - apple-silicon
+- medical-imaging
+- ct
+- segmentation
+- vista3d
 - research
 language:
 - en
 license_name: nvidia-open-model
+license_link: https://huggingface.co/MedMLX/vista3d-ct-mlx/blob/main/LICENSE
+inference: false
+pipeline_tag: image-segmentation
 ---
+# VISTA-3D CT Segmentation
+Native MLX port of [NVIDIA NV-Segment-CT (VISTA-3D)](https://github.com/NVIDIA-Medtech/NV-Segment-CTMR).
+Run automatic 3D CT segmentation locally on Apple Silicon.
+- Automatic whole-volume segmentation with the NVIDIA checkpoint
+- Native MLX inference on Metal
+- Converted automatic and correction weights included
+MLX implementation by [MedMLX](https://github.com/MedMLX).
+[GitHub](https://github.com/MedMLX/mlx-segment-ct) · [Usage](https://github.com/MedMLX/mlx-segment-ct#quick-start) · [Upstream](https://github.com/NVIDIA-Medtech/NV-Segment-CTMR)
+**Requires the companion `mlx-segment-ct` 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 "mlx-segment-ct @ git+https://github.com/MedMLX/mlx-segment-ct.git" huggingface_hub
+hf download MedMLX/vista3d-ct-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 mlx_segment_ct.medmlx import run
+result = run(
+    image_path='ct.nii.gz',
+    weights_path='models',
+    output_dir='outputs',
+    segment_all=True,
+)
 print(result["outputs"])
 ```
+## Input and output
+Input is one 3D CT in NIfTI format (`.nii` or `.nii.gz`), in Hounsfield units.
+The quick start uses automatic `segment_all` inference.
+Output is `nv_segment_ct_mask.nii.gz` on the input grid, using the upstream
+0–254 label vocabulary; 255 means not covered.
+## Technical details
 Native result: **success**. Original-code comparison: **pass**, `minimum per-label mask Dice` = `1.0`.
 The demonstrated VISTA3D configuration uses NVIDIA NV-Segment-CT weights. Preserve that download origin; legacy MONAI weights have different terms.
+These are recorded results for one configuration, not a new benchmark or an
+estimate of clinical accuracy. The [native run](https://huggingface.co/MedMLX/vista3d-ct-mlx/blob/main/native-run.json)
+and [original-code comparison](https://huggingface.co/MedMLX/vista3d-ct-mlx/blob/main/reference-comparison.json)
+retain the commands, precision, geometry and output checks.
+<details>
+<summary>Checkpoint provenance and recorded configuration</summary>
+Recorded configuration: **NV-Segment-CT (VISTA-3D) automatic segment_all, weights afb51518**.
+Evaluated package revision: `d8969d90a299b0aebf62fce3a9afbf204734995b`.
+Recorded input: AMOS22 (validation) / amos_0008.
+Original publisher: NVIDIA.
+Original implementation: [upstream source](https://github.com/NVIDIA-Medtech/NV-Segment-CTMR).
+Source revision or version: `f9f5f51b589e5dc9c23c453cf5138398e4084056`.
+Original checkpoint: [pinned checkpoint](https://huggingface.co/nvidia/NV-Segment-CT/resolve/afb51518689f71e6abb367ee6301b2cd0225c66a/vista3d_pretrained_model/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: **LicenseRef-NVIDIA-Open-Model** ([license](https://huggingface.co/MedMLX/vista3d-ct-mlx/blob/main/LICENSE)).
+Upstream code: **Apache-2.0**. MLX port code:
+[Apache-2.0](https://github.com/MedMLX/mlx-segment-ct/blob/main/LICENSE).
+Retain the [attribution and notices](https://huggingface.co/MedMLX/vista3d-ct-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 the applicable NVIDIA Open Model Agreement and a Notice file containing: Licensed by NVIDIA Corporation under the NVIDIA Open Model License