We believe watching some examples is the better way to understand how to program plugins for Icy !
So for each topic we provide a brief description and basic tutorials.
Before getting further you need to set up your Icy development environment by following this step-by-step tutorial.
All examples described here are available in the Plugin Tutorials GitHub project and you can also download and test them in Icy by using the tutorial keyword in the plugin browser or search bar.
Topics
Plugin
Image structure
Region of Interest
Overlay
GUI
Image representation
Event
Chart / Graphic
Miscellaneous
Javadoc (package representation)
Plugin is the way for developer to provide new features in the application.
For that you have to extend the base Plugin class so your program could be installed and used in Icy.
PluginActionable is the base class for plugin which should be visible in the GUI interface so we can launch them from a button.
Don't forget to check available interface for Plugin as PluginDaemon,
PluginSearchProvider or PluginROI to enable specific behavior on your plugin.
Documented source code examples
Hello World Plugin
Getting the list of registered plugin
Others interesting classes to see
PluginLoader is used to detect and load all plugin classes in Icy, you can use it to request information about installed plugins.
PluginLauncher is used to launch plugin.
PluginInstaller is used to install / update / remove plugin.
The basic image classes of Icy are the Sequence and the and IcyBufferedImage.
The Sequence class allows the definition of an image over the 5 [XYCZT] dimensions.
It contains a list of and IcyBufferedImage and maintain a [Z,T] position for each of them.
The IcyBufferedImage object overrides the AWT BufferedImage object so it remains compatible with the available API as image transformation and processing.
Still only JAI actually seems to support our image format, AWT API seems limited to most common image formats only. So basically IcyBufferedImage offers the same features
as BufferedImage with expanded image format support and also adding many methods for easier image data access and manipulation.
Data are organized in channel (one data array per channel) so for a classical ARGB image we have 4 channels --> 4 arrays (byte data here).
We retained this organization because almost time the image processing algorithm work on a channel basis.
IcyBufferedImage internally uses IcyColorModel class, this structure is responsible of the image data storage and can be of any type:
- unsigned byte 8 bits [0 .. 255]
- signed byte 8 bits [-128 .. 127]
- unsigned short 16 bits [0 .. 65535]
- signed short 16 bits [-32768 .. 32767]
- unsigned int 32 bits [0 .. 4294967295]
- signed int 32 bits [-2147483648 .. 2147483647]
- float 32 bits [0 .. 1] (default but can be anything else)
- double 64 bits [0 .. 1] (default but can be anything else)
We also defined our own IcyColorSpace class (inherit from ColorSpace) which allow a versatile color representation of the image data by using ARGB ColorMap and value bounding (sort of threshold) per channel.
Documented source code examples
How to Generate images of all type available
How to do a very basic intensity operation on an image whatever is the data type of the image
Another example of generic image processing whatever is the image format
Others interesting classes to see
SequenceUtil Sequence utilities class.
IcyBufferedUtil IcyBufferedImage utilities class.
Region of interest define region which can be used as input or output for any processing.
ROI Base roi class from which every ROI derive.
ROI2D / ROI3D / ROI4D / ROI5D Base class for 2D / 3D / 4D / 5D roi.
ROI2DShape Base class for all shape style 2D roi (ROI2DRectangle, ROI2DEllipse, ROI2DPolygon...)
ROI2DArea Area style 2D roi class.
Documented source code examples
Processing data from roi: fast build of the mask
Creating an area roi from code
Creating an overlay displaying intensity chart of the pixel over roi
Others interesting classes to see
BooleanMask2D 2D boolean mask class, used internally by ROI for boolean operations and others calculations.
RoiUtil Roi utilities class which is used to compute some basic operations.
The overlays are used to interact and draw rich information on image, the base Overlay class replaces the deprecated AbstractPainter class and Painter interface.
Documented source code examples
How to create a simple overlay over an image (sequence)
How to create a more advanced overlay to react on mouse events
Fancy animated overlays creation
Create overlays for VTK (3D display)
Others interesting classes to see
Anchor2D Example of overlay which can be used to move objects over the sequence.
VtkPainter Interface for easier handling of overlay in a VTK Canvas (3D rendering).
Icy uses the Swing API for the UI with a specific third library look and feel: Substance.
This look and feel provides a consistent and nice GUI so Icy looks exactly the same whatever is the underlying Operating System.
Icy provides some tools to help in designing Swing GUI which may be paintful when you do it yourself by hands.
One of the most important one is the EzPlug plugin which automatically generate the GUI depending your inputs.
You can see it in action in the EzPlug Tutorial plugin.
Documented source code examples
Simple action frame example.
How to use a template to have a simple plugin with an action button
Others interesting classes to see
Viewer Frame used to display an image in Icy.
IcyFrame Base frame class in Icy, provide some facilities as the "externalization" feature.
ActionFrame / ActionDialog Simple action frame / dialog (with ok / cancel button couple).
AnnounceFrame Display an annoucement message in the bottom right of the application.
ToolTipFrame Display a tooltip in the bottom right of the application.
ConfirmDialog / IdConfirmDialog Simple confirmation dialog.
ImageLoaderDialog Dialog used to choose the image to open.
ImageSaverDialog Dialog used to select where save an image.
GuiUtil Tools to generate customized label, textarea or panel easily, no used that much now.
LookAndFeelUtil Tools related to the look and feel (Icy uses the Substance LAF library).
ComponentUtil Tools and helpers for Swing components (size, position, decoration...).
WindowPositionSaver Helper for window position / state saving.
Interesting packages to browse
icy.gui.frame Package containing custom Icy frames.
icy.gui.frame.progress Package containing custom Icy progress frames (frame display in bottom right corner).
icy.gui.dialog Package containing custom Icy dialog.
icy.gui.component Package containing custom Icy components.
icy.gui.util Package containing tools for GUI.
To display an image Icy use the IcyCanvas class which actually take an image as input and render it to the screen.
By default we have 2 available canvas:
Canvas2D Classic 2D image display.
Canvas3D Real time 3D rendering for stack image (using the VTK library).
We can directly provide new canvas from plugin by implementing the PluginCanvas interface so they will appears in the canvas selection of the viewer.
A canvas class should extends IcyCanvas / IcyCanvas2D / IcyCanvas3D...
depending the final representation adopted but it may eventually directly extends Canvas2D and modify a bit of its behavior if that match the requirements.
Example plugins (sources code provided in jar file)
Montage2D
Chart1DCanvas
Java as many Object Oriented language relies a lot on events and same goes for Icy which use them internally.
You may be interested in launching an action on a specific event (as "image opened" event).
Documented source code examples
How to listen major events in Icy
How to listen focused image / window events in Icy
You may want to present your statistical results from your analysis in graphical format, for that Icy use the very nice and comprehensive JFreeChart library to do it.
Documented source code examples
Create a simple graph with JFreeChart in Icy
Create a deviation graph with JFreeChart in Icy
Here are others topics which may have some interests for plugin development, be sure to check in them before reinventing the wheel !
Interesting packages to browse
icy.math Mathematical related stuff (many tools and helper classes).
icy.network Network stuff and utilities.
icy.ImageJ ImageJ wrapper utilities.
icy.type Basic type declaration and utilities.
icy.type.collection.array Array type declaration and utilities.
icy.util General and misc utility classes.
Interesting classes to know about
ArrayUtil / Array1DUtil / Array2DUtil... Array conversion, allocation... utilities.
SearchEngine global search engine in Icy (access it through the main interface : Icy.getMainInterface().getSearchEngine())
Clipboard system and local clipboard.
XMLPreferences base class to store preferences in Icy.
It uses a similar syntax than standard java Preferences object but store them in XML format instead.
XMLUtil General XML utilities to build or read XML files.
XLSUtil General XLS utilities to build or read excel documents.