Clean model card formatting and usage

README.md

@@ -2,80 +2,126 @@
 license: cc-by-nc-4.0
 library_name: mlx
 tags:
-- medical-imaging
+- mlx
+- native-mlx
 - apple-silicon
+- medical-imaging
+- x-ray
+- segmentation
+- noncommercial
 - research
 language:
 - en
+inference: false
+pipeline_tag: image-segmentation
 ---
-# FleXray flux0375 single member, label 'lungs', threshold 0.5, no TTA
 
-Native MLX package: [flexray-mlx](https://github.com/MedMLX/flexray-mlx).
-Evaluated revision: `d768bb15d04ee677ecec0c469fd3170256b345df`.
+# FleXray Radiograph Segmentation
 
-This card describes the one configuration evaluated in the MedMLX paper. It is research software; the single-case comparison does not estimate clinical accuracy.
+Native MLX port of [FleXray](https://github.com/VictorButoi/FleXray).
+Segment anatomical structures in radiographs locally on Apple Silicon.
 
-## Source and checkpoint
+- Released `flux0375` member
+- Lung segmentation in the quick start
+- Single-member inference; noncommercial weights
 
-Original publisher: VictorButoi.
-Original implementation: [https://github.com/VictorButoi/FleXray](https://github.com/VictorButoi/FleXray).
-Source revision or version: `bf6d01426fd3ae012aff9253ec9c9952c58bc960`.
-Original checkpoint: https://huggingface.co/VictorButoi/flexray/resolve/6b63ddf09cfdff99aea494e3738cf243a4e22cdb/members/flux0375/model.safetensors
+MLX implementation by [MedMLX](https://github.com/MedMLX).
+[GitHub](https://github.com/MedMLX/flexray-mlx) · [Usage](https://github.com/MedMLX/flexray-mlx#quick-start) · [Upstream](https://github.com/VictorButoi/FleXray)
+
+**Requires the companion `flexray-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.
 
-Conversion: released safetensors snapshot loaded directly.
-Conversion changes tensor layout or storage as specified by the native package; it does not retrain the model.
+## Quick start
 
-## Recorded example
+```bash
+uv venv --python 3.12
+source .venv/bin/activate
+uv pip install "flexray-mlx @ git+https://github.com/MedMLX/flexray-mlx.git" huggingface_hub
 
-NLM Montgomery County CXR / MCUCXR_0001_0
+hf download MedMLX/flexray-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 flexray_mlx.medmlx import run
 
-# Replace file and directory names with your locally obtained inputs and weights.
-kwargs = {
-    "image_path": "MCUCXR_0001_0.png",
-    "weights_path": "flexray",
-    "output_dir": "out",
-    "label_name": "lungs",
-    "ensemble": False,
-    "overwrite": True
-}
-result = run(**kwargs)
+result = run(
+    image_path='chest.png',
+    weights_path='models',
+    output_dir='outputs',
+    label_name='lungs',
+    ensemble=False,
+)
 print(result["outputs"])
 ```
 
+Only `flux0375` is packaged. Keep `ensemble=False`; the retained upstream
+ensemble descriptor lists five members, but the other four are not included.
+
+## Input and output
+
+Input is one radiograph: a raster image supported by Pillow or a single-frame
+2D DICOM. The example segments the lungs.
+
+Each run writes:
+
+- `source_image_label.png` — 0/1 mask at source resolution
+- `source_image.png` — 8-bit grayscale input
+- `probabilities.npy` — float32 probabilities for all 61 labels
+- `prediction.json` — label, threshold and member metadata
+
+## Technical details
+
 Native result: **success**. Original-code comparison: **pass**, `minimum_per_label_dice` = `0.9999704176268988`.
 
 Paper uses flux0375 only; the prepared bundle supports `ensemble=False`. The unchanged upstream ensemble descriptor lists all five members, but only the flagship member is packaged. Original comparison passes. Montgomery radiograph panels are excluded from submission/distribution pending image-sharing clearance.
 
-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.
+These are recorded results for one configuration, not a new benchmark or an
+estimate of clinical accuracy. The [native run](https://huggingface.co/MedMLX/flexray-mlx/blob/main/native-run.json)
+and [original-code comparison](https://huggingface.co/MedMLX/flexray-mlx/blob/main/reference-comparison.json)
+retain the commands, precision, geometry and output checks.
 
-## Distribution terms
+<details>
+<summary>Checkpoint provenance and recorded configuration</summary>
 
-Upstream code: **MIT**. Weights: **CC-BY-NC-4.0**.
-Converted weights are hosted in this repository.
+Recorded configuration: **FleXray flux0375 single member, label 'lungs', threshold 0.5, no TTA**.
 
-Paper uses flux0375 only; the prepared bundle supports `ensemble=False`. The unchanged upstream ensemble descriptor lists all five members, but only the flagship member is packaged. Original comparison passes. Montgomery radiograph panels are excluded from submission/distribution pending image-sharing clearance. Converted weights may retain the identified upstream license and required notices; the accompanying notices describe the redistribution terms.
+Evaluated package revision: `d768bb15d04ee677ecec0c469fd3170256b345df`.
 
-Full [upstream license](LICENSE) accompanies any weight distribution.
+Recorded input: NLM Montgomery County CXR / MCUCXR_0001_0.
 
-Required notices:
+Original publisher: VictorButoi.
+Original implementation: [upstream source](https://github.com/VictorButoi/FleXray).
+Source revision or version: `bf6d01426fd3ae012aff9253ec9c9952c58bc960`.
+Original checkpoint: [pinned checkpoint](https://huggingface.co/VictorButoi/flexray/resolve/6b63ddf09cfdff99aea494e3738cf243a4e22cdb/members/flux0375/model.safetensors).
 
-- Retain the applicable license, copyright and attribution notices; identify the upstream checkpoint, authors, and MLX conversion changes.
-- Credit the creator and source, link the applicable CC license, retain supplied notices, and identify conversion changes.
-- Label converted weights noncommercial and preserve the applicable noncommercial limitation.
+The released safetensors snapshot is loaded directly, without retraining.
+
+The [replay harness](https://github.com/MedMLX/Med-MLX/blob/main/benchmarks/README.md)
+describes how to reproduce the recorded configuration with local paths.
 
-Review sources:
+</details>
 
-- https://github.com/VictorButoi/FleXray
-- https://huggingface.co/VictorButoi/flexray/resolve/6b63ddf09cfdff99aea494e3738cf243a4e22cdb/members/flux0375/model.safetensors
+## Intended use
 
-## Packaged files
+Research and education. Outputs require human review and are not intended for
+clinical diagnosis or treatment decisions.
 
-- `ensemble.json`
-- `members/flux0375/checksums.json`
-- `members/flux0375/config.yml`
-- `members/flux0375/label_schema.json`
-- `members/flux0375/model.safetensors`
-- `members/flux0375/preprocessing.json`
+## License
+
+Weights: **CC-BY-NC-4.0** ([license](https://huggingface.co/MedMLX/flexray-mlx/blob/main/LICENSE)).
+Upstream code: **MIT**. MLX port code:
+[Apache-2.0](https://github.com/MedMLX/flexray-mlx/blob/main/LICENSE).
+
+Retain the [attribution and notices](https://huggingface.co/MedMLX/flexray-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.
+- Credit the creator and source, link the applicable CC license, retain supplied notices, and identify conversion changes.
+- Label converted weights noncommercial and preserve the applicable noncommercial limitation.