Update README.md

README.md

@@ -33,11 +33,11 @@ It takes 256×256 px patches as input and outputs per-cell contours, centroids,
 The full pipeline consists of three steps:
 
 ```
-┌───────────────┐      ┌────────────────┐     ┌──────────────────┐
-│ 1. Normalize │ ──→  │ 2. Patchify  │ ──→  │ 3. Inference   │
-│  (Reinhard)  │      │(256px, 64ov) │     │(Cell Detection) │
-└───────────────┘      └────────────────┘     └──────────────────┘
-    SVS / TIF            PNG patches        Masks + Centroids
+┌───────────────┐       ┌────────────────┐      ┌───────────────────┐
+│ 1. Normalize  │ ──→  │  2. Patchify   │ ──→ │  3. Inference   │
+│   (Reinhard)  │      │ (256px, 64ov)  │     │ (Cell Detection)│
+└───────────────┘       └────────────────┘      └───────────────────┘
+    SVS / TIF             PNG patches          Masks + Centroids
 ```
 
 ### Magnification
@@ -100,6 +100,81 @@ python inference.py \
 
 ---
 
+## Example: Reproducible Walkthrough
+
+To verify your installation, run the pipeline on the example slide included in this repository
+(`TCGA-56-8628-01Z-00-DX1`, LUSC, ~36 MB).
+
+### Download the model, example slide, and reference image
+
+```python
+from huggingface_hub import hf_hub_download
+
+REPO_ID = "roobee79/HNE2Cell"
+
+model_path = hf_hub_download(
+    repo_id=REPO_ID,
+    filename="HNE2cell_all_patch73_jit.pt"
+)
+
+slide_path = hf_hub_download(
+    repo_id=REPO_ID,
+    filename="TCGA-56-8628-01Z-00-DX1.AAC57164-E0F9-4DF0-87EA-5C50FB201895.svs"
+)
+
+ref_path = hf_hub_download(
+    repo_id=REPO_ID,
+    filename="standard-ilc.tif"
+)
+```
+
+### Run the pipeline
+
+```bash
+# Place the downloaded slide in a working directory
+mkdir -p example/slides
+cp <slide_path> example/slides/
+
+# Step 1: Normalize
+python normalize.py \
+    --input_dir ./example/slides \
+    --target ./standard-ilc.tif
+
+# Step 2: Patchify at 40x
+python patchify.py \
+    --input_dir ./example/slides \
+    --magnification 40 \
+    --patch_size 256 \
+    --overlap 64 \
+    --workers 8
+
+# Step 3: Inference
+python inference.py \
+    --input_dir ./example/slides/TCGA-56-8628-01Z-00-DX1.../patches \
+    --output_dir ./example/results \
+    --model_path ./HNE2cell_all_patch73_jit.pt \
+    --magnification 40 \
+    --batch_size 32
+```
+
+### Expected output
+
+```
+example/results/
+├── Aligned-hne.tif        # Normalized full-resolution H&E
+├── Aligned-hne.jpg        # 4× preview
+├── patch_*_mask.png       # Per-patch cell type masks
+└── patch_*_centroid.csv   # Cell centroids with type labels
+```
+
+Approximate runtime on a single NVIDIA A100: **~20 min** for the full slide
+(~XXX,XXX cells detected across 16 classes).
+
+> The example slide is from **TCGA-LUSC** and is redistributed under the
+> [NIH Genomic Data Sharing Policy](https://sharing.nih.gov/genomic-data-sharing-policy).
+
+---
+
 ## Input / Output Details
 
 ### Input
@@ -141,7 +216,9 @@ y_global = y + y_offset
 
 ## Normalization Reference Image
 
-The pipeline uses Reinhard color normalization in LAB color space. You need a reference image (`standard-ilc.tif`) that represents your target stain appearance. Include this file alongside the model or provide your own.
+The pipeline uses Reinhard color normalization in LAB color space. You need a reference image
+(`standard-ilc.tif`) that represents your target stain appearance. The reference image is
+included in this repository, or you can supply your own.
 
 ---
 
@@ -149,13 +226,15 @@ The pipeline uses Reinhard color normalization in LAB color space. You need a re
 
 ```
 HNE2Cell/
-├── README.md                          # This file
-├── HNE2cell_all_patch73_jit.pt        # TorchScript model
-├── post_processing.py                 # Cell post-processing module
-├── normalize.py                       # Step 1: Reinhard normalization
-├── patchify.py                        # Step 2: Patch extraction
-├── inference.py                       # Step 3: Model inference
-└── standard-ilc.tif                   # Reference image for normalization
+├── README.md                                                    # This file
+├── HNE2cell_all_patch73_jit.pt                                  # TorchScript model
+├── normalize.py                                                 # Step 1: Reinhard normalization
+├── patchify.py                                                  # Step 2: Patch extraction
+├── inference.py                                                 # Step 3: Model inference
+├── post_processing.py                                           # Cell post-processing module
+├── tools.py                                                     # Utility functions
+├── standard-ilc.tif                                             # Reference image for normalization
+└── TCGA-56-8628-01Z-00-DX1.AAC57164-E0F9-4DF0-87EA-5C50FB201895.svs   # Example slide (TCGA-LUSC)
 ```
 
 ---
@@ -172,3 +251,5 @@ If you use HNE2Cell in your research, please cite:
 }
 ```
 
+The example slide is derived from data generated by the TCGA Research Network:
+<https://www.cancer.gov/tcga>.