Updating Waterloo plots

Recall that Waterloo provides a Matlab OOP class called GXPlot, which wraps the underlying Waterloo plot type and can be retrieved using the getObject() method. For a GXPlot named p, the data can easily be updated from Matlab by passing it a new data array of values:

p.getObject().getXData().setDataBufferData(XData);
p.getObject().getYData().setDataBufferData(YData);

This will be fast enough for most purposes, although the exchange of arrays between Matlab and Java is done by copying the data rather than by reference (a limitation imposed by the Java Native Interface rather than Matlab).
If only a few data points are to be changed at any one time, an alternative approach is available of setting individual data points (referenced by their index, 0 being the first):

p.getObject().getXData().setEntry(index, value);
p.getObject().getYData().setEntry(index, value);

These methods will update the plot p, as well as all other plots that share its underlying data buffer.
All that is then needed is to update the display. This means:

1. Optionally, checking and rescaling the axes as needed
2. Calling repaint on the graph or its container

The best way will often be to make the container a listener on the relevant data object (the container houses the axes, so these will then be repainted if the scale changes). For example, for the YData:

% get a reference to the plot's graph container
container = p.getObject().getParentGraph().getGraphContainer();
% attach the graph as a listener to the ydata buffer
dataObject = p.getObject().getYData();
dataObject.addPropertyChangeListener(p.getObject().getParentGraph());

Now any change to the YData object will fire a property change event causing the display to update.

A simple example

f = GXFigure();
set(gcf, 'Units','normalized', 'Position',[0.3 0.3 0.4 0.4], 'Name','TestUpdate1');
% Create some data and plot a bar chart
Y = hist(randn(1,100), 50);
container = gxgca();
p = bar(container, -1:0.0408:1, Y, 'BarWidth',0.0408, 'Fill','LIGHTCORAL');
container.getView().setAxesBounds(-1,0,2,225);
container.getView().setBackground(kcl.waterloo.defaults.Colors.getColor('WHEAT'));
container.getView().setBackgroundPainted(true);
refresh();
% Attach the graph as a listener to the ydata buffer
p.getObject().getYData().addPropertyChangeListener(p.getObject().getParentGraph());
% Now update the ydata in a loop - pausing for 0.1s on each iteration.
% The listener attached above will cause a repaint
for k = 1 : 50
    Y = hist(randn(1,100),50);
    Y = Y + p.getObject().getYData().getRawDataValues().';
    p.getObject().getYData().setDataBufferData(Y);
    pause(0.1);
end

Note that the repaints will be done on the Event Dispatch Thread (EDT). The call to the Matlab pause above causes EDT to be flushed so a full repaint is done for each iteration of the loop. Using a timer, as in the example below, can avoid this and allows the Swing repaint mechanisms to collapse multiple repaint calls into a single rendering operation. This will almost always be faster: use drawnow and pause sparingly with Waterloo code.

Improving speed

Refreshing the display as above requires that

1. the graph container is repainted together with the axes – using internal axes that are rendered as part of step [2] will speed this up
2. the graph is repainted including grids and internal axes – speed this up by turning off, or reducing the number of, grid lines. Switch off background painting – the container’s background will suffice (this is the default).
3. the plot displays are updated – to speed this up:
   • Use objects that are easily translated into a square pixel-grid on screen. e.g. use squares instead of circles in a scatter plot
   • Use solid lines, not dashed or dotted ones
   • Turn off anti-aliasing of the plot

As painting is done on the EDT it will not block the Matlab thread. The time taken to update a plot will be variable, but it typically takes 5-20 msecs.

Fast plot updates

In the beta release, new methods have been added to the plots: plotRedraw() and plotUpdate() both redraw a plot without refreshing the background, grids or axes.
In the default implementation, plotUpdate simply calls plotRedraw: there actions are identical. plotUpdate is intended to be overridden in custom user subclasses to paint only points that have been added to end of a plot since the last update and the logic to do that needs to be added to the plot methods in those subclasses.
This logic can also be synthesized on-the-fly (e.g. in Matlab, as in the example below) by adding NaNs in the data objects – Waterloo ignores these values. In the example below, a timer is used to update the plot.

