| | --- |
| | 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 |
| | ``` |
| |
|
| | --- |
| |
|
| |
|
