Add paper figures and a runnable single-tile example

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/morphology_controls.png filter=lfs diff=lfs merge=lfs -text
+assets/pipeline.png filter=lfs diff=lfs merge=lfs -text
+assets/spatial_fidelity.png filter=lfs diff=lfs merge=lfs -text
+examples/paper_tile/reference_generated.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -22,7 +22,6 @@ base_model_relation: finetune
 - **Code and complete instructions:** [a12dongithub/PathOGen](https://github.com/a12dongithub/PathOGen)
 - **Model repository:** [a12donhf/CPathOGen](https://huggingface.co/a12donhf/CPathOGen)
 - **Authors:** Samarth Singhal and Varang Rai
-- **Paper:** arXiv link will be added after submission.
 
 ## What the model does
 
@@ -32,7 +31,64 @@ Researchers can keep diffusion noise fixed, change a requested control, and comp
 
 The checkpoint uses latent concatenation with a learned spatial encoder. It is not a standard Diffusers `ControlNetModel` or standalone `DiffusionPipeline` checkpoint.
 
-## Run inference
+## Figures from the paper
+
+![Controllable image generation and recorded black-box predictions for post-hoc interpretation](assets/principle.png)
+
+**Counterfactual probing:** change a control, generate a matched image, and measure the downstream model's prediction response.
+
+![CPathOGen pipeline from CellViT++ weak labels to spatial and morphology-conditioned latent diffusion](assets/pipeline.png)
+
+**Generation pipeline:** CellViT++ supplies cellular maps and morphology/appearance summaries; the spatial encoder and FiLM condition latent diffusion synthesis.
+
+![Three examples showing the cell map, real H&E tile, and generated H&E tile](assets/spatial_fidelity.png)
+
+**Spatial examples:** input maps, associated real tiles, and condition-matched generated tiles from the paper. Map colors are tumor (white), immune (cyan), stroma (green), dead (yellow), and non-neoplastic epithelium (orange).
+
+![Five-level sweeps of nuclear size, eccentricity, solidity, gradient, and RGB appearance](assets/morphology_controls.png)
+
+**Morphology and appearance examples:** the paper's five-level control sweeps. Most columns use relative standardized offsets; the historical eccentricity illustration instead uses absolute standardized coordinates with 20 steps and spatial strength 1. Nuclear size changes area and perimeter together. These are paper illustrations, not new generations from the quickstart.
+
+## Run one real example in Colab
+
+Select a **GPU runtime** in Colab, then run the cell below. It downloads one prepared paper-tile condition, so you do not need the full dataset, Google Drive, or CellViT++ to try the generator. The public weights require no Hugging Face token.
+
+```python
+from pathlib import Path
+import torch
+
+if not torch.cuda.is_available():
+    raise RuntimeError("Select Runtime > Change runtime type > GPU in Colab.")
+
+%cd /content
+if not Path("/content/CPathOGen-example/.git").is_dir():
+    !git clone -q --depth 1 https://github.com/a12dongithub/PathOGen.git /content/CPathOGen-example
+%cd /content/CPathOGen-example
+%pip install -q -r inference/requirements.txt
+
+from huggingface_hub import hf_hub_download
+from IPython.display import display
+from PIL import Image
+
+MODEL_ID = "a12donhf/CPathOGen"
+map_path = hf_hub_download(MODEL_ID, "examples/paper_tile/map.npz")
+morphology_path = hf_hub_download(MODEL_ID, "examples/paper_tile/morphology.json")
+preview_path = hf_hub_download(MODEL_ID, "examples/paper_tile/input_map.png")
+
+!python inference/generate.py --spatial-map "{map_path}" --morphology-json "{morphology_path}" --tile TCGA-E2-A15D_x46080_y24576_TR --seed 1872879198 --steps 30 --spatial-strength 2 --output outputs/paper_example.png
+
+print("Input spatial map")
+display(Image.open(preview_path))
+print("Generated H&E")
+display(Image.open("outputs/paper_example.png"))
+print("Controls and run metadata: outputs/paper_example.json")
+```
+
+The first run downloads approximately **4.16 GB of generator weights**, plus the base-model text encoder, tokenizer, and scheduler. Downloads are cached. This produces one 512 x 512 PNG and its condition/provenance JSON; it does not run eight-seed selection or downstream probing. Keep the seed fixed when comparing edited controls. Exact pixels can differ across hardware and numerical precision.
+
+This model card documents GPU inference through the project code; it is not a hosted Hugging Face inference widget.
+
+## Local inference and custom inputs
 
 Use Python 3.10/3.11, a compatible CUDA-enabled PyTorch build, and an NVIDIA GPU.
 
@@ -83,6 +139,17 @@ checkpoint-30000/
   vae/diffusion_pytorch_model.safetensors
   film_mlps.pt
   spatial_encoder.pt
+assets/
+  principle.png
+  pipeline.png
+  spatial_fidelity.png
+  morphology_controls.png
+examples/paper_tile/
+  map.npz
+  morphology.json
+  metadata.json
+  input_map.png
+  reference_generated.png
 ```
 
 The FiLM and spatial-encoder files contain PyTorch state dictionaries and are loaded with `weights_only=True`. Optimizer, scheduler training state, and random-state pickle files are excluded. Original weights are preserved; the checkpoint is not quantized or converted. `release_manifest.json` records per-file SHA-256 hashes and sizes.
@@ -107,3 +174,5 @@ Research uses include controlled histopathology synthesis and probing model sens
 ## License
 
 Model weights retain the CreativeML Open RAIL++-M terms inherited from Stable Diffusion 2.1; see `LICENSE-MODEL`. Third-party software, analyzers, and datasets retain their respective licenses and access requirements.
+
+Paper figures are shared under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) with attribution to Samarth Singhal and Varang Rai; see [assets/README.md](assets/README.md). This does not change the model-weight license.

assets/README.md

@@ -0,0 +1,10 @@
+# Paper figures
+
+These figures accompany **CPathOGen: Spatially and Morphologically Controlled H&E Counterfactuals for Probing Pathology Models**, by Samarth Singhal and Varang Rai.
+
+- `principle.png`: rendered from paper Figure 1.
+- `pipeline.png`: rendered from paper Figure 2.
+- `spatial_fidelity.png`: assembled from the same tile assets used in paper Figure 3, with matching cell-color legend.
+- `morphology_controls.png`: assembled from the same tile assets used in paper Figure 4. Dose labels are shortened to standardized control coordinates; eccentricity uses the paper image package's historical absolute-coordinate sweep.
+
+Figure artwork is shared under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/). Attribute the authors and indicate changes when adapting the artwork. Third-party datasets retain their original terms. The generator weights remain under their separate CreativeML Open RAIL++-M license.

examples/paper_tile/README.md

@@ -0,0 +1,11 @@
+# Single paper-tile example
+
+Tile: `TCGA-E2-A15D_x46080_y24576_TR`.
+
+- `map.npz`: the original five-channel spatial condition, using the `map` key and shape `(512, 512, 5)`.
+- `morphology.json`: 16 already standardized morphology/appearance values, in the checkpoint's feature order.
+- `input_map.png`: the paper visualization; use the NPZ, not this RGB preview, for inference.
+- `reference_generated.png`: the previously generated paper-package baseline, not a new inference result.
+- `metadata.json`: seed, sampling settings, channel order, and condition provenance.
+
+Use seed `1872879198`, `30` steps, and spatial strength `2`. Different hardware or precision can yield different pixels. This example needs neither the full dataset nor a nucleus analyzer. Follow the Colab cell in the model card to generate a new image from these conditions.

examples/paper_tile/map.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9931a70d066f7110351b412205248e0a8039a0415bce37fff9645e09ff2c9676
+size 13900

examples/paper_tile/metadata.json

@@ -0,0 +1,23 @@
+{
+  "tile": "TCGA-E2-A15D_x46080_y24576_TR",
+  "seed": 1872879198,
+  "steps": 30,
+  "spatial_strength": 2.0,
+  "morphology_representation": "standardized training feature coordinates",
+  "channel_order": [
+    "neoplastic",
+    "inflammatory",
+    "connective",
+    "dead",
+    "epithelial"
+  ],
+  "spatial_shape": [
+    512,
+    512,
+    5
+  ],
+  "map_sha256": "9931a70d066f7110351b412205248e0a8039a0415bce37fff9645e09ff2c9676",
+  "source": "Condition and generated baseline used in the paper image package",
+  "green_offset_standardized_units": 0.0,
+  "reference_note": "Fixed controls and seed; pixel-identical output is not guaranteed across hardware or precision."
+}

examples/paper_tile/morphology.json

@@ -0,0 +1,18 @@
+{
+  "area_mean": -0.09236620366573334,
+  "area_var": -0.4095771014690399,
+  "eccentricity_mean": -1.2148321866989136,
+  "eccentricity_var": -0.3638562858104706,
+  "solidity_mean": 1.5003626346588135,
+  "solidity_var": -1.0003763437271118,
+  "perimeter_mean": -0.141899973154068,
+  "perimeter_var": -0.5273236632347107,
+  "grad_mean": 0.37052053213119507,
+  "grad_var": 0.22863806784152985,
+  "r_mean": 0.33253344893455505,
+  "r_var": 1.0801981687545776,
+  "g_mean": 0.21002225577831268,
+  "g_var": 0.5473105311393738,
+  "b_mean": 0.2969951629638672,
+  "b_var": 0.6543741822242737
+}