Provides MATLAB assets used to acquire experiment data with ScanImage-controlled 2-Photon Random Access Mesoscope (2P-RAM).
This project provides additional assets that are not originally installed on the Mesoscope control PC sourced from MBF Bioscience. Primarily, the assets exposed by this project are used to detect and correct imaging plane motion and are originally developed in the Pachitariu and Stringer lab.
Additionally, the project provides the 'setupAcquisition' function, developed in the Sun lab to automate the preparation for data acquisition and enable the sl-experiment library to bidirectionally interface with the ScanImage software that controls the Mesoscope during runtime.
- MATLAB version R2022b+ with ScanImage version 2023.1.0 (Premium). This code will likely work with later MATLAB and ScanImage versions.
These additional toolbox dependencies must be installed via the MATLAB interface before using assets from this project:
- Parallel Computing Toolbox to support fast online motion detection and correction.
Note! Typically, the computer used to run this code is purchased from MBF Bioscience (together with ScanImage license). In this case, the vendor should satisfy all hardware dependencies and may be requested to also resolve all software dependencies.
- Nvidia GPU. This library uses GPU hardware acceleration to support online motion detection and correction by processing Mesoscope-acquired images. The library was tested with Nvidia GTX 1660.
- Download this repository to the Mesoscope control PC. Use the latest stable release from GitHub, as it always reflects the current state of our data acquisition hardware and software.
- Open MATLAB and navigate to the Command Window.
- Use the
addpath("PATH_TO_THIS_REPOSITORY")command, replacing the PATH_TO_THIS_REPOSITORY with the absolute path to the downloaded and unpacked repository on the local machine.
If installation worked as expected, the setupAcquisition() MATLAB function should now be available for calling from
the Command Window.
All assets from this library are intended to be used via the setupAcquisition function, which automatically configures
motion detection and correction. It also generates the motion estimation files as part of the acquisition preparation
sequence.
The sl-experiment advises the user to call the setup function as part of the broader Mesoscope preparation sequence. While it is possible to use provided assets outside the sl-experiment context, this is not the intended use pattern.
In most cases, setupAcquisition function consists of three major steps:
- Motion estimation setup. During this step, the function configures the acquisition according to the user-defined parameters and establishes the single-plane or the z-stack of planes to be acquired at runtime. Then, it generates a set of additional sub-planes within 20 microns above and below each target plane and acquires ~ 20 images at each plane (traversing the entire stack on each acquisition pass). The produced z-stack is then used to set up the MotionEstimator file used to detect and correct motion in the X, Y and Z axes.
- High-definition zstack acquisition. After setting up the motion detection, the function increases the resolution of the target ROIs by 1.5 Scale Factor and repeats the zstack acquisition. This generates a high-definition zstack.tiff file kept with the TIFF files acquired during experiment runtime.
- Data Acquisition. Finally, the function configures the acquisition and motion detection parameters for the runtime and enters the acquisition loop. While in the loop, the function starts or stops the acquisition depending on the marker file(s) created by the sl-experiment library (see sl-experiment ReadMe for details).
Note! The function can also be used to resume an interrupted runtime by calling it with an optional recovery
argument set to true. In this runtime mode, the function skips steps 1 and 2, going directly to step 3.
Use the doc MATLAB command to generate the API documentation for all assets distributed under this project.
After generating the documentation, use the help MATLAB command to view the documentation at any time.
Note! All users are highly encouraged to check the setupAcquisition documentation to familiarize themselves with function arguments and the range of supported runtime configuration options.
This project uses semantic versioning. For the versions available, see the tags on this repository.
- Ivan Kondratyev (Inkaros)
- Marius Pachitariu
- Carsen Stringer
- Georg Jaindl
This project is licensed under the GPL3 License: see the LICENSE file for details.
- All Sun Lab members for providing the inspiration and comments during the development of this project.
- The members of the Pachitariu and Stringer lab that developed the motion detection and correction code featured in this project and the original acquisition setup function.