Using Micro-Manager from your Matlab environment.
The Micro-Manager Core Java API is contained in the file MMCoreJ.jar. Any Java program (including Matlab) that wants to use the Micro-Manager API needs to put MMCoreJ.jar in its ClassPath. When CMMCore Java object is first created in the calling program it will automatically attempt to load native library MMCoreJ_wrap. This library must be visible to the Java run-time. Default locations and exact names of libraries are platform dependent.
On Windows, the native library file is MMCoreJ_wrap.dll and it must reside either in the system path or in the current working directory of the program in order to be detected by the Java run-time.
MMCore can be used in Matlab through its Java interface. After setting up the Java environment as described above, MMCoreJ.jar must be added to Matlab Java class path and the directory for the MMCore dynamic libraries (including MMCoreJ_wrap) must be added to the system path.
The following recipe has worked in the past for version <=1.3 If you are using MM of version 1.4.6 (as of 06/20/11 its the nightly build) than look for simpler instructions below:
Matlab has an extensive Java support which makes things easy, just do the following:
1. Install Micro-Manager in a path without any spaces (for instance: C:\Micro-Manager1.2).
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.3).
3. In Matlab command prompt
>> edit classpath.txt
Add the location of the jar file you just installed (its in the Micro-Manager folder), include the .jar at the end, for instance:
C:/Program Files/Micro-Manager-1.3/ij.jar
C:/Program Files/Micro-Manager-1.3/plugins/Micro-Manager/MMCoreJ.jar
C:/Program Files/Micro-Manager-1.3/plugins/Micro-Manager/MMJ_.jar
C:/Program Files/Micro-Manager-1.3/plugins/Micro-Manager/bsh-2.0b4.jar
C:/Program Files/Micro-Manager-1.3/plugins/Micro-Manager/swingx-0.9.5.jar
4. In Matlab command prompt
>> edit librarypath.txt
Add the location of the dll files, for instance:
C:\Program Files\Micro-Manager-1.3
5. Restart Matlab
6. create a java object of class MMCcore
>> import mmcorej.*;
>> mmc=CMMCore;
>> mmc.loadSystemConfiguration
(‘C:\Micro-Manager1.2\MMConfig_demo.cfg’);
The following recipe has worked for versions 1.4.6 - 1.4.11 (and newer hopefully):
1. Install Micro-Manager in a path without any spaces (for instance: C:\Micro-Manager1.4.6).
At least with recent versions of MATLAB, there is no need to install in a path without spaces (tested with MATLAB R2013a).
2. In Matlab command prompt
>> edit classpath.txt
Add the location of all the jar files MM installed under plugins\Micro-Manager:
for example:
C:/Micro-Manager-1.4/ij.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/MMAcqEngine.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/MMCoreJ.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/MMJ_.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/clojure.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/bsh-2.0b4.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/swingx-0.9.5.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/swing-layout-1.0.4.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/commons-math-2.0.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/ome-xml.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/scifio.jar
C:/Micro-Manager-1.4/plugins/Micro-Manager/guava-17.0.jar
At least in recent versions of MATLAB (tested with R2013a), the file classpath.txt is automatically generated and should not be edited manually, lest it be overwritten. If classpath.txt contains a comment to that effect, use instead this command:
edit([prefdir ‘/javaclasspath.txt’]); The first time you edit the file, it will have to be created. After restarting MATLAB, you can check that the paths have been included in the MATLAB classpath by typing javaclasspath at the command prompt.
3. In Matlab command prompt
>> edit librarypath.txt
Add the location of the dll files, for instance: C:/Micro-Manager-1.4.6/
4. Add the location of the dll files to the system path. This is not required for all device drivers but is required to access the Andor driver on a Windows 7 system.
5. Restart Matlab
6. create a java object of class MMCcore
>> import mmcorej.*;
>> mmc = CMMCore;
>> mmc.loadSystemConfiguration ('C:\Micro-Manager1.4\MMConfig_demo.cfg');
The Micro-Manager Core API is described here: </apidoc/mmcorej/latest/mmcorej/CMMCore.html>
The following simple script will snap an image from an up-to-16-bit monochrome camera and display it in MATLAB:
>> mmc.snapImage();
>> img = mmc.getImage(); % returned as a 1D array of signed integers in row-major order
>> width = mmc.getImageWidth();
>> height = mmc.getImageHeight();
>> if mmc.getBytesPerPixel == 2
pixelType = 'uint16';
else
pixelType = 'uint8';
end
>> img = typecast(img, pixelType); % pixels must be interpreted as unsigned integers
>> img = reshape(img, [width, height]); % image should be interpreted as a 2D array
>> img = transpose(img); % make column-major order for MATLAB
>> imshow(img);
A function to help MATLAB recognize Micro-Manager
As of uManager version 1.4.18 there is a conflict between deprecated java classes used by MATLAB and the Google Guava library, specifically the google-collect.jar. One work around is to load the uManager specific libraries before the MATLAB default libraries. This gives uManager libraries priority in the java class path. This can be done by adding the text ‘‘
The following code, when saved and used as a function will scan the Micro-Manager folder and create a text file, with all the jar information, in MATLAB’s prefdir where the javaclasspath.txt file should be located. Run this script before first using MATLAB and Micro-Manager together. This script will locate all of the *.jar files within the Micro-Manager directory tree and save their locations to a text file. The text file is saved to the MATLAB prefdir directory. The contents of this file can be appended to a text file named javaclasspath.txt. From then on, every time MATLAB starts the files located in this text file will be added to the MATLAB’s static JAVA path.
Verify the MATLAB java path using the command javaclasspath().
Verify Micro-Manager is responding using the commands import mmcorej.*; mmc=CMMCore.
Inputs = path2MM, the root directory of the Micro-Manager software
function [] = MMsetup_javaclasspath(path2MM)
fileList = getAllFiles(path2MM);
fileListJarBool = regexp(fileList,'.jar$','end');
fileListJarBool = cellfun(@isempty,fileListJarBool);
fileListJar = fileList(~fileListJarBool);
fid = fopen(fullfile(prefdir,'MMjavaclasspath.txt'),'w');
fprintf(fid,'<before>\r\n');
cellfun(@(x) fprintf(fid,'%s\r\n',x), fileListJar);
fclose(fid);
%% nested directory listing ala gnovice from stackoverflow
% inputs and outputs are self-explanatory
function fileList = getAllFiles(dirName)
dirData = dir(dirName); % Get the data for the current directory
dirIndex = [dirData.isdir]; % Find the index for directories
fileList = {dirData(~dirIndex).name}'; % Get a list of the files
if ~isempty(fileList)
fileList = cellfun(@(x) fullfile(dirName,x),fileList,'UniformOutput',false);
end
subDirs = {dirData(dirIndex).name}; % Get a list of the subdirectories
validIndex = ~ismember(subDirs,{'.','..'}); % Find index of subdirectories
% that are not '.' or '..'
for iDir = find(validIndex) % Loop over valid subdirectories
nextDir = fullfile(dirName,subDirs{iDir}); % Get the subdirectory path
fileList = vertcat(fileList, getAllFiles(nextDir)); % Recursively call getAllFiles
end