Metadata-Version: 2.5
Name: synthrad-sct
Version: 0.1.1
Summary: One-command installer for the COMP3888 P40 abdomen MRI-to-sCT models
Project-URL: Source, https://github.sydney.edu.au/fyan0582/COMP3888_W11_04_P40/tree/main/installer
Project-URL: Weights, https://github.sydney.edu.au/dmat0262/synthrad-sct-weights
Author: COMP3888 W11-04 P40
Keywords: installer,medical-imaging,mri,synthetic-ct,synthrad
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Requires-Dist: pyyaml>=6
Requires-Dist: questionary>=2
Requires-Dist: rich>=13
Description-Content-Type: text/markdown

# synthrad-sct installer

One command that sets up the abdomen MRI-to-sCT models from this repository:
it clones the code, builds a Python 3.11 environment, downloads the trained
weights, checks them, and runs a smoke test. No retraining.

## For the client

You need [uv](https://docs.astral.sh/uv/getting-started/installation/),
git and the [GitHub CLI](https://cli.github.com), plus read access to this
repository and [dmat0262/synthrad-sct-weights](https://github.sydney.edu.au/dmat0262/synthrad-sct-weights)
on `github.sydney.edu.au` (on campus or VPN). You do not need to clone anything.

Log in once, so that uv, git and the installer reuse the same login and never ask for a token:

```bash
gh auth login --hostname github.sydney.edu.au
uvx synthrad-sct init
```

The installer asks a few questions:

1. **GitHub token**, only if you skipped `gh auth login`. Make one at
   <https://github.sydney.edu.au/settings/tokens/new?scopes=repo>, or set
   `SYNTHRAD_GITHUB_TOKEN`.
2. **Where to clone.** Skipped if you run it inside an existing clone.
3. **Which models.** B6 and B2 are pre-selected.
4. **CPU or CUDA.** Detected automatically. On macOS it is always CPU.
5. **Web previewer.** Optionally installs the Gradio demo, which supports B2 or B3.

Then it:

- creates `.venv` with Python 3.11, which uv downloads if needed;
- installs PyTorch 2.5.1 and the pinned NumPy/SimpleITK/SciPy versions the
  weights were trained with;
- downloads each `epoch_0400.pt` and checks its SHA-256 against the hash
  recorded with the test results;
- puts each file where the inference code already looks:
  `<experiment>/checkpoints_AB_400epochs/<run>/epoch_0400.pt`;
- writes `ct_free_inference/configs/inference.local.yaml`;
- runs `ct_free_inference/smoke_models.py` on the downloaded weights.

If a download is interrupted, run the command again. It resumes and skips
anything already downloaded and checked.

| Model | What it is | Test MAE (HU) | Evidence |
| --- | --- | ---: | --- |
| B6 | 2.5D U-Net + PatchGAN, 5 slices, GAN weight 0.01 | 108.80 | MRI-only pipeline |
| B2 | 2.5D U-Net + PatchGAN, 5 slices, 256 crop | 113.03 | historical paired workflow |
| B0 | 2D U-Net + PatchGAN, centre slice | 114.20 | historical paired workflow |
| B3 | 2.5D U-Net + PatchGAN, 5 slices, 512 crop | 118.00 | historical paired workflow |

See [AB_EXPERIMENTS_README.md](https://github.sydney.edu.au/fyan0582/COMP3888_W11_04_P40/blob/main/AB_EXPERIMENTS_README.md) for what the
evidence columns mean.

### Other commands

```bash
synthrad-sct list                           # models, scores, which are installed
synthrad-sct doctor                         # check git/uv/token/GPU/.venv/weights
synthrad-sct download --models B3 B0        # add weights to an existing setup
synthrad-sct init -y --models B6 --device cpu --no-previewer   # no prompts
```

Prefix each with `uvx`, or install once with `uv tool install synthrad-sct`.
Without PyPI, the same CLI runs straight from Git:
`uvx --from "git+https://github.sydney.edu.au/fyan0582/COMP3888_W11_04_P40.git#subdirectory=installer" synthrad-sct init`.

## For the team: publishing the weights

The weights are files on the `weights-v1` release of
[dmat0262/synthrad-sct-weights](https://github.sydney.edu.au/dmat0262/synthrad-sct-weights),
kept apart from this course repository so they outlive it. They are never
committed to Git: GitHub rejects files over 100 MB. You need the [GitHub CLI](https://cli.github.com) logged in
with `gh auth login --hostname github.sydney.edu.au`.

```bash
cd installer
uv run synthrad-sct publish --dry-run B0=/path/B0/epoch_0400.pt B2=/path/B2/epoch_0400.pt \
  B3=/path/B3/epoch_0400.pt B6=/path/B6/epoch_0400.pt
# then the same command without --dry-run
```

`publish` first writes the weights repository's `README.md` (a model card)
and `SHA256SUMS` from the pinned table, then creates the release if needed and
uploads the files. It refuses any file whose SHA-256 differs from the checkpoint the
reported results came from. Hashes are pinned in
`src/synthrad_sct/models.py`, and the tests check them against `results/` and
`metadata/`. If a model is retrained, update the recorded results and the
pinned hash together, and publish under a new tag.

## Releasing to PyPI

Bump `version` in `pyproject.toml` and `__init__.py`, then:

```bash
cd installer
rm -rf dist && uv build
UV_PUBLISH_TOKEN=pypi-… uv publish
```

If the package is ever removed from PyPI, switch the commands in this README and
`weights_repo.INSTALL` back to the Git form first.

## Tests

```bash
cd installer
uv run --with numpy --with SimpleITK python -m unittest discover -s tests -v
```
