tags	license
biology microscopy traction-force pytorch pix2pix gan	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/:

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 on Hugging Face.

---

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:

python -m training.train \
  --data path/to/dataset \
  --model single_cell \
  --epochs 100 \
  --substrate fibroblasts_PDMS

Spheroid:

python -m training.train \
  --data path/to/dataset \
  --model spheroid \
  --epochs 100

Resume / fine-tune from checkpoint:

python -m training.train \
  --data path/to/dataset \
  --model single_cell \
  --resume ckp/last_checkpoint.pth \
  --epochs 150

---