Simplify model card with concise usage and MedMLX branding

README.md

@@ -15,30 +15,38 @@ license_link: https://github.com/HengruiTianSJTU/LesionDiffusion
 pipeline_tag: image-to-image
 ---
 
-# LesionDiffusion for MLX
+<img src="https://huggingface.co/MedMLX/lesiondiffusion-mlx/resolve/main/banner.png" alt="MedMLX — Generate. CT / LESION SYNTHESIS" width="100%">
 
-Converted LMNet, LINet, text-encoder and VQ weights for native MLX lesion synthesis on Apple Silicon. This entry remains **private**; original checkpoint and component terms remain applicable. Intended for research and education, not clinical use.
+# LesionDiffusion
 
-Use the public [lesiondiffusion-mlx v0.2.1 package](https://github.com/MedMLX/lesiondiffusion-mlx/releases/tag/v0.2.1), source revision `41f7400dd6f34b1b5844732ad2360a1301cdb9fa`, on an Apple Silicon Mac with Metal and Python 3.13 or 3.14. Inference does not require PyTorch. The package reads this consolidated safetensors bundle directly; no source patch is needed.
+Synthesize lesions in CT with native MLX using the released LMNet, LINet and VQ components.
 
-## Install and download
+[GitHub](https://github.com/MedMLX/lesiondiffusion-mlx) · [Files](https://huggingface.co/MedMLX/lesiondiffusion-mlx/tree/main) · [Docs](https://github.com/MedMLX/lesiondiffusion-mlx/blob/main/README.md#quick-start)
 
-Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git, then create a Python environment and install the pinned public package. Install the Hub CLI as a standalone tool; your Hugging Face account needs access to this private model entry.
+| Input | Output |
+| :--- | :--- |
+| CT + aligned binary organ mask | Synthetic CT and lesion mask |
+
+**Apple Silicon · Metal · Python 3.13 / 3.14**
+
+Private weights. Your Hugging Face account needs access.
+
+## Quick start
 
 ```bash
 uv venv --python 3.13
 source .venv/bin/activate
-uv pip install "lesiondiffusion-mlx @ git+https://github.com/MedMLX/lesiondiffusion-mlx.git@41f7400dd6f34b1b5844732ad2360a1301cdb9fa"
+
+repo="https://github.com/MedMLX/lesiondiffusion-mlx"
+release="$repo/releases/download/v0.2.1"
+uv pip install "$release/lesiondiffusion_mlx-0.2.1-py3-none-any.whl"
 uv tool install huggingface-hub
+
 hf auth login
-hf download MedMLX/lesiondiffusion-mlx --local-dir lesiondiffusion-weights
+hf download MedMLX/lesiondiffusion-mlx --local-dir models
 ```
 
-The download contains `model.safetensors`, `conversion.json`, `tokenizer.json`, and retained notices. Weights are stored in FP32 with `<stage>.` prefixes: `lmnet`, `lmnet_text`, `linet`, `linet_text`, and `vq`. The package applies its declared inference precision profile when loading each stage.
-
-## Public API
-
-Provide a CT NIfTI and an aligned binary organ mask (0 background, 1 organ). For a liver example:
+Replace the example input paths with your own files.
 
 ```python
 from lesiondiffusion_mlx.medmlx import run
@@ -46,7 +54,7 @@ from lesiondiffusion_mlx.medmlx import run
 result = run(
     image_path="ct_1mm_ras.nii.gz",
     organ_mask_path="liver_mask.nii.gz",
-    weights_path="lesiondiffusion-weights",
+    weights_path="models",
     output_dir="out",
     organ="liver",
     lesion_type="tumor",
@@ -59,30 +67,10 @@ result = run(
 print(result["outputs"]["synthetic_image"])
 ```
 
-The default `conditioned` mode sends phenotype text to LINet and uses native FP16 convolution. It changes generated outputs relative to `inference_mode="source"`, which follows the pinned upstream inference behavior, including disabled LINet image-text conditioning and source-ordered convolution arithmetic. Both modes default to 200 steps and seed 23. Source-mode agreement does not establish conditioned-mode equivalence or generated-image quality.
-
-The [v0.2.1 input/output contract](https://github.com/MedMLX/lesiondiffusion-mlx/blob/v0.2.1/README.md#input-and-output) defines supported geometry, organ labels, placement and optional phenotype controls. Axis-aligned inputs are standardized to an even-dimensioned RAS 1 mm grid; oblique or sheared transforms are refused. Inputs must support the documented 152 × 152 × 64 and 128³ crops. The CT and mask must resolve to the same standardized grid.
-
-A successful run returns output paths under `result["outputs"]`: `synthetic_image`, `target_mask` and `organ_mask`. The files are `synthetic_ct.nii.gz`, `lesion_mask.nii.gz` and `organ_mask.nii.gz` on the standardized grid. Existing outputs require explicit `overwrite=True` to replace them. In the default full reconstruction, voxels outside the lesion can also change, and CT intensities are clipped to [-1000, 1000] HU. See the package contract for `output_region="box"`. Synthetic output is not ground truth.
-
-## Qualification scope
-
-The v0.2.1 release acceptance on October 24, 2026 used the installed wheel with public `medmlx-core==0.2.3`, MLX 0.32.4 and no PyTorch in the inference environment. A complete default conditioned 200-step, seed-23 public-API run finished in 372.0 seconds on one fixed AMOS22 `amos_0008` CT/liver crop (label 6; 160 × 160 × 128, RAS, 1 mm). The generated CT was finite, output masks had the required label types, and output geometry and coded forms matched the prepared input. This is an execution and output-contract check, not an assessment of appearance, lesion fidelity or clinical effectiveness.
-
-All 139 current owner tests passed with zero skips, including the independent pinned-source numerical/contract tests. Their reduced-width and source-mode scope is described in the [technical notes](https://github.com/MedMLX/lesiondiffusion-mlx/blob/v0.2.1/docs/technical.md). The full conditioned run above is not a paired full-checkpoint source comparison.
-
-Before this card update, every tensor in this Hub bundle was compared on CPU against the fresh canonical conversion used for that release acceptance: all 1,141 tensor keys, shapes, dtypes and values across five stages matched exactly, as did the tokenizer bytes. Both `source` and `conditioned` asset admission passed through the installed v0.2.1 public package. The Hub serialization was not given a separate full inference rerun; its tensor-equivalence check does not extend the model qualification.
-
-## Source and conversion
-
-Original publisher: HengruiTianSJTU. Source: [LesionDiffusion](https://github.com/HengruiTianSJTU/LesionDiffusion), pinned revision `880736e2b8a4d9becdb6594da7f8af6db19d04d1`.
-
-The bundle was converted from the released `LMNet.ckpt`, `LINet.ckpt` and `VQ.ckpt` components, with an explicitly supplied BiomedCLIP tokenizer. Conversion uses EMA weights and changes tensor layout/storage without retraining. `conversion.json` records the source revision, layout and precision profile. To repeat conversion from assets obtained from the original publisher, use the [v0.2.1 conversion recipe](https://github.com/MedMLX/lesiondiffusion-mlx/blob/v0.2.1/README.md#quick-start) and its optional `conversion` extra. Do not use this card as a grant to obtain or redistribute upstream assets.
-
-## Distribution terms and notices
+Use an aligned CT and binary organ mask on a RAS 1 mm grid. Synthetic output is not ground truth.
 
-Upstream LesionDiffusion code: **MIT**. Native package code: **Apache-2.0**, with component-specific notices in the [source distribution](https://github.com/MedMLX/lesiondiffusion-mlx/blob/v0.2.1/THIRD_PARTY_NOTICES.md). **Checkpoint redistribution terms remain unresolved; retrieve original checkpoints directly from the original publisher.**
+## Use & license
 
-This entry is a **private converted-weight archive**. Public redistribution review remains separate; the original checkpoint and component terms are unchanged. This update grants no new or broader license and does not clear the model for public redistribution.
+For research and education. Not validated for clinical use.
 
-Retain the applicable license, copyright and attribution notices, identify the upstream checkpoint and authors, and identify the MLX conversion changes. The existing `NOTICE` and `SOURCE_LICENSE` files are retained without alteration. Review the [original publisher's project](https://github.com/HengruiTianSJTU/LesionDiffusion) and its component terms before use or redistribution.
+Upstream checkpoint and component terms apply; redistribution is not cleared. [Notices](https://huggingface.co/MedMLX/lesiondiffusion-mlx/blob/main/NOTICE).