function update2(thisDelay)
    if nargin == 0
        DELAY = 0.01;
    else
        DELAY = thisDelay;
    end
    % Set up and create some data
    f = GXFigure();
    set(gcf, 'Units','normalized', 'Position',[0.3 0.3 0.4 0.4], 'Name','TestAnimation');
    x = linspace(-pi*4, pi*4, 50);
    y = cos(x);
    % Now  the plot
    gr1 = subplot(f, 1,1, 1);
    p1 = line(gxgca, [], [], 'LineSpec', '-og');
    gr1.getObject().getView().setAxesBounds(-pi*4,-2.5,pi*8,5);
    % We'll draw 2 points only in each timer call below (2 points needed for interconnecting line)
    % This plot will therefore show only these points when the normal paint mechanism is
    % used unless all the data are added at the end: which the timer callback below does
    p1.getObject().setXData(x(1:2));
    p1.getObject().setYData(y(1:2)*2);
    p1.getObject().getParentGraph().setLeftAxisPainted(false);
    p1.getObject().getParentGraph().setRightAxisPainted(false);
    p1.getObject().getParentGraph().setTopAxisPainted(false);
    p1.getObject().getParentGraph().setBottomAxisPainted(false);
    p1.getObject().getParentGraph().setInnerAxisPainted(true);
    p1.getObject().getParentGraph().setInnerAxisLabelled(true);
    p1.getObject().getParentGraph().getGraphContainer().repaint();
    drawnow();
    t = timer('ExecutionMode','fixedSpacing', 'Period',DELAY, 'TimerFcn', {@localTimer, p1.getObject(), x, y});
    start(t);
    function localTimer(t, EventData, p1, x, y)
        k = get(t,'TasksExecuted');
        if k > numel(x)
            % Finished
            stop(t);
            p1.setXData(x);
            p1.setYData(y*2);
            p1.plotRedraw();
        elseif k > 1
            % Add 2 new data points to the plot
            p1.setXData(x(k-1:k));
            p1.setYData(y(k-1:k)*2);
            p1.plotRedraw();
        end
    end  % localTimer
end  % update2

Calls to plotRedraw and plotUpdate are extremely fast, typically 1-2 msecs. Each call to plotRedraw() adds two new data points to the existing plot. The result is the animated plot shown at the very top of this article.
Notes:

• this example used the same timer callback to update both data and display; it will often be best to do this is separate callbacks – the refresh rates for data update and display animation can then be set independently.
• readers who need plot animation may find interest in the related Matlab functions comet and comet3, or this week’s POTW multicomet.
• plot animation in standard Matlab typically relies on the EraseMode property. In the upcoming HG2, this mechanism will no longer work, at least as seen in the HG2 prequel that is available today. So if your code uses any plot animation, you should expect it to break when HG2 is released (2014?), and you will need to convert your code to use HG2’s new animation functionality. Waterloo graphs and animation, being independent Java-based, are not expected to be affected, and will run the same way in both HG1 and HG2.

Deploying graphics to the web

Waterloo enables export of static graphics to a variety of vector and bit-mapped formats (PNG, PDF, SVG etc.) that can be included in web pages. In the beta version, deployment to web is also supported directly, with automatic generation of the graphics files together with accompanying HTML files and optional CSS styling sheets and supporting Javascript. These are available from the Graph Editor, which is activated by double-clicking a graph and selecting the world () button.
Two formats are presently supported:

• Scalable Vector Graphics (SVG). By default, the generated files provide conversion of the SVG to HTML5 canvas commands when loaded into a browser via the canvg.js JavaScript by Gabe Lerner. Use of canvg provides better cross-browser consistency in the rendering of the graphics, particularly for text. Note that only static graphics are presently supported with SVG.
• Through the Processing script language for visual arts and processing.js JavaScript.

Processing script output supports animations using a new class developed for Waterloo (PDEGraphics2D), which also supports an AWT/Swing container. The generated script files can be loaded and customized using the Process.app file available at the web site above.
In addition, experimental (and presently quirky) support for generating animated GIFs is included. The animations for this blog were generated using this. Animated GIFs are to be preferred when vector graphics are not required because GIFs

• are universally and consistently supported in browsers
• are smaller and less computationally intensive. They therefore consume less power and are environmentally friendlier. Visitors to a website, especially those using battery-powered devices, are likely to stay longer on the site.

