Waterloo graphics

November 28, 2012 39 Comments

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

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:

Figure 1: Some Waterloo graphs showing a selection of some of the plots available. The list of available plots will grow in time. Click for details

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.

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.

Figure 2: A multi-layered graph. Each plot has its own graph layer with independent axes.

Built-in mouse interactivity and GUIs for interactive plot editing.

Figure 3: A plot editor for a single-layered graph. Java programmers might note here the use of a few custom-designed Swing widgets: a dial that subclasses JSlider and supports multiple-turns, and a color chooser that uses standard names for web colors. Click for details — Figure 3: A plot editor for a single-layered graph. Java programmers might note here the use of a few custom-designed Swing widgets: a dial that subclasses `JSlider` and supports multiple-turns, and a color chooser that uses standard names for web colors. Click for details

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:

Figure 5: Mixed Matlab and Waterloo graphics in a single Matlab figure. Click for details

Next week, I will give more Matlab code examples.

39 Responses

Slayton November 29, 2012 at 06:50 Reply

I’ve been wondering for years why someone had not already written a nice replacement for the Matlab plotting libraries. I’m excited to try out Waterloo although I’m a bit disappointed by the state of the website. Hopefully they’ve put more effort into the actual library than they did for their website.

Malcolm Lidierth November 29, 2012 at 10:12 Reply

@Slayton
Library – close to 2 years
Website – about 4 days, but I am hoping any problems you had were temporary blip – I was seeing missing pages etc today too but the web pages are there. It may be related to a SourceForge hardware upgrade that started yesterday.

Dani December 2, 2012 at 13:16 Reply

Downloaded it, works like a charm. Could not figure out how to zoom though.

Malcolm Lidierth December 2, 2012 at 16:19 Reply

@Dani
You can
1. Press and move the mouse on the GRAPH to shift the graph axes left/right/up/down
2. Press and move the mouse on an AXIS to “zoom” (shrink or expand) it (towards zero drags the limits inwards/away drags them outwards)
3. Double-click a graph to bring up the editor GUI and set the axis limits in that.
4. Also in the editor, set the rotation and zoom – but “zoom” here shrinks/expands the area of the graph in its container which may not be what you mean. Its useful when a rotated graph has its corners outside of the clip limits of the container.

If any of that does not work please let me know about platform/Java/MATLAB version etc.

If there are features you think should be included, also please shout.

William Stevenson December 3, 2012 at 09:00 Reply

I get the following error:
Looking for sigTOOL support…??? Undefined variable “kcl” or class
“kcl.waterloo.graphics.gui.Welcome.createWelcome”.

Error in ==> waterloo at 235
welcomeFrame=kcl.waterloo.graphics.gui.Welcome.createWelcome();

Malcolm Lidierth December 3, 2012 at 12:26 Reply

@William
My guess is that you have installed only the Waterloo_MATLAB_Library folder. That needs to be added to the MATLAB path (without subfolders) but needs to be located in the waterloo folder with all its sibling folders, That is where all the Java code is to be found including e.g. kcl.waterloo.graphics.gui.Welcome.createWelcome.
Waterloo uses relative paths to find everything it needs – whether you are in MATLAB, R, Groovy or any of the other supported environments.
See here

Xin Jin December 7, 2012 at 06:55 Reply

Hi there,
I am trying to use Waterloo graphics on Win7.
Here is the error message when I tried to test the scatterplot case described in your email.
Something still missing?

Undefined variable "kcl" or class "kcl.waterloo.graphics.GJGraph.createInstance".

Error in GXGraph (line 36)
                graphicObject=kcl.waterloo.graphics.GJGraph.createInstance();

Error in GXFigure/subplot (line 112)
                varargout{1}=GXGraph(p);

Malcolm Lidierth December 7, 2012 at 18:08 Reply

@Xin
See the answer above to @William.
ML

Ruben December 13, 2012 at 18:58 Reply

