docs and recon container

Author: ChristianHinge

README.md

@@ -154,7 +154,10 @@ docker run --rm \
   ghcr.io/bic-mac-challenge/recon:latest
 ```
 
-The reconstructed PET is written to `/data/output/pet.nii.
+The reconstructed PET is written to `/data/output/pet.nii.gz`.
+
+> [!WARNING]
+> Running reconstruction requires **~20 GB of RAM** and takes **20–120 minutes** depending on CPU speed. The `intermediates/` folder uses **~50 GB** of additional disk space — consider deleting it after a successful reconstruction.
 
 ---
 

docs/docker-packaging.md

@@ -3,7 +3,7 @@
 Your container is run once per subject with two volume mounts:
 
 ```bash
-docker run --rm \
+timeout 300 docker run --rm \
   --memory 128g \
   --network none \
   --gpus all \
@@ -31,9 +31,8 @@ Your container must write the predicted CT to **`/data/output/ct.nii.gz`** — a
 
 ## Baseline as a Starting Point
 
-The baseline Dockerfile lives at `src/baseline/v2/inference/docker/Dockerfile`. It uses a PyTorch base image, installs dependencies from `requirements.txt`, copies code and weights, and sets the inference script as the entrypoint. Use it as a template.
+The baseline Dockerfile lives at `src/baseline/Dockerfile`. It uses a PyTorch base image, installs dependencies from `requirements.txt`, copies code and weights, and sets the inference script as the entrypoint. You can use it as a template.
 
-The key adaptation for any submission is reading inputs from `/data/features/` and writing output to `/data/output/`:
 
 ```python
 FEATURES_DIR = Path("/data/features")
