Once again I would like to welcome guest blogger Malcolm Lidierth of King’s College London, who has already written here in the past. Today Malcolm will describe the Waterloo open-source project and its usage in Matlab.
The Waterloo graphics project
A recent addition to the open-source Waterloo graphics library addresses this by providing a pure Java library of 2D graphics functions that can easily be integrated in Matlab. An accompanying Matlab library provides support for these objects in Matlab OOP wrappers. While these do not quite provide a drop-in replacement for Matlab graphics code, in most instances they require very few code line changes to try out the library using existing Matlab code. Here is a taster of some of the plots presently supported:
Waterloo is a free, open-source project and it draws upon resources from many other open-source resources: notably the JXGraph class that is part of the SwingLabs SwingX project and was originally developed for the “Filthy Rich Clients” book by Chet Haase and Romain Guy. JXGraph formed the basis for some of the core graphics classes in Waterloo.
Highlights of the project include:
- Platform-independent, pure Java library callable from any environment that supports a Java Virtual Machine (JVM). So far, I have tested it with Groovy, Java, Matlab, the R statistical environment, Scala and SciLab.
- High-speed rendering if you activate the appropriate graphics pipeline – e.g. DirectX for Windows and Quartz for Mac.
- Anti-aliased graphics and text together with full support for transparency supported at color, plot and graph levels.
- Graphics can be annotated with lines, arrows, text etc that are Java Graphics 2D–based, but also, because the graphs are Swing-based, with other Swing components such as JLabels, JTextFields etc.
- As Waterloo graphs are also Swing components, they too can be added to other Swing components (a Matlab figure for example) as well as to other graphs, for example to create graphical insets.
- Multi-layered graphs, with each layer having independent axes.
- Built-in mouse interactivity and GUIs for interactive plot editing.
- Linear and log axes implemented via Java objects that also format the axes labeling etc.: so for a log axis you have a choice of base 10, 2 and e as well as -log10. Polar plotting is partially implemented and will be improved in later releases.
- User-selectable preference settings with a GUI to change them (and save them across sessions).
- Export to PDF and SVG files – and also to the clipboard with preservation of vector graphics quality if your platform supports it. In designing the Java Graphics 2D methods, care has been taken to optimize the grouping of graphics objects to facilitate editing in vector-graphics based packages such as Adobe Illustrator and the open-source InkScape editor. Support is included also for bitmap graphics output to both file and clipboard.
- Graphics can be saved to portable XML files. These use the standard
java.util.bean.XMLCoder, which is a built-in feature of all JVMs so the files are fully portable. Full serialization/de-serialization is supported so the full state of the graph when it was saved is restored on reloading. Writing and reading of these files has built-in support for gzip compression and decompression of the XML data stream.
- An interactive GUI-based “Graph Explorer” that can be run as a stand-alone Java executable to view the generated graphs, or be run from a console session (including from the Matlab desktop; note that until I find a fix, Unix-based platforms will need Matlab R2012a or later for this). You can share XML files with others: they can view and edit them without Matlab.
- Tested so far on Windows XP/7 (Oracle JRE 6 &anp; 7), Mac OS Snow Leopard (Apple JRE 6 & OpenJDK 7) and Ubuntu Linux 12.10 (IcedTea OpenJDK JRE 6 & 7).
Benefits for Matlab users
For Matlab-users, we can add:
- Runs “out-of-the-box”. Unzip the distribution and add the Waterloo Matlab Library folder to your path. Running waterloo.m then adds everything needed to the path and sets up the Java dynamic class path for the current Matlab session – so Waterloo is only installed when needed. However, for all JRE 6-based Matlab versions, I would recommend upgrading to the latest JRE 6 release (update 37 at the time of writing): you will get better and faster graphics performance and recent security fixes (including some relevant to the use of XML files as in Waterloo). For best performance on Windows, also edit or create a “java.opts” file to activate DirectX graphics pipeline (then restart Matlab: you cannot alter this setting for the current JVM session). Use:
- Integration of the Waterloo and Matlab graphics via Matlab OOP wrappers. You can mix-and-match Waterloo and standard Matlab graphics in a single Matlab figure.
- Mixed Matlab and Waterloo graphics are treated specially for serialization. Waterloo creates a folder instead of a single file containing  a Matlab .fig file,  a Waterloo XML file, and  a set of image files – one for each Matlab axes object. In Matlab, the folder can be re-loaded and both Matlab and Waterloo graphics will be fully de-serialized. Outside of Matlab, e.g. in the Waterloo Graph Explorer, the image files will be used to display Matlab graphs. By default, these images are saved as PNG files but you can install a custom function to generate other formats including SVG (Graph Explorer provides an SVG viewer using Apache Batik).
- The Graph Explorer embeds a copy of the Groovy Console so users can pass variables between the host workspace and the console and use it to run Groovy scripts from Matlab, R, SciLab etc.
- Tested variously on Matlab R2008a through R2012b on Mac, Windows and Ubuntu Linux. Although the Matlab OOP uses R2008+ classes, the base Java library could probably be invoked directly from earlier Matlab versions.
- Ability to attach Matlab callbacks to the underlying Java objects. That includes property change callbacks for data objects, individual plots and graphs and for their Swing containers.
Sample Matlab usage
I will finish with a simple example of mixing Matlab and Waterloo graphics:
% Create some data t = 0 : .035 : 2*pi; [x,y] = pol2cart(t, sin(2*t).*cos(2*t)); % Now do the plotting hFig = GXFigure(); % Create Waterloo-enabled Matlab figure ax1 = subplot(1, 2, 1); % Create Matlab axes ax2 = subplot(hFig, 1, 2, 2); % Create Waterloo "axes" scatter(ax1, x, y); % Matlab scatter plot scatter(ax2, x, y); % Waterloo scatter plot set(gcf, 'Units', 'normalized', 'Position', [0.1 0.1 0.8 0.8]);
Here is the output:
Next week, I will give more Matlab code examples.