I have installed the Waterloo folder. I ran the “waterloo.m” file and this was OK.
Next I tried to run the “waterloodemo.m” file and I got the following error:
The class “GTool” is undefined.
Perhaps Java is not running.

Error in waterloodemo (line 23)
GTool.setTheme(‘blue’);

Malcolm Lidierth December 14, 2012 at 05:35 Reply
Ruben
What does
which GTool
which GTool
at the command line return?
Dinesh Dileep January 27, 2013 at 22:10 Reply

I got the same error. I tried “which GTool”. It says “not found”.
Dinesh Dileep January 27, 2013 at 22:13 Reply

Actually I figured out the problem. I had to set path with option of adding all subfolders.
Malcolm Lidierth January 28, 2013 at 01:34 Reply

@Dinesh
waterloo.m adds the sub-folders when you run it – and does more besides e.g. adding with subfolders will not set up the java class path.
Yoshi July 4, 2013 at 02:01 Reply

Hi, I also got the same error…
“which GTool” says
“/Applications/MATLAB74/waterloo/Waterloo_MATLAB_Library/Waterloo_Swing_Library/GTools/GTool.m”

MATLAB Version: R2007a
Java VM Version: Java 1.6.0_51 with Apple Inc. Java HotSpot(TM) Client VM mixed mode

Thank you in advance for your help.
Malcolm Lidierth July 4, 2013 at 07:39 Reply

@Yoshi
I am afraid you need R2008a or later in any case to use GTool.

qt December 19, 2012 at 04:07 Reply
Hi there..

I am trying to run matlab r2010a with java 1.7, by changing MATLAB_JAVA to a location with jre7. That works fine for everything but plots, so I was hoping waterloo would resolve my problem.

I tried installing waterloo, but still I only get “grey” windows when i try to plot something e.g:
hFig = GXFigure(); plot(1:100)
hFig = GXFigure(); plot(1:100)
That is the same behavior I see for normal plotting:
figure,plot(1:100)
figure,plot(1:100)
Has anyone else been able to use java 1.7 with matlab?

HAC December 20, 2012 at 13:40 Reply

I’ve been able to use JRE 1.7 with Matlab 2012b (win7 64-bit). Waterloo appears to work fine.
Malcolm Lidierth December 21, 2012 at 05:34 Reply

@qt
See the examples here

Alex January 11, 2013 at 03:56 Reply

Yes you’re completely right!
The native plotted graph in Matlab is very ugly.
I’ve been written my own graph api in java for 2D line graph (very simple) to use in matlab since few years.
I will try this nice projet.
Valeri January 20, 2013 at 09:00 Reply

Very impressive library! Do you have it implemented in a pure Java project (not depending on Matlab)? Could you, please, give me a link for any example in Java application.
Sincerely, Valeri

Malcolm Lidierth January 21, 2013 at 09:46 Reply

Take a look at this LINK .
Lots of Java/Groovy examples/tutorials and more to come.
Malcolm

Valeri January 21, 2013 at 10:29

Thank you, I have found only one Groovy example (Scatter) in the Code Examples section.
At least it is something to start. But I am looking forward for Java examples.
Appreciate to have them in the nearest future.

Malcolm Lidierth January 21, 2013 at 18:24 Reply

@Valeri
Take at a look at the kcl.waterloo.demo package in kcl-waterloo-base.jar.

Valeri January 22, 2013 at 13:19

Thank you. It is looking pretty encouraging. The problem is only that I am newbie in Java (always working with C,C++,Matlab) and to make the transition from the library functions to the desktop application is a big distance for me. I’ll try,but it is better to find the ready project to learn the transition. At least for the scientific graphics (from small details to big animations) Java gives more flexible environment and I have no choice.
Malcolm Lidierth January 23, 2013 at 04:52

I know the problem having moved to Java from MATLAB/Fortran some years back. Are you using the MATLAB editor to write code? Eclipse, Netbeans, IntelliJ etc (all free) provide fantastic as-you-type coding tips.
Valeri January 23, 2013 at 12:50

