diff --git a/README.md b/README.md index 5409410..1ada95c 100644 --- a/README.md +++ b/README.md @@ -11,14 +11,16 @@ pattern given certain DMD patterns, determining system point-spread functions an determining the affine transformation between the DMD coordinates and the imaging space coordinates. The various files are described in more detail below. -This repository is associated with the Biomedical Optics Express paper +# Published work using this code +* This DMD simulation tools and SIM reconstruction code were originally created for our Biomedical Optics Express paper [Multicolor structured illumination microscopy and quantitative control of polychromatic light with a digital micromirror device](https://doi.org/10.1364/BOE.422703) -and the [BioRxiv preprint](https://doi.org/10.1101/2020.07.27.223941). -The repository state at the time of publication is archived [here](https://doi.org/10.5281/zenodo.4773865), or available as +([preprint](https://doi.org/10.1101/2020.07.27.223941)). The repository state at the time of publication is archived [here](https://doi.org/10.5281/zenodo.4773865), or available as a [release](https://github.com/QI2lab/mcSIM/releases/tag/v1.0.0) on GitHub. +* The SIM reconstruction code was also used in [Resolution doubling in light-sheet microscopy via oblique plane structured illumination ](https://doi.org/10.1038/s41592-022-01635-8) +([preprint](https://doi.org/10.1101/2022.05.19.492671)). This version is archived [here](https://doi.org/10.5281/zenodo.6419901) or available as a [release](https://github.com/QI2lab/mcSIM/releases/tag/v0.2.0) +* For a tutorial on SIM reconstruction, see our [I2K 2022 talks](https://github.com/QI2lab/I2K2022-SIM). -For a tutorial on SIM reconstruction, see our [I2K 2022 talks](https://github.com/QI2lab/I2K2022-SIM). - +# Installation The best way to use this python package is to install it with pip ``` git clone https://github.com/QI2lab/mcSIM.git @@ -32,7 +34,7 @@ cd mcSIM pip install -e . ``` The dependencies for the experimental control code are not installed by default because -the DMD control code relies on the windows specific [pywinusb](https://pypi.org/project/pywinusb/). To install these dependencies run +the DMD control code relies on the Windows specific [pywinusb](https://pypi.org/project/pywinusb/). To install these dependencies run ``` git clone https://github.com/QI2lab/mcSIM.git cd mcSIM @@ -41,15 +43,14 @@ pip install .[expt_ctrl] Some functions can be optionally run on a GPU. If this is desired, ensure your python environment has the appropriate version of [CuPy](https://cupy.dev/) installed -# Analysis and simulation code - +# SIM reconstruction code ### [sim_reconstruction.py](mcsim/analysis/sim_reconstruction.py) -Code for reconstructing SIM images from raw data using a Gustafsson/Wiener filter style reconstruction. Several different +Code for reconstructing SIM images from raw data using a Gustafsson/Wiener filter style reconstruction. Several reconstruction options are available, largely following either the approach of [openSIM](https://doi.org/10.1109/JSTQE.2016.2521542) or [fairSIM](https://doi.org/10.1038/ncomms10980). To get started with reconstructing SIM data, see the example script [reconstruct_sim.py](examples/reconstruct_sim.py). - +# DMD simulation code ### [simulate_dmd.py](mcsim/analysis/simulate_dmd.py) Code for simulating the diffraction patterns produced by the DMD. Various scripts illustrating the usage of this code can be found in the [examples](examples) @@ -63,6 +64,7 @@ patterns for the DMD. It also contains many tools for working with the basis vec representation of DMD patterns. This allows a complete enumeration of DMD diffraction orders in a compact and computationally efficient form. +# Utility code ### [fit_dmd_affine.py](mcsim/analysis/fit_dmd_affine.py) Code to fit the affine transformation between the DMD coordinates and camera coordinates using imaging data from a DMD pattern consisting of many small points. These code relies @@ -80,21 +82,21 @@ This code is taken from https://github.com/jacobkimmel/ps_decomp (with permissio Miscellaneous image processing tools, primarily for working with Fourier transforms ### [mm_io.py](mcsim/analysis/mm_io.py) -Tools for IO of MicroManager style tif files and metadata. +Tools for IO of MicroManager style tif files and metadata. ### [localize-psf](https://github.com/QI2lab/localize-psf/blob/master/localize_psf) Useful tools for automatically localizing sparse fluorescent beads and performing both 2D and 3D PSF fitting using various PSF models. Also provides useful statistics and figures summarizing the results. This code has now been split out into a [separate repository](https://github.com/QI2lab/localize-psf). For more information about these tools, see the [readme](analysis/localize-psf/README.md) -pip installing the mcsim repository as described above will also pull in these dependncies. +pip installing the mcsim repository as described above will also pull in these dependencies. # Examples Scripts illustrated examples of different DMD simulations and analysis are stored in [examples](examples). Associated data is located in [examples/data](examples/data) # Hardware control code -Hardware control is based around [MicroManager2.0](https://micro-manager.org/). Currently we control the instrument +Hardware control is based around [MicroManager2.0](https://micro-manager.org/). Currently, we control the instrument using a fork of the [napari-micromanager](https://github.com/QI2lab/napari-micromanager) project which controls the MicroManager core using [pymmcore-plus](https://github.com/tlambert03/pymmcore-plus). Our fork of this project relies on MicroManager device drives to control cameras and stages, and on python code to control the DMD and DAQ. @@ -104,7 +106,7 @@ The "device adapters" for the DMD and DAQ are found below Code for controlling the DLP6500 DMD over USB on Windows. This code was initially based on the approaches of [Lightcrafter6500DMDControl](https://github.com/mazurenko/Lightcrafter6500DMDControl) and [Pycrafter6500](https://github.com/csi-dcsc/Pycrafter6500). Extension to other operating systems has not been -implented but should be straightforward. +implemented but should be straightforward. This file also includes functions used to define pattern sequences on the DMD using patterns have either been previously loaded onto the firmware using the [Texas Instruments DLP6500 and DLP9000 @@ -112,11 +114,7 @@ GUI](https://www.ti.com/tool/DLPC900REF-SW) or which are loaded "on-the-fly". Th for running these patterns based directly on their index in the firmware. There is also a higher-level interface which supports defining "channels" and "modes" which can be saved in a json configuration file. -When run as a script, this file provides a command line interface to programming DMD pattern sequences. - -### [expt_ctrl/dmd_config.json](mcsim/expt_ctrl/dmd_config.json) -Configuration file describing firmware patterns as well as "modes" and "channels" for the DMD. This file is used by -dmd instances created with [dlp6500.py](mcsim/expt_ctrl/dlp6500.py) +When run as a script, this file provides a command line interface to programming DMD pattern sequences. ### [expt_ctrl/daq.py](mcsim/expt_ctrl/daq.py) Code for controlling a national instruments DAQ through [PyDAQmx](https://pypi.org/project/PyDAQmx/) @@ -139,5 +137,4 @@ Example scripts which are useful for controlling various instruments during test [set_dmd_odt_pattern.py](mcsim/expt_ctrl/set_dmd_odt_pattern.py) # Instrument design -Mechanical drawings of some parts used in the setup are included in the [parts](parts) directory. For a more complete description of the setup and -a parts list, see the published paper linked above. See in particular the [parts list](parts/parts_list.md) +A [parts list](parts/parts_list.md) and mechanical drawings of some parts used in the setup are included in the [parts](parts) directory. For a more complete description of the optical path, see our BOE paper linked above.