For the present, only static graphics are supported through the GUIs, so animations need to be created programmatically. A “record” button will be added to the GUIs in future Waterloo releases.
Users can edit the default settings for deployment using the preferences editor, now available from the Graph Editor using the key () button. For SVG, the options are shown below: allowing a choice of whether SVG is to be embedded in the generated HTML file; whether canvg.js should be used and selection of a styling sheet. Customize the file addresses relative to the target folder for the HTML file or use a URL. The “httpd.py” file here is a Python 2.7 script that will set up a local server and display the HTML file in your system browser – it is needed only if the security rules for your browser prevent the files being loaded directly from the local file system.

The post Waterloo graphics animation and web deployment appeared first on Undocumented Matlab.

1. Introducing new plot types: contours, bars, polar and area charts
2. Mouse-selectable regions of interest
3. Support for fast-plot updates without redrawing the entire graph
4. Support for web-deployment of the graphs using SVG or Processing and ProcessingJS

Today I will concentrate on [1] and [2], illustrated with some Matlab examples; I will discuss [3] and [4] next week.

Installation of Waterloo in Matlab

For those readers who have not yet installed Waterloo in Matlab, the process is very simple: download the latest zip file and extract it. All the sub-folders in the waterloo folder are needed but only the Waterloo_MATLAB_Library subfolder (not its subfolders) should be added to the Matlab path. Once installed, just type waterloo at the Matlab prompt in each Matlab session.
A Matlab script file that will do it all is available here (Waterloo_installer.m). The script is harmless to run if you already have Waterloo installed, but if not then it will automatically find the latest zip file on SourceForge, download and install it, and then configure the Matlab path appropriately.

Contour plots

I ended my last guest article with an example of work-in-progress: filled contours. The beta release now fully supports these.
Recall from the previous articles that GXFigure creates a Waterloo-compatible Matlab figure window. gxgca() returns a reference to the container for the graph as a Matlab GXGraph object, much as Matlab’s built-in gca returns an axes reference.
Here is Matlab’s Lincoln penny demo in Waterloo:

% Get some pre-defined colors
colors = [kcl.waterloo.defaults.Colors.getColor(0)];
for k = 1 : 17
    colors = horzcat(colors,kcl.waterloo.defaults.Colors.getColor(k));
end
f = GXFigure();
set(gcf, 'Name','Filled Contour', 'Units','normalized', 'Position',[0.3 0.3 0.4 0.4])
load penny;
ax = subplot(f,1,1,1);
ax.getObject().setAspectRatio(1);
p2 = contourf(ax, flipud(P), 18, 'LineStyle','-', 'LineWidth',0.4);
p2.getObject().setFillClipping(false);
p2.getObject().setFill(colors);
drawnow();

(resulting in the contour plot above)
To transform Abe Lincoln to a logarithmic world, just double-click the graph and select the log transform. The result is shown on the right here:

• the data model incorporates an extra object to do the work
• such plots implement a new interface – GJTransformUpdateInterface – that specifies a transformUpdate() method that refreshes the pixel-coordinates. End-users will not normally need to concern themselves with this, as transformUpdate method will be called by the listeners as required.

Categorical data

Waterloo always uses numeric data to position markers, bars etc in a plot. However, categorical data can be used to supplement those data. Here is an example using the new bar plot:

f = GXFigure();
set(gcf, 'Name','TestBar4', 'Units','normalized', 'Position',[0.1 0.1 0.8 0.8]);
m = {'Jan', 'Feb', 'March', 'April', 'May', 'June', 'July', 'Aug', 'Sept', 'Oct', 'Nov', 'Dec'};
gr1 = subplot(f, 2, 2, 1);
a = bar(gr1, 1:12, 1:12);
for k = 1 : 12
   a.getObject().getDataModel().getXData().setCategory(k, m{k});
end
gr1.getObject().setTitleText('Label using the XData categories');
gr1.getObject().getView().autoScale();

Support for categorical labels on the axes is supported for all plots via the common data model. For bar charts, the extra object associated with the plot also supports adding labels to the bars themselves:

f = GXFigure();
set(gcf, 'Name','Categorized Bars', 'Units','normalized', 'Position',[0.3 0.3 0.4 0.4]);
m = {'Jan', 'Feb', 'March', 'April', 'May', 'June', 'July', 'Aug', 'Sept', 'Oct', 'Nov', 'Dec'};
gr = subplot(f, 1, 1, 1);
c = barh(gr, 1:10, 1:10,'stacked');
c.getObject().setFill([java.awt.Color.yellow, java.awt.Color.blue]);
c.getObject().getDataModel().getExtraObject().setFontForeground([java.awt.Color.BLACK, java.awt.Color.WHITE]);
for k = 1 : 12
   c.getObject().getDataModel().getExtraObject().getLabels().add(k-1, m{k});