I am using NetBeans 7.01, because it has also a gui editor. No problems with gui, it can be perfectly constructed even in C,C++, but the real bottle neck is the scientific graphics of publication quality. I am already tied to jump between Matlab, PowerPoint, CorelDraw to make axes, ticks, texts, extra pictures inside main figures in an appropriate shape. LaTeX doesn’t help. The best thing would be to have a good formatted picture already when processing data. GnuPlot has low quality. MathGL is slow in animation. Only JavaView is enough fast and has a good graphics quality (but, unfortunately only for 3D and not in the processing time). I was not able to find something appropriate in C,C++, but some examples in Java2D are encouraging. That’s why I am here.

Malcolm Lidierth January 24, 2013 at 05:33 Reply

@Valeri
Not quite sure what you a trying but you can get good SVG and PDF output from Waterloo. The dev release also now has an HTML output that uses the SVG as the base to paint to an HTML5 canvas via the canvg javascript – that gives consistent performance across browsers back to Safari 5.1 and IE7 (using flashcanvas).

You can easily add images from CorelDraw/Powerpoint to Waterloo graphs – they are Swing components.

Speed. There are many speed improvements that will be made in time e.g. there is no need to repaint the graph containers/grids on every refresh – an offscreen buffer could often be blitted in.

Johannes Korsawe February 14, 2013 at 06:36 Reply
This looks neat! However, i have a problem if i compile the example code, Malcolm gave from up there. Error message reads:
```
>> mcc -vm comptest_waterloo
Compiler version: 4.14 (R2010b)  
Depfun error: 'Error: File: Y:\waterloo\Waterloo_MATLAB_Library\Waterloo_Swing_Library\@MUtilities\MUtilities_R2006b_onwards.m Line: 1 Column: 10 
Class name and filename do not agree.' 
??? Error using ==> mcc
Error executing mcc, return status = 1 (0x1).
```
What do I have to take into account if I want to use Waterloo graphics inside some MATLAB code and deploy it as usual as a standalone application?

Best regards,
Johannes

Johannes Korsawe February 14, 2013 at 07:11 Reply

I was now able to compile by giving the two files MUtilities_R2006a.m and MUtilities_R2006b_onwards.m another suffix, e.g. .EMM . Now i have the file comptest_waterloo.exe.

But now i have another problem: I added the path to the Waterloo_MATLAB_Library to my default MATLAB path. In startup.m i added the command waterloo; s.t. the correct environment shows up at MATLAB startup. By doing so and compiling, i hoped the necessary informations to be added to the compilated executable automatically.

However, if i try to execute the executable (no matter if from DOS window or by MATLAB ! system command), i get the following error messages:

>> !comptest_waterloo.exe

Project Waterloo…Graphics Library loaded…Swing Library loaded…Utilities loaded

Project Waterloo [Version=1.1 Dated:14-Feb-2013 15:04:00]
Setting up Waterloo distribution

Project Waterloo Java files added to MATLAB Java class path

Looking for sigTOOL support…??? Undefined variable “kcl” or class
“kcl.waterloo.graphics.gui.Welcome.createWelcome”.

Error in ==> waterloo at 235

Error in ==> startup at 4

??? Undefined variable “kcl” or class
“kcl.waterloo.graphics.GJGraph.createInstance”.

Error in ==> GXGraph.GXGraph>GXGraph.GXGraph at 36

Error in ==> GXFigure.subplot at 112

Error in ==> comptest_waterloo at 8

Undefined variable “kcl” or class “kcl.waterloo.graphics.GJGraph.createInstance”.
MATLAB:undefinedVarOrClass

I assume
Johannes Korsawe February 14, 2013 at 07:13 Reply

I assume, i either have to configure my Windows system in a way it respects the waterloo JAVA libraries, or i have to link the waterloo libraries into the executable by using the deploytool (?).

