*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:

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.
- 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:

Next week, I will give more Matlab code examples.

Related posts:

- Waterloo graphics examples Some Matlab usage examples for the open-source Waterloo graphics package. ...
- Waterloo graphics beta The Waterloo graphics library extends Matlab graphics with numerous customizable plots that can be embedded in Matlab figures. ...
- Waterloo graphics animation and web deployment Waterloo graphics can be updated very quickly in Matlab, enabling plot animation; web deployment of the graphics is also possible. ...
- Handle Graphics Behavior HG behaviors are an important aspect of Matlab graphics that enable custom control of handle functionality. ...
- Matlab and the Event Dispatch Thread (EDT) The Java Swing Event Dispatch Thread (EDT) is very important for Matlab GUI timings. This article explains the potential pitfalls and their avoidance using undocumented Matlab functionality....
- Inactive Control Tooltips & Event Chaining Inactive Matlab uicontrols cannot normally display their tooltips. This article shows how to do this with a combination of undocumented Matlab and Java hacks....

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.

@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.

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

@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.

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();

@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

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?

@Xin

See the answer above to @William.

ML

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’);

Ruben

What does

`which GTool`

at the command line return?

I got the same error. I tried “which GTool”. It says “not found”.

Actually I figured out the problem. I had to set path with option of adding all subfolders.

@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.

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.

@Yoshi

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

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:

That is the same behavior I see for normal plotting:

Has anyone else been able to use java 1.7 with matlab?

I’ve been able to use JRE 1.7 with Matlab 2012b (win7 64-bit). Waterloo appears to work fine.

@qt

See the examples here

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.

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

Take a look at this LINK .

Lots of Java/Groovy examples/tutorials and more to come.

Malcolm

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.

@Valeri

Take at a look at the

`kcl.waterloo.demo`

package inkcl-waterloo-base.jar.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.

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.

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.

@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.

This looks neat! However, i have a problem if i compile the example code, Malcolm gave from up there. Error message reads:

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

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

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

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

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

(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

@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.

@Dan

Also, which version of Java does MATLAB use? Type ver at the matlab prompt. You should see something like:

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.

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).

Pingback: Waterloo graphics beta | Undocumented Matlab

Pingback: Waterloo graphics examples | Undocumented Matlab

Pingback: Plotly graphs | Undocumented Matlab