imswitch2 0.3.0

Imswitch2 is a Python application for flexible, modular microscope control. It supports a wide range of hardware — cameras, lasers, stages, DAQ cards, rotation mounts, pulse generators — through a configuration-driven manager system. Switching hardware means editing a JSON file, not the code.

This is a clean-slate continuation of the ImSwitch project, focused on safety, maintainability, and AI-assisted development under strict human oversight.

Features

Quick start

Two ways in: a ready-made installer, or pip.

Download a ready-made installer

Don't want to manage a Python environment? Every release ships a standalone build with Python and every dependency inside it — nothing else to install.

Both links always point at the newest release. Three things to know before you click:

• They are unsigned. Windows SmartScreen says "unrecognized app" — choose More info → Run anyway. macOS refuses to open it at all on first launch — right-click ImSwitch2 and choose Open. Nothing is wrong with the download; code-signing certificates cost money the project has not spent yet.
• A bundled Imswitch2 cannot load pip-installed device plugins or vendor SDKs, and scripts in it can only import what was bundled. Great for analysis, teaching and trying it out; for a microscope, install with pip instead.
• macOS is Apple Silicon only, and in practice macOS runs the analysis side — NI-DAQmx has no macOS support at all, and the Thorlabs and TIS camera SDKs are Windows/Linux only.

Having trouble, or want to build one yourself? See docs/packaging.rst.

Install with Python

Requires Python 3.10+ and PyQt5. Windows / macOS / Linux all supported.

pip install imswitch2, then run imswitch. This is the right choice for a microscope: a pip install can load device plugins and vendor SDKs, and a bundled one cannot.

Clone instead to develop on Imswitch2 itself, or for the newest fixes — PyPI releases trail main:

# 1. Clone and install (core install — UI + file I/O, no hardware drivers)
git clone https://github.com/Imswitch2/ImSwitch2.git
cd Imswitch2
pip install -e .

# 2. Launch
python -m imswitch

Imswitch2 creates ~/ImSwitchConfig/ on first launch and opens a setup-picker dialog. Pick one of the bundled example setups (e.g. example_no_hardware.json) to see the UI without any device connected.

The first launch is slow — give it a minute. Before the window appears, Imswitch2 creates its ~/ImSwitchConfig/ folder structure and copies the example setups and scripts into it, and Python, napari and matplotlib build their caches. Later launches skip all of this and start much faster.

A fresh install loads three modules, one tab each down the left edge of the window: Hardware Control (ImControl, the microscope), Image Processing (ImProcess, reconstruction and analysis) and Scripting (ImScripting, the script editor). To change which ones load, use Preferences > Set active modules… or edit ~/ImSwitchConfig/config/modules.json. A modules.json you changed is kept when you update Imswitch2 (see Updates to the shipped files below).

For real hardware:

pip install -e ".[hardware]"   # NI-DAQ, Lantz, pyVISA
pip install -e ".[full]"       # also napari, OpenCV, vispy

Documentation

Offical Documentation on readthedocs

The full documentation lives under docs/ and is rendered with Sphinx.

Build the docs locally

# One-off — install the doc toolchain
pip install sphinx sphinx-rtd-theme

# Build the HTML site
cd docs
sphinx-build -b html . _build/html

# Open it in your browser
#   macOS:    open _build/html/index.html
#   Linux:    xdg-open _build/html/index.html
#   Windows:  start _build/html/index.html

For a live-reloading dev server while editing docs:

pip install sphinx-autobuild
sphinx-autobuild docs docs/_build/html
# → serves at http://127.0.0.1:8000 and rebuilds on save

Regenerate screenshots

All widget screenshots under docs/images/auto/ are produced by a single script that launches Imswitch2 with the example_no_hardware.json setup and grabs each dock individually:

python tools/screenshot_widgets.py

See docs/how-to/auto-screenshots.rst for details and CI integration notes.

Hardware support

Imswitch2 ships managers for 42+ devices across five categories. Every manager has its JSON config field-by-field documented under docs/devices/.

Don't see your hardware? Adding a new driver is one file plus one JSON entry — see docs/how-to/port-from-third-party.rst for the canonical recipe, and docs/adding-device-support.rst for the abstract-base reference.

Configuration

Imswitch2 reads all hardware configuration from ~/ImSwitchConfig/:

~/ImSwitchConfig/                  (Linux / macOS)
Documents\ImSwitchConfig\          (Windows)
  ├── config/
  │   ├── imcontrol_options.json   # active setup filename + recording folder
  │   └── modules.json             # which modules (tabs) load at startup
  └── imcontrol_setups/
      └── my_microscope.json       # hardware definition

Updates to the shipped files. The example setups, the mock setups, the scripting tutorials and config/modules.json are copied into ~/ImSwitchConfig/ from the Imswitch2 package. At every start, a copy you have not edited that is an older shipped version is updated to the current one, and an untouched script Imswitch2 no longer ships is moved to the trash. Files you edited are never changed or removed; the log names the ones that differ from the current version -- delete one and restart to get the current version.