Any help appreciated!

Best regards,
Johannes
Malcolm Lidierth February 16, 2013 at 11:53 Reply

Johannes

I have little MCR/deploytool experience.

[1] MUtilities_R2006b_onwards.m can be deleted – there are two legacy copies of MUtilities than work back to R2006a. They are not needed on modern MATLABs and upset deploytool.

[2] Am I right in thinking that your deployed app is calling waterloo.m?
That is not needed. waterloo.m dynamically sets up the paths for a MATLAB session from inside the desktop. If that is run before deploying the app, there should be no need to do it again from within the app (and it may well not work because paths are set relative to the waterloo.m file path).

ML

Daniel Gallichan May 30, 2013 at 02:05 Reply

I just tried to install Waterloo on OSX 10.8.3 with Matlab R2013a and I get this:

>> addpath ~/matlabdownloads/Waterloo_MATLAB_Library/
>> waterloo

Project Waterloo...Graphics Library loaded...Swing Library loaded...Utilities loaded

Project Waterloo [Version=1.1 Dated:18-Nov-2012 13:21:10]
Setting up Waterloo distribution

Project Waterloo Java files added to MATLAB Java class path

Looking for sigTOOL support...   
Undefined variable "kcl" or class "kcl.waterloo.graphics.gui.Welcome.createWelcome".

Error in waterloo (line 235)
welcomeFrame=kcl.waterloo.graphics.gui.Welcome.createWelcome();

(In case it’s also relevant, I have Java 7 Update 21 installed)

Any suggestions what I might try to get it to work?

Thanks
Dan

Malcolm Lidierth May 30, 2013 at 02:53 Reply

@Dan

You seem to have the Waterloo MATLAB Library only where you need to install the other components also.
You need a main folder named “waterloo” as the code uses relative addressing to find everything it needs.

The beta version (Git only at present) gives more helpful error messages in such cases.

The short script below will do all the work if you prefer from inside MATLAB – but I would recommend a clean MATLAB session. Cut and paste this into the MATLAB command window. Installation on Mountain Lion will normally be to ~/Documents/waterloo.

Notes:
1. Do not save the path afterwards. Waterloo.m sets ups the path automatically in each session (that speeds up MATLAB searches when Waterloo is not in use).
2. You may her the cooling fan kick in – that is likely to be anti-virus software checking all the java .jar files which are compressed.

% To use Waterloo, you need to type "waterloo" at the MATLAB prompt
% at the start of each subsequent MATLAB session
if ~isempty(which('waterloo.m'))
    fprintf('It looks like Waterloo is already present at:n%sn',strrep(which('waterloo.m'),[filesep 'Waterloo_MATLAB_Library' filesep 'waterloo.m'],''));
    disp('Delete the old waterloo folder and remove it from your MATLAB path first');
else
    installFolder=fullfile(char(java.lang.System.getProperty('user.home')), 'Documents');
    disp('Downloading zip.....this will take a few minutes');
    % N.B. Using latest here is not guaranteed to give the same result as clicking latest on the sourceforge site.
    f=unzip('http://sourceforge.net/projects/waterloo/files/Waterloo%5B1.1Alpha2%5D/Waterloo%5B1.1Alpha2%5D.zip/download', installFolder);
    disp('Setting MATLAB Path.....');
    if isdir(fullfile(installFolder,'waterloo','Waterloo_MATLAB_Library'))
        addpath(fullfile(installFolder,'waterloo','Waterloo_MATLAB_Library'));
        savepath();
        fprintf('Installed the following %d files/folders:n', numel(f));
        for k=1:numel(f)
            disp(f{k});
        end
        disp('To use Waterloo, you need to type "waterloo" at the MATLAB prompt during each MATLAB session');
        waterloo();
        disp('Note: You may be prompted to add a Waterloo Setting folder when first running Waterloo');
        disp('This allows you to set user-specified default colors etc.');
    else
        disp('Installation was not successful');
    end
