A Way to Create Reusable Tools

There are a lot of ways to create reusable tools and widgets in lots of programming languages, including MATLAB. Today I
want to illustrate creating a reusable visualization tool that can then be incorporated into a more complex visualization
tool. Several of us (Scott, Mike, and I) at The MathWorks developed this example for the MATLAB World Tour that took place earlier this year. I even posted some pictures from some of the events.

Contents

Here's a GUI Using the Tool

Here I show the tool embedded in a GUI (graphical user interface). There's a slider that allows the user to choose a viewing
plane through the x-axis of the 3-D volume.

[x,y,z,v] = flow();
volvisGUI(x,y,z,v)

Code Architecture

The code is split into two files, the actual GUI, in volvisGUI.m and the viewer that shows planes slicing through the volume, in volumeVisualization.m. Let's first look at a skeleton of the code for volumeVisualization.

dbtype volumeVisualizationPseudo

1     function s = volumeVisualizationPseudo(x,y,z,v)
2     %volumeVisualizationPseudo   Pseudo-code for volumeVisualization.
3     
4     %   Copyright 2007 The MathWorks, Inc.
5     
6     %% Initialize
7     initDisplay(x,y,z,v)
8     
9     %% Nested Functions
10        %% Add slice plane
11        function addSlicePlane(xLoc)
12        end
13        %% Delete Slice plane
14        function deleteLastSlicePlane()
15        end
16        %% Initialize DIsplay
17        function initDisplay(x,y,z,v)
18        end
19    
20    % Export structure
21    s.addSlicePlane = @addSlicePlane;
22    s.deleteLastSlicePlane = @deleteLastSlicePlane;
23    s.xMin = min(x(:));
24    s.xMax = max(x(:));
25    end

Initialization

In this code, you can see that the figure is initialized, and a structure is returned. This structure contains the minimum
and maximum values possible for a plane along the x-axis as well as function handles to two functions, one to add a slice
plane, and one to delete the last slice plane. The two function handles are the functionality I may then use if I want to
build on top of this visualization.

Let me try out the engine now. First I create the visualization.

close all
s = volumeVisualization(x,y,z,v)

s = 
           addSlicePlane: @volumeVisualization/addSlicePlane
    deleteLastSlicePlane: @volumeVisualization/deleteLastSlicePlane
                    xMin: 0.1000
                    xMax: 9.9000

Next, let me add and remove some slices.

s.addSlicePlane(5)

s.addSlicePlane(3.2)

Now delete the last plane added.

s.deleteLastSlicePlane()

And again.

s.deleteLastSlicePlane()

And again. Or can I? I only added two slices and I am now up to deleting the third!

s.deleteLastSlicePlane()

The Engine Code

Whew! No seg-fault or other crash. Let's look at the actual code to see what's going on. I'll discuss it in segments.

dbtype volumeVisualization

1     function s = volumeVisualization(x,y,z,v)
2     %volumeVisualization Engine for choosing y-z planes to view.
3     %   s = volumeVisualization(X,Y,Z,V) returns a structure 
4     %   containing information about the visualization of volume
5     %   data described by X,Y,Z,V.  The fields are:
6     %          addSlicePlane -- function handle to add a slice
7     %                           plane at location x
8     %   deleteLastSlicePLane -- function handle to delete the
9     %                           last slice plane added
10    %                   xMin -- minimum x location for a plane
11    %                   xMax -- maximum x location for a plane
12    %
13    %      Example:
14    %      [x,y,z,v] = flow;
15    %      s = volumeVisualization(x,y,z,v);
16    %      s.addSlicePlane(3.7)
17    %      s.addSlicePlane(7.5)
18    %      pause
19    %      s.deleteLastSlicePlane()
20    %      pause
21    %      s.deleteLastSlicePlane()
22    
23    %   Copyright 2007 The MathWorks, Inc.
24    
25    %% Store handles to the various planes
26    %initialize handle to axis
27    %initialize handle to slice plane
28    hAxis = [];         
29    hSlicePlanes = [];  
30    
31    %% Create data for generic slice through yz-plane
32    [yd,zd] = meshgrid(linspace(min(y(:)),max(y(:)),100), ...
33        linspace(min(z(:)),max(z(:)),100));
34    
35    %% Plot the volume initially
36    initDisplay()
37    
38    %% Nested Functions
39        function addSlicePlane(xLoc)
40        %addSlicePlane   Add a slice plane xLoc.
41            xd            = xLoc*ones(size(yd));
42            newSlicePlane = slice(hAxis, x, y, z, v, xd, yd, zd);
43            hSlicePlanes   = [ hSlicePlanes, newSlicePlane ];
44            set(newSlicePlane,'FaceColor'      ,'interp',...
45                              'EdgeColor'      ,'none'  ,...
46                              'DiffuseStrength',.8       );
47        end
48    
49        function deleteLastSlicePlane()
50        %deleteLastSlicePlane Delete the last slice plane added.
51            if ~isempty(hSlicePlanes)
52                delete(hSlicePlanes(end));
53                hSlicePlanes = hSlicePlanes(1:end-1);
54            end
55        end
56    
57        function initDisplay()
58        %initDisplay  Initialize Display.
59    
60            % Draw back and bottom walls
61            if isempty(hAxis) || ~ishandle(hAxis)
62                hAxis = gca;
63                hold on;
64            end
65            hx = slice(hAxis, x, y, z, v, ...
66                max(x(:)),       [],       []) ;
67            hy = slice(hAxis, x, y, z, v, ...
68                [],       max(y(:)),       []) ;
69            hz = slice(hAxis, x, y, z, v, ...
70                [],              [],min(z(:))) ;
71    
72            % Make everything look nice
73            set([hx hy hz],'FaceColor','interp',...
74                'EdgeColor','none')
75            set(hAxis,'FontSize',18,'FontWeight','Bold');
76            xlabel('X');ylabel('Y');zlabel('Z')
77            daspect([1,1,1])
78            axis tight
79            box on
80            view(-38.5,16)
81            colormap (jet(128))
82        end
83    
84    s.addSlicePlane = @addSlicePlane;
85    s.deleteLastSlicePlane = @deleteLastSlicePlane;
86    s.xMin = min(x(:));
87    s.xMax = max(x(:));
88    
89    end