A GUI editor is included for building setup files without writing JSON by hand. Open it from a running ImSwitch under Tools > Edit hardware configuration..., or standalone without starting the microscope:

python utility_scripts/imswitch_config_editor.py

The editor loads built-in templates for every supported manager, lets you add and configure devices visually, and saves valid JSON directly into imcontrol_setups/.

Minimal setup file

A two-device setup (one synthetic camera -- AVManager serves mock frames, no video driver is bundled -- one Cobolt laser, no DAQ):

{
  "detectors": {
    "Camera": {
      "managerName": "AVManager",
      "managerProperties": {
        "cameraListIndex": "mock",
        "avcam": { "exposure": 100, "gain": 1 }
      },
      "analogChannel": null,
      "digitalLine": null,
      "forAcquisition": true
    }
  },
  "lasers": {
    "561 nm": {
      "managerName": "Cobolt0601NewLaserManager",
      "managerProperties": { "digitalPorts": ["COM4"] },
      "analogChannel": null,
      "digitalLine": null,
      "wavelength": 561,
      "valueRangeMin": 0,
      "valueRangeMax": 200
    }
  },
  "availableWidgets": ["Settings", "View", "Recording", "Image", "Laser"]
}

For per-field reference for every other manager's JSON shape, see docs/devices/.

Project structure

Imswitch2/
├── imswitch/                       # Main package
│   ├── imcontrol/                  # Hardware control module
│   │   ├── model/managers/         # One manager class per device type
│   │   ├── controller/             # Widget controllers + CommunicationChannel
│   │   ├── view/                   # Qt widgets + napari viewer
│   │   └── _data/user_defaults/    # Example setup files
│   ├── imcommon/                   # Shared framework (Qt layer, signals, logging)
│   ├── improcess/                  # Post-acquisition processing module (was: imreconstruct)
│   └── imscripting/                # Scripting console module
├── utility_scripts/                # Config editor GUI + device templates
├── tools/                          # Maintenance scripts (screenshots, codegen, …)
├── docs/                           # Sphinx site (architecture, how-tos, device ref)
└── .github/workflows/              # CI pipeline

Deep dive: docs/design/ARCHITECTURE.md.

AI agent workflow

Imswitch2 uses AI agents as development assistants under strict human oversight:

GitHub Issue → Agent plans → Isolated branch/worktree → Tests → PR → Human review → Merge

• All agent code changes require human review — no automatic merges.
• Red-zone files (hardware timing, laser control, DAQ) require explicit maintainer approval.
• Agents work in isolated branches or worktrees; parallel agents don't share state.
• Every claim in the docs is grounded in source code — agents are explicitly forbidden from inventing fields, defaults, or vendor library calls.

See AGENTS.md for the full rules and templates.

Contributing

Contributions are very welcome — code, docs, hardware support, bug reports, use-case studies, all of it.

• See CONTRIBUTING.md for the workflow and code-style expectations.
• Project governance: GOVERNANCE.md.
• Community standards: CODE_OF_CONDUCT.md.

Quick ways to help:

• Try Imswitch2 on your microscope and file a setup recipe.
• Report bugs with reproducible JSON setups attached.
• Improve docs — especially per-device cards under docs/devices/.
• Port a driver from a sibling project (see docs/how-to/port-from-third-party.rst).

Citation

If you use Imswitch2 in your research, please cite the original ImSwitch JOSS paper:

@article{Casas-Moreno2021,
  doi       = {10.21105/joss.03394},
  url       = {https://doi.org/10.21105/joss.03394},
  year      = {2021},
  publisher = {The Open Journal},
  volume    = {6},
  number    = {64},
  pages     = {3394},
  author    = {Xavier Casas Moreno and Staffan Al-Kadhimi and Jonatan Alvelid and Andreas Bodén and Ilaria Testa},
  title     = {ImSwitch: Generalizing microscope control in Python},
  journal   = {Journal of Open Source Software}
}

Acknowledgments & third-party code

Imswitch2 is a fork of ImSwitch, and builds on a lot of other people's work — vendored code (with its licences), projects we modelled our behaviour on (Fiji/ImageJ, Picasso, napari), and the papers behind the methods we implement.

See ACKNOWLEDGMENTS.md for the full list, and licenses/ for third-party licence texts.

Parts of Imswitch2 were written with AI assistance, and standard image-processing routines have a limited number of sensible implementations — so some code may resemble other projects' even where it was written independently. If you believe your project is an uncredited source, please open an issue. We will add the attribution, or relicense or remove the code if there is a licence conflict.

License

GNU General Public License v3.0 — see LICENSE.

Third-party components retain their own licences — see ACKNOWLEDGMENTS.md and licenses/.