end

Malcolm Lidierth May 30, 2013 at 02:59 Reply
@Dan

Also, which version of Java does MATLAB use? Type ver at the matlab prompt. You should see something like:
```
Operating System: Mac OS X  Version: 10.8.3 Build: 12D78 
Java Version: Java 1.6.0_45-b06-451-11M4406 with Apple Inc. Java HotSpot(TM) 64-Bit Server VM mixed mode
```
AFAIK, there is no way to get MATLAB to recognise Java 7 on Mac. If you have found a way, I’d like to know it too.

Malcolm Lidierth June 19, 2013 at 18:22 Reply

A beta release of Waterloo was posted a few days ago and has led to a sudden, and confusing, increase in downloads of the previous Alpha2 release. My guess is the script above may be to blame, so here is an updated version (it really should be written to find the latest version automatically but I have not found a way to do that yet, simply using the “latest” URL copied from the SourceForge download button will not work – any suggestions welcomed).

% To use Waterloo, you need to type "waterloo" at the MATLAB prompt
% at the start of each subsequent MATLAB session
if ~isempty(which('waterloo.m'))
    fprintf('It looks like Waterloo is already present at:n%sn',strrep(which('waterloo.m'),[filesep 'Waterloo_MATLAB_Library' filesep 'waterloo.m'],''));
    disp('Delete the old waterloo folder and remove it from your MATLAB path first');
else
    installFolder=fullfile(char(java.lang.System.getProperty('user.home')), 'Documents');
    disp('Downloading zip.....this will take a few minutes');
    % N.B. Using latest here does is not guaranteed to  give the same result as clicking latest on
    % the sourceforge site.
    f=unzip('http://sourceforge.net/projects/waterloo/files/Waterloo%5B1.1Beta%5D/waterloo.zip/download', installFolder);
    disp('Setting MATLAB Path.....');
    if isdir(fullfile(installFolder,'waterloo','Waterloo_MATLAB_Library'))
        addpath(fullfile(installFolder,'waterloo','Waterloo_MATLAB_Library'));
        savepath();
        fprintf('Installed the following %d files/folders:n', numel(f));
        for k=1:numel(f)
            disp(f{k});
        end
        disp('To use Waterloo, you need to type "waterloo" at the MATLAB prompt during each MATLAB session');
        waterloo();
        disp('Note: You may be prompted to add a Waterloo Setting folder when first running Waterloo');
        disp('This allows you to set user-specified default colors etc.');
    else
        disp('Installation was not successful');
    end
end

Waterloo graphics beta | Undocumented Matlab June 26, 2013 at 11:02 Reply

[…] Malcolm Lidierth of King’s College London. Malcolm has written several articles here, including a couple of articles on his Waterloo graphing library. Today, Malcolm discusses new features in this library, as it […]
Waterloo graphics examples | Undocumented Matlab July 2, 2013 at 10:01 Reply

[…] usage examplesIB-Matlab partnersMatlab-Java bookTODOPoliciesSite map ← Waterloo graphics Pinning annotations to graphs […]
Plotly graphs | Undocumented Matlab December 19, 2013 at 16:30 Reply

[…] the integration of Plotly graphs and charts in Matlab. Unlike the open-source JFreeChart and Waterloo plotting libraries that were described here in the past, Plotly is a commercial (not open-source) […]
Mike Peschel February 25, 2017 at 07:40 Reply

Hi Malcolm,
is there an equivalent to Matlab’s image() or imagesc() function in Waterloo?
Thanks!

HTML tags such as <b> or <i> are accepted.
Wrap code fragments inside <pre lang="matlab"> tags, like this:

<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>

I reserve the right to edit/delete comments (read the site policies).
Not all comments will be answered. You can always email me (altmany at gmail) for private consulting.

Click here to cancel reply.

The Waterloo graphics project

Main features

Benefits for Matlab users

Sample Matlab usage

Related posts:

39 Responses

Leave a Reply