synthrad-sct 0.1.0__py3-none-any.whl

synthrad_sct/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

synthrad_sct/__main__.py

@@ -0,0 +1,4 @@
+import sys
+from .cli import main
+
+sys.exit(main())

synthrad_sct/cli.py

@@ -0,0 +1,307 @@
+"""synthrad-sct: install the team's MRI-to-sCT models in one command."""
+from __future__ import annotations
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (BarColumn, DownloadColumn, Progress, TextColumn,
+                           TimeRemainingColumn, TransferSpeedColumn)
+from rich.table import Table
+
+from . import __version__, environment as env, weights_repo
+from .github import Client, GitHubError, find_token, git_auth_env, prompt_token, sha256_file
+from .models import DEFAULT_MODELS, GITHUB_HOST, MODELS, WEIGHTS_REPO, WEIGHTS_TAG
+
+console = Console()
+
+
+def interactive(args):
+    return not args.yes and sys.stdin.isatty()
+
+
+def get_token(args):
+    token, source = find_token()
+    if token:
+        console.print(f"[dim]Using GitHub token from {source}.[/]")
+        return token
+    if not interactive(args):
+        raise GitHubError(f"No GitHub token. Set SYNTHRAD_GITHUB_TOKEN or run "
+                          f"`gh auth login --hostname {GITHUB_HOST}`.")
+    return prompt_token(console)
+
+
+def models_table(repo=None):
+    table = Table(title="Registered models (44-patient AB test means)", title_justify="left")
+    for column in ("Key", "Model", "MAE (HU)", "PSNR (dB)", "MS-SSIM", "Evidence"):
+        table.add_column(column, justify="right" if column[0] in "MP" and column != "Model" else "left")
+    if repo:
+        table.add_column("Installed")
+    for m in MODELS.values():
+        row = [m.key, m.summary, f"{m.mae_hu:.2f}", f"{m.psnr_db:.2f}", f"{m.ms_ssim:.3f}", m.evidence]
+        if repo:
+            row.append("[green]yes[/]" if (repo / m.checkpoint).is_file() else "[dim]no[/]")
+        table.add_row(*row)
+    return table
+
+
+def choose(args):
+    """Fill in models, device and previewer from flags, prompting for anything not given."""
+    import questionary
+    cuda = env.has_cuda()
+    if args.models is None:
+        if interactive(args):
+            console.print(models_table())
+            args.models = questionary.checkbox(
+                "Which models do you want?",
+                choices=[questionary.Choice(f"{m.key}  {m.summary}", m.key, checked=m.key in DEFAULT_MODELS)
+                         for m in MODELS.values()],
+                validate=lambda picked: bool(picked) or "Pick at least one model.").unsafe_ask()
+        else:
+            args.models = list(DEFAULT_MODELS)
+    if args.device is None:
+        detected = "cuda" if cuda else "cpu"
+        if interactive(args) and cuda:
+            args.device = questionary.select("Run inference on:", choices=["cuda", "cpu"],
+                                             default=detected).unsafe_ask()
+        else:
+            args.device = detected
+    if args.device == "cuda" and not cuda:
+        console.print("[yellow]No NVIDIA GPU detected; installing CUDA wheels anyway as requested.[/]")
+    has_arm = any(MODELS[k].previewer for k in args.models)
+    if args.previewer is None:
+        args.previewer = has_arm and interactive(args) and questionary.confirm(
+            "Also set up the web previewer (Gradio demo, B2/B3 only)?", default=True).unsafe_ask()
+    elif args.previewer and not has_arm:
+        console.print("[yellow]The previewer only runs B2 or B3; skipping it.[/]")
+        args.previewer = False
+
+
+def download(repo, keys, token, tag):
+    pending = [MODELS[k] for k in keys if not verified(repo / MODELS[k].checkpoint, MODELS[k].sha256)]
+    for k in set(keys) - {m.key for m in pending}:
+        console.print(f"[green]✓[/] {k} already downloaded and verified")
+    if not pending:
+        return
+    client = Client(token)
+    assets = client.release_assets(tag)
+    missing = [m.asset_name for m in pending if m.asset_name not in assets]
+    if missing:
+        raise GitHubError(f"Release {tag} is missing {', '.join(missing)}. Ask the team to run "
+                          "`synthrad-sct publish` for those models.")
+    columns = (TextColumn("{task.description}"), BarColumn(), DownloadColumn(),
+               TransferSpeedColumn(), TimeRemainingColumn())
+    with Progress(*columns, console=console) as progress:
+        for m in pending:
+            asset = assets[m.asset_name]
+            task = progress.add_task(m.key, total=int(asset["size"]))
+            def advance(n, absolute=False, task=task):
+                progress.update(task, completed=n) if absolute else progress.advance(task, n)
+            client.download(asset, repo / m.checkpoint, m.sha256, advance)
+            progress.update(task, description=f"[green]✓[/] {m.key}")
+
+
+def verified(path, sha256):
+    return path.is_file() and sha256_file(path) == sha256
+
+
+def step(text):
+    console.rule(f"[bold]{text}", align="left")
+
+
+def cmd_init(args):
+    console.print(Panel.fit(f"[bold]synthrad-sct[/] {__version__}\nAbdomen MRI → synthetic CT, "
+                            "COMP3888 W11-04 P40", border_style="cyan"))
+    token = get_token(args)
+    repo = env.find_repo(args.dir)
+    if repo:
+        console.print(f"Using the repository at [bold]{repo}[/]")
+    else:
+        target = Path(args.dir or "COMP3888_W11_04_P40").resolve()
+        if interactive(args) and not args.dir:
+            import questionary
+            target = Path(questionary.path("Clone the repository into:", default=str(target),
+                                           only_directories=True).unsafe_ask()).expanduser().resolve()
+        step(f"Cloning into {target}")
+        repo = env.clone(target, git_auth_env(token))
+    choose(args)
+    console.print(f"\nModels: [bold]{' '.join(args.models)}[/]   Device: [bold]{args.device}[/]   "
+                  f"Previewer: [bold]{'yes' if args.previewer else 'no'}[/]")
+    if interactive(args):
+        import questionary
+        if not questionary.confirm("Continue?", default=True).unsafe_ask():
+            return 1
+    python = None
+    if not args.skip_env:
+        step(f"Python {env.PYTHON_VERSION} environment in .venv")
+        python = env.create_venv(repo)
+        step(f"Installing dependencies ({args.device})")
+        env.install_dependencies(repo, python, args.device, args.previewer)
+    step(f"Downloading weights from {GITHUB_HOST}/{WEIGHTS_REPO} release {args.tag}")
+    download(repo, args.models, token, args.tag)
+    config = env.write_local_config(repo, args.models, args.device)
+    console.print(f"[green]✓[/] Wrote {config.relative_to(repo)}")
+    if python and not args.skip_smoke:
+        step("Smoke test: loading each checkpoint and predicting one patch")
+        env.smoke_test(repo, python, args.models, args.device)
+    next_steps(repo, args.models, args.previewer, python)
+    return 0
+
+
+def next_steps(repo, keys, previewer, python):
+    py = os.path.relpath(python, repo) if python else "python"
+    activate = (r".venv\Scripts\activate" if os.name == "nt" else "source .venv/bin/activate")
+    lines = [f"cd {repo}", f"{activate}", "",
+             "# One MRI volume → sCT",
+             f"python ct_free_inference/generate.py --model {keys[0]} --mri path/to/mr.mha "
+             f"--config {env.LOCAL_CONFIG.as_posix()} --output-dir outputs/{keys[0]}"]
+    if previewer:
+        arm = next(k for k in keys if MODELS[k].previewer)
+        lines += ["", "# Web previewer on http://localhost:7860",
+                  f"cd previewer && python app.py --arm {arm} --checkpoint ../{MODELS[arm].checkpoint}"]
+    lines += ["", "# Full docs: ct_free_inference/README.md"]
+    console.print(Panel("\n".join(lines), title="[green]Ready[/]", border_style="green", expand=False))
+    if not python:
+        console.print(f"[dim]Environment setup was skipped; use your own Python {env.PYTHON_VERSION} "
+                      f"environment instead of {py}.[/]")
+
+
+def cmd_download(args):
+    repo = env.find_repo(args.dir)
+    if not repo:
+        raise env.SetupError("Run this inside the repository, or pass --dir.")
+    keys = args.models or list(DEFAULT_MODELS)
+    download(repo, keys, get_token(args), args.tag)
+    env.write_local_config(repo, keys, args.device or ("cuda" if env.has_cuda() else "cpu"))
+    return 0
+
+
+def cmd_list(args):
+    console.print(models_table(env.find_repo(args.dir)))
+    console.print("[dim]B2/B3/B0 scores come from the earlier paired workflow; B6 from the MRI-only "
+                  "pipeline. See AB_EXPERIMENTS_README.md.[/]")
+    return 0
+
+
+def cmd_doctor(args):
+    repo = env.find_repo(args.dir)
+    checks = [("git", bool(shutil.which("git")), shutil.which("git") or "install from git-scm.com"),
+              ("uv", bool(shutil.which("uv")), shutil.which("uv") or "optional, recommended"),
+              ("GitHub token", bool(find_token()[0]), find_token()[1] or "none found"),
+              ("NVIDIA GPU", env.has_cuda(), "CUDA available" if env.has_cuda() else "CPU only"),
+              ("repository", bool(repo), str(repo) if repo else "not inside a clone")]
+    if repo:
+        python = env.venv_python(repo / ".venv")
+        checks.append((".venv", python.exists(), str(python)))
+        for m in MODELS.values():
+            path = repo / m.checkpoint
+            state = ("verified" if verified(path, m.sha256) else
+                     "HASH MISMATCH" if path.is_file() else "not downloaded")
+            checks.append((f"weights {m.key}", state == "verified", state))
+    table = Table(show_header=False)
+    for name, ok, detail in checks:
+        table.add_row("[green]✓[/]" if ok else "[yellow]•[/]", name, detail)
+    console.print(table)
+    return 0
+
+
+def cmd_publish(args):
+    """For the team: upload the epoch-400 checkpoints as release assets."""
+    files = {}
+    for item in args.checkpoints:
+        key, _, path = item.partition("=")
+        if key not in MODELS or not path:
+            raise env.SetupError(f"Expected KEY=PATH with KEY in {', '.join(MODELS)}; got {item!r}.")
+        path = Path(path).expanduser().resolve()
+        actual = sha256_file(path)
+        if actual != MODELS[key].sha256:
+            raise env.SetupError(f"{path} is not the evaluated {key} checkpoint "
+                                 f"(sha256 {actual[:12]}…, expected {MODELS[key].sha256[:12]}…).")
+        console.print(f"[green]✓[/] {key}: {path} matches the recorded hash")
+        files[key] = path
+    if args.dry_run:
+        return 0
+    if not shutil.which("gh"):
+        raise env.SetupError("Publishing needs the GitHub CLI: https://cli.github.com")
+    repo = f"{GITHUB_HOST}/{WEIGHTS_REPO}"
+    # Commit the text files first: an empty repository has no commit to tag a release on.
+    code = env.find_repo()
+    commit = code and subprocess.run(["git", "rev-parse", "HEAD"], cwd=code,
+                                     capture_output=True, text=True).stdout.strip()
+    for name, text in (("README.md", weights_repo.readme(args.tag, commit)),
+                       ("SHA256SUMS", weights_repo.sha256sums())):
+        try:
+            changed = weights_repo.push_file(name, text, f"Update {name} for {args.tag}")
+        except RuntimeError as error:
+            raise env.SetupError(str(error)) from None
+        console.print(f"[green]✓[/] {name} {'updated' if changed else 'already current'}")
+    if subprocess.run(["gh", "release", "view", args.tag, "-R", repo], capture_output=True).returncode:
+        env.run(["gh", "release", "create", args.tag, "-R", repo, "--title", "Model weights (epoch 400)",
+                 "--notes", "Epoch-400 generator checkpoints for B0/B2/B3/B6. See README.md "
+                            "for scores, hashes and the one-line installer."])
+    with tempfile.TemporaryDirectory() as staging:
+        # Assets are named after the file, and every checkpoint is called epoch_0400.pt.
+        named = []
+        for key, path in files.items():
+            link = Path(staging, MODELS[key].asset_name)
+            try:
+                link.symlink_to(path)
+            except OSError:
+                shutil.copy2(path, link)
+            named.append(str(link))
+        env.run(["gh", "release", "upload", args.tag, "-R", repo, "--clobber", *named])
+    console.print(f"[green]✓[/] Uploaded {', '.join(files)} to {repo} release {args.tag}")
+    return 0
+
+
+def parser():
+    p = argparse.ArgumentParser(prog="synthrad-sct", description=__doc__)
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def common(sp, models=True):
+        sp.add_argument("--dir", help="Repository directory (or clone target for init).")
+        sp.add_argument("--tag", default=WEIGHTS_TAG, help="Weights release tag.")
+        sp.add_argument("-y", "--yes", action="store_true", help="Accept defaults; never prompt.")
+        if models:
+            sp.add_argument("--models", nargs="+", choices=list(MODELS))
+            sp.add_argument("--device", choices=["cpu", "cuda"])
+
+    init = sub.add_parser("init", help="Clone, set up Python, download weights and smoke-test.")
+    common(init)
+    init.add_argument("--previewer", action=argparse.BooleanOptionalAction, default=None)
+    init.add_argument("--skip-env", action="store_true", help="Use your own environment.")
+    init.add_argument("--skip-smoke", action="store_true")
+    init.set_defaults(func=cmd_init)
+    dl = sub.add_parser("download", help="Download and verify weights only.")
+    common(dl)
+    dl.set_defaults(func=cmd_download)
+    ls = sub.add_parser("list", help="Show the models and their test results.")
+    ls.add_argument("--dir")
+    ls.set_defaults(func=cmd_list)
+    doc = sub.add_parser("doctor", help="Check tools, token, environment and weights.")
+    doc.add_argument("--dir")
+    doc.set_defaults(func=cmd_doctor)
+    pub = sub.add_parser("publish", help="(Team) upload checkpoints to the weights release.")
+    pub.add_argument("checkpoints", nargs="+", metavar="KEY=PATH")
+    pub.add_argument("--tag", default=WEIGHTS_TAG)
+    pub.add_argument("--dry-run", action="store_true", help="Only verify the hashes.")
+    pub.set_defaults(func=cmd_publish)
+    return p
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (GitHubError, env.SetupError) as error:
+        console.print(f"[red]✗[/] {error}")
+        return 1
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Cancelled. Run the same command again to resume.[/]")
+        return 130