end
gr.getObject().getView().autoScale();

Note that the standard method setFill, is used to set the bar colors and as two colors are supplied the data are assumed to contain a pair of multiplexed series. This is common to all plots.
To customize the labels, we need to set a property in the extra object which is retrieved with a call to c.getObject().getDataModel().getExtraObject().
The same principles apply to pie charts:

f = GXFigure();
set(gcf, 'Name','TestPie1', 'Units','normalized', 'Position',[0.1 0.1 0.8 0.8]);
colors = [kcl.waterloo.defaults.Colors.getColor(0)];
y = ones(1,18)*100/18;
gr = subplot(f, 1, 1, 1);
colors = [kcl.waterloo.defaults.Colors.getColor(1),...
    kcl.waterloo.defaults.Colors.getColor(17),...
    kcl.waterloo.defaults.Colors.getColor(2),...
    kcl.waterloo.defaults.Colors.getColor(16),...
    kcl.waterloo.defaults.Colors.getColor(3),...
    kcl.waterloo.defaults.Colors.getColor(15),...
    kcl.waterloo.defaults.Colors.getColor(4),...
    kcl.waterloo.defaults.Colors.getColor(14)];
c = pie(gr, [10 20 45 42 22 26 42 20], logical([0 0 1]), 'FaceColor',colors);

Polar charts

Polar bar and compass charts are also now supported:

f = GXFigure();
set(gcf, 'Name','TestPie1', 'Units','normalized', 'Position',[0.1 0.1 0.8 0.8]);
load sunspot.dat  % Contains a 2-column vector named sunspot
colors = [kcl.waterloo.defaults.Colors.getColor(0)];
for k = 1 : 17
    colors = horzcat(colors,kcl.waterloo.defaults.Colors.getColor(k));
end
gr1 = subplot(f, 1,2, 1);
a = polarbar(gr1, sunspot(1:48,2), 'FaceColor',colors, 'EdgeWidth',0.5);
[a,b] = hist(sunspot(:,2),12);
gr2 = subplot(f, 1,2, 2);
b = polarbar(gr2, a, 'FaceColor',colors);
Z = eig(randn(20,20));
a = compass(gr1, real(Z), imag(Z), 'LineColor','r');

Area plots

Area plots are supported through a new plot class and also by having all plots implement a new Java interface. To illustrate, create two line plots:

f = GXFigure();
set(gcf, 'Name','TestAreaFill', 'Units','normalized', 'Position',[0.4 0.1 0.5 0.4]);
x = 0.5 : 0.5 : 10;
y = sin(x);
gr1 = gxgca();
a1 = line(gr1, x, y, 'LineSpec','-ob');
b1 = line(gr1, x, y*2, 'LineSpec','-sg');
gr1.getObject().getView().autoScale();
% Filling the area between the two plots requires one extra line and a refresh call to paint the result:
a1.getObject().setAreaFill(b1.getObject());
refresh();

All the work is done in the Java code because plots now implement the GJFillable interface. All that is required is to call the setAreaFill() method on a class implementing GJFillable, specifying another GJFillable as input.
A new java class, GJFill, also implements GJFillable and can be used to fill an area relative to a scalar constant or an arbitrary shape. I have also written a Matlab wrapper class for this (GXFill, see below) but I shall use a Java-based example here.
Whether the fill is made horizontally (from the plot) or vertically (from the axes) can be selected by setting the orientation property of the GJFill instance. This can also be set to arbitrary, in which case we can create a custom fillable area sythesized from java.geom shapes:

