MingzhenL/vessa-2d-ssl-bundle

VESSA 2D + semi-supervised baselines — handoff bundle

Working bundle for the chest X-ray heart + implanted-device segmentation project: the VESSA Stage-1 teacher checkpoint, the Stage-2 code for four semi-supervised frameworks (Mean Teacher, FixMatch, UniMatch v1, UniMatch v2) with and without VESSA pseudo-label supervision, the student-as-memory (studmem) extension for UniMatch v2, the canonical scorer, the dataset/template-bank builders, and a worked example dataset.

Start with HANDOFF.md — it is the task description for the agent that inherits this work.

Path	What
HANDOFF.md	the task, setup, data prep, experiment matrix, scoring, traps
code/VESSA_univ1/train_semi/	Stage-2 entrypoints: mt_, fixmatch_, unimatchv1_, unimatch_ (=v2) _vessa_multiclass.py, unimatch_vessa_multiclass_studmem.py, supervised_multiclass.py, studmem/
code/VESSA_univ1/train_vessa/	VESSA model + inference (vessa_prompt.py), vendored SAM2 (model/sam2_main/, weight NOT included)
code/VESSA/metric_calculator/	canonical scorer (metric_master.py, miseval)
code/VESSA/data_preprocessing/	prepare_percentage_dataset.py, build_template_bank.py — builds <NAME>_<PCT>percent_exact_processed banks
checkpoints/vessa_stage1_17ds_10pct/ckpt_model/	VESSA Stage-1 teacher (DeepSpeed ZeRO-2 dir, 23 GB; both files are required)
pretrained_dino/dinov2_base.pth	DINOv2-base init for the UniMatch v2 / v1 students (331 MB)
example_data/RL_dataset/CXR*	public Shenzhen CXR lung set in the expected format + its 1/5/10 % banks — use it to validate the pipeline before the new data arrives
configs_template/	config templates for the new dataset at 1 / 5 / 10 / 100 %
envs/	requirements_portable.txt (curated) and vessa_rl_pip_freeze.txt (exact)
docs/	VESSA_FRAMEWORK_HANDOFF.md (full framework manual, 17 traps), STUDMEM_README_PORTABLE.md, run instructions
results/gate_p1_full_6516936.json	the 2D studmem pseudo-label gate result on STS 1 % (template-only 0.794 → +student 0.841 Dice)

Public assets to download separately (links in HANDOFF.md): SAM 2.1 Hiera-Large, Qwen3-VL-4B-Instruct (pinned revision), DINOv2 ViT-S/14 (torch.hub).