synthrad_sct/environment.py

@@ -0,0 +1,122 @@
+"""Repository, Python environment and inference configuration setup."""
+from __future__ import annotations
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+from .models import GITHUB_HOST, GITHUB_REPO, MODELS
+
+PYTHON_VERSION = "3.11"  # What every experiment's environment.yml pins.
+# Match the training lock files, so inference runs on the versions the weights were trained with.
+TORCH = "torch==2.5.1"
+PINS = ["numpy==1.26.4", "SimpleITK==2.5.2", "scipy==1.14.1"]
+TORCH_INDEX = {"cpu": "https://download.pytorch.org/whl/cpu",
+               "cuda": "https://download.pytorch.org/whl/cu118"}
+MARKER = Path("ct_free_inference/model_registry.py")
+LOCAL_CONFIG = Path("ct_free_inference/configs/inference.local.yaml")
+
+
+class SetupError(RuntimeError):
+    pass
+
+
+def find_repo(start=None):
+    start = Path(start or Path.cwd()).resolve()
+    for directory in (start, *start.parents):
+        if (directory / MARKER).is_file():
+            return directory
+    return None
+
+
+def clone(target, env):
+    if not shutil.which("git"):
+        raise SetupError("git is not installed. Install it from https://git-scm.com and retry.")
+    url = f"https://{GITHUB_HOST}/{GITHUB_REPO}.git"
+    run(["git", "clone", url, str(target)], env=env)
+    if not (target / MARKER).is_file():
+        raise SetupError(f"Cloned {url}, but {MARKER} is missing; is this the right repository?")
+    return target.resolve()
+
+
+def has_cuda():
+    if platform.system() == "Darwin" or not shutil.which("nvidia-smi"):
+        return False
+    return subprocess.run(["nvidia-smi", "-L"], capture_output=True).returncode == 0
+
+
+def venv_python(venv):
+    return venv / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+
+
+def create_venv(repo):
+    venv = repo / ".venv"
+    python = venv_python(venv)
+    if python.exists():
+        version = subprocess.run([str(python), "-c", "import sys;print('%d.%d'%sys.version_info[:2])"],
+                                 capture_output=True, text=True).stdout.strip()
+        if version == PYTHON_VERSION:
+            return python
+        raise SetupError(f"{venv} uses Python {version}, not {PYTHON_VERSION}. Remove it and run again.")
+    if shutil.which("uv"):
+        # uv downloads Python 3.11 itself when the machine does not have it.
+        run(["uv", "venv", "--python", PYTHON_VERSION, str(venv)])
+    else:
+        base = find_python311()
+        run([*base, "-m", "venv", str(venv)])
+        run([str(python), "-m", "pip", "install", "--upgrade", "pip"])
+    return python
+
+
+def find_python311():
+    if sys.version_info[:2] == (3, 11):
+        return [sys.executable]
+    for candidate in (["py", "-3.11"], ["python3.11"]):
+        if shutil.which(candidate[0]) and subprocess.run(
+                [*candidate, "--version"], capture_output=True).returncode == 0:
+            return candidate
+    raise SetupError("Python 3.11 was not found. Install uv (https://docs.astral.sh/uv/) "
+                     "and run this through `uvx`, which provides Python automatically.")
+
+
+def install_dependencies(repo, python, device, previewer):
+    pip = (["uv", "pip", "install", "--python", str(python)] if shutil.which("uv")
+           else [str(python), "-m", "pip", "install"])
+    # macOS has only CPU/MPS wheels on PyPI; elsewhere pick the matching PyTorch index.
+    index = [] if platform.system() == "Darwin" else ["--index-url", TORCH_INDEX[device]]
+    run([*pip, TORCH, *index])
+    run([*pip, "-r", str(repo / "ct_free_inference/requirements.txt"), *PINS])
+    if previewer:
+        run([*pip, "-r", str(repo / "previewer/requirements.txt"), *PINS])
+
+
+def write_local_config(repo, keys, device):
+    """Copy the committed config, set the device and point each model at its downloaded weights."""
+    base = repo / "ct_free_inference/configs/inference.yaml"
+    config = yaml.safe_load(base.read_text(encoding="utf-8"))
+    config["device"] = device
+    config["use_amp"] = device == "cuda"
+    for key in keys:
+        # Relative to project_root, which read_config resolves from this file's directory.
+        config["models"][key]["checkpoint"] = str(MODELS[key].checkpoint)
+    path = repo / LOCAL_CONFIG
+    path.write_text("# Written by synthrad-sct. Ignored by Git; safe to edit.\n"
+                    + yaml.safe_dump(config, sort_keys=False), encoding="utf-8")
+    return path
+
+
+def smoke_test(repo, python, keys, device):
+    run([str(python), "ct_free_inference/smoke_models.py", "--device", device,
+         "--config", str(LOCAL_CONFIG), "--models", *keys,
+         "--output", "ct_free_inference/checks/model_smoke.json"], cwd=repo)
+
+
+def run(command, cwd=None, env=None):
+    result = subprocess.run(command, cwd=cwd, env=env)
+    if result.returncode:
+        shown = " ".join(c for c in command if "AUTHORIZATION" not in c)
+        raise SetupError(f"Command failed ({result.returncode}): {shown}")

