The DataViewer based 3D bifurcation diagram viewer.
The following sections describe the usage of modules which may be utilized to visualize the overall structure of bifurcation diagrams. These modules communicate with VBM through an interface described in Section.
The DataViewer based 3D bifurcation diagram viewer.
This module is the single most important, and highly used, module which is part of the current VBM distribution. This module provides a visualization of a three dimensional projection of the bifurcation diagram.
This module has been implemented using a three dimensional geometry visualization library called DataViewer, described in http://lcvmwww.epfl.ch/DV. DataViewer consists of a set of C++ classes developed by Paffenroth, Stone, Vrajitoru and Ahearn. DataViewer is written on top of the OpenGL API and designed to make the development of special purpose visualization software easy for those who are not experts in OpenGL.
Basically, when this module is used, four representatives from the bifurcation diagram are chosen. Three are used as the coordinates of a three dimensional object, and the fourth is used to define a color. The three dimensional object can then be rotated, translated, and scaled using the mouse or the keyboard. The color of each point is derived by taking the value of the specified representative at that point and applying a color-map. For example, in Figure the color-map is a standard rainbow where blue corresponds to the minimum value of the selected representative and red corresponds to the maximum value of the selected representative.
As shown in Figure, the contents of the pointer objects are displayed as small spheres. The pointer objects may be interactively modified by using the mouse and clicking on the graphical representation of the bifurcation diagram. An active pointer may be chosen, and when the mouse is clicked over a point of the bifurcation diagram, the pointer object is modified to designate that point. In this way the user may explore the data set as well as select points for further computation.
The bifurcation diagram may be manipulated by using both the mouse and the keyboard. Note, this information is repeated in several sections since it is the same for all DataViewer based modules. We include it to make each section as self-contained as possible.
Keyboard bindings
Perform rotations about the vertical axis.
Perform rotations about the horizontal axis.
Perform rotations about the axis "coming out of the screen".
Translate the object horizontally.
Translate the object vertically.
Zoom the object.
Mouse bindings
Selects the vertex of the bifurcation diagram under the mouse and places the current pointer there.
Performs rotations of the bifurcation diagram based upon the virtual trackball paradigm.
The bifurcation diagram continues to rotate in the same direction as it was rotating when the button was release.
The bifurcation diagram stops rotating.
Translates the bifurcation diagram based upon the movements of the mouse.
As the mouse is moved up the bifurcation diagram is moved closer to the eye-point, and as the mouse is moved down the bifurcation diagram is moved further away from the eye-point.
There is one tag which this module utilizes, namely the "VBM_Connectivity" tag. The details of the usage of this tag are defined in Section.
All of this modules options may be set by using its control panel. When the module is started its control panel is created as a separate window and iconified. It may either be accessed by using standard window manager methods for deiconifing it, or by using the "Deiconify Panel" on the bottom of the bifurcation visualization window Figure.
The main control panel for the DataViewer
based bifurcation diagram viewer.
There are two top level tabs on the main control panel, namely "Visualization Options" and "Save and Load", and the following sections describe the options that can be set by selecting these tabs. Note, some of the control panels are common to several modules. We have chosen to describe them multiple times to make the documentation for each module self contained.
This class defines the AnimateDraw function of DataViewer (under the Animate menu) such that at each of its calls the current pointer is moved one step forward in the diagram. Thus, by opening the Animate Draw Window, one can move step by step in the diagram, or make an animation from a given number of steps.
This toplevel page contains all of the widgets for changing options for this bifurcation diagram viewer. The sub pages, and the options that they change are in the following sub-sections.
This page allows the user to select what columns of data from the VBM file to plot in the bifurcation diagram viewer. The X coordinate,Y coordinate, and Z coordinate rows allow manipulation of which spatial coordinates are plotted, while the Color coordinate row controls the use of a column of data as a color (more detail on the coloring feature can be found in Section).
An example row of the "Coord and Scale"
option page.
Each row begins with a label which shows the minimum value for the selected column and ends with a label which shows the maximum value (as denoted by "a" and "e" in Figure). These minimums and maximums are taken over the entire bifurcation diagram (not just one branch). The selection widget (denoted by "b" in Figure) allows the user to select which column of the data they wish to visualize. The first type-in widget (denoted by "c" in Figure) allows the user to select a scaling value for the column. Each value in the column is multiplied by the scaling value before being plotted. A useful trick is to scale some value by 0 to get a "plan view" of the other two columns. The second type-in widget (denoted by "e" in Figure) allows the user to translate each column of data separately. The translation value is added to each value in the column. For example, the "Center" button at the bottom of this paged may be used to set the translation value for X, Y, and Z so that the bifurcation diagram appears in the center of the window. Note that the color row does not have scale or translation since they do not make sense for the color coordinate (more on the color coordinate is in Section).
This page allows the setting of general visualization options. At the top of this page are two toggle buttons. If the top button (marker "Lines") is selected then the one dimensional sections of the bifurcation diagram will be rendered as lines (i.e. unshaded). If the bottom button (marker "Cylinders") is selected then the one dimensional sections of the bifurcation diagram will be rendered as tubes (i.e. shaded). Two dimensional and three dimensional sections of the bifurcation diagram are unaffected by the above choices. The next widget is marked "Width" and is used to set the width with which one dimensional parts of the bifurcation diagram are drawn.
WARNING: The width has different interpretations depending on whether "Lines" or "Cylinders" is chosen. For "Lines" it is number of pixels, and for "Cylinders" it is the radius of the cylinder. The graphics may look quite strange if the drawing method is changed without making the appropriate change to the width. For example a value of "3" may be perfectly reasonable for the number of pixels in a line, but far too large for the width of the cylinder.
The widget marked "Sphere size" controls the size of the marker spheres in the bifurcation visualization window, and the row of colored toggle buttons controls which marker sphere is currently being manipulated (i.e. which sphere moves when you click the left mouse button).
The last two controls on this page are two sliders with which the user can control the lighting complexity and the geometry complexity. The exact definition of these values is beyond the scope of this manual, but the idea is that these allow the user to trade image quality for rendering speed. Low values of these sliders make the image render faster, but be lowering image quality (e.g. smaller number of triangles per sphere, turning off shading), while high values render more slowly but are of higher quality. "7" is the default value and the user is encouraged to experiment to find values which are good balance between speed and quality.
This page can be used to mark by spheres a subset of the points in the bifurcation diagram according to a given criteria. The marked points can be selected afterwards by clicking directly on the corresponding spheres, which is a more precise operation than the usual point selection.
The left side of the page is related to the geometrical aspects of the marker spheres. The type-in labeled "Marker sphere size" is used to set the size of the marker spheres. The selection widget labeled by "COLOR Coordinate" is used to select the column of data to color by using the color map defined later on this page. The geometry complexity of the marker spheres may be set, independently of the geometry complexity of the rest of the bifurcation diagram, by using "Geom Complexity" slider. Next there are three toggles which allow the user to select which colormap they wish to use for the markers. Colormaps are covered in greater detail in Section. One color map which is somewhat specialized is the "11 discrete colors" colormap. In this colormap points of the bifurcation diagram are divided into eleven groups, and two points are placed in the same group if the values in their columns defined by "COLOR Coordinate" are sufficiently close. The eleven colors in this colormap have been chosen to have the highest color separation possible (i.e. they are easy to tell apart from each other). If there are more than eleven groups of values then the twelfth and higher groups are all assigned the color white.
The right hand side of this page can be used to define the criteria by which one can mark some of the points in the bifurcation diagram. It provides four ways to define the marker criteria. The widgets for the first method are already in the page to starts with, while the widgets for the three others can be added to the page by clicking on their corresponding button. For each method, after defining the criteria, one has to press the "Add markers" button attached to the method's widgets. This button adds the markers to the internal data structures, but to actually have them appear in the window the "Draw" button must be pressed as well. Each new operation of adding markers erases the old ones. One can also delete all the markers with the last widget on this page, labeled "DELETE markers (does not Draw)" (and press the Draw button afterwards).
The first 3 lines on the right hand side of the page define the markers by comparing one of the columns in the data with a real number expression. For example, (see Figure), if one chooses the column named "Cls", the function named ">" and the real value 0.1 as the second argument, then all the points for which "Cls > 0.1" will be marked with a sphere. After choosing the criteria, one has to press the button with the label "Add call markers (does not Draw)" to actually add the markers, then the Draw button to see them. The last call function in the menu is special, because it is not a comparison function. It checks if the selected column is approximately an integer, with the precision given by the second argument. For example, integer(Li,0.01) is true if the difference between Li and the closest integer to Li is smaller than 0.01, i.e. "abs(Li-round(Li))<0.01".
An example of marker function selection.
The next widget, labeled "Widgets for typein markers", adds the widgets for the second method of defining the marker criteria. You can see an example of these widgets in Figure.
An example of typein marker function.
The first one is a type-in labeled "Marker ball function". This widget may be used to enter an arbitrary Python expression and a sphere will be placed on any point of the bifurcation diagram for which this expression is true. Any standard Python function may be used. In addition, each name that is defined in the VBM data file may be used as a variable name in the expression. For example, if the VBM file defines the following names
M1;M2;M3;F;Writhe;MaxX;MinR;MaxR;MinMSquared;MaxMSquared;Angle
then one could use the following expression
M1 > 0.1 and Angle < 3.14159
to mark all points in the bifurcation diagram for which the first column is greater then 0.1 and the last column is less then 3.14159.
The second widget is labeled as "Add typein markers". Once the parameters of the markers has been set using the previous widgets the user may press this button to create the marker spheres (remember to also press the Draw button afterwards). Note, the computation of the markers for this method is done purely in Python, and hence may take a significant amount of time. Thus, the flip side for the gain in generality is the computational time.
The next button, labeled as "Widgets for comparing 2 variables", adds to the page some widgets for marking points by comparing two variables. These widgets are similar to the ones for comparing a variable with a real number. In the example shown in Figure, one marks all the points where the value in the column named "x" is equal to the value in the column named "y".
An example of comparing 2 variables.
At last, the button labeled "Widgets for calling any function by name" adds widgets for calling any predefined function by its name and arguments. The first widget, labeled as "Import module" specifies the module that contains the definition of the function to be called. In principle, this has to be a Python module, but it can also be defined in another language and compiled as a Python module. In the example shown in Figure, the module to be imported is named "marker_functions.so", but the extension ".so" has to be ignored. For the record, this is a module from the VBM distribution, is written in c and compiled as a shared object that can be imported from Python. This procedure allows us to define functions that are fast and efficient, but can also be used in a scripting language like Python.
An example of calling a marker function by name.
The second widget is a typein for the name and arguments of the function. For the previous example, it is the function called "between" that takes 3 arguments, one of which is a column of the data. As for the typein widgets, all the names defined in the VBM file as the names of the columns can be used as an argument instead of the corresponding column number.
In the actual function call, VBM adds three arguments to the function that the user does not have to specify. These arguments correspond to the data array, to the marker array, and to the branch. The first argument is a Python array of points, each of them being represented as an array of real numbers. The second argument is an array of markers, each of them being an array of size 2, containing the branch number and the point number. The third argument is the current branch number the function is called on. A branch is a group of points in the VBM file (see Section for more details). For example, the function "between" has the following c prototype:
void between(PyObject *data, PyObject *markers, int branch,
double expr1, int ind_var, double expr2);
This function marks all the points for which "expr1 < ind_var < expr2".
After setting all the arguments for this group of widgets, you have to press the "Add call markers" button, then the "Draw" button to see them.
This last method for adding the markers provides enough flexibility, but one may need to know Python or c programming to be able to use it.
The "Preprocess Data" page provides access to an interesting visualization/computation tools that this module provides. When the user presses the "New Preprocessor Function" a small dialog is create in which the user may enter a Python function which creates new values to visualize in the bifurcation diagram (see Figure).
The type-ins which may be used
to create a preprocess function.
The type-in labeled "Preprocess Function" may be used to enter a Python expression which will be evaluated on every point of the bifurcation diagram. When the user presses the "Add Columns" button the result of this calculation will be added as a new column of data, with whatever name appears in the "Preprocess Function Name" type-in. This new column of data may then be visualized in the same way as the other columns in the bifurcation diagram.
For example, consider the case where the VBM file has the following names defined.
M1;M2;M3;F;Writhe;MaxX;MinR;MaxR;MinMSquared;MaxMSquared;Angle
One could compute and plot the square of the norm of
M1,M2,
and M3 by using something similar
to
Figure.
An example of a type-in with
a function entered.
This would create a new column called "Energy" which can be used in any way in which the other columns may be used.
Note, pressing the "Add Columns" button creates the data, but the new data will not be available for visualization until the bifurcation diagram is updated by pressing the "Draw" button.
The "View options" panel allows you to set the axes options, to choose the colormap and to perform some file operations.
The "Axes Option" section of this page controls the appearance of the coordinate axes in the bifurcation diagram window. The "Axes length" type-in controls the length of the axes, while the "Axes width" type-in allows the user to enter the width of the axes in pixels. Finally, the "Axes on" and "Axes off" toggle switch may be used to control whether the axes appear in the window or not.
Note, the axes always appear at the center of the coordinate system for the bifurcation diagram (after any translations have been applied). Accordingly, the bifurcation diagram always spins around the origin of the axes.
DataViewer provides several different color maps which may be used to translate floating point values into colors (i.e. RGB values). In DataViewer a color map is a function defined over some range of floating point numbers (defined by a minimum and maximum value) which returns an RGB triple. An example of such a function might assign black to the minimum value, white to the maximum value, and interpolate values in between as some shade of grey. Another example might assign blue to the minimum value, red to the maximum value, and the interpolate values in between to create a "rainbow" (we note that while the idea of a "rainbow" which smoothly varies from blue to red may be quite intuitive, the actual implementation of such a colormap can be somewhat subtle).
Normally VBM will compute the minimum and maximum values for the color map by using the appropriate column of data over the entire bifurcation diagram.
The "Colormap" section of the "View options" page allows the user to choose from three different colormaps for the visualization of their data. The "Linear Color Map" sets the minimum value to blue, the maximum value to red, and uses a "rainbow" in between. The "Gray-Scale" color map sets the minimum value to black, the maximum value to which, and uses shades of grey in between. The "Discrete Color Map" color map is different from the previous two in that it only returns colors at integer values and white everywhere else. It is a special purpose color map and it probably not useful for general visualization problems.
One color map which is somewhat specialized is the "11 discrete colors" colormap. In this colormap points of the bifurcation diagram are divided into eleven groups, and two points are placed in the same group if the values in their columns defined by "COLOR Coordinate" are sufficiently close. The eleven colors in this colormap have been chosen to have the highest color separation possible (i.e. they are easy to tell apart from each other). If there are more than eleven groups of values then the twelfth and higher groups are all assigned the color white.
The "Save and Load" section of this page contains buttons for saving and reading information about the bifurcation diagram, including saving it in other formats.
Save View
There are many parameters which make up how a specific bifurcation diagram appears, e.g. its current rotation, width, what columns have been selected, etc. The file chooser activated by this button may be used to save a file which contains all of the parameter for the current visualization so that it may be read in later to recover the same view.
Read View
The file chooser activated by this button may be used to read in a view file which was previously saved with the "Save View" operation. Note, the contents of the view file depends on the VBM file which was being visualized at the time the view file was created. If you attempt to read in a view file which was created for a different VBM file then you are currently visualizing the behavior is undefined (it may work, but will probably not do what you expect!).
Save VRML
This button may be used to save a VRML version of the current bifurcation diagram. This functionality is under construction and not all DataViewer properties have direct VRML analogs, but the resulting VRML file is VRML 1.0 compliant.
The "Grid" page controls the appearance of the grid in the bifurcation visualization window. The toggle buttons "Grid on" and "Grid off" control whether the grid appears or not. The slider labeled "Grid lines" allows the user to set the number of lines to be used in the creation of the grid. Higher numbers make the grid "denser". The "First Start", "Second Start", "First End", and "Second End" type-ins allow the use to define the coordinates of two opposite corners of the grid so that it may be moved around in the plane defined by the orientation toggle buttons below. The "R","G", and "B" type-ins control the color of the grid, while the "Cylinder on" and "Cylinder off" toggles whether the grid is drawn as lines (i.e. no shading) or as cylinders (i.e. shading). The "Width" type-in in interpreted as number of pixels when the grid is drawn without shading and as the radius of the cylinder when it is drawn with shading. Finally, the three toggle buttons labeled "YZ Plane", "XY Plane", and "XZ Plane" control the orientation of the grid.
This module is not a visualization module as much as a module for the manipulation of pointers on a bifurcation diagram. It allows the pointers to be placed on specific points of the bifurcation diagram, with finer control then is possible with the graphics interface. It also allows animations to be performed by moving a pointer along a branch of the bifurcation diagram.
The text based bifurcation diagram viewer.
The top text panel shows the list of pointer objects that have been given to this bifurcation diagram. Basically, it shows the Python string representation of the pointer object. The second text panel shows the Python string representation of the bifurcation diagram. Both of these are not of use for most standard visualization purposes (unless the user is an expert in the interpretation of string representations of Python objects), but they can be used quite effectively for debugging VBM data files.
On the other hand, the pointer controls at the bottom of the window may be used for precise control of pointer location, when used in conjunction with a graphical bifurcation diagram viewer, such as the module in Section. The top slider controls which branch of the bifurcation diagram on which the pointer will be placed, and the second slider controls on which point of the selected branch the point will be placed. The button marked "Update" is used after the two sliders have been set and the user wishes to have the values take affect. When the "Animate" checkbox is pressed the selected point is updated each time either of the slider is moved (i.e. the function normally called by the "Update" button to be called every time either slider is moved).
Finally, at the very bottom of the window is shown the list of currently available pointers. Different pointers may be manipulated by selecting the appropriately colored button.