Help

We start off with the function declaration, followed by lines 2-21 for the help including an example.

Variable Initialization

We next initialize variables to hold the handle to the axes in which the data are plotted and another array for the handles
to the slice planes. They start off empty. We also make an array of values for the y and z data for a generic slice. And
then we initialize the plot, by calling the nested function initDisplay. You can see that we plot several slices along different directions and alter aspects of the plot such as colormap, aspects
of the axes, etc.

Finally, we set up a structure to return the minimum and maximum values for the slices along the x-axis and function handles
to two functions, for adding and deleting slices. These function handles refer to nested functions in the file volumeVisualization.m and I will discuss these functions in the next section.

The Main Work

The main work for this application is done after the initialization and is embodied in the two nested functions addSlicePlane and deleteLastSlicePlane.

When I call addSlicePlane, I insert a plane at a particular x-location. The function creates data for the slice plane, instantiates a slice, makes
it pretty by altering some color and shading properties, and adds the handle to the latest slice to the list of slice handles.
As simple as that.

Calling deleteLastSlicePlane again manages the list of slice planes by deleting the last element on the list from the plot, and removing it from the list
of slice planes. If that list is empty, the function essentially does nothing, which is why it had the good graces to not
error out on me earlier.

The GUI

I am now poised to use this M-file to create the initial GUI I showed. That GUI has a slider that maps to positions for planes
along the x-axis. When a user selects a value, the slider callback simply deletes the last slice plane and adds a new one
at the chosen location. Here's the code.

dbtype volvisGUI

1     function volvisGUI(x,y,z,v)
2     % volvisGUI Interactive volume visualization.
3     %
4     %   Example:
5     %   [x,y,z,v] = flow;
6     %   volvisGUI(x,y,z,v)
7     
8     %   Copyright 2007 The MathWorks, Inc.
9     
10    %% Initalize visualization
11    figure;
12    s = volumeVisualization(x,y,z,v);
13    s.addSlicePlane(s.xMin);
14    
15    %% Add uicontrol
16    hSlider = uicontrol(...
17        'Units','normalized', ...
18        'Position',[.75 .05 .2 .05], ...
19        'Style','slider', ...
20        'Min',s.xMin, ...
21        'Max',s.xMax, ...
22        'Value',s.xMin, ...
23        'Callback',@updateSliderPosition);
24    
25    %%
26        function updateSliderPosition(varargin)
27            s.deleteLastSlicePlane();
28            x = get(hSlider,'Value');
29            s.addSlicePlane(x);
30        end
31    
32    end
33    

Modular Programming Architecture

I've demonstrated here a programming architecture, using nested functions, where you can create individual tools, and incorporate
them into larger applications.

I have the visualization engine and I showed how to use it both in a stand-alone way as well as how to incorporate it into
a GUI. It now can operate as a tool ready to incorporate in other applications. For example, I could have chosen it to power
an animation. Or I could add other degrees of freedom in a GUI by supplying a way to choose other colormaps perhaps.

The Files

You can find the running files for this example on the File Exchange at MATLAB Central.

How might you use such ideas for creating tools you can reuse and share easily? Post your thoughts here.

Get the MATLAB code

Published with MATLAB® 7.4