synthrad_sct/github.py

@@ -0,0 +1,151 @@
+"""Release-asset downloads from the university GitHub Enterprise instance.
+
+Every API call there needs a token, including reads of releases, so the token
+is looked up once and reused for cloning and downloading.
+"""
+from __future__ import annotations
+import base64
+import getpass
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from .models import GITHUB_HOST, WEIGHTS_REPO
+
+TOKEN_ENV = ("SYNTHRAD_GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN")
+TOKEN_URL = f"https://{GITHUB_HOST}/settings/tokens/new?scopes=repo&description=synthrad-sct"
+API = f"https://{GITHUB_HOST}/api/v3"
+CHUNK = 1024 * 1024
+
+
+class GitHubError(RuntimeError):
+    pass
+
+
+def find_token(environ=os.environ, run=subprocess.run):
+    for name in TOKEN_ENV:
+        if environ.get(name):
+            return environ[name].strip(), name
+    if shutil.which("gh"):
+        result = run(["gh", "auth", "token", "--hostname", GITHUB_HOST],
+                     capture_output=True, text=True)
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip(), "gh CLI"
+    return None, None
+
+
+def prompt_token(console):
+    console.print(f"\nThe weights live on [bold]{GITHUB_HOST}[/], which needs a personal access token.")
+    console.print(f"Create one with the [bold]repo[/] scope here:\n  [link={TOKEN_URL}]{TOKEN_URL}[/link]")
+    console.print(f"[dim]Tip: set {TOKEN_ENV[0]} or run `gh auth login --hostname {GITHUB_HOST}` to skip this prompt.[/]\n")
+    token = getpass.getpass("Paste token (hidden): ").strip()
+    if not token:
+        raise GitHubError("No token given.")
+    return token
+
+
+def git_auth_env(token):
+    """Pass the token to git through the environment, not argv or the saved config."""
+    basic = base64.b64encode(f"x-access-token:{token}".encode()).decode()
+    env = dict(os.environ)
+    count = int(env.get("GIT_CONFIG_COUNT", "0"))
+    env.update({"GIT_CONFIG_COUNT": str(count + 1),
+                f"GIT_CONFIG_KEY_{count}": f"http.https://{GITHUB_HOST}/.extraheader",
+                f"GIT_CONFIG_VALUE_{count}": f"AUTHORIZATION: basic {basic}"})
+    return env
+
+
+class _StripAuthOnRedirect(urllib.request.HTTPRedirectHandler):
+    # Asset downloads redirect to signed storage URLs, which reject a second credential.
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        new = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new is not None and urllib.parse.urlsplit(newurl).netloc != urllib.parse.urlsplit(req.full_url).netloc:
+            new.remove_header("Authorization")
+        return new
+
+
+_opener = urllib.request.build_opener(_StripAuthOnRedirect)
+
+
+class Client:
+    def __init__(self, token, repo=WEIGHTS_REPO, opener=_opener):
+        self.token, self.repo, self.opener = token, repo, opener
+
+    def _request(self, url, accept="application/vnd.github+json", headers=None):
+        request = urllib.request.Request(url, headers={
+            "Authorization": f"token {self.token}", "Accept": accept,
+            "User-Agent": "synthrad-sct", **(headers or {})})
+        try:
+            return self.opener.open(request, timeout=60)
+        except urllib.error.HTTPError as error:
+            if error.code == 401:
+                raise GitHubError("The token was rejected (401). Check it has not expired.") from None
+            if error.code == 404:
+                raise GitHubError(f"Not found: {url}. The token may lack access to {self.repo}, "
+                                  "or the weights release has not been published yet.") from None
+            raise GitHubError(f"GitHub returned {error.code} for {url}.") from None
+        except urllib.error.URLError as error:
+            raise GitHubError(f"Could not reach {GITHUB_HOST}: {error.reason}. "
+                              "Are you on the university network or VPN?") from None
+
+    def release_assets(self, tag):
+        with self._request(f"{API}/repos/{self.repo}/releases/tags/{tag}") as response:
+            release = json.load(response)
+        return {a["name"]: a for a in release.get("assets", [])}
+
+    def download(self, asset, destination, sha256, progress=None, attempts=4):
+        """Resumable download to destination.part, renamed only after the hash matches."""
+        destination = Path(destination)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        partial = destination.with_name(destination.name + ".part")
+        size = int(asset["size"])
+        for attempt in range(1, attempts + 1):
+            offset = partial.stat().st_size if partial.exists() else 0
+            if offset > size:
+                partial.unlink()
+                offset = 0
+            try:
+                if offset < size:
+                    self._fetch(asset["url"], partial, offset, progress)
+                # A dropped connection can end the body early without an error.
+                if partial.stat().st_size < size:
+                    raise OSError("connection closed before the download finished")
+                break
+            except (GitHubError, OSError) as error:
+                if attempt == attempts:
+                    raise GitHubError(f"Download of {asset['name']} failed: {error}") from None
+                time.sleep(2 * attempt)
+        actual = sha256_file(partial)
+        if actual != sha256:
+            partial.unlink()
+            raise GitHubError(f"{asset['name']} hash mismatch: expected {sha256}, got {actual}. "
+                              "The partial file was removed; run the command again.")
+        partial.replace(destination)
+
+    def _fetch(self, url, partial, offset, progress):
+        headers = {"Range": f"bytes={offset}-"} if offset else {}
+        with self._request(url, "application/octet-stream", headers) as response:
+            if offset and response.status != 206:
+                offset = 0  # Server ignored the range; start over.
+            if progress:
+                progress(offset, absolute=True)
+            with partial.open("ab" if offset else "wb") as f:
+                for chunk in iter(lambda: response.read(CHUNK), b""):
+                    f.write(chunk)
+                    if progress:
+                        progress(len(chunk))
+
+
+def sha256_file(path):
+    h = hashlib.sha256()
+    with Path(path).open("rb") as f:
+        for chunk in iter(lambda: f.read(CHUNK), b""):
+            h.update(chunk)
+    return h.hexdigest()