@@ -49,24 +48,14 @@ nib.save(nib.Nifti1Image(pred_hu, ref.affine, ref.header), str(OUTPUT_DIR / "ct.
 
 ---
 
-## Submitting
-
-Save your image and email it (or a download link) to **bic-mac-challenge@github.io**:
-
-```bash
-docker save my-model:latest | gzip > my-model.tar.gz
-```
+## Validating Before Submission
 
-Subject line: `[DRY-RUN] <TeamName>` or `[FINAL] <TeamName>`
-
-See [submission-guide.md](submission-guide.md) for phase details.
+Before sending us your image, run it on the 4 validation subjects and upload the predictions to Codabench to confirm your container works end-to-end and your scores look reasonable. We cannot debug containers that fail silently on our infrastructure, so this step is required.
 
 ---
 
-## Common Pitfalls
-
-**Hardcoded paths** — make sure your container reads from `/data/features/`, not from training-time paths.
+## Submitting
 
-**Affine mismatch** — always copy the header from `features/nacpet.nii.gz` when saving output; don't derive it from an intermediate resampled volume.
+See [submission-guide.md](submission-guide.md) for full submission instructions, including how to share your image via Docker Hub or a compressed archive.
 
-**Network downloads at runtime** — `torch.hub`, `huggingface_hub`, etc. will fail. Bake weights in during `docker build`.
+---

docs/reconstruction.md

@@ -23,6 +23,9 @@ Intermediate outputs (μ-map, ACF sinogram, STIR-format files) are written to `o
 
 ---
 
+> [!WARNING]
+> Running reconstruction requires **~20 GB of RAM** and takes **20–120 minutes** depending on CPU speed. The `intermediates/` folder uses **~50 GB** of additional disk space — consider deleting it after a successful reconstruction.
+
 ## Running the Pipeline
 
 ### Option 1: Docker (recommended)

docs/submission-guide.md

@@ -33,27 +33,27 @@ If you only submit `ct.nii.gz`, you will receive CT metrics only. Submitting bot
 
 - NIfTI format (`.nii.gz`)
 - Same shape and affine as `features/nacpet.nii.gz`
-- CT values in Hounsfield units (valid range approximately −1000 to +3000 HU)
+- CT values in Hounsfield units 
 
 ### Zip structure
 
 ```
 submission.zip
-├── sub-068/
+├── sub-004/
 │   ├── ct.nii.gz
 │   └── pet.nii.gz   # optional
-├── sub-074/
+├── sub-009/
 │   ├── ct.nii.gz
-│   └── pet.nii.gz
-├── sub-081/
+│   └── pet.nii.gz   # optional
+├── sub-010/
 │   ├── ct.nii.gz
-│   └── pet.nii.gz
-└── sub-087/
+│   └── pet.nii.gz   # optional
+└── sub-018/
     ├── ct.nii.gz
-    └── pet.nii.gz
+    └── pet.nii.gz   # optional
 ```
 
-Upload to the [Codabench competition page](https://www.codabench.org/competitions/12555/).
+Upload to the [Codabench competition page](https://www.codabench.org/competitions/12555/#/participate-tab).
 
 ---
 
@@ -67,25 +67,28 @@ We run your container on the 4 validation subjects and return either:
 
 See [docker-packaging.md](docker-packaging.md) for how to build and test your container locally before submitting.
 
-### Container requirements
-
-Your container must:
-- Read inputs from `/data/features/` (read-only mount)
-- Write `ct.nii.gz` to `/data/output/`
-- Complete within 5 minutes per subject
-- Not require network access
 
 ### How to submit
 
-Save your image and email it (or a download link) to **bic-mac-challenge@github.io**:
+Email **bic-mac-challenge@github.io** with subject line `[DRY-RUN] <TeamName>` and include:
+- Team name, Docker image name and tag
+- A short description of your approach
+- A link to your image using **one** of the options below
 
+**Option A — Docker Hub (preferred):**
 ```bash
-docker save my-model:latest | gzip > my-model.tar.gz
+docker tag my-model:latest <dockerhub-username>/my-model:latest
+docker push <dockerhub-username>/my-model:latest
 ```
+Send us the full image name (e.g. `myteam/my-model:latest`).
 
-Subject line: `[DRY-RUN] <TeamName>`
+**Option B — Compressed archive via file sharing:**
+```bash
+docker save my-model:latest | gzip > my-model.tar.gz
+```
+Upload `my-model.tar.gz` to Google Drive, Dropbox, or similar and share the download link.
 
-Include in the body: team name, Docker image name and tag, and a short description of your approach.
+Dry Run submissions are limited to two per month per team.
 
 ---
 
@@ -103,11 +106,7 @@ Results and winner announcements: **September 1, 2026**.
 
 ### How to submit
 
-Same as the dry run — email your container to **bic-mac-challenge@github.io** with subject:
-
-```
-[FINAL] <TeamName>
-```
+Same as the dry run — email your container to **bic-mac-challenge@github.io** with subject `[FINAL] <TeamName>`, using Docker Hub or a compressed archive with a file sharing link.
 
 ---
 

src/recon/Dockerfile

@@ -54,8 +54,8 @@ ENV OVERWRITE=""
 ENV VERBOSE=""
 
 CMD python3 main.py \
-    /data/recon \
-    /data/ct/ct.nii.gz \
-    /data/output \
+    --recon_dir /data/recon \
+    --ct /data/ct/ct.nii.gz \
+    --output_dir /data/output \
     ${OVERWRITE:+--overwrite} \
     ${VERBOSE:+--verbose}

src/recon/docker-compose.yaml

@@ -28,7 +28,7 @@ def reconstruction_pipeline(
         overwrite=False,
         verbose=False,
         ):
-
+    
     out_pet_nifti_path         = os.path.join(output_dir, 'pet.nii.gz')
     intemediates_dir           = os.path.join(output_dir, 'intermediates')
     face_swapped_ct_path       = os.path.join(intemediates_dir, 'ct_face_swapped.nii.gz')
@@ -40,6 +40,8 @@ def reconstruction_pipeline(
     mult_acf_sino_path         = os.path.join(intemediates_dir, "mult.hs")
     pet_hv_path                = os.path.join(intemediates_dir, "pet_20.hv")
 
+    log.warning("Running reconstruction requires 20GB of RAM and takes 20-120 minutes depending on CPU. The intermediates folder takes up ~50GB of additional space. Consider deleting it after succesfull reconstruction")
+
     os.makedirs(intemediates_dir, exist_ok=True)
 
     check_input_hashes(intemediates_dir, ct_path, ct_face_and_bed_path, overwrite)
@@ -106,11 +108,11 @@ def reconstruction_pipeline(
     # Step 6: Calculate ACF sinogram
     if not os.path.exists(acf_sino_path) or overwrite:
         t = time.perf_counter()
-        log.info("[6/10] Converting mu-map from image to ACF sinogram...")
+        log.info("[6/10] Converting mu-map image to ACF sinogram...")
         calculate_acf(mumap_hv_path, add_sino_path, acf_sino_path, acf_forwardprojector)
         log.info(f"      done ({time.perf_counter()-t:.1f}s)")
     else:
-        log.info("[6/10] Converting mu-map from image to ACF sinogram (skipped)")
+        log.info("[6/10] Converting mu-map image to ACF sinogram (skipped)")
 
     # Step 7: Apply ACF to additive sinogram
     if not os.path.exists(add_acf_sino_path) or overwrite:
@@ -133,7 +135,7 @@ def reconstruction_pipeline(
     # Step 9: Reconstruct PET
     if not os.path.exists(pet_hv_path) or overwrite:
         t = time.perf_counter()
-        log.info("[9/10] Reconstructing PET (this will take some time)...")
+        log.info("[9/10] Reconstructing PET (this will take some time - especially first subiteration)...")
         run_reconstruction(recon_template, add_acf_sino_path, mult_acf_sino_path, prompts_sino_path, pet_hv_path, verbose=verbose)
         log.info(f"      done ({time.perf_counter()-t:.1f}s)")
     else: