Installation follows the standard Python package management principles: After extracting the files from the package, enter the newly created directory and just run

 python install

to build and install the package. Note that you might have to perform this with a user with sufficient rights. This could mean that you have to be root if installing under UNIX.

This will install ClusterViz as a package under your Python site-packages directory. It will also install the front-end script clusterviz into a location such that you should be able to execute it.


ClusterViz does depend on two other Python modules to function. These are the following:

  • Numeric for array operations. Development of this module has actually already ceased and we will replace it by its successor in the near future. Information is available here and it can be downloaded from here.
  • PyOpenGL. This is the interface to do OpenGL programming from Python. Without this obviously no visualization is possible. Get it from here.
  • RPy. This is optional. ClusterViz can make use of an existing installation of the statistics software R to make plots. Then you also will need RPy.

Running the program

The program is called


Just run this Python script with the data file to work on as argument:

 clusterviz FILE

To get information about how to use it you can issue:

 clusterviz -h

To use another algorithm than the default and fast hard k-means algorithm use one of these commands (which are documented in the above help output).
Soft k-means with beta = 30:

 clusterviz -s 30 FILE

Mixture models:

 clusterviz -m FILE

Data file format

The data are presented to ClusterViz in a flat-file format. Per line one data sample is expected whose components are white-space separated. Earlier versions of ClusterViz supported only three-dimensional data. This restriction has now been lifted. X-dimensional data can be projected down to three dimensions by just using the first three dimensions and disregarding the rest for displaying. Other possibilities are to determine via a command line option which dimensions to use in this way or to give a linear transformation matrix that is applied for the display (see the --help option for the syntax). Note that the clustering process itself works on the non-transformed data and only the display is result of the projection.
Example data sets to try ClusterViz out can be downloaded from the project's Sourceforge file area.

GUI controls

There are a number of commands available in the GUI. To see them just hit 'h' while the GUI is running.

Keyboard commands

h Toggle display this help information
q / ESC Quit program
f Switch to fullscreen display
w Switch to a windowed display
p Pause the clustering thread
r Restart the clustering thread
b Go back one step in the clustering process history
n Go forward one step in the clustering process history
j Toggle the display of the trajectories
d Toggle the display of the data
c Toggle the display of the cluster represntations

Mouse control

Here LMB means left mouse button; MMB, RMB analogous.
Rotate LMB-click
MMB-click / Shift-LMB-click
Zoom RMB-click