synthrad_sct/models.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import os
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+GITHUB_HOST = "github.sydney.edu.au"
+GITHUB_REPO = "fyan0582/COMP3888_W11_04_P40"
+# Weights are release assets in their own repository, so they can outlive the course repo.
+WEIGHTS_REPO = os.environ.get("SYNTHRAD_WEIGHTS_REPO", "dmat0262/synthrad-sct-weights")
+WEIGHTS_TAG = "weights-v1"
+
+
+@dataclass(frozen=True)
+class Model:
+    key: str
+    folder: str
+    run: str
+    summary: str
+    sha256: str
+    mae_hu: float
+    psnr_db: float
+    ms_ssim: float
+    evidence: str
+    previewer: bool = False
+
+    @property
+    def asset_name(self):
+        return f"{self.key}_epoch_0400.pt"
+
+    @property
+    def checkpoint(self):
+        # The default location model_registry.checkpoint_for already searches.
+        return PurePosixPath(self.folder, "checkpoints_AB_400epochs", self.run, "epoch_0400.pt")
+
+
+# Hashes are the epoch-400 checkpoints recorded in each experiment's results/ or metadata/.
+# Metrics are 44-patient AB test means, quoted from the same files.
+MODELS = {m.key: m for m in [
+    Model("B0", "2D-U-Net-PatchGAN", "B0_2D_UNet_PatchGAN_AB",
+          "2D U-Net + PatchGAN, centre slice, 256 crop",
+          "547feffff2a3f6b7c8c708eafb0068158df64e036d4735e6dd3a2ff42f567df6",
+          114.20, 24.91, 0.767, "historical paired workflow"),
+    Model("B2", "5-slices-2.5dU-Net-PatchGAN", "B2_5Slice_2.5D_UNet_PatchGAN_AB",
+          "2.5D U-Net + PatchGAN, five slices, 256 crop",
+          "0f742a3ac56db2bc030d0c1a9b4c975b42e5c6745e2f36e9225cc48e3556ecd3",
+          113.03, 24.97, 0.768, "historical paired workflow", previewer=True),
+    Model("B3", "5-slices-2.5dU-Net-PatchGAN-512Crop", "B3_5Slice_2.5D_UNet_PatchGAN_512Crop_AB",
+          "2.5D U-Net + PatchGAN, five slices, 512 crop",
+          "942529899f9e49be9bbc4e85389edb4a8fa2271ff93e4332535187a9fbb77935",
+          118.00, 24.68, 0.753, "historical paired workflow", previewer=True),
+    Model("B6", "5-slices-2.5dU-Net-PatchGAN-GAN001", "B6_5Slice_2.5D_UNet_PatchGAN_GAN001_AB",
+          "2.5D U-Net + PatchGAN, five slices, GAN weight 0.01",
+          "a2f5883b53a006726a515afabda9d58f5d05e47bb1281474c8783f2c70d81c13",
+          108.80, 25.04, 0.776, "MRI-only pipeline"),
+]}
+DEFAULT_MODELS = ("B6", "B2")

