Using Plugins

On the main Morphanalyser window, click 'Plugins' -> 'Add a Plugin' to add a plugin. A file browser window will open, select a jar file containing one or more Batchable3D and/or Plugin3D classes. The plugin will add a new cascaded menu to the Plugins menu, the cascaded menu will contain each "Batchable3D" class as both a single and a batch item on the "Plugins" sub menu.

To remove a plugin, click 'Plugins' -> 'remove an existing Plugin'

Writing Batchable and Plugin classes

MorphAnalyser handles two plugin interfaces. The first, Batchable3D, allows single and batch processing of 3D images. A no-args constructor (or no constructor for the no args default) needs to be provided for loading at runtime (using java reflection). Most of the work should be done in the process method, which will be used to process each ObjectGeometry (as listed in a standard text list file, with one .obj per line). Other methods required include an initialisation method, 3 methods to indicate if the template should be read or written, and if the object geometry should be written. A finish method is used for any clean up, and a getName method is used to retrieve the name displayed on the menu. A simple example of a Batchable3D that crops to a plane is given below:

public class BatchCropPlugin3D implements  Batchable3D {
   MorphAnalyser2 morphanalyser;

   public boolean process(ObjectGeometry obj, Template3D t3d, boolean single) {
       float[] plane = morphanalyser.getPlane();
       obj.trimToPlane2(plane);
       return true;
   }

    public boolean initialise(MorphAnalyser2 morphanalyser) {
        this.morphanalyser = morphanalyser;
        return true;
    }

    public void finish() {}
  
    public String getName() {return "Crop";}

    public boolean getReadTemplate3D() {return false;}

    public boolean getWriteTemplate3D() {return false;}

    public boolean getWriteObjectGeometry() {return true;}

}

The second interface, Plugin3D, is more general, and simply supports a setup and cleanup method. The example below adds a new menu and menu item to the user interface for illustration.

public class HelloPlugin3D implements Plugin3D {
    JMenu helloMenu;
    MorphAnalyser2 morph;
    
    public boolean setup(MorphAnalyser2 morphanalyser) {
        morph = morphanalyser;
        helloMenu = new JMenu("Hello");
        morphanalyser.addMenu(helloMenu);
        JMenuItem helloItem = new JMenuItem("Hello");
        helloItem.addActionListener(new ActionListener() {

            public void actionPerformed(ActionEvent e) {
                JOptionPane.showMessageDialog(morph, "Hello");
            }

        });
        helloMenu.add(helloItem);
        return true;
    }

    public boolean cleanup(MorphAnalyser2 morphanalyser) {
        morphanalyser.removeMenu(helloMenu);
        return true;
    }

}

Using ObjectGeometry Factories

In order to support more advanced rendering (e.g. normal maps etc.) the ObjectGeometry class can be extended. The system uses an ObjectGeometryFactory class to create instances of the particular ObjectGeometry subclass. Factories are added in the same way as Plugins. If the selected jar contains one or more classes implementing a particular Factory, a new selectable factory is added to the Plugins menu (in Factories submenu).

Morphanalyser uses Factories to specify the way that the 3D objects are loaded and rendered. The default Factory (installed by default) is DefaultObjectGeometryFactory. It makes Morphanalyser load a geometry and render it with only one texture. This file needs to be in the same directory as the object file and have the same base name. For example, if we want to open an object whose name is "face.obj", its corresponding texture must be located in the same directory, with the name "face.jpg" or "face.bmp".

There is another Factory that can be used for multitexture rendering ( MultiTextureObjectGeometryFactory ). It is included in the MorphAnalyserPlugins (so if MorphAnalyserPlugins.jar is added as plugin, another factory will appear in the Factories submenu : MultiTextureObjectGeometryFactory ). It implements a bump mapping rendering technique which requires 4 normal maps (red, green, blue and specular) and 2 textures (diffuse and specular). If selected the folder containing the object to open must also contain a text file with the same base name as the object and the extension ".multi" that says where to find the different normal maps and texture (in the following order: red normal map, green normal map, blue normal map, specular normal map, specular texture and diffuse texture). The examples also contain a simpler version which only requires a texture and a normal map.

For Developers

Collaborators can res to our svn repository. If the jar file for plugin is not available, here is an example of how to get and compile MorphAnalyserPlugins with Netbeans:

Menu Team->Subversion->Checkout.
On Repository URL, type '​http://cherry.dcs.aber.ac.uk/svn/svn' and click next.
On Repository Folder, type 'MorphAnalyserPlugins/trunk'. Check Skip trunk. Verify if the local folder is Ok and click finish.
After checkout completed, open the MorphAnalyserPlugins project or accept if Netbeans proposes to.
In the project properties, add the following dependance libraries: FaceMorphLib.jar, Morphanalyser.jar and jogl (j3dcore.jar, j3dutils.jar, vecmath.jar)
Clean and compile. The corresponding jar is generated in the dist folder of the project.