Metadata-Version: 2.4
Name: SyMBac
Version: 0.5.2
Summary: A package for generating synthetic images of bacteria in phase contrast or fluorescence. Used for creating training data for machine learning segmentation and tracking algorithms.
Author-email: Georgeos Hardo <gh464@cam.ac.uk>
License-Expression: GPL-2.0-only
Project-URL: Homepage, https://github.com/georgeoshardo/SyMBac
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tifffile>=2026.2.24
Requires-Dist: scikit-image>=0.26.0
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: tqdm>=4.67.3
Requires-Dist: pandas>=3.0.1
Requires-Dist: natsort>=8.4.0
Requires-Dist: ipython>=9.10.0
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: joblib>=1.5.3
Requires-Dist: scipy>=1.17.1
Requires-Dist: napari[all]>=0.6.6
Requires-Dist: pymunk>=7.2.0
Requires-Dist: pyglet>=2.1.13
Requires-Dist: matplotlib-scalebar>=0.9.0
Requires-Dist: psfmodels>=0.3.3
Requires-Dist: zarr>=3.1.5
Requires-Dist: optuna>=4.0.0
Requires-Dist: cmaes>=0.10.0
Requires-Dist: noise>=1.2.2
Provides-Extra: torch
Requires-Dist: torch>=2.10.0; extra == "torch"
Provides-Extra: cupy
Requires-Dist: cupy-cuda12x; extra == "cupy"
Provides-Extra: docs
Requires-Dist: sphinx_automodapi; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx_copybutton; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: pandoc; extra == "docs"
Dynamic: license-file

# SyMBac: Synthetic Micrographs of Bacteria