synthrad_sct/weights_repo.py

@@ -0,0 +1,85 @@
+"""Text files committed to the weights repository, generated from the pinned model table."""
+from __future__ import annotations
+import base64
+import hashlib
+import json
+import subprocess
+
+from .models import GITHUB_HOST, GITHUB_REPO, MODELS, WEIGHTS_REPO
+
+INSTALL = "uvx synthrad-sct init"
+
+
+def sha256sums():
+    return "".join(f"{m.sha256}  {m.asset_name}\n" for m in MODELS.values())
+
+
+def readme(tag, commit=None):
+    rows = "\n".join(f"| {m.key} | {m.summary} | {m.mae_hu:.2f} | {m.psnr_db:.2f} | "
+                     f"{m.ms_ssim:.3f} | {m.evidence} |" for m in MODELS.values())
+    source = f"[`{commit[:12]}`](https://{GITHUB_HOST}/{GITHUB_REPO}/tree/{commit})" if commit else "main"
+    return f"""# synthrad-sct weights
+
+Trained generator checkpoints for the abdomen MRI-to-synthetic-CT models in
+[{GITHUB_REPO}](https://{GITHUB_HOST}/{GITHUB_REPO}) (COMP3888 W11-04 P40).
+This repository holds no code. The checkpoints are files on the
+[`{tag}` release](https://{GITHUB_HOST}/{WEIGHTS_REPO}/releases/tag/{tag}), not commits.
+
+## Install
+
+Log in once, then let the installer clone the code, set up Python and fetch these weights:
+
+```bash
+gh auth login --hostname {GITHUB_HOST}
+{INSTALL}
+```
+
+## Models
+
+All are epoch-400 generators trained on SynthRAD2025 Task 1 AB (abdomen) with the
+frozen 114 / 17 / 44 patient split. Scores are 44-patient test means.
+
+| Key | Model | MAE (HU) | PSNR (dB) | MS-SSIM | Evidence |
+| --- | --- | ---: | ---: | ---: | --- |
+{rows}
+
+B0, B2 and B3 were scored by the earlier paired workflow; B6 by the MRI-only
+pipeline. See `AB_EXPERIMENTS_README.md` in the code repository.
+
+## Integrity
+
+`SHA256SUMS` lists each file's hash, the same hashes the installer checks and the
+code repository records with each model's results. After a manual download:
+
+```bash
+sha256sum -c SHA256SUMS --ignore-missing
+```
+
+Weights match code at {source}. A retrained model is published under a new tag;
+files on an existing tag are never replaced.
+
+## Limitations
+
+Abdomen only, for MR protocols close to SynthRAD's centres. Research use, not a
+clinical tool. Check the SynthRAD2025 data licence before redistributing.
+"""
+
+
+def git_blob_sha(text):
+    data = text.encode()
+    return hashlib.sha1(b"blob %d\0" % len(data) + data).hexdigest()
+
+
+def push_file(path, text, message, run=subprocess.run):
+    """Create or update one file through the contents API; returns False if it was already current."""
+    endpoint = f"repos/{WEIGHTS_REPO}/contents/{path}"
+    current = run(["gh", "api", "--hostname", GITHUB_HOST, endpoint], capture_output=True, text=True)
+    sha = json.loads(current.stdout)["sha"] if current.returncode == 0 else None
+    if sha == git_blob_sha(text):
+        return False
+    command = ["gh", "api", "--hostname", GITHUB_HOST, "-X", "PUT", endpoint, "-f", f"message={message}",
+               "-f", f"content={base64.b64encode(text.encode()).decode()}"]
+    result = run(command + (["-f", f"sha={sha}"] if sha else []), capture_output=True, text=True)
+    if result.returncode:
+        raise RuntimeError(f"Could not write {path} to {WEIGHTS_REPO}: {result.stderr.strip()}")
+    return True

