Difference between revisions of "Writing plugins for Micro-Manager"

Revision as of 13:08, 25 January 2015

Micro-Manager's classpath is set up so that Micro-Manager plugins can import classes from:

1. the Java 2 SE 6.0 Libraries
2. Micro-Manager Core
3. Micro-Manager GUI
4. ImageJ
5. Apache Commons Math

The MMPlugins API provides you access to the GUI and core instances (objects) already created by Micro-Manager startup. Micro-Manager will call public void setApp(ScriptInterface app); you can get the GUI object, core and acquisition engine objects thus:

   MMStudioMainFrame gui_ = (MMStudioMainFrame) app;
   CMMCore core_ = gui_.getMMCore();
   AcquisitionEngine acq_ = gui_.getAcquisitionEngine();

Once you have compiled your code into a .class file or a .jar file, drop that file into Micro-Manager's mmplugins directory, and it will be loaded at startup.

The source code for a number of Micro-Manager plugins is publicly available here. Seamus Holden has also contributed a Hello World Example plugin.

Using Netbeans

The dynamic loading feature (described above) is useful if you are developing your plugin using an IDE such as Eclipse or Netbeans. (The Micro-Manager distribution includes swing-layout-*.*.jar so that you can use the free Netbeans GUI Builder for your plugin.) Here are the steps for Netbeans:

1. Install Netbeans. Note, Netbeans currently comes with the Java 1.7.0 run time environment. After install, you will need to manually install and add the JRE that Micro-Manager uses: 1.6.0, 64-bit if you need it. Additionally, if you are developing with JDK 6, you will need NetBeans 7.3.1 as that was the last release compatible with JDK 6 and later versions require JDK 7.
2. Select New > New Project... > Java > Java Class Library.
3. Name your plugin project and press Finish.
4. Under the Projects tab, right-click your plugin project and choose Properties.
5. Then choose Libraries > Compile > Add JAR/Folder.
   1. Browse to C:\Program Files\Micro-Manager-1.4\plugins\Micro-Manager and choose all jars in that directory.
   2. Click Add JAR/Folder again and add C:\Program Files\Micro-Manager-1.4\ij.jar
   3. Click Categories > Run and set Main Class to ij.ImageJ, working directory to C:\Program Files\Micro-Manager-1.4\ . Click OK.
6. Now choose Debug > Debug Project from the Menu and ImageJ/Micro-Manager should launch. Close it for now.
7. Right-click your Source Packages in your project, under the Projects tab. Select New > Java Class... and give your plugin a class name and package name.
8. Edit the class declaration so that it contains the phrase implements org.micromanager.api.MMPlugin. Left-click on the light-bulb with a red pimple to the left of this line, and select "Implement all abstract methods."
9. Compile your project, and manually copy the project jar file to Micro-Manager's mmplugins directory. Alternatively, you can add the following to your project build.xml file (look in the Project "Files" tab in Netbeans):

       <property name="pluginsDir"  location="C:\Program Files\Micro-Manager-1.4\mmplugins" />
       <target name="-post-jar">
       System.out.println(info);
       <echo message="--Copied MM plugin JAR to basedir: ${basedir}" />
       <copy file="${basedir}/${dist.jar}" toDir="${pluginsDir}" />
       </target>

When "Clean and Build" is run, this will automatically copy the current version of your plugin to the mmplugins folder.

10. Now choose Debug > Debug Project and your nascent plugin should appear in the Plugins menu.

You can also dynamically load your plugin by including a line in the MMStartup.bsh file. (This file should reside in the root directory of your Micro-Manager installation; if there isn't one yet, you can create it with any text editor program.) For example:

       gui.installPlugin("org.micromanager.surveyor.SurveyorPlugin");

Make sure you change the "Layout Generation Style" property from "Automatic" to "Swing Layout Extensions Library" as explained on the Netbeans website.

Configure Eclipse to edit a plugin

1. Get Micro-manager source code if you don't already have it, at least the trunk (see this page)
2. Install Eclipse (these instructions for Kepler)
3. Add Micro-manager's JRE to Eclipse
   1. Window -> Preferences; under Java, select Installed JREs and click Add...
      1. Use Standard VM
      2. Set the JRE Home to C:\Program Files\Micro-Manager-1.4\jre (or similar).
      3. Eclipse should fill in the rest.
      4. Click Finish
   2. Check the checkbox next to the newly-added JRE.
4. Create a new project for Micro-Manager Studio:
   1. File -> New -> Java Project...
      1. Select an appropriate name (e.g. the name of the plugin)
      2. Uncheck "Use Default Location"
      3. Point Location to plugin code location, in trunk the path is plugins\<plugin name> (note: do not use plugins\<plugin name>\src\org\micromanager\<plugin name>)
      4. Eclipse should auto-configure all sorts of useful things.
   2. Click Next
      1. On the Libraries tab, click Add External JARs and add all the JARs in Browse to C:\Program Files\Micro-Manager-1.4\plugins\Micro-Manager (or similar):
      2. Also Add External JAR ij.jar at C:\Program Files\Micro-Manager-1.4\ (or similar)
      3. Add any other relevant JARs, or add later from Project Properties
   3. Click Finish.
5. Set up debug configuration at Project -> Properties; then Run/Debug Settings
   1. Add New configuration, Java Application; click "OK"
      1. Make sure the project is set to be the current project
      2. Specify the main class as ij.ImageJ
      3. At the bottom of the Arguments tab, change the working directory to "other" and browse to C:\Program Files\Micro-Manager-1.4\
      4. Click OK
   2. Make sure everything works by launching debug view from Run -> Debug
6. To build a JAR file
   1. File -> Export (or right click on the project in the Project Explorer, select Export)
   2. Select Java -> JAR file, then click "Next"
   3. Point JAR export location to C:\Program Files\Micro-Manager-1.4\mmplugins\<plugin name>
   4. Click "Finish"