Shape2Force (S2F)
Predict traction-stress maps from bright-field images of single cells and spheroids.
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 Cellular Traction Stress from Label-Free Imaging", 2026.
Checkpoints
| checkpoint | model | input |
|---|---|---|
ckp/single_cell/ckp_singlecell_GN.pth |
S2F + substrate | bright-field image and substrate setting |
ckp/single_cell/ckp_singlecell_GN_image_only.pth |
S2F | bright-field image |
ckp/spheroid/ckp_spheroid_GN.pth |
S2F | bright-field image |
ckp/spheroid/ckp_spheroid_FN.pth |
supervised attention U-Net (11.8 M parameters) | bright-field image |
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
- Choose Model type: Single cell or Spheroid
- Place checkpoints (
.pth) inS2FApp/ckp/for local use. - Select a Checkpoint from
ckp/ - For S2F + substrate: choose the substrate setting (preset, default 6 kPa, or manual values)
- Upload an image or pick from
samples/ - Click Run prediction
2. Web App Online
Use the online app (version 1.2.0) 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
5. Baselines and Ablations
Evaluation of the released checkpoints and the baseline and ablation models: see experiments/README.md.