top bar

Micro-Manager Configuration Guide

Revision as of 09:23, 13 September 2011 by Ziah Dean (Talk | contribs)

Created on July 31, 2006 by Nenad Amodaj
Revised on January 31, 2007
Revised on August 21, 2008 by Nico Stuurman


In order to control a specific microscope, the Micro-Manager application needs to know what hardware is part of the microscope, load and initialize the appropriate drivers, define configuration presets, create labels for device positions, etc.. Typically, on startup the Micro-Manager application loads a configuration file containing commands configuring all aspects of the system. To start using Micro-Manager, you will first need to create a configuration file specific for your system

Startup screen

Figure 1. Startup screen: selection of the configuration file

Upon Micro-Manager startup an introductory splash screen pops-up displaying the configuration file that is about to be loaded. By default, Micro-Manager attempts to load the file used in the previous session. You can either use that file, load another configuration file, or start Micro-Manager with no configuration file by selecting "none". After pressing OK the initialization process starts and when it finishes without errors, Micro-Manager is ready for use. Configuration files can be also loaded at any time using the Tools | Load Hardware Configuration command from the main menu. Each time you load a configuration file, the current configuration is un-initialized (shut down) and the new one is initialized. Re-loading a configuration file has (almost) the same effect as restarting the application. You may also switch and save any configuration files under the Tools menu.

The way to create a configuration file is by using the Configuration Wizard (Tools | Hardware Configuration Wizard), which will guide you, step-by-step, through the configuration process and generate a configuration file for you. The wizard will generate a text file that can be edited in a text editor. The syntax of this file is described below.

Hardware Configuration Wizard

The hardware configuration wizard guides you through the creation of a configuration file in 9 steps. Each step will display specific help in the lower half of the wizard's window. Before you begin, you should assemble as much information about your hardware as possible. For instance, you should know which serial ports of your computer are attached to what hardware. Preferably, you should test the functionality of the hardware with software provided by the vendor. Information and helpful advice about specific devices can be found on the Micro-Manager web site. When you get stuck, you can get support through the Micro-Manager mailing list. Remember, this is the most important part in getting Micro-Manager to be fully functional.

Hardware wizard step 3
Figure 2. Step 3 of the hardware configuration wizard: selection of devices.

You can exit the wizard at any step by closing the wizard's window. You will be prompted to save the configuration file. Doing so (even when something did not work) will be helpful in trouble shooting potential issues. The most critical part of the wizard is between steps 4 and 5. At this point the hardware is being initialized, and errors/problems will most often manifest themselves here. At the end of the wizard, save the file using the '.cfg' extension.

Configuration Presets

Any property that Micro-Manager knows about can be changed using the Property Browser (Tools | Device/Property Browser). Changing properties using the Property Browser quickly becomes cumberson and impracticle. Micro-Manager therefore uses the concept of 'Configuration Presets' that let you quickly change a group of device properties. Configuring these Configuration Presets in a meaningful way is a very important part of configuring Micro-Manager. Configuration Presets also let you modify the User Interface of Micro-Manager to suit your needs.

Configuration Presets
Figure 3. Example of Configuration Presets in the Main Micro-Manager window

Before setting up Configuration Presets, you should familiarize yourself with the Device/Property Browser. It is also worthwhile to experiment with the Configuration Presets in the demo configuration.

Preset Editor
Figure 4. Initial Screen of the Preset Editor

To make a new configuration group (a new row in the table with Configuration settings), press the Group '+' button at the bottom left of the Configuration Settings table. A Group Editor window will appear that looks similar to the Device/Property Browser, but has a third column called 'Use in Group?'. Check the box in the 'Use' column for any property that you want to be included in this configuration group. For instance, you might want to make a group called 'Channel' in which you 'Use' the emission and excitation filter wheels in your system and also set the Core-Shutter (to switch between the fluorescent and transmitted light shutter).

You will now be presented with a second window, (the Preset Editor), that will list only those properties you have chosen for your new group. Set the properties that you selected to their desired positions and name the Preset (for instance: 'GFP'). Click 'OK', and you will have the first Configuration Prest in this group. To add Presets to the group, select the group (by clicking on the name of the group, 'Channel' in this example), and clicking the Preset '+' button. The Preset Editor will appear again for each new preset. The 'Configuration' column in the user interface will now be a dropdown menu, selecting an item from this menu will change the state of your microscope.

When you select only a single property in the 'Use' column when making a new Configuration Preset Group, Micro-Manager will do some magic. For instance, when this property is displayed as a slider in the Device/Property Browser, a slider will appear in the main Micro-Manager window. If the property has a few values (like a filter wheel), all available values will appear in a dropdown list in the main window. This way you can quickly add control over a single device property, for instance the position of a filter wheel, to the main Micro-Manager window.

