Download | Movies | Demos | Features 'n versions |
Manual | Partiview FAQ | Papers | Why the name?

Ndaona is a package of Matlab functions for automatically creating visualizations of certain types, such as time-varying textured 3d scatterplots and animated networks around the planet. It does so by creating Partiview files. Partiview is a fast 4d data viewer written by Stuart Levy of the National Center for Supercomputing Applications at UIUC.

Ndaona provides support for directed graphs, world graphs, animation, publishing the resulting visualizations in a form distributable to others, embedding kernel matrices, etc. However, bear in mind that Ndaona is a demo, a way for me to prototype some visualization concepts.

Ndaona_techreport.pdf : an in-progress technical report describing Ndaona (January 2006). As it is aimed at a machine learning audience, it doesn't mention world graphs.

Ndaona was presented at the HLT-NAACL 2006 Demo Session. Here is the 4-page description, the Demo Script, and the reviewers' comments.

The incomplete flow chart above shows some of the things Ndaona can do. The key points to note are that Ndaona is separate from Partiview, that Partiview does the actual visualization, and that Ndaona does more than just munging data into Partiview's format.

Download

Ndaona 0.83 (19 Jan 06) It has Matlab files, Partiview binaries, and a few other files. Unzip it somewhere and when you're working in Matlab, make sure that that 'somewhere' is in Matlab's path. (Also you should never be able to get to another Ndaona version on your Matlab path.)

Movies

Tone Recognition in Mandarin: this was made with this model; another model of the same data is in the demos section.

  • With (my horrible) narration : WMV (15 Mb) DivX (12 Mb) MP4 (14Mb, 320 x 240, suitable for Video iPods)
  • Without narration : WMV (15 Mb) DivX (12 Mb) AVI (zipped, 38 Mb)

Faces in Linear Kernel Space: this was made with the Brendan Frey model in the demos below. Narration will be added, so be warned.

  • With music: WMV (8Mb) DivX (6Mb)
  • Without music: WMV (8Mb) DivX (6Mb) AVI (zipped, 32 Mb)

The music used in the above clips is from Kevin MacLeod.

Demos

Wondering if you should bother using this tool at all? See if any of these demos run on your machine. All you have to do is unzip a file, then click on a .bat file (in Windows) or a .command file (in OS X). If you're running Linux, you'll have to say chmod +x *.csh and then run the .csh file.

Most of the demos below run on in stereo on a GeoWall. (Thanks to Dharmesh Maniyar (Aston University, Birmingham) for pointing out that the USPSLLE demo on here came up in stereo by default. This was corrected on 8 June 05.)

In all cases using the PICDIR parameter, supply a different value depending on where the images are stored relative to the directory where you're working in Matlab.

tonesvmpe.zip: How well a linear svm (in LIBSVM) classifies Mandarin tones, from the Eurospeech 2005 paper by myself, Gina Levow and Yi Xu (who recorded the original data).. Made using the command below with the workspace in xutf_libsvm_linkernel.mat loaded.
   opts.filename = 'xutfsyll';
   pix = makebarglyphs(Xtest,opts);
   ndaona('CLASSPROBS',CPtest,'CLASSES',Ltest,'PIC',pix,
      'GLYPHSIZE',0.2,'PUBLISH','tonesvmpe', 'GROUPNAMES',
      {'hi','rise','lo','fall'},'NOAXES','GEOWALL','PICDIR',
      'images_xutfsyll');
As with the rest of the examples, there are several alternatives to the above command, e.g. writing GS instead of GLYPHSIZE, or writing parameter names in lower case - see documentation below. Also, you will change the argument supplied with the parameter PICDIR depending on where your pictures are stored. And you can leave out the 'geowall' parameter if you don't have a stereo 3d system available.
damaptask.zip: How well a linear svm (in LIBSVM) classifies Dialog Acts from MapTask using the data in damaptask.mat and
  ndaona('CLASSPROBS',ProbEst,'CLASSES',L,'GLYPHSIZE',0.2,
    'CLASSNAMES',daclassnames, 'CLASSNAMES',daclassnames, 
    'ATTRIB',SomePros, 'ATTRIBNAMES',SomeProsNames,
    'INFO',RawText,'PUBLISH','damaptask','geowall');
