Waterloo graphics

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

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.

    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).
  • Waterloo preferences

    Waterloo preferences

  • 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

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

Next week, I will give more Matlab code examples.

Categories: Guest bloggers, GUI, Java, Medium risk of breaking in future versions

Tags: , , , ,

Bookmark and SharePrint Print

39 Responses to Waterloo graphics

  1. Slayton says:

    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.

  2. Dani says:

    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.

  3. William Stevenson says:

    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

  4. Xin Jin says:

    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);
    
  5. Ruben says:

    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?

    • Dinesh Dileep says:

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

    • Dinesh Dileep says:

      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.

    • Yoshi says:

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

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

  6. qt says:

    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)

    That is the same behavior I see for normal plotting:

    figure,plot(1:100)

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

  7. Alex says:

    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.

  8. Valeri says:

    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

    • Valeri says:

      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 in kcl-waterloo-base.jar.

    • Valeri says:

      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.

    • Valeri says:

      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.

  9. Johannes Korsawe says:

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

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

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

      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

  10. Daniel Gallichan says:

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

      @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%s\n',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 says:

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

  11. Malcolm Lidierth says:

    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%s\n',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
  12. Pingback: Waterloo graphics beta | Undocumented Matlab

  13. Pingback: Waterloo graphics examples | Undocumented Matlab

  14. Pingback: Plotly graphs | Undocumented Matlab

  15. Mike Peschel says:

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

Leave a Reply

Your email address will not be published. Required fields are marked *