Once you are satisfied with your current presets you save them into the current configuration file (or a new one) using "Save" button next to 'Configuration settings'. You can save the presets to the configuration file that you made previously. Next time you start up with that configuration file, your presets will be automatically loaded.

The 'Edit' and '-' (Delete) buttons allow you to change and remove Configuration Groups and Presets. If you add a property to a Group, then all existing Presets in that Group will now include the current value of the new Property.

Startup Presets

There are a few configuration group/preset names with special meaning to Micro-Manager. If you make a configuration preset group called 'System', then you can define the groups 'Startup' and 'Shutdown'. These configuration presets will be applied on startup and shutdown of Micro-Manager respectively.

Pixel Size Calibration

Pixel size calibrations are organized in a way similar to Configuration Preset Groups. You will define a group of properties that affect the pixel size, and when the current settings of the system 'matches' one of the Pixel Size Calibration 'Presets', Micro-Manager will apply that pixel size to the metadata of the images you take.

Pixel Size Calibration Editor
Figure 5. Pixel Size Calibration Editor

To set up Pixel Size Calibrations, start the Pixel Size Calibration editor (Tools | Pixel Size Calibration). Click the 'New' button. A window, very similar to the window you saw when setting up new Configuration Preset Groups will appear. Check the boxes in the 'Use' column for those properties that affect the pixel size i.e objectives, auxiliary magnification (Optovar) etc. Do not check the camera 'Binning'property (binning is automatically taken into account by Micro-Manager). Some other properties might not appear in the list since they are automatically taken into account (so called 'Magnifier' devices, these automatically tell Micro-Manager how they affect pixel size). Give this Pixel Size Calibration a label (the name is unimportant, it should be unique and might help you to remember the settings) and enter the pixel size. When you press 'New' again, only the previously selected properties will appear. Set these to the appropriate settings, give a label and the pixel size. The Pixel Size can also be edited inside the 'Pixel Size calibration' window.

If a non-motorized device affects the pixel size calibration (for instance: your objective turret is non-motorized) you can add a device from the demo-adapter to represent this non-motorzied device and include this demo device in the pixel size calibration settings. When you now manually change the setting of the non-motorized device you should also change the setting of the demo device and Micro-Manager will select the correct pixel size calibration.

Again, do not forget to save the configurations after editing pizel size calibrations (you can use the 'Save' button next to Configuration Presets in the main window to this end). These settings are saved in the same file to describe the hardware and configuration presets (your 'configuration' file).

Configuration file syntax

A configuration is defined in a text file (with default extension *.cfg) containing a list of simple commands to build the desired system state: devices, labels, equipment, properties, and configurations. The format is as follows:

  • Each line consists of a number of string fields separated by "," (comma) characters. No extra spaces are allowed for formatting, i.e. space characters will treated as parts of the field.
  • Lines beginning with "#" are ignored (can be used for comments).
  • Each line in the file will be parsed by the system and as a result a corresponding command will be immediately executed.

The first field in the line always specifies the command from the following set of values:

  • Device -- loads device
  • Label -- attaches a label to the specified device position
  • Equipment -- defines various equipment attributes used for image annotation
  • Property -- sets a specific device property
  • ConfigGroup -- defines a single entry in the configuration group

    Remaining fields in the line are used for specifying the corresponding command parameters. The number of parameters depends on the actual command used.

    The following listing shows configuration file for the Demo setup.

# Generated by Configurator on Wed Jan 10 12:06:46 PST 2007

# Reset

# Devices

# Pre-init settings for devices

# Pre-init settings for COM ports

# Initialize

# Delays

# Roles

# Camera-synchronized devices

# Labels
# Dichroic
# Emission
# Excitation
# Objective
Label,Objective,3,Nikon 20X Plan Fluor ELWD
Label,Objective,1,Nikon 10X S Fluor
Label,Objective,0,Nikon 40X Plan Flueor ELWD

# Configuration presets
# Group: Camera
# Preset: MedRes

# Preset: Default

# Preset: LowRes

# Preset: HiRes

# Group: Objective
# Preset: 20X

# Preset: 40X

# Preset: 10X

# Group: Channel
# Preset: FITC

# Preset: Rhodamine

# Preset: DAPI

# Preset: Cy5

# Group: System
# Preset: Startup

# Preset: Shutdown

# Group: LightPath
# Preset: Camera-left

# Preset: Eyepiece

# Preset: Camera-right

# PixelSize settings
# Resolution preset: 20x
ConfigPixelSize,20x,Objective,Label,Nikon 20X Plan Fluor ELWD

# Resolution preset: 40x
ConfigPixelSize,40x,Objective,Label,Nikon 40X Plan Flueor ELWD

# Resolution preset: 10x
ConfigPixelSize,10x,Objective,Label,Nikon 10X S Fluor

© Micro-Manager : Vale Lab, UCSF 2006-2011 | All Rights Reserved | Contact