This document provides instructions for controlling the MicroManager microscopy software via MATLAB to enable real-time cell image processing capabilities. It outlines how to import MicroManager classes into MATLAB, set up the environment, and provides an example workflow of how the existing ACTIVE image analysis software could be modified to allow real-time processing and control of the microscope during live cell imaging. Key areas that could be automated based on analysis results are also discussed.
2. Purpose: This document is intended to provide
instructions to control MicroManager software via
MATLAB. In addition, it outlines potential areas to change
within ACTIVE to allow for real-time cell image
processing.
3. Table of Contents
I. Overview and Uses ……………………………………………………………………………………………… 4,5
II. Import Instructions and Setup ……………………………………………………………………………. 6-9
III. Example Real Time Processing Pathway via ACTIVE ………………………………………. 10-20
IV. Contact Info & Acknowledgements ……………………………………………………………………… 21
4. Task of researching and developing a method to integrate Biomaterials automated microscopes
with existing ACTIVE MATLAB software
Project Overview & Uses
1. Design and document program to integrate critical
microscope functions under MATLAB control.
2. Record documentation regarding project progress and
hardware/software integration
3. In accordance with the requirements of BEN 485:
• 2 page design summary
• Preliminary design review
• Final design review
• Design notebook
4. Achieve following outcomes:
• Design systems, components, and processes
necessary to meet a desired need
• Use computer-based tools relevant to gathering
information from, and interacting with, living
systems
• Apply techniques, skills, and modern engineering
tools necessary for engineering practice
• An ability to communicate effectively
Objectives Uses
1. Introduce real-time processing capabilities to existing
ACTIVE framework
2. Control Micro-Manager core functions via MATLAB
commands and open GUI and acquisition tools from
.m files
3. Directly import images and scope parameters to
create an organized and readable archive for future
experiments
4
5. µManager software architecture and general design features
Project Overview & Uses
System Requirements
Compatible operating systems: Windows, Linux and
Mac OS X
Required software:
• Micro-Manager-1.4 or higher
• MATLAB 2012b or higher
Program Description
Manager is software for control of microscopes. It
works with almost all microscopes, cameras and
peripherals on the market, and provides an easy to use
interface that lets you run your microscopy-based
experiments. µManager runs as a plugin to ImageJ, is
Open Source, and is free. µManager is developed in
Ron Vale's laboratory at UCSF and is funded by an NIH
grant R01-EB007187 from the National Institute of
Biomedical Imaging and Bioengineering (NBIB).
*via micro-manager.org
5
6. Accessing native Java classes via MATLAB’s import feature
Import Instructions & Setup
1. Install Micro-Manager in a path without any spaces (for instance:
C:Micro-Manager-1.4).
2. Add the path with the drivers (all the .dll files) to the windows PATH
enviromental variable
• (Start->Settings->Control Panel->System->Advanced-
>Environment Variables, make a new 'User variable for
Administrator named 'PATH' and set it to the location of Micro-
Manager (for instance: C:/Program Files/Micro-Manager-1.4).
3. Open MATLAB, set the current directory via: cd 'C:/Program
Files/Micro-Manager-1.4'
4. Manually add C:/Program Files/Micro-Manager-1.4 to the
librarypath.txt file found within MATLAB->Toolbox->Local
5. Run the following snippet to add all .jar files to the dynamic Java
Class Path:
path2MM = 'C:/Program Files/Micro-Manager-1.4'
fileList = getAllFiles(path2MM);
fileListJarBool = regexp(fileList,'.jar$','end');
fileListJarBool = cellfun(@isempty,fileListJarBool);
fileListJar = fileList(~fileListJarBool);
fid = fopen(fullfile(prefdir,'javaclasspath.txt'),'w');
fprintf(fid,'<before>rn');
cellfun(@(x) fprintf(fid,'%srn',x), fileListJar);
fclose(fid); 6
7. Accessing native Java classes via MATLAB’s import feature
Import Instructions & Setup
5.) Verify javaclasspath and librarypath.txt contain the jar files and that
the current directory is C:/Program Files/Micro-Manager-1.4
6.) Import mmcorej.*
7.) mmc = CMMCore
At this point you now have access to all commands within the core
Micromanager program. This includes exposure, shutter state, channels,
etc. In order to access the gui the following steps must be taken.
>> import org.micromanage.api.ScriptInterface
>> gui = org.micromanager.MMStudio(false)
>> gui.getMMCore();
>> mmc = gui.getMMCore();
>> acq = gui.getAcquisitionEngine2010;
This will open the gui as a MATLAB window which can be controlled as
usual. In addition, the core commands will also be available.
7
8. Accessing native Java classes via MATLAB’s import feature
Import Instructions & Setup
Required for
functions
calling mmc
& gui class
Required for
multi image
acquisition
features
The following lines should be inserted into the classpath.txt file located within the local
toolbox of MATLAB’s program files. Addition of these will allow MATLAB to access the .jar
files that contain the API to run the scope controls.
8
9. Visual example of controlling Mmanager setup via MATLAB command
Import Instructions & Setup
9
10. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Key:
Function dependencies within .m file
Inputs from one function originating from output of second function
Optional function
Suggested addition to allow for real-time processing
Wrapper functions that utilize branching components
10
11. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
11
12. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Function name Description Input(s) Output(s)
run_tracking_contour2 Main wrapper function inputfilename (optional) xyzs_id, xyzs_id_columns,
filename, framerate, new_dir
makecontourparentarray A function that creates a
nested list of contours from
the image
nlevels, A, halfobjectsize,
noise_wavelength, plottoggle
parent_info, parent_vec,
x_vector, y_vector
bpass Implements a real-space
bandpass filter to suppress
pixel noise and slow-scale
image variations while
retaining information of a
characteristic size
img, lambda, w res
sibling_matrix creation Creates a matrix that
contains information for all
potential interaction events
(divisions and merging)
xyzs_id, xyzs_id_columns sib_matrix, xyzs_id
Collision_corrector_rtc2 A function that constructs
and characterizes interaction
events between sibling cells.
The function also classifies
merging or division events in
an array
xyzs_id, sib_matrix,
xyzs_id_columns,
max_collision_time
xyzs_id, sib_matrix,
event_array,
xyzs_id_columns
12
13. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Function name Description Input(s) Output(s)
cost A function that calculates the
cost of switching cell IDs
during a collision event. This
cost is determined from cell
characteristics that are
normalized by the frame
averages, and then
weighting factors allow the
user to define which
parameters are more
revealing of a cell's identity
xyzs_id1, xyzs_id2,
frame_avg
total_cost, cost_vector
pos_2 A function that performs a
position or fingerprint cost
analysis for each non-
duplicated entry in a specific
event's information. This
information is then used to
correct mislabelled cells
during tracking
event_info, xyzs_id,
xyzs_id_columns, frame_avg
lookup_table, pos_matrix
13
14. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Function name Description Input(s) Output(s)
collision_tag_rtc2_3 This function 'fixes' mislabled
ID tags resulting from cell
merging events. It achieves
this by running a positional
or fingerprint cost function
on the cells involved in a
given collision and calculates
the cost for switching cell
IDs after the collision
xyzs_id, event_array,
xyzs_id_columns, frame_avg
xyzs_id and mastertable
trackmen_new A function that uses time
and position arrays to find
new particles, loop old ones,
calculate trivial bonds and
also account for particles
that do not reappear
xyzs, maxdisp, memory,
dim, goodenough, memory
lub
luberize A function that reassigns
unique IDs with numerical
values
tracks newtracks
14
15. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Function name Description Input(s) Output(s)
insertrows A function that insert rows
(matrix B) into matrix A at
specific locations
A, B, ind C, RA, RB
division_corrector : A function that analyzes
interaction events classified
as divisions and reclassifies
incorrect frustrated divisions.
The code duplicates parent
information for dividing cells
so that both daughter cells
retain parent information
prior to the division
xyzs_id, event_array,
xyzs_id_columns,
particle_radius, image,
min_frame, border_width,
frust_toggle
xyzs_id, event_array,
div_matrix
relabel A function that relabels
collision IDs based on a
mastertable. IDs are
reversibly updated
mastertable, xyzs_id,
xyzs_id_columns
xyzs_id
find_particles_fixed A function that finds unique
particles from a set of
contour data
parent_info, parent_vec,
x_vector, y_vector,
removeflagged, area_thresh,
min_area, fit_height
particles, pellipses,
weird_vec
15
16. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Function name Description Input(s) Output(s)
ellipse_mask3 A function that executes a
masking analysis to calculate
sum of intensity and area for
each particle
particles, A particles
fit_ellipse A function that fits an ellipse
to a 2D dataset given in the
data using a least-squares fit
(Fitzgibbon approach)
xvector, yvector, plottoggle xc, yc, a, b, theta, and es
frame_char A function that relabels
collision IDs based on a
mastertable. IDs are
reversibly updated
mastertable, xyzs_id,
xyzs_id_columns
xyzs_id
find_particles_fixed A function that determines
frame averages of the major
axis, minor axis, aspect
ratio, orientation angle, area,
integrated intensity, and
average intensity
xyzs_id, xyzs_id_columns frame_avg
16
17. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Function name Description Input(s) Output(s)
plot_ellipse A function that plots ellipse
data generated from the fit
ellipse function
xc, yc, a, b, theta, npoints eplotdata
print_ellipse A function that plots all cell
ellipse information, given a
cell array of ellipse x, y point
information (single array
entry=series of single ellipse
x, y data pairs)
pel, Style image of plotted ellipses
make_ellipse_movie A function that creates a
movie overlay of cell images
and ellipse information.
Sibling information is plotted
in different colors as cells
interact
xyzs_id, xyzs_id_columns,
stackname, data_folder,
figbase, folder_name
a
plot_collisions_rtc2_3 A function that plots videos
for division and merging
events
xyzs_id, event_array,
stackname,
xyzs_id_columns,
data_folder, post_correct,
and video_disp_toggle
n/a
17
18. Altering existing ACTIVE software to allow for real-time cell image processing
Example ACTIVE Pathway
Run_tracking_
contour_2
RT_processing
User input:
1.) RT
processing
2.) Post
processing
Run_tracking_
contour_2
Existing
ACTIVE
pathway:
Bpass, etc
Example pathway:
• Choose folder to save img files
to
• Loop through folder & determine
if new image
• Compare new image to last
using existing ACTIVE
segmentation pathway
• Create criteria based on desired
experimental inquiry
• Use scope control to adjust
stimulus intensity
.tiff
.jpeg
18
19. Potential considerations when developing real time analysis pathway
Example ACTIVE Pathway
Recommendations for Development
• Creation of wrapper to include main code as well as
new functions to allow for real time analysis.
Specifically, ability to import images directly from
camera and iterate through folder where images are
stored
• Time between images may be dependent on
computation time for ACTIVE; samples with higher
cell density may result in longer analysis
• Data dependencies (.tiff vs .jpeg) will require
alteration of main code functions that currently are
intended for image stacks produced by ImageJ
Areas of Interest for Automation
• Adjust stage speed to compensate for sample shift
• Automatically adjust Field Intensity based on output
of ACTIVE analysis
• Readjust Z Focal Plane during imaging
• Adjust stimulus levels and set criteria for feedback
resulting from analysis results/cell motility
• Directly import photos from microscope and create
function to generate .tiff file simultaneously with
real time processing
19
20. Common commands used to control core scope functions via MATLAB
Example ACTIVE Pathway
• Creation of wrapper to include main code as well as
new functions to allow for real time analysis.
Specifically, ability to import images directly from
camera and
• Time between images may be dependent on
computation time for ACTIVE; samples with higher
cell density may result in longer analysis
Control Name Preset Package Class Method Description
Snap mmcorej CMMCore snapImage()
Acquires a single image with current
settings
Live org.micromanager.api ScriptInterface enableLiveMode(boolean)
Album org.micromanager.api ScriptInterface getCurrentAlbum
Refresh org.micromanager.api ScriptInterface refreshGUI() Refreshes GUI
Exposure (ms) mmcorej CMMCore setExposure() Sets exposure in milliseconds
Binning mmcorej CMMCore
Shutter mmcorej CMMCore setShutterOpen(boolean) Opens shutter of selected device
Auto-Shutter mmcorej CMMCore setAutoShutter(boolean)
If enabled. Shutter automatically
opens and closes when image is
taken
Camera mmcorej CMMCore
setCameraDevice(cameraLab
el)
Channel mmcorej CMMCore setChannelGroup
More methods available at:
GUI: https://valelab4.ucsf.edu/~MM/doc/mmstudio/org/micromanager/api/ScriptInterface.html
Core: https://valelab4.ucsf.edu/~MM/doc/mmcorej/mmcorej/CMMCore.html
20
21. Contact Information & Acknowledgements
pamohun@syr.edu (716) 864 - 1392
Acknowledgements and Citations:
Edelstein, A. Advanced Methods of Microscope Control Using Mmanager Software; Journal of
Biological Methods, 2014 Vol 2
Baker RM, Brasch ME, Manning ML, Henderson JH. 2014 Automated,contour-based tracking
and analysis of cell behaviour over long time scales in
environments of varying complexity and cell density. J. R. Soc. Interface 11:
20140386. http://dx.doi.org/10.1098/rsif.2014.0386
Special thanks to: Shelby Buffington, Jay Henderson, Megan Brasch, Alexis Pena, Arthur
Edelstein
21
23. Automated Contour-Based Tracking for In-Vitro Environments
ACTIVE Description
Language MATLAB
Authors
Richard M. Baker, Megan E. Brasch, M. Lisa Manning, James H.
Henderson
Reference
J. R. Soc. Interface 11: 20140386.
http://dx.doi.org/10.1098/rsif.2014.0386
Quick facts:
• Main code consists of 31 individual .m files
• All analysis takes place after imaging
23