Update README.md

README.md

@@ -1,3 +1,138 @@
----
-license: mit
----
+---
+language:
+  - en
+license: mit
+tags:
+  - object-detection
+  - pathology
+  - whole-slide-imaging
+  - spatial-transcriptomics
+  - roi-selection
+  - tumor-microenvironment
+  - computational-pathology
+  - tme-segmentation
+  - foundation-model
+pipeline_tag: object-detection
+---
+
+# ROI-ST: Automated ROI Selection for Spatial Transcriptomics Whole-Slide Images
+
+## Model Summary
+
+**ROI-ST** is a multi-scenario framework for automated Region of Interest (ROI) selection in whole-slide images (WSIs) intended for downstream spatial transcriptomics (ST) analysis. It combines a trained tile-level classifier, TME segmentation masks, and generalist/specialist foundation model embeddings to identify spatially informative ROIs and benchmark them against manual pathologist annotations.
+
+The framework comprises three independent scenarios of increasing complexity, each targeting a different combination of inputs and use cases. It is released to support reproducibility of the results reported in *[paper title]*.
+
+---
+
+## Scenarios Overview
+
+| Scenario | Approach | Key Input | Key Output |
+|----------|----------|-----------|------------|
+| **Scenario 1 — GFM** | Tile-level classifier on foundation model embeddings | HDF5 embeddings + WSI | Probability heatmap, predicted ROI window |
+
+---
+
+## Intended Use
+
+### Primary Use
+This framework is intended for **research use** in computational pathology and spatial transcriptomics, specifically:
+- Automated ROI candidate identification from WSIs prior to ST placement
+- Benchmarking AI-driven ROI selection against manual pathologist annotations
+- Reproducibility of results reported in *[paper title]*
+
+### Out-of-Scope Use
+- Clinical diagnostic decision-making
+- Use without appropriate pre-computed embeddings or segmentation masks
+- Deployment outside the H&E / SVS / OME-TIFF formats described below
+
+---
+
+## System Requirements
+
+| Component | Version |
+|-----------|---------|
+| **Python** | 3.11.0 |
+| **PyTorch** | 2.1.2 + CUDA 12.1 |
+| **TorchVision** | 0.16.2 |
+| **pathologyfoundation (PLIP)** | 0.1.14 |
+| **trident (UNI-V2)** | 0.2.0 |
+| **tmesegformer** | 0.1.0 |
+| **OpenSlide-Python** | 1.3.1 |
+| **NumPy / Pandas / Matplotlib / SciPy / scikit-learn** | see `requirements.txt` |
+
+**GPU requirements:** ≥ 24 GB VRAM recommended for WSI-scale inference.
+
+| Hardware | CUDA | Status |
+|----------|------|--------|
+| NVIDIA H100 | 12.x | ✅ Validated |
+| NVIDIA A100 | 12.x | ✅ Validated |
+| NVIDIA RTX 4090 | 12.x | ✅ Validated |
+
+### Installation
+
+```bash
+python3.11 -m venv roi_env
+source roi_env/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+python -m pip check
+```
+
+---
+
+## Scenario 1 — GFM: Classifier on Foundation Model Embeddings
+
+Uses a trained classifier (`tile_classifier.pkl`) applied to tile-level embeddings (HDF5) to compute per-tile probabilities and identify the highest-probability ROI window.
+
+### Inputs
+
+| Argument | Description |
+|----------|-------------|
+| `--model_dir` | Directory containing `classifier.pkl` |
+| `--test_h5` | HDF5 file with `coords`, `features`, `patch_size_level0` |
+| `--test_tif` | Whole-slide `.tif` image |
+| `--roi_json` | JSON file with manual ROI coordinates `{x0, y0, x1, y1}` |
+| `--out_dir` | Output directory |
+| `--thumb_width` | Thumbnail width in pixels (default: 1000) |
+
+### Outputs
+
+| File | Description |
+|------|-------------|
+| `probability_heatmap.png` | Tile probability heatmap with predicted ROI overlay |
+| `probability_histogram.png` | Distribution of tile-level probabilities |
+| `thumbnail_overlay.png` | Thumbnail with manual vs predicted ROI rectangles |
+
+### Usage
+
+```bash
+python3 scenario_1.py \
+  --model_dir "./model" \
+  --test_h5 "./uni_embeddings/gbm_xxx.h5" \
+  --test_tif "./raw_tif/gbm_xxx.tif" \
+  --roi_json "./roi_json/gbm_xxx_roi.json" \
+  --out_dir "./output"
+```
+
+---
+
+## Citation
+
+If you use this framework, please cite:
+
+```bibtex
+@article{[citation_key],
+  title   = {[Paper title]},
+  author  = {[Authors]},
+  journal = {[Journal]},
+  year    = {[Year]},
+  doi     = {[DOI]}
+}
+```
+
+---
+
+## License
+
+This model is released under the **MIT License**. See `LICENSE` for details.