f = GXFigure();
set(gcf, 'Name','Constant Fill', 'Units','normalized', 'Position',[0.3 0.3 0.4 0.4]);
x = 0.5 : 0.5 : 10;
y = sin(x);
gr1 = subplot(f, 1, 1, 1);
a1 = line(gxgca, x+1, y+3, 'LineSpec','-sg');
% Now create a GJFill instance, using a constant as the reference (1.5 in this case), and use this as this area's fill
v = kcl.waterloo.graphics.plots2D.GJFill(a1.getObject(), 1.5);
a1.getObject().setAreaFill(v);
%% Start complex
   % Alternately, we can use an arbitrary fill shape:
   v.setOrientation(javaMethod('valueOf', 'kcl.waterloo.graphics.plots2D.GJFill$ORIENTATION', 'ARBITRARY'));
   a1.getObject().setAreaFill(v);
   % Create a shape (which can be complex)
   area = java.awt.geom.Area(javaObject('java.awt.geom.Rectangle2D$Double',1,1,5,5));
   area.add(java.awt.geom.Area(javaObject('java.awt.geom.Rectangle2D$Double',8,1,2,5)));
   % Add the shape to the GJFill instance
   v.setArbitraryArea(java.awt.geom.Area(area));
%% End complex
% Customize the fill color
v.setAreaPaint(java.awt.Color(0,1,0,0.5));
% Manually rescale and refresh the plot
gr1.getObject().getView().setAxesBounds(0,0,12,5);
refresh();

To make this simpler from Matlab, a new Matlab class GXFill is provided. This constructs and adds a fill in a single step:

fill = GXFill(plot_reference, value, orientation);

where value is a scalar or a Java Shape object, and orientation is a string e.g. ‘horizontal’. Note that the coordinates are specified in axes units and they will rescale and be transformed as needed when the axes are changed.

Specifying/selecting ROIs

Finally, regions of interest (ROIs) can be selected both programmatically and with the mouse. One of these can be set as the “current” ROI and that is the one that is mouse selectable: set the current ROI using shift-left mouse drag, set the region and rescale to display only that region using shift-right mouse drag.
To create an ROI that can be dragged and resized, add a GJRoi instance to the graph, e.g. with an existing current ROI selected:

gr = gxgca;
gr = gr.getObject().getView();
gr.add(kcl.waterloo.graphics.GJRoi.createInstance(gr, gr.getCurrentROI()));

Waterloo and Matlab’s Java support

Note: It appears that HG2, like HG1, creates an offscreen bitmap that is then blitted onto a Java Canvas within a Matlab figure. Matlab warns that the JavaFrame property will (no longer may) be discontinued in some future release, but it is my guess that this will not be the case when HG2 is released. A new set of uicontrols may indeed be included using a C-based library like wxWidgets or Qt. However, it seems unlikely that Java support will be dropped completely – too much of Matlab’s GUI uses Java (for example, the new desktop introduced in R2012b is entirely Java-based). So the Waterloo Matlab library should work, even if a switch is needed to using JFrames instead of Matlab figures for output.
For the adventurous, Waterloo graphs can also be deployed using JavaFX via the SwingNode class – but that requires installation of the latest Java 8 (currently in early release status). Noting that Matlab is still (as of R2013a) using Java 6, this may indeed be a big jump (note last week’s article on upgrading Matlab to use Java 7).
Naturally, Waterloo’s graphs and classes can also be used in stand-alone Java applications, entirely outside Matlab, even on a $30 ARM6 Raspberry Pi.
Next week, I will look at methods for animating plots (e.g. using Matlab timers) and deploying vector graphics to web pages using the in-built GUIs.

The post Waterloo graphics beta appeared first on Undocumented Matlab.

• A Java API for the core code provides a simple and consistent mechanism for creating plots using the same data model for each of them, from line and scatter through quiver and contour plots.
• A Groovy API that can be used to call the Java API via some static methods that use Groovy’s dynamic typing mechanisms and so allows the same code to be called with different classes on input from different environments – a cell array from MATLAB for example.
• A Matlab API that mimics the standard MATLAB graphics routines and variously calls the Java-API and Groovy API as required.

I will concentrate here on the Matlab API, which is likely to be of more interest to the majority of readers. This uses Matlab OOP wrappers for the underlying Java objects and all provide access to them by using the getObject() method on the wrappers, so Matlab and Java code can be easily mixed.

Simple Waterloo plots

To create a Matlab figure that can accept Waterloo graphics call GXFigure instead of figure e.g.

f = GXFigure(10);

creates figure 10 and enables it for Waterloo.
In Matlab, you might use gca to create a figure and a set of axes – for Waterloo use gxgca instead. The graph reference also needs to be provided as input to force Matlab to use the Waterloo plotting methods. So

 scatter(1:10,1:10,'^r')