frey.zip: Can a linear kernel separate happy and sad faces of Brendan Frey? This embedding was created using the dataset "frey_rawface.mat" from Sam Roweis' Data page as follows:

The pictures in images_freyface.zip were created with the commands below (note that Roweis' MAT file has a single matrix ff that is a D x N matrix (not a N x D matrix) representing N 28 x 20 pictures. Also, its integers are in uint format and need to be converted to double before the kernel calculation.
     opts.byrows=1; opts.height=28; 
     opts.filename='freyface';
     imagenames = makepix(ff',opts);
   
The 3d model was then created with the commands below:
     Klin = calckernel('linear',[],double(ff)');        
     ndaona('KERNEL',Klin,'PIX',imagenames,'PICDIR',
       'images_freyface', 'PUBLISH','frey', 'GLYPHSIZE',
        0.2,'GEOWALL',1e-4);
    
uspsre_rbfsvm_pe.zip: How well does a RBF SVM classify digits? Made with data in this MAT file:
     opts.mirror=2; opts.rotate=90; 
     opts.filename='uspste'; opts.invert=1;
     pix = makepix(Xte,opts);
     ndaona('CLASSPROBS',PEte,'PUBLISH','uspsre_rbfsvm_pe',
       'CLASSES',Lte,'CLASSNAMES',digitnames, 'GLYPHSIZE',0.6,
       'MAXGLYPHSIZE',0.2,'PICS',pix,'PICDIR','images_uspste',
       'GEOWALL',0.01,'INFO',pix,'NOAXES');
   

The command above creates a model with a black background as that looks better. (See picture left, top) However, if you want a white background (picture left, bottom), as is often required for publications and printing, add the parameter 'BACKGROUND' to the above command e.g. ndaona(...,'NOAXES','BACKGROUND').

The 0.01 after the GEOWALL parameter is the stereo separation. The default (0.005) works fine but this works better.

Some users may want to increase the MAXGLYPHSIZE parameter, possibly even leaving it at the default value. It controls the maximum size that the digits can get when you are close to them.

The entries in PEte are classification probability estimates computed by LIBSVM using a RBF kernel with LIBSVM's default parameters (admittedly sans model selection, since this is just a demo).

Also note that the test-train split in the USPS data is nonstandard as this dataset originally came from the Gaussian Processes for Machine Learning page.

When using makepix, we used the 'invert' option as this creates images with black digits on white backgrounds. Since the white stuff gets colored by class color, this is much more visible, especially if the whole background is white (which is good for papers). Alternatively, we could have just sent in -Xte to makepix instead of Xte.

yalefacespca.zip: How well does Principal Components Analysis separate faces? Made with data in yalefacesdata.mat and the commands
     opts.filename='yale';
     images = makepix(X,opts);
     ndaona('POS',X,'PCA','PUBLISH','yalefacespca',
       'GROUPS',labels,'GLYPHSIZE',0.1,'PICS',images,
       'PICDIR','images_yale','geowall');
   

A fun thing to try is seeing how these are embedded with different kernels:

     ndaona('KER',calckernel('linear',[],X),
        'PUBLISH','YFlinkernel',...);
     ndaona('KER',calckernel('rbf',0.01,X),
        'PUBLISH','YFrbfgammapt01',...);
     ndaona('KER',calckernel('rbf',0.001,X),
        'PUBLISH','YFrbfgammapt001',...);
    
StanfordMamoca.zip (6 Mb) What features does Laplacian Eigenmaps capture on a moving human body? This was made with mamoca.mat and the command
      ndaona('pos',X,'att',Ys,'publish','StanfordMamoca',
        'centering',2,'noaxes','geowall');  
Type 'run' to start the animation within Partiview. There are 23000 points here over 10 timesteps.

Data courtesy of Thomas Andriacchi & Stefano Corazza from Stanford Biomotion Lab's Mamoca project.

overlays.zip : How well does an algorithm do on optimizing network overlays on Matlab? An example of an animated world graph, made with matei.mat and the command
     ndaona('WORLDPOS',coords,'PUBLISH','overlays',
     'LABELS',domainnames,'EDGES',links,'geowall');
   
Type 'run' to start the animation within Partiview. To translate the model, press the CTRL key and press the left mouse button down as you move the mouse.

This data is courtesy of Matei Ripeanu of the University of British Columbia Electrical and Computer Engineering Department.

uspslle.zip: How does Local Linear Embedding embed handwritten digits? Made with uspslle.mat, the pictures in uspstest_pics.zip and
     ndaona('POS',Ylle,'images',images,'picdir',
     'uspstest_pics','classes',labels, 'edges',
     Wlle,'publish','uspslle','geowall',0.001,
     'maxglyphsize',0.2);
  
alex5k.zip: Word similarities computed by Infomap are embedded in three dimensions using Isomap (with six nearest neighbours). Made with alex5k_infomap_isomap6nn.mat and
    ndaona('pos',Yiso6nn,'edges',Wiso6nn,'labels',words,
    'publish','alex5k', 'fov',150,'maxglyphsize',0.1,
    'glyphsize',0.01,'labelsize',0.5,'geowall');
  
I'll be the first to admit that this is a fine example of visual clutter!
Press the button marked g1=edges to turn off the edges in the graph.

Features and Versions

Archived copies: 0.80 (2 Jan 06),
ndaona 0.78 (7 Nov 05),
ndaona 0.75 (8 June 05).
makepv.m was the Ndaona prototype presented at a NIPS 2004 demo.

Features planned:

  • Recompile Partiview so that it allows more than 29 attributes
  • Modify PICS setup so that the same picture can be used multiple times
  • Add option to use simple kinds of pictures for groups when pictures not supplied, e.g. crosses, wedges, etc, so that groups can be recognized by icon shape when color is being used for something else.
  • Adding more dimensionality reduction algorithms (e.g. Isomap, Laplacian Eigenmaps, LLE)

New features added from version 0.84 to 0.85 (Versions 0.84 and 0.85 have been taken down to fix some other things, use 0.83 in the meantime!)

  • Corrected easily-fixed-but-very-annoying bug that crashed when the user supplied no attributes.
  • Removed 30-character restriction on INFO.

New features added from version 0.83 to 0.84.

  • Made INFO values consistent with POSITION values.
  • Made it possible to change colors by attributes even when multiple groups were present, by setting fixed ranges for each attribute across all groups.
  • Now using different color maps (with Partiview's vcmap command) for continuous user-supplied-attribute features and discrete group features.
  • Added USEPOLYSIDES parameter so that points in group n (n=1,2,...) have n+2 sides. Only useful when there are at most five or six groups.

New features added from version 0.81 to 0.83

  • Added 'invert' option to makepix.m.
  • Modified makebarglyphs.m so it now makes much much smaller files.
  • Fixed some harmless bugs in ndaona.m that earlier resulted in larger files being created than required.
  • Added INFO parameter to add comments to every point
  • Now if data is in more than one group, there is a column that colors by group. The color of all groups can now be changed using .cmap files.
  • Should now be able to deal with the case where points remain the same but attributes change with time.

New features added from version 0.8 to 0.81

  • Fixed some bugs in makepix.m to do with rotations and mirroring.

New features added from version 0.78 to 0.8

  • Added separate Matlab files makepix.m and makebarglyphs.m to create sgi images from raw data.
  • An improved graphics parameter estimation algorithm. Now you don't have to modify the values of parameters GLYPHSIZE and MAXGLYPHSIZE so much.
  • The code is much cleaner as it's been heavily revamped. Old bugs have been removed (and not always replaced).
  • The kernel embedding has been upgraded, from a published (in a book, not a paper) algorithm that has been claimed to work but doesn't, to an experimental algorithm that seems to work and not crash. (If it crashes on you, please send me an email, preferably with the kernel matrix. Thanks.)
  • There is an additional file (calckernel.m), originally written by Vikas Sindhwani, for quick calculation of kernels.
  • If points are too faint when looking at all points at once (i.e. you are far away), type in the command menu "gall points on".
  • If you're using this on a stereo 3d system and wish to bring up the stereo version at once, send in the parameter 'GEOWALLSTART' instead of 'GEOWALL'. Its argument (optional) is the stereo separation.

New features added from version 0.75 to 0.78

  • The linux binary of Partiview was compiled with static libraries, so it should always work now.
  • The Partiview binary included here is version 0.8 and allows affine mapping (very nice feature, more documentation about it later)
  • BACKGROUND (or just BG) : if you supply this parameter with no value, the background is white. If you supply it with a 3-element vector of RGB values between 0 and 1, these will be used to define the background color.

New features added from version 0.7 to 0.75

  • CLASSPROBS : Now you can supply class probabilities instead of positions (this is useful for machine learning researchers); Ndaona then uses the Parametric Embedding algorithm (Iwata, Saito, Ueda, Stromsten, Griffiths & Tenenbaum, 2004). You may wish to run Ndaona multiple times, as my implementation of their algorithm produces different embeddings each time it is run.
  • Ndaona now returns a matrix M of embedded positions (in a cell array, with M{t} representing the positions used at the t-th time step).

New features added from version 0.6 to 0.7

  • GLYPHSIZE : a new parameter specifying how much you want to multiply the polygons that Ndaona comes up with. (Later note: With Ndaona 0.8, this usually needs to be a value between 0.1 and 1, sometimes more than 1. For example, if you think polygons are 5 times bigger than they should be, then set this to 0.2.)
  • You can supply JPEGs of images as glyphs, thanks to the incorporation of some files from Peter Acklam's PNM Toolbox.
  • Now if you click on the home button you get back to the view you see when Partiview starts up. Thanks to Oya Aran (Bogazici University, Istanbul) for suggesting this feature.

Manual

The general format for using Ndaona is by typing in Matlab

       ndaona (param1,value1,param2,value2,...,paramN,valueN);
       

There are exceptions; values don't need to be supplied if you're happy with their default. Parameter names are case-INsensitive, and there are often several options - you don't have to remember whether a paramter is called 'PIC' or 'PICS' or 'PICTURES' or 'IMAGES' for example.

Parameters and their acceptable values are given below.

Parameters determining the location of data points

  • POSITIONS / POSITION / POS : this is a N by D matrix representing N data points in D dimensions. If D is 1 or 2, then the (y and) z coordinates are set to zero. If you have time animated data with T steps, it is a T-element cell array, each element of which is a Nt x 3 (or 1 or 2) matrix representing Nt points in 3 dimensions. (Nt can change with each time step.)

  • WORLDPOSITIONS / WORLDPOSITION / WORLDPOS / LATLONG : this is the Positions matrix when you are plotting a world graph. Don't supply both a Positions and a World Positions matrix! It is a N x 2 matrix (for N latitude-longitude coordinates) or a T-element cell array whose elemnets are Nt x 2 matrices, for static and time-varying data respectively.

  • CLASSPROBABILITIES / CLASSPROBS / CPROB / CP : this is a matrix of class probabilities, i.e. M(i,j) = probability that point i is class j. The Parametric Embedding algorithm (Iwata et al, NIPS 2004) is used to map these into 3 dimensions. (Note that my implementation of it is not stable, so that running it different times will give different results. Also note that Ndaona returns the positions of the embedding produced, so you can save it and supply it as a POSITIONS matrix the next time you call Ndaona.)

  • KERNEL / KER : this is a N x N matrix that can be supplied instead of a Positions matrix (don't supply both). The positions are then computed using the eigenvectors of the Laplacian of its eigenvectors. You can supply time-varying kernels in cell arrays, but this may not work well because of the eigenvalue sign-switching problem.

If you supply a N x D Positions matrix, you can choose to have a dimensionality reduction algorithm applied to it first.

  • PCA : This parameter name does not have to be submitted with a value. If you say this, then the Positions matrix will have PCA applied to it and the positions mapped at its top three dimensions. If you want the top k dimensions, then supply k as its value.

  • NORMPCA : Works just like PCA; with normalized PCA, each eigenvector is divided by the square root of its eigenvalue.

Parameters determining the location of edges

Here, read 'data point' for 'node'.

Yes, you can have fixed nodes with varying edges.

  • EDGES : In the case of static data representing E edges on N points, this is either a E x 2/3/4 matrix or a sparse N x N symmetric matrix or a E x 2 cell array (or in the case of time-varying data, a T-element cell array) each of whose elements is such a matrix.

    If you supply a E x 2 matrix, call it edgm then if the e-th edge joins the a-th node to the b-th node (indices start at 1) then edgm(e,1) = a and edgm(e,2) = b. If you refer to a node that's out of range, you'll get an error message and the 'edge' will not appear.

    If you supply a sparse N x N matrix that is not symmetric, it will be symmetrized.

    If you have supplied unique names for each data point using the 'NAMES' / 'ID' parameter, then you can supply instead a N x 2 cell array if the e-th edge joins the node with name edgm{e,1} with the one named edgm{e,2}. If the data is time-varying, then, yes, this will be a cell array of cell arrays.

  • DIREDGES : pretty much the same rules apply, so we won't list this in full.

    If you supply a N x 2 matrix, call it edgm then if the e-th edge joins the a-th node to the b-th node (indices start at 1) then edgm(e,1) = a and edgm(e,2) = b. It is your fault if you refer to a node that's out of range...

    You can also supply non-symmetric sparse graph as described in 'EDGES'.

If you do not supply a matrix defining the positions of the nodes, then the edges will be used to determine this. By default, the first three eigenvalues of the Laplacian of the adjacency matrix of the graph (or of the underlying graph of the digraph) will be used to determine this.

You cannot supply only edges for a world graph.

Parameters determining the color and width/height of edges

Unlike data points, edges can have at most two attributes associated with them. These are represented by color and width (for Euclidean graphs) or height (for world graphs). You can specify these in several ways, depending on whether edges were supplied as dense/sparse matrices or/and as cells of such matrices.
   EDGECOL / EDGECOLOR / EDGECOLORS
   EDGEW / EDGEWID / EDGEWIDTH / EDGEWIDTHS
   EDGEH / EDGEHT / EDGEHEIGHT / EDGEHEIGHTS

If the Edges matrix is a E x 2 matrix, add a third and fourth column to it (if you have one or two edge attributes respectively). By default, any third column will be represented by color and any fourth column will be represented by height (if we're making with a world graph) or width (if we're making a scatterplot). If you would like to switch this, set EDGEHEIGHT or EDGEWIDTH to 3, or set EDGECOL to 4.

If the Edges matrix is a N x N sparse matrix, each nonzero entry is represented by an edge/arrow whose color represents the value of the entry. If you want the width/height of the arrow to represent this instead, send in any nonzero value of EDGEHEIGHT or EDGEWIDTH and don't send in the parameter EDGECOL.

Parameters determining what is displayed at each data point

  • GLYPHSIZE / GS : While Ndaona tries to guess an optimal size for you, it is not always successful. This is a multiplicative factor (default 1).

  • LABELSIZE / LSIZE / LS : While Ndaona tries to guess an optimal size for labels, it is not always successful. This is a multiplicative factor (default 1).

  • ATTRIBUTES / ATTRIBUTE / ATTRIBS / ATTRIB : if attributes do not change with time, this is a N by A matrix representing A attributes of N points. If attributes change with time, this is a T-element cell array, each element of which is a Nt x A matrix representing the A attributes of Nat points. (Nt can change with time, but not the number of attributes.)

    The Attributes matrix (call it att should agree with the matrix defining positions. In particular, we mean the following (we assume for simplicity that positions have been supplied with the POSITIONS parameter with value pos).

    • Positions and Attributes are fixed: pos and att are both matrices with N rows.
    • Fixed positions, changing attributes : If pos is a N x D matrix, then att is a T-element cell array and each att{t} a N x A matrix.
    • Changing positions, fixed attributes : If att is a N x A matrix, then pos is a T-element cell array with each pos{t} a N x 3 matrix (or a Nx1 or Nx2 matrix).
    • Changing positions, changing attributes : both pos and att are both T-element cell arrays, and for every t from 1 to T, both pos{t} and att{t} have the same number of rows.

  • COL / COLOR / COLORS : by default, colors are for the first attribute (and are continuous). If no attribute is supplied, they are by groups (and are discrete).

  • CMAP / COLORMAP : If you are coloring by groups, you can supply your own colors as a C x 3 matrix.

Parameters determining how data is partitioned into groups

If you are happy with all your data being in one group, ignore this section. (The default values are fine for you.)

  • GROUPS : This is an N-element vector or a cell array of vectors that agrees with the number of data points. The vectors' entries are integers from 1 to G representing the group number of the entry.

    Now your data will be organized into the G groups, with a button for each group so you can turn groups on and off easily.

  • GROUPNAMES. By default, your buttons will be labelled 'g1','g2',... 'gG'. If you don't want that, supply with this parameter a cell array gpnames such that the name of the i-th group is gpnames{i}.

    You don't have to specify every group name. For example, say you have 5 groups, and you only have names for the second and fourth. Then you could define gpnames as

            gpnames = cell(5,1);
            gpnames{2} = 'yoyo';
    	gpnames{4} = 'ma';
    

    Your groups will then be named 'g1','yoyo','g3','ma', and 'g5'.

Other Parameters

  • GEOWALL : This parameter does not need a value. If you want to supply one, it will define the eye separation. The default eye separation is 0.005 .

Making your own pictures

You can use any method to create your own glyphs (to supply with the parameter 'PICTURES'). In that case, ignore this section.

If you do not have your own images, Ndaona also provides a couple of functions for making glyphs that could be of use. Suppose you have a N x D feature matrix representing N D-dimensional vectors.

  1. You want to create histogram representations of your vectors.
  2. The vector already represents an image, stored row-by-row or column-by-column.

The functions makebarglyphs.m and makepix.m both create pictures in a new directory and return the names of pictures created.

    (1) When you want histogram glyphs

    In this case, you should use makebarglyphs.m . It takes the N x D feature matrix and a structure opts with fields

                .dpi (a positive integer, by default 5)
                .zcutoff (default 3)
                .filename: if this equals 'blah' then the pictures 
                     generated are called blah1.sgi, blah2.sgi,...
                .picdir: the directory (relative to the current Matlab 
                     directory) where generated pictures are placed. 
                     By default this is 'images_blah' or the concatenation 
                     of 'images_' and opts.filename if the latter is supplied.
     

    This creates glyphs with z-normalized features. For each feature, the mean and standard deviation are computed and the normalization "new feature = (old feature - mean) / stdeviation" is performed. (If the feature has standard deviation 0, then it is just divided by its mean. If its mean is also 0, then the feature is 0 anyway.)

    The x-axis of each glyph has the features/dimensions, while the y-axis is between -opts.zcutoff and +opts.zcutoff.

    If the resulting pictures are too low-res, increase opts.dpi to 10, then 15, etc. If the resulting pictures are too big, decrease opts.dpi to 4, 3, 2 or 1.

    Remember that the smaller the pictures created, the more you can show in a scatterplot, as only so many glyphs will fit into graphics memory.

    (2) When each vector represents a H x W pixel image

    Before anything else, the feature matrix is normalized by the minimum and maximum values in it so that all its values are between 0 and 1. Now, the more values that are closer

    Sorting out height and width

    In this case you should use makepix.m . The arguments to makepix include the N x D matrix M, where D=H*W and M represents N pictures with H x W pixels. You have to supply a structure opts with the fields

                .height = H
                .width = W
                .byrows = 0 or 1 
                .mirror = 0 (no reflection) or 1 (left-to-right) 
                                            or 2 (up-to-down)
                .rotate = 0 or 90 or 180 or 270
                .invert = 0 (default) or 1
                .filename: if this equals 'blah' then the pictures 
                     generated are called blah1.sgi, blah2.sgi,...
                .picdir: the directory (relative to the current Matlab 
                     directory) where generated pictures are placed
    

    The invert option can make things easier to see.

    First you have to know whether your vector is stored by columns or by rows. Suppose it represents the binary image below (H=height=4, W=width=3).

                   0     0     1
                   1     0     0
                   1     0     0
                   1     0     0
    
    • The default assumption is that the image is stored column-by-column then it is represented as the row vector
                   0 1 1 1    0 0 0 0    1 0 0 0
      
      In this case you should set opts.byrows to 0 (or don't set it at all, as this is the default value)
    • If the image is stored row-by-row then it is represented as the row vector
                   0 0 1   1 0 0   1 0 0   1 0 0
      
      In this case you should set opts.byrows to 1.

    Rotations and Mirroring

    Images are often stored in a format that requires reflecting and/or rotating to get them so we can see them. What you should do is create a few pictures without using any rotating or reflecting and then figure out what transformations are required.

    makepix.m will do reflections before rotating.

    Here's what the 4 x 3 image above will look with opts.mirror set to 0, 1 or 2 (if there is no reflection)

            opts.mirror=0     opts.mirror=1     opts.mirror=2
    
               0  0  1           1  0  0           1  0  0
               1  0  0           0  0  1           1  0  0
               1  0  0           0  0  1           1  0  0
               1  0  0           0  0  1           0  0  1
    

Partiview FAQ

Information not found here may be found on the main partiview site at the NCSA.

Picture format

At the moment, Partiview requires JPG or SGI format pictures only.

Navigation

The trick is to hold the mouse button down while moving. Navigation is inertia-based (this is a feature, not a bug!), so the scene keeps moving when you let go of the mouse button, depending on how fast you were moving the mouse when you let go. Move-click with the left mouse button to rotate, with the right mouse button to zoom.

To translate, move the mouse with the right mouse button pressed, while pressing the CTRL key. Alternatively, press the 'f' key, move around with the left mouse button pressed, then press the 'o' key to return to the original setting of the left-mouse-move command.

Using the Command Window

Partiview starts up with two screens, one for the model visualized and the other is a command menu, shown below:

You can type commands in the command window. To get a cursor there, click in the bottom line of the window ("Cmd:...") or press TAB.

Minimize the command window by pressing the "_" button near its top right corner. Click on the "x" button removes the window completely, so you probably dont want to do that.

Getting Pictures

Type in the command window

     snapshot

And you'll find in the current matlab directory a file of the form snap.000.ppm (on Windows) or snap.000.sgi (on *nix) that has a screenshot of the current picture displayed on partiview. The next time you type the command, the picture snap.001.ppm/sgi will be created, and so on. The next time you run Partiview, the snap counter goes back to 000.

You may want this picture to not have the command window in it. To do that, close or minimize the command window, and then press TAB and type (blindly) snapshot. This results in the same picture without the menu or with the menu in a corner that you can crop out.

You can only make movies on Linux, for technical reasons. Here's documentation on that at the Cosmus site.

Axes

Partiview comes up with three axes. The red, green, and blue ones represent the first, second, and third dimensions respectively. The colored half of each axes is positive. To get the size of the axes, type in the command window

       censize

The second-bottom part of the command window now displays the length of censize, for example

       censize 10.134 (interest-marker size)

Ignore the "interest-marker size" thing. This means that each half-axis is 10.134 units. The units are pixels, but you'll only ever use them relatively. So for example, if you want to change the length of the axes to 20, type in the command window

       censize 20

To turn the axes off, type

       censize 0

To multiply or divide the size of the axes by, say, 5, type

       censize *5
       censize /5

I find censize a useful way to find out the dimensions of what I'm looking at, when I don't remember/know the stats of the original matrices.

Changing image size

While ndaona tries to guess how large you want your images, it is not guaranteed to succeed. You may want to make images larger or smaller. Making them smaller also makes it easier on your graphics card. To halve the size of all images, say

       gall polysize /2

To multiple the size of all images by 1.5, say

       gall polysize *1.5

The 'gall' makes the command apply to all groups that your data is in. Otherwise it only applies to the current group, which is displayed somewhere in the top left quadrant of the command menu.

You should remember how much you increased/decreased the size by, because you can specify that with the GLYPHSIZE parameter.

Changing the maximum image size

This controls the area of the screen (in pixels) that an object can occupy when you get close to it. Like GLYPHSIZE this is controlled with a multiplicative parameter - MAXGLYPHSIZE (or MGS for short). So if, for example, you think the pictures are twice as big as they need to be when you get close to them, supply the MAXGLYPHSIZE parameter with value 0.5.

If you aren't quite sure how much larger or smaller you want pictures to be, do the following.

If you type gall polymin in the Partiview command window, you will see its parameters for all groups. Each group will have two parameters, e.g. g4 polymin 1 20. The second one (here the 20) is what we're interested in - make a note of it for future reference. It means that when you get close to a point it will occupy at most an area of 20 pixels on the screen. If you'd like to see what this looks like with, say 40 pixels, just type in the command window g4 polymin 1 40 (to affect just the group g4) or gall polymin 1 40 (to affect all groups). Note that if you type gall polymin - 40 then the first value will remain unchanged (for all groups, or just g4 if you said g4 instead of gall).

Changing Stereo Separation

PS: This is only for GeoWall users and the ilk.

Usually you can just send in the parameter 'GEOWALL' without any parameter, and the default value will be fine. But if not, read on. If you type stereo -0.004 crosseyed in the Partiview command window (you can leave off the word crosseyed after the first time you type it) the separation will become -0.003. Note that the value should be negative, since we are really using parallel stereo and not crosseyed.

Once you are happy with a stereo separation, say -0.035, either

  • Run ndaona again but this time supplying the value 0.035 (note that you should supply a positive value) after the GEOWALL parameter, OR
  • If your project name (i.e. what you supplied with the PUBLISH parameter) is myname, edit the file myname/data/myname_geowall.cf. Near the end of the file will be a command like eval stereo -0.000??0000 crosseyed where ?? is some number. Change this to eval stereo -0.0035 crosseyed .

Papers

Ndaona_techreport.pdf : an in-progress technical report describing Ndaona (January 2006). As it is aimed at a machine learning audience, it doesn't mention world graphs.

If Ndaona and Partiview prove useful for you, it would be greatly appreciated if you cited the paper

and one of the papers below (sure, cite both if you want!)

What does Ndaona mean?

Ndaona means "I have seen" in chiShona, a language in the country where I grew up.