synthrad_sct-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: synthrad-sct
+Version: 0.1.0
+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
+```

synthrad_sct-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+synthrad_sct/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+synthrad_sct/__main__.py,sha256=ev6t1FIlUhYLSYDceY1ixjUeIwJgI8TcP0DvCihqjz0,51
+synthrad_sct/cli.py,sha256=-6k-iRwqQ_T7Edc9UN-yDT4HCSMb_gxTF9y8_CbP98k,14423
+synthrad_sct/environment.py,sha256=GrJN3fJa3MViGRP-NgO5hT69zGh_JWD369pv9wQh194,4908
+synthrad_sct/github.py,sha256=XkHRdGy1H2Nkqk5zZ3YDHSqxo8s8srzjKmVmxbbPUpo,6531
+synthrad_sct/models.py,sha256=y7DmncIjF9dk4Ykvk7ZGtzziAnQF4zV3YB1UnxQD1Rs,2308
+synthrad_sct/weights_repo.py,sha256=LVLDGYGUiK1RZCAMdsvCVW1Fd6mdH6mk4yFgu8jYI3E,3142
+synthrad_sct-0.1.0.dist-info/METADATA,sha256=MBIzaSPcuhiLjZeOXlNkpAv5rk-MQHibCllm2Ryvjrg,5446
+synthrad_sct-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+synthrad_sct-0.1.0.dist-info/entry_points.txt,sha256=q0nUNXIZWkJVwD2KIfuqljxIYEKu6Tdf0iQZXUoe62A,55
+synthrad_sct-0.1.0.dist-info/RECORD,,

synthrad_sct-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

synthrad_sct-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+synthrad-sct = synthrad_sct.cli:main