Content

Vaa3D plugins are programs you can develop to take advantage of the management, visualization and analysis tools of Vaa3D. They are written in C++ (most of the time), with Qt supported.

A Vaa3D plugin is essentially a dynamic library file. As long as you put it under the "plugins" folder as mentioned, Vaa3D is able to find it (subject to the conditions that must be of the same operating system, based on the same/compatible Qt version(s), and built using the same Release or Debug flag of the compiler). You can indeed put plugins under different folder hierarchy from what have been set as default in a released Vaa3D package.

You can use Vaa3D plugins to do a number of things and in many different ways, such as

• analyzing 3D images, writing output to files;
• visualizing images and surface objects in user-defined way;
• extending Vaa3D functions (e.g. for tera-bytes of large data)
• taking advantage of the fast volume image rendering, 3D pinpointing, and easy 4D image data management of Vaa3D;
• pipelining these plugins.

In the Vaa3D executable package, the default Vaa3D plugins are released under the “plugins” folder, parallel to the Vaa3D executable.

You can also find the available plugins using the following three convenient methods:

• Go to Vaa3D GUI main menu and select the "Plug-In" menu, then select "Plugin Manager". You will see a tree-list of all plugins, including their locations and version information.
• Go to Vaa3D GUI main window, left side control button and select the "A" button (means "applications"). Then you can see a toolbar appears on the top of the main window. You can then click this toolbar button, and you can define short-cuts to all plugins and their internal menu functions.
• On command line console (e.g. Linux , Mac or Windows terminal), type the command (assuming you are running Linux. If you run Mac, you may need to use 'vaa3d64.app/Contents/MacOS/vaa3d64' to replace 'vaa3d' below).

vaa3d -h (Mac OS and Linux)
vaa3d_msvc.exe /h (Windows)

and you can have a complete list of all available plugins. You can then get individual help information of a plugin using

vaa3d -h -x <plugin_name> (Mac OS and Linux)
vaa3d_msvc.exe /h /x <plugin_name> (Windows)

If you check out Vaa3D source code, you can find the plugins source code in the “released_plugins” folders. Since Vaa3D has been used in several different projects, and different contributors may have different licenses, currently the "standard released plugins" are arranged into two different code repositories, but can be batch-complied together following the instructions below. Assuming you are using Linux or Mac, and use the command version of git (if you are using Windows, or other git clients, it is easy to figure the alternatives by yourself!)

git clone https://github.com/Vaa3D/v3d_external.git
git clone https://github.com/Vaa3D/vaa3d_tools.git

for Unix (Mac OS and Linux)

cd vaa3d_tools
ln -s ../v3d_external/v3d_main v3d_main
ln -s ../v3d_external/bin bin
cd ../v3d_external
ln -s ../vaa3d_tools/released_plugins released_plugins_more
cd ../vaa3d_tools/released_plugins
sh build_plugindemo.sh 

for Windows

cd vaa3d_tools
mklink /j  v3d_main ..\v3d_external\v3d_main
mklink /j  bin ..\v3d_external\bin
cd ../v3d_external
mklink /j  released_plugins_more  ..\vaa3d_tools\released_plugins
cd ../vaa3d_tools/released_plugins
build_plugindemo_msvc.bat

The last few lines create symbolic links for necessary header files and output plugins.

Many plugins have been developed by various parties. Some of them can be checked out as [toolboxes].

• More than 100 ITK filters of more than 10 major categories of image analysis functions (e.g. registration, segmentation, etc) were converted to Vaa3D plugins. This project was started in a Vaa3D-ITK hackathon (June 1-4, 2010) participated by Luis Ibaniz, Yang Yu, Lei Qu, and Hanchuan Peng, and later refined by Ping Yu. The project is a continuing effort to develop a useful open-source library based on ITK and Vaa3D; the source code can be checked-out as follows and can be built using both ITK 3.2 and 4.0. After you check out the code from the following site, the source code of these plugins can be found from "hackathon/2010/ITK-V3D-Plugins" sub-folder.

git clone https://github.com/Vaa3D/vaa3d_tools.git/

• Another more than 100 ITK example programs were converted to Vaa3D plugins primarily by Hang Xiao. The code is yet to be released.

LOCI Bioformats is a useful Java-based library to load many image formats. Vaa3D has two plugins to invoke Bioformats library.

• Simple bioformats binding. A plugin implemented by Yang Yu, Yinan Wan, et al to invoke the Java library using a system call to convert an image file to a temporary TIFF file, and then load the TIFF file into computer memory. This plugin is provided as a "standard" released plugin when you build Vaa3D. The source code can be found in the subfolder checked out at

released_plugins/v3d_plugins/bioformatio_simple_bind

• Calling Bioformats in memory directly via JNI. This was primarily implemented by Yang Yu. But it may take some efforts to build for different operating systems. This is obsolete at this moment; interested people are encouraged to refine it and contribute back. The source code can be found at subfolder

released_plugins/special_v3d_plugins/bioformat

You can run Vaa3D plugins via the following ways:

• from the Vaa3D GUI main menu: Plugins with domenus can be executed by clicking the Plug-In menu items.
• create short-cut buttons from the main Vaa3D GUI window to access various menus of plugins directly;
• access plugins' internal functions/menus from command line directly;
• access plugins' internal functions/menus from other programs (e.g. Matlab) if a binding toolbox is available.
• from another plugin: you can also let plugins call each other, please consult [applications] to see the instructions.

An interesting advantage of using Vaa3D plugins for large image data sets is that if you are developing a plugin from source code, and build the binary form and run from Vaa3D GUI, normally you do NOT even need to restart Vaa3D every time you recompile the plugin. This means that you don't have to close your already opened large images (as loading from files can be very time-consuming or non-repeatable). What you need to do is to go to Vaa3D main menu -> Plug-In -> Rescan all plugins. Sometimes you may not even need to rescan (if the plugin folder structure has not been changed and the loaded dynamic library has been unloaded from memory)!

It is quite easy to develop your own plugins by following the guideline. You can build the plugin's executable form using the following way.

Before writing a Vaa3D plugin, please make sure that on your computer you have

• Qt properly installed;
• Vaa3D source code;
• a c++ compiler (e.g. gcc)

If you have any questions regarding the installation and configuration of Vaa3D, please see the instructions [here].

In most cases, you can simple run the following commands to compile a plugin from source code. If the "DESTDIR" variable is also set in the plugin project file (.pro file), it should be deployed automatically.

qmake <plugin_project_file>
make

After compiling a new plugin, just put it into the "plugins" folder of the Vaa3D program folder. You can define any sub-folder, or sub-folder of a sub-folder, to contain the plugin dynamic-linked library file. Vaa3D will automatically find the plugin.

To learn the details in Vaa3D plugin API, check the advanced plugin API.