README.md

---
tags:
  - biology
  - microscopy
  - traction-force
  - pytorch
  - pix2pix
  - gan
license: mit
---

# Shape2Force (S2F)

Predict force maps from bright-field microscopy images of single-cell or spheroid. 

If you find this software useful, please cite:

Lautaro Baro#, Kaveh Shahhosseini#, Amparo Andrés-Bordería, Claudio Angione*, and Maria Angeles Juanes*. **"Shape-to-force (S2F): Predicting Cell Traction Forces from LabelFree Imaging"**, 2026.



---

## Ways to Use S2F

### 1. Web App (local)

Run the Streamlit GUI from `S2FApp/`:
```bash
git clone https://github.com/Angione-Lab/Shape2Force.git
cd Shape2Force/S2FApp
pip install -r requirements.txt
streamlit run app.py
```
1. Choose Model type: Single cell or Spheroid
2. Place checkpoints (`.pth`) in `S2FApp/ckp/` for local use.
3. Select a Checkpoint from `ckp/`
4. For single-cell: pick Substrate (e.g. fibroblasts_PDMS)
5. Upload an image or pick from `samples/`
6. Click Run prediction

---
### 2. Web App Online

Use the [online app](https://huggingface.co/spaces/Angione-Lab/Shape2force) on Hugging Face. 

<p align="center">
  <img src="./S2FApp/res/ss.png" width="450" alt="Shape2Force Web App" />
</p>

---
### 3. Jupyter Notebooks

For interactive usage and custom analysis, use the notebooks in `notebooks/`:

- **`notebooks/Singlecell_inference.ipynb`** – Load a folder of brightfield images, run single-cell predictions, plot samples, and save all predictions with metrics.
- **`notebooks/Singlecell_evaluation.ipynb`** – Evaluate single-cell model on a dataset with ground truth; compute metrics and plot predictions.
- **`notebooks/Spheroid_inference.ipynb`** – Run spheroid predictions on brightfield images, plot samples, and save predictions.
- **`notebooks/Spheroid_evaluation.ipynb`** – Evaluate spheroid model on as dataset with ground truth; compute metrics and plot predictions.

Once cloned, open a notebook in Jupyter and adjust the configuration cell (paths, model type, substrate).

---

### 4. Training & Fine-Tuning

**Dataset layout:** A folder with `train/` and `test/` subfolders. Each subfolder has:
- `BF_001.tif` (bright-field image)
- `*_gray.jpg` (force map / heatmap)
- Optional `.txt` (cell_area, sum_force)

**Single-cell:**
```bash
python -m training.train \
  --data path/to/dataset \
  --model single_cell \
  --epochs 100 \
  --substrate fibroblasts_PDMS
```

**Spheroid:**
```bash
python -m training.train \
  --data path/to/dataset \
  --model spheroid \
  --epochs 100
```

**Resume / fine-tune from checkpoint:**
```bash
python -m training.train \
  --data path/to/dataset \
  --model single_cell \
  --resume ckp/last_checkpoint.pth \
  --epochs 150
```

---