The visualizer is a tool for use with the Library of Data Structures for Java (jdsl) which is produced by the Center for Geometric Computing (geomlib) at Brown University. It is recommended for use as an application with java 1.3.x Virtual Machines, and utilizes the AWT and Networking packages.
3) How to Visualize Your Data Structure
4) Data Structures currently implemented
7) Other Frequently Asked Questions
8) Known bugs in version 1.2.1
The visualizer is a utility that allows you to graphically visualize many of
the data structures used in jdsl. It can visualize the interactions of multiple
structures at one time and keeps a history of the operations the user has
performed on the data structures. It also has the capability to allow the
outside user to add snapshots to the history in order to visualize algorithms.
It can be used either to visualize ref implementations of data structures, or can interface with students' implementations of the jdsl interfaces for teaching purposes, so long as the students implement a minimal subset of the methods of the interfaces needed.
1a) Running the Visualizer
The visualizer can be run in two methods: either from the command line or from
inside code. It can be run in three fashions:
Standard:(prompts for initial data structure)
Unix Command line: jdslviz
PC Command line: jdslviz.bat
From code: new jdsltools.visualization.jdslviz("");
Invisible: (used if you do not wish the visualizer to prompt for a data structure upon startup, but instead to wait to be passed a data structure from outside) (see section 1h)
Unix Command line: jdslviz invisible
PC Command line:: jdslviz.bat invisible
From code: new jdsltools.visualization.jdslviz("invisible");
As an applet:
appletviewer jdslviz.html
or from your browser jdslviz.html (note: If running the visualizer from a browser, see section 7)
Setting your classpath:
Make sure that your java classpath includes the .jar files in the lib directories of both your jdsl-teach and jdsltools-teach release -- otherwise the visualizer may be unable to find essential classes.
Note:
If you wish for the visualizer to run in the smaller window size when
created from code, set the environment variable VIZSIZE=SMALL.
1b) Choosing your data structure
When you add a data structure to the visualizer, the window that pops up
prompts you for a visualizer type, a class name, and a name to refer to the structure
by (if you allow it to remain as Default, it will be set to the type of
structure you have chosen plus a number. It is important to note that you must
choose the correct visualizer for your structure, that your structure must
correctly implement the necessary interfaces to be visualized by that container
visualizer (see that section of Help), and that the
classname must be typed in format package.classname ; also note that your
classpath must be set so that the visualizer can find your class.(If your
package is BT, and is at /u/rsb/16/BT, then your classpath should
include /u/rsb/16/
1c) The Visualizer window
The window you see in front of you has four sections. In the top-left we have
the data structure which is currently active. At the top-right we have the
timeline which represents the history of your structure. At its simplest, you
can click and drag along it and the structure window will display your
structure at an earlier point in time as you go up. At the bottom-left there is
a panel of buttons with which you can interact with your chosen data structure,
according to its interface. At the bottom-right, there is a panel that allows
you to manipulate the items passed into and returned from your structure.
1d) Menus and menu options
The file menu allows you to quit or pop this window up. As you are looking at
this window, it can be inferred you have figured this out. The containers menu
allows you to visualize additional containers, delete the currently active
container, or to switch which container is currently active by selecting it
from the menu.
1e) The Error Window
All exceptions or errors that occur in your structure will appear in an error
window.
1f) Selecting Nodes
A position or locator can be selected by clicking on it with the left mouse
button. The selected node with turn yellow. For methods that require two nodes,
you can select the second one with the right mouse button. It will turn orange.
1g) The locator display box (Heap and Red-Black Tree only)
In some containers, there is a box in the lower-right corner which displays the
returned locator, when applicable. This is the locator referenced by such
commands as insert(locator) and makeLocator. Click on it to
select it.
2a) Basics
The bottom of the timeline has the most recent event -- the top of the timeline
has the oldest event. Click and drag along the timeline to look at a different
point in the history of your structure.
2b) Colors
Red: An event that occurred in the structure currently visible.
Blue: An event that occurred in a different structure
Green: The structure as it currently is.
Other colors: User defined
2c) Taking Snapshots
To take a snapshot of a specific moment in time for the visualizer, Add inside
your code at the exact instant you wish the snapshot the line:
viz.VisualizationController.snapshot(java.awt.Color.gray);
(or whatever color you prefer, or leave it blank for default coloration)
3a) Visualizing Data Structures
You will only be able to visualize your own data structure if it conforms to
one of the sets of interfaces discussed in the section at the end.
You must correctly implement the following
methods for the visualizer's output to be remotely meaningful:
3a1)Sequence: first(),after()
3a2)Binary Tree: root(),leftChild(),rightChild(),isExternal()
3a3)Restructurable Binary Tree: same as BinaryTree
3a4)Heap: getBinaryTree() must return a valid BinaryTree.
3a5)Red-Black Tree:getBinaryTree() must return a valid BinaryTree.
3b) Visualizing Algorithms
To visualize the operation of an algorithm on a data structure, first make sure
that data structure is visualizable. Then add the data structure(s) the
alogirthm occurs on to the visualizer if they are not already inside it. You
can do this with the command
viz.VisualizationController.addContainer (Container c, String name);
Then, as your algorithm proceeds, instruct the visualizer to take a snapshot
along each salient point of the structure's history, as
discussed in section 2.
4a)Sequence
Interface:
jdsl.core.api.Sequence
Containers:
jdsl.core.ref.NodeSequence
jdsl.core.ref.ArraySequence
jdsl.core.ref.HTNodeSequence
jdsl.core.ref.RTNodeSequence2
4b) Binary Tree
Interface:
jdsl.core.api.BinaryTree
Containers:
jdsl.core.ref.BTNodeBinaryTree
jdsl.core.ref.LinkedBinaryTree (limited implementation)
4c) Restructurable Tree
Interface:
jdsl.core.api.RestructurableBinaryTree
Containers:
jdsl.core.ref.RestructurableNodeBinaryTree
4d) Heap
Interfaces:
jdsl.core.api.PriorityQueue
viz.BinaryTreeBased
viz.ComparatorBased
Containers:
jdsltools.visualization.Wrappers.VBTHeap
4e) Red-Black Tree
Interfaces:
jdsl.core.api.Dictionary
viz.BinaryTreeBased
viz.RedBlackBased
viz.ComparatorBased
Containers:
jdsltools.visualization.Wrappers.VRBTree
First you must run the visualizer. The visualizer can be run in four different
modes -- but for now we will concentrate on its simplest form. So run one of
the jdsl structures by typing:
java jdsltools.visualization.jdslviz
A window will pop up with a popup menu and two text fields. The popup menu
allows you to choose which sort of data structure you mean to visualize, the
top field lets you choose which class to implement that data structure, and the
bottom field lets you name the structure. For now, leave the popup menu at
"Sequence" and do not alter the text in either field. Leaving the
name as Default means that the visualizer will give your structure an
appropriate name. Now click OK.
A window will pop up. There will be some buttons at the Bottom-Left. Click InsertFirst several times. Note that elements appear in the window. Now click on one of the circles with the left mouse button. It hilites yellow. It is now the selected position. Replace its element. The yellow position (or locator) is the currently selected one for any operation.
Click on another with the right mouse button. It will hilite orange. Now click the swap button. If you ever need two different positions for an operation, orange-select the second one.
Now try clicking on some of the other operations -- you will note that operations that return ints or booleans (such as size or isEmpty) return their results in a box next to the button. You will further notice that operations that take an int as input (such as atRank) require you to type the int into a box next to the button. Finally, you will note that operations that return an enumeration create a new enumeration in the list of containers. To return to the original container, select it from the menu list of containers. Also experiment with turning on and off the random element option at bottom-right.
Now let's add a second container. Go to the Containers Menu and select "Add Container". Choose Heap from the popup menu of container types. Click OK.
The first thing you ought to do is click insert(key, element) once. Notice something odd? The nodes are different shapes. The big ones are internal positions with locators (the locators are the squares). The little ones are external positions in the tree (if you don't understand the relevance of the difference between internal and external positions, much less locators, don't worry. You'll learn in lecture.)
Another thing you might find relevant is the little square locator in the bottom right corner. Since locators can exist independent of the data structure, they can be manipulated outside of it too -- right here.
Play around with the structure a bit. Try some of the different buttons. Sooner or later (and if it doesn't happen eventually, click removeMinElement() until it does) you will see a message appear in the mini-window labeled "Error Messages". This means that your structure has generated an error message. Some messages (like that you can't remove the minimum element of an element-free container) are reasonable. Others indicate bugs in your data structure.
Now look at the bar with circles in the upper right corner. This is the history of your data structure. The green box is the current event. Drag the black circle upwards to a red box. This represents an earlier point in the history of your data structure. Now drag to a blue box. Nothing happens, right? Now go to the containers menu and select your other container. It looks different, doesn't it? This is because blue boxes represent events that happened in other containers (this is useful when two data structures affect one another). Note: You can also add your own, user-defined events to the visualizer.
Now quit the visualizer from the File menu. Congratulations! You have just taken a tour of the visualizer. If you want to learn more about how to use it, open it and click on the Help button in the Add Container popup window, or choose Help from the File menu.
PS -- a helpful hint: If you are confused, first check the FAQ at the end of the visualizer help. Your question might just be answered there!
Note that all of the following are only possible if you have the source code for the visualizer.
6a) Customizing color
Have your data structure implement jdsltools.visualization.ColorBased, and create a jdsltools.visualization.ColorInfo object to handle the coloring of each of the aspects of your data structure.
6b) Customizing the methods presented/
visualizing new types of data structures
It’s your choice which of your data structure’s methods the visualizer will present. Go into the jdsltools/visualization/ButtonParser/cfg and modify the file which contains the name of the data structure you wish to modify. Each method is represented by one string in this file. Some examples include:
METHOD: find PARAM: [Object(FROM: key) ] RETURN:
Locator
METHOD: expandExternal PARAM: [Position ] RETURN:
void
METHOD: root PARAM: [ ] RETURN: Position
METHOD: replaceElement PARAM: [Locator,Object(FROM:
element) ] RETURN: Object
It is important to match the syntax as closely as possible. The method’s name should be found after the keyword “METHOD:”. The parameters to the method should be found inside the PARAM brackets – multiple parameters are denoted with a comma. For parameters of type Object, you must include whether that parameter is coming from the key or element field of the interface. Finally, you must include what type the method returns.
In order to create a new type of data
structure that can be visualized as a sequence or tree, you need only take the
following steps: make sure that it implements
jdsl.core.api.InspectableSequence, java.util.Iterator,
jdsl.core.api.InspectableBinaryTree, jdsl.core.api.InspectableTree, or
jdsltools.visualization.BinaryTreeBased. Next, make a config file in folder jdsltools/visualization/ButtonParser/cfg
containing the methods you wish it to display, and named “MyInterfaceCFG” – for
example, the config file for interface “BinaryTree” is named “BinaryTreeCFG”.
Q: How do you choose which tree to use in a link or replaceSubtree operation?
A: Select it in the popup menu immediately to the right of the button.
Q: How do
you enter integer input for operations like atRank(int)?
A: Type the integer into the box at the right of the button.
Q: How do I
insert a premade locator in Heap or Red-Black Tree?
A: Click on the locator in the box at the lower right corner. If it is empty,
you can use the makeLocator function to fill it. (You can also click on a
locator in the data structure being visualized, if you wish to error-check)
Q: The
visualizer was supposed to return a locator that's in the current structure,
but it didn't hilite!
A: Look in the bottom-right corner. Locators returned show up there.
Q: I'm
creating the visualizer directly from code, and it automatically shows up in a
gigantic size!
A: Set environment variable
VIZSIZE=SMALL before launching the visualizer.
Q: Who wrote
the visualizer?
A: The visualizer has been developed by:
Ryan Shaun Baker
Michael Boilen
Keith Schmidt
Lucy Perry
Lubomir Bourdev
Mark Handy
Marcin Romaszewicz
· The layout algorithms used in displaying tree-based structures sometimes align to the center and sometimes align to the left.
· When switching containers, the timeline sometimes returns to the bottom of the screen
· Clicking on an already selected locator does not deselect it, for tree-based structures. Workaround: click on a position without a locator.