microsim

Light microscopy simulation in python.

The goal of this library is to generate highly realistic simulated data such as the following:

(this data was generated using segmentations from cell jrc_hela-3 at OpenOrganelle as the ground truth)

https://github.com/user-attachments/assets/905fa1af-c8bd-406e-87a7-7c5921de74d1

Documentation

Documentation is at https://talleylambert.com/microsim/. Start with First simulation, read the User guide for how each part of the simulation works, and see the API reference for every option.

[!WARNING] microsim is in early development and changes quickly. Releases may break the API or change simulation results for the same parameters. If you depend on it, pin a specific version and record it with your results.

Installation

from PyPI

pip install "microsim[all]"

[!NOTE] At the moment, this library is a bit more "application" than it is "library". If you are following the docs or tutorials, its probably best to install the full [all] extra, which brings in io, visualization, and other data-fetching dependencies. However, the bare minimal install is fully functional for generating data.

Local Development

gh repo clone tlambert03/microsim
cd microsim
uv sync

From github

To get the bleeding edge version, which will change rapidly, you can install from github.

pip install "microsim[all] @ git+https://github.com/tlambert03/microsim"

With GPU support

If available, microsim can use either Jax or Cupy to accelerate computations. These are not installed by default, see the jax or cupy installation instructions, paying attention to your GPU requirements. Support for torch is planned.

Usage

Construct and run a microsim.Simulation object.

from microsim import schema as ms
from microsim.util import ortho_plot

# define the parameters of the simulation
sim = ms.Simulation(
    truth_space=ms.ShapeScaleSpace(shape=(128, 512, 512), scale=(0.02, 0.01, 0.01)),
    output_space={"downscale": 8},
    sample=ms.Sample(labels=[ms.MatsLines(density=0.5, length=30, azimuth=5, max_r=1)]),
    modality=ms.Confocal(pinhole_au=1),
    output_path="au1.tiff",
)

# run it
result = sim.run()

# optionally plot the result
ortho_plot(result)