Metadata-Version: 2.4
Name: closed-loop-microscopy
Version: 1.1.0
Summary: Closed-loop feedback control for optogenetic microscopy in Python
Keywords: microscopy,optogenetics,closed-loop,micro-manager,DMD
Author: Harrison-Oatman
Author-email: Harrison-Oatman <ho6729@princeton.edu>
License-Expression: MIT
License-File: LICENSE.md
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Dist: h5py>=3.14.0
Requires-Dist: natsort>=8.4.0
Requires-Dist: numpy
Requires-Dist: opencv-python-headless>=4.12.0.88
Requires-Dist: pyarrow>=15
Requires-Dist: pydantic>=2
Requires-Dist: pymmcore-plus>=0.14.0
Requires-Dist: pymmcore>=11.2.1.71.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: scikit-image>=0.25.2
Requires-Dist: scipy
Requires-Dist: tifffile>=2025.9.20
Requires-Dist: useq-schema>=0.9.2
Requires-Dist: zarr>=3.0
Requires-Dist: pycromanager>=1.0.2 ; extra == 'calibration'
Requires-Dist: cellpose>=4.0.6 ; extra == 'cellpose'
Requires-Dist: torch ; extra == 'cellpose'
Requires-Dist: torchvision ; extra == 'cellpose'
Requires-Dist: napari>=0.9.0 ; extra == 'gui'
Requires-Dist: pyside6>=6.10.2 ; extra == 'gui'
Requires-Python: >=3.11
Project-URL: Documentation, https://pyclm.readthedocs.io
Project-URL: Homepage, https://github.com/Harrison-Oatman/PyCLM
Project-URL: Issues, https://github.com/Harrison-Oatman/PyCLM/issues
Provides-Extra: calibration
Provides-Extra: cellpose
Provides-Extra: gui
Description-Content-Type: text/markdown

# PyCLM

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20385964.svg)](https://doi.org/10.5281/zenodo.20385964)

A Modular Closed-Loop Microscopy Software in Python

Please see our documentation at [readthedocs](https://pyclm.readthedocs.io/en/latest/first_time_setup.html)

![](documentation/imgs/Figure%201.png "PyCLM Overview")

## Overview

PyCLM is a python-based closed-loop microscopy software designed for running many dynamic and/or feedback-controlled optogenetic experiments simultaneously. Through PyCLM, it is possible to design spatial light patterns that change over time, follow individual cell positions, or change in response to cell features.

This approach to closed-loop microscopy is oriented around three major goals:

1. **Efficiency.**
Ideally, the number of possible simultaneous experiments should be limited only by the physical constraints of the microscopy system.
- Microscope control, data export, image segmentation, and pattern generation are split into separate processes that run in parallel, minimizing unneeded microscope downtime.

2. **(Re)usability.** Re-running experiments, combining multiple experiments, or changing experimental parameters should be as quick as possible, without requiring any programming experience.
- Descriptive and intuitively organized .toml files are used for experiment configuration, and can be reused or quickly edited for later experiments.
- Several common use-case configurations are provided for dynamic light input and feedback control experiments.

3. **Extensibility.** It should be possible to implement a wide range of new segmentation and stimulation methods on top of the existing software.
- Segmentation and stimulation methods inherit from a base class, and are required to implement three straightforward functions.

## Installation

```bash
pip install "closed-loop-microscopy[gui]"
```

The package is `closed-loop-microscopy`; the import name and the command are
`pyclm`. Leave out `[gui]` for a headless install (checking, previews, dry
runs, reading data). For development, clone the repository and run
`uv sync`.

Try it without a microscope:

```bash
pyclm new demo --demo
pyclm run demo --dry --gui
```

The demo runs two experiments on the virtual microscope with synthetic cells:
a sweeping bar of light, and a closed loop that segments the cells with a
method the directory brings along (`demo_methods.py`) and lights the outward
half of each.

See [First-Time Setup Guide](https://pyclm.readthedocs.io/en/latest/first_time_setup.html) to get started.

### Hardware requirement: Micro-Manager

PyCLM controls hardware through [pymmcore-plus](https://github.com/pymmcore-plus/pymmcore-plus), which wraps the [Micro-Manager](https://micro-manager.org) C++ core.  The Python package installs without issue, but running a real experiment requires:

1. **Install Micro-Manager** — download the nightly build for your platform from [micro-manager.org](https://micro-manager.org/wiki/Download_Micro-Manager_Latest_Release).
2. **Point PyCLM at your MM installation** — set the `config_path` field in `pyclm_config.toml` to your Micro-Manager `.cfg` hardware configuration file.

Importing the package and using the dry-run (`--dry`) mode work without a Micro-Manager installation.


## Citation

If you use PyCLM in your research, please cite:

> Oatman HR, Lad BC, Nguyen L, Gubbens JH, Toettcher JE. An optogenetic smart
> microscopy platform reveals signaling dynamics-dependent control over
> collective cell migration. *Cell Systems* 17(9) (2026).
> [doi:10.1016/j.cels.2026.101674](https://doi.org/10.1016/j.cels.2026.101674)

The paper describes version 1.0.1. To record the version you used, also cite
that release: every release has its own DOI on Zenodo, all listed under
[doi:10.5281/zenodo.20385964](https://doi.org/10.5281/zenodo.20385964)
(which always resolves to the latest). GitHub's "Cite this repository" button
gives both, from `CITATION.cff`.
