KylianSu/vessel-bezier-retinal-weights

ST — Weights & Training Logs

Companion Hugging Face repository for the audited GitHub handoff KylianSu/reproduce_dr.

This repo holds all weights, training logs, and reviewer-facing artifacts for the NeurIPS 2026 submission on Bezier-conditioned ControlNet + parameter-level counterfactual verification of vessel geometry → diabetic retinopathy (DR).

Layout

weights/
  sd21_lora_fundus_v2/                      <-  Paper-final LoRA (noise_offset=0.1, rank=64)
    pytorch_lora_weights.safetensors        51 MB
  sd21_lora_fundus_v1/                      <-  Earlier LoRA, kept for comparison
    pytorch_lora_weights.safetensors        51 MB

  controlnet_g3_bezier_v3/                  <-  Paper-final G3 (Bezier-hint) ControlNet
    best_controlnet.pth                     78 MB
    train.log + hint_preview_epoch*.png
  controlnet_g2_encoder_v2/                 <-  Paper-final G2 (z_spatial-hint) ControlNet
    best_controlnet.pth                     78 MB
    train.log
  controlnet_g3_bezier_v1_legacy/           <-  Earlier G3 versions (logs + previews only;
  controlnet_g3_bezier_v2_legacy/               weights already pruned during 2026-04-23 cleanup)

  clip_finetune/                            <-  BiomedCLIP two-stage finetune (Stage 2 final)
    20260326_041223/best_model.pth          748 MB
    train.log + history.json + config.json
  vessel_encoder_v2/                        <-  VesselEncoderV2 (z_tok / z_spatial producer)
    20260407_201552/best_encoder_v2.pth     382 MB
    train.log + history.json + config.json

  cls_binary_leakfree/                      <-  Downstream DR classifiers (leak-free baselines)
    baseline/best_model.pth                 30 MB    (EfficientNet-B2 @ 384)
    baseline_resnet50/best_model.pth        90 MB    (ResNet-50 @ 384)
    baseline_vitb16/best_model.pth          329 MB   (ViT-B/16 @ 384, low DR sensitivity)
    augmented_g{2,3}_{400,4k}[_10pct]/      Prompt-bug-era synth augmentation (retained for comparison)
  cls_binary_leakfree_pfix/                 <-  Prompt-fixed augmentation (paper §5.3 main table)
    aug_g{2,3}_{400,4k}[_10pct]_pfix/       8 variants, 30 MB each

experiment_E/                               <-  Track 4 DR-prompt main experiment
  hints/ + gen/                             hints + generated images for every start x config
  stage{1,2,3}*.csv + stems.json + causal_curves*.png
experiment_E_uncond/                        <-  Track 4 Uncond (paper's strongest Delta = +0.781 cohort)
  hints/ + gen/ + CSV + top-5 champion visualization

How to download

# Whole repo (~2.8 GB)
hf download KylianSu/vessel-bezier-retinal-weights --repo-type model --local-dir ./hf_weights

# Or a single subtree
hf download KylianSu/vessel-bezier-retinal-weights --include "weights/sd21_lora_fundus_v2/*" --local-dir ./hf_weights

How the code expects the files

After download, copy (or symlink) the relevant folders back under the code repo's train_logs/, cls_binary_leakfree/, cls_binary_leakfree_pfix/, experiment_E/, experiment_E_uncond/:

rsync -a hf_weights/weights/sd21_lora_fundus_v2/  $ST_BASE/train_logs/sd21_lora_fundus_v2/
rsync -a hf_weights/weights/controlnet_g3_bezier_v3/  $ST_BASE/train_logs/diffusion_sd21/20260415_140655_group3_bezier_v3/
# ... etc, matching paths referenced in scripts/*.sh

The source repository now provides an exact restore script:

git clone https://github.com/KylianSu/reproduce_dr.git
cd reproduce_dr
bash scripts/00_setup_env.sh
bash scripts/01c_restore_paper_weights.sh

See docs/13_remote_handoff.md for the complete clean-machine procedure. The script verifies the six paper-final trainable checkpoints against data_manifests/PAPER_FINAL_MODEL_SHA256SUMS.

Derived-data handoff

The private dataset repository KylianSu/btecf-dr-handoff preserves the recomputed AutoMorph masks, Bézier/CLIP features, fixed splits, Track 1/2 outputs, and both updated n=500 reruns. An authorized researcher can restore and checksum all of them with:

hf auth login
bash scripts/15_download_handoff_assets.sh

The current n=500 files are a reproducible post-submission rerun using the audited AutoMorph preprocessing. They preserve the fixed-start design and main tortuosity conclusion, with small numerical variation from the updated masks. They should be cited as the updated rerun rather than as a byte-identical copy of the submission snapshot. The archived n=50 files remain the direct evidence for the submitted Table 4/5 statistics.

Other artifacts you still need (not in this repo)

• Stable Diffusion 2.1 base (24 GB): https://huggingface.co/stabilityai/stable-diffusion-2-1-base
• BiomedCLIP pretrained (753 MB): https://huggingface.co/microsoft/BiomedCLIP-PubMedBERT_256-vit_base_patch16_224
• EyePACS + APTOS + Messidor images: use the pinned upstream download scripts and manifests in the GitHub repository. These third-party images are intentionally not redistributed here.

License

TBD — please contact the project owner (see GitHub repo) before any external redistribution.