in Matlab becomes:

scatter(gxgca, 1:10,1:10,'^r')

Here are the outputs:

Combining Waterloo plots

Waterloo plots can be added together. To draw a line through a set of scatter points, a line plot is added to it. Similarly, an error bar plot can be added to that. The Waterloo Matlab-API has an errorbar function that does that. As the plots are additive the process can be continued to create a series of such compound plots:

f = GXFigure();
ax = subplot(f,1,1,1);
set(gcf, 'Units', 'normalized', 'Position', [0.1 0.1 0.8 0.8], 'Name', 'TestError');
x = 0.5 : 0.5 : 10;
y = log(x);
a1 = errorbar(ax, x, y, y/3.5, 'LineSpec', '-ob');
errorbar(a1, [], y*2, y/3.5*2,'LineSpec', '-sg');
errorbar(a1, [], y*5, y/3.5*5, 'LineSpec', '-dr');
Y = errorbar(a1, [], y*10, y/3.5*10, 'LineSpec', '-^m');
ax.getObject().getView().autoScale();

Here I have created a GXFigure, used its subplot method to create a graph, plotted the first errorbar series to it and parented the remaining plots from the first. As they share their x-data, that is specified as empty for the last three plots.

ax.getObject().getView().autoScale();

• ax is the Matlab OOP wrapper created by subplot – it’s a GXGraph.
• ax.getObject() returns the Java Swing container which has a “view” (which is the graph)
• ax.getObject().getView() returns the graph

ax.getObject().getView().autoScale() just causes the graph to be auto-scaled to fit in all the graphics. The axes can be moved, expanded and shrunk using the mouse and double-clicking displays a GUI editor as shown last week. Clicking on a plot causes the plot to become the current Waterloo graphic object, which can then be accessed with gxgco instead of gco (just as gxgca was used in place of gca).

Combining Matlab and Waterloo sub-plots

I have shown only single-axes plots till now. The subplot function can, as in Matlab, create multiple axes and these can be used to mix Waterloo and Matlab graphics in a single figure as here (upper-left and lower-right are Matlab):

Some additional examples

Here then are a few more plot examples:

f = GXFigure();
set(f.Parent, 'Units', 'normalized', 'Position', [.2 .2 .6 .6], 'Name', 'TestQuiver');
[X,Y] = meshgrid(-2:.2:2);
Z = X.*exp(-X.^2 - Y.^2);
[DX,DY] = gradient(Z,.2,.2);
ax = subplot(gxgcf,1,1,1);
q1 = quiver(ax,X,Y,DX,DY, 0.9);

f = GXFigure();
set(gcf, 'Units', 'normalized', 'Position', [0.1 0.1 0.8 0.8], 'Name', 'TestStairs');
x = linspace(-2*pi,2*pi,40);
y = sin(x);
ax = subplot(f, 1, 2, 1);
a1 = stairs(gxgca, x, y, 'LineColor', 'r');
b1 = stairs(gxgca, x, y*2,'LineColor', 'g');
c1 = stairs(gxgca, x, y*5,'LineColor', 'm');
d1 = stairs(gxgca, x, y*10,'LineColor', 'b');

load penny;
f = GXFigure();
ax = subplot(f,1,1,1);
ax.getObject().setAspectRatio(1);  % This sets the aspect ratio of the view in the container
p2 = contour(ax, flipud(P), 30);

Future work

Waterloo is far from finished and more plot types are being added. Here is a taster of a filled contour plot which will be available in the next update (see the development version GIT repository):

f = GXFigure();
set(gcf, 'Name', 'TestContour', 'Units', 'normalized', 'Position', [0.2 0.2 0.7 0.5])
ax = subplot(f,1,1,1);
ax.getObject().setAspectRatio(1);
p1 = contourf(ax, peaks(100), 20);
p1.getObject().setAlpha(0.3);

The post Waterloo graphics examples appeared first on Undocumented Matlab.

The Waterloo graphics project

One of Matlab’s limitations is the quality of its 2D graphics. Plots are more pixellated and less interactive than some might expect in a modern programming environment.
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:

Main features

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: -Dsun.java2d.noddraw=false
• 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 [1] a Matlab .fig file, [2] a Waterloo XML file, and [3] 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:

The post Waterloo graphics appeared first on Undocumented Matlab.