**Update 2025** Please see the [`SyMBac_2`](https://github.com/georgeoshardo/SyMBac_2/) repo. There is currently a big update coming which will feature lineage tracking ability, full texture generation within cells, spatial fluorescence (membrane, nucleoid, ribosome, etc), and more advanced image simulation models, and BENDY cells! It will also (hopefully) bring about full modularity of SyMBac so you can plug in individual parts of the pipeline to your own workflows. 

[Read the paper: Synthetic Micrographs of Bacteria (SyMBac) allows accurate segmentation of bacterial cells using deep neural networks
](https://doi.org/10.1186/s12915-022-01453-6
), Georgeos Hardo, Maximillian Noka, Somenath Bakshi

[***Read the docs***](https://symbac.readthedocs.io/en/latest/)

[***New! Try the Colab version***] (please let me know if you run into issues)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/19_kxRDjvkq1t8c8In4z0nN82CZtb2dbZ?usp=sharing)

  * [What is it?](#what-is-it-)
  * [Why would I want to generate synthetic images?](#why-would-i-want-to-generate-synthetic-images-)
  * [How do I use these synthetic images?](#how-do-i-use-these-synthetic-images-)
  * [Prerequisites](#prerequisites)
  * [Installation](#installation)
    + [If you're using a GPU:](#if-you-re-using-a-gpu-)
  * [Usage](#usage)
  * [FAQs](#faqs)



## What is it?

SyMBac is a tool to generate synthetic phase contrast or fluorescence images of bacteria. Currently the tool only supports bacteria growing in the mother machine, however support for bacteria growing in monolayers (and maybe even biofilms!) is coming. 

<img src="https://github.com/georgeoshardo/SyMBac/raw/main/readme_files/example_comparison.jpeg" alt="comparisons" width="600" />



## Why would I want to generate synthetic images?

Because you're sick of generating your own training data by hand! Synthetic images provide an instant source of high quality and unlimited training data for machine learning image segmentation algorithms! 

The images are tuned to perfectly replicate your experimental setup, no matter what your microscope's objective is (we have tested 20x air all the way to 100x oil), no matter your imaging modality (phase contrast/fluorescence), and no matter the geometry of your microfluidic device. 

Additionally,

* SyMBac is very fast compared to humans:

<img src="https://github.com/georgeoshardo/SyMBac/raw/main/readme_files/speed_comparison.png" alt="comparisons" width="400"  />

* The image generation process uses a rigid body physics model to simulate bacterial growth, 3D cell geometry to calculate the light's optical path, and a model of the phase contrast/fluorescence optics (point spread function), with some post-rendering optimisation to match image similarity:

<img src="https://github.com/georgeoshardo/SyMBac/raw/main/readme_files/image_generation.jpeg" alt="comparisons"  width="600" />

## How do I use these synthetic images?

That is up to you. SyMBac is **not** a machine learning tool. It is a tool to generate unlimited free training data which accurately represents your experiment. It is up to you to train a machine learning network on these synthetic images. We do however provide example notebooks for how to train a U-net (as implemented by [DeLTA](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1007673)).

 <img src="https://github.com/georgeoshardo/SyMBac/raw/main/readme_files/training.png" alt="comparisons"  width="350" />

## Prerequisites

SyMBac is meant to be run *interactively* (in a notebook + with a small Qt/GTK interface), so make sure that you are running this on a local machine (you should have access to the machine's display).

A GPU is strongly recommended for convolution performance but is not required — SyMBac will fall back to CPU FFT convolution if no GPU backend is available.

## Installation

### Base install (CPU only, no GPU acceleration)

```sh
pip install SyMBac
```

This works on any machine. Convolution will use scipy's FFT backend, which is significantly slower than GPU-accelerated convolution.

### NVIDIA GPU (recommended)

Install SyMBac with [CuPy](https://cupy.dev/) for CUDA-accelerated convolution:

```sh
pip install "SyMBac[cupy]"
```

This requires a working NVIDIA driver and CUDA 12.x installation. Check with `nvcc --version` or `nvidia-smi`.

### Apple Silicon (MPS)

Install SyMBac with PyTorch for Metal Performance Shaders acceleration:

```sh
pip install "SyMBac[torch]"
```

PyTorch will use the MPS backend on Apple Silicon Macs automatically.

### Development version

```sh
pip install "git+https://github.com/georgeoshardo/SyMBac"
```

### Jupyter widgets

Activate the Jupyter widgets extension. This is needed to interact with sliders in the notebooks to optimise images.

```sh
jupyter nbextension enable --py widgetsnbextension
```

## Usage

[***Read the docs***](https://symbac.readthedocs.io/en/latest/)

## FAQs

* Do I need to have a GPU?
  * No, although image synthesis will be around 40x slower on the CPU. SyMBac will detect that you do not have CuPy installed and default to using CPU convolution.
  * Interactive image optimisation will be very painful on the CPU. By default I turn off slider interactivity if you are using the CPU, so that you can move a slider without the CPU being maxed out. This means that every time you move a slider you must click the button to update the image (do a convolution).
* Can I generate fluorescence images as well?
  * Yes, you can do fluorescence image generation, just make sure that in the interactive image generation part of the code, you select fluorescence.
  * Since our fluorescence kernel is defined to be a subset of the phase contrast kernel, you can choose **any** condenser, and your fluorescence kernel should be correct. Just ensure that the imaging wavelength, numerical aperture, refractive index, and pixel size are set correctly.
* What format do my images need to be in?
  * The real images you are trying to replicate should be in the format of single-trench timeseries images. If you are unsure what this is, you can call `get_sample_images()["E. coli 100x"]` from `SyMBac.misc`for an example image.
* I'm getting libGL MESA-LOADER errors
  * See https://unix.stackexchange.com/questions/655495/trying-to-run-pygame-on-my-conda-environment-on-my-fresh-manjaro-install-and-ge
* I'm getting `ContextException: Could not create GL context` when trying to visualise my simulation in real time
  * Try `conda install -c conda-forge libstdcxx-ng`, and if you're on Ubuntu/Debian `sudo apt install libgl1-mesa-dri`
