Homework 3

Overview

• become familiar with KML files and how to integrate locations of interest into Google Earth,
• understand the recursive structure of tree data,
• explore different treemap layout algorithms,
• and refine a treemap visualization tool that lets you burrow into the directory structure of your computer's harddrive.

Part 1: Google Earth (30 points)

To begin, read through the kml examples page. Go through the exercise and explore the functionality and navigation of Google Earth.

Next, read through the kml geometry page. When you get to the exercise section, complete steps 1-4. Copy the example #2 file and rename it to GoogleEarth_1.kml. Modify this file to contain five locations that you visit on a typical day, such as home, work, school, coffee, gym, bar, library, etc. Note: you can get the coordinates of your locations by searching for an address in the Fly to bar, and then mousing over the destination --- your coordinates appear in the bottom left of the viewer, but you made need to change your Google Earth preferences to have them appear in latitude and longitude coordinates. Add descriptions for each of the locations, and also create a polygon for a building or point of interest at each spot. Save this file and include it with your write-up.

Go onto the next tutorial on kml symbolism. Again, read through the examples on this page. Copy your GoogleEarth_1.kml file and rename the copy GoogleEarth_2.kml. Modify your icons to be clocks that indicate the approximate time of day you arrive at each of your locations, and size each according to the relative amount of time you spend there. Finally, select a color mapping scheme using ColorBrewer for your five locations, and set the polygon colors according to the order in which you visit each location. Save this file and include it with your write-up.

Continuing on to the kml cartography page, work through the exercise section and answer the nine questions posed there in your write-up.

Finally, read about how to generate paths on the Google KML documentation page. Copy your GoogleEarth_2.kml file and rename the copy a GoogleEarth_3.kml. Add a path between each of your locations in the order in which you visit each spot. Save this file and include it with your write-up.

Part 2: Treemaps (70 points)

We start with an exercise on trees and recursion, followed by an exploration of (tree)map layouts in the Processing framework. The last part will involve combining these ideas to refine a Treemap tool.

Treemaps are 2-dimensional charts that map data with a tree-like structure (like file structures on your computer, categorization of cars, etc) to a rectangular area using a variety of algorithms that subdivide space. One of the key features of a treemap is that a user can click on any part of the display to burrow down and see that part's structure. The whole data structure is hierarchical, but different parts can be displayed by themselves. A historical overview of the development of treemaps can be found here.

To prepare for the following exercise, complete the following steps:

1. Download Fry's treemap library, unzip it and place the treemap folder into your sketchbook folder.
2. Download the following zip file containing all of the example code from the book -- download the zip file here and place in your Processing sketchbook directory.
3. Read carefully through Chapter 7 in the Fry book and work through the examples included in the above zip file. Each sketch is named according to the subsection title in the chapter.

The treemap library comes with some documentation, which is found in your treemap/reference folder --- open the index.html file in this reference folder. What's missing are just all of the comments. We've tried our best to provide explanations when needed.

Also, be aware that some of the code in the book contains bugs, and some of the descriptions are not accurate enough. Some comments:

1. pages 183 and 184: File.list never lists the . and .. directory entries. Thus, the following code is unnecessary:
   if (contents[i].equals(".") || contents[i].equals("..")) { continue; }
2. pages 183 and 184: sort() is not case-insensitive.
3. page 205 (in the draw() function): The following code
   if (mouseInside()) { taggedItem = this; }
   has to be moved to the if part of the first if-then-else statement. (Compare the code in from the book with the one that we provide.)

Submission Note: You do not need to include your applets in your write-up. Instead, make an applet directory in your write-up folder, and place each of the sketch directories that we describe below into this directory.

2.1) Getting Started: (Directory) Trees (10 points)

Open the Using_Recursion_to_Build_a_Directory_Tree sketch that we provided in the example directory, and save it as Ex_2_1. Download this example directory tree structure, unzip the file to reveal the directory structure, and replace "path" in Ex_2_1.pde with the location of this example directory (no slashes at the end). Add a function printLeafNodes(), which prints a list of all leaf nodes, to the Node class. We define leaf nodes to be files or directories with no "children" (the "B" directory in the example directory is also considered a leaf). Next, add println("Leaf Nodes:"); and rootNode.printLeafNodes(); to the end of the setup() function. When you run this, your program should print out a.txt - k.txt and the B directory.

Add another function printInternalNodes() to the Node class. This routine should print only internal (children) nodes (i.e., all nodes except the leaf nodes). Add println("Internal Nodes:"); and rootNode.printInternalNodes(); to the end of the setup() function to test it. When you run this, your program should print the following directories as internal nodes: example, A, C, E, F, D. The screen shot below is a print out of this:

Zip the sketch folder "Ex_2_1" and put it into the folder with your write-up.

2.2) The Mapping Part of Treemaps (30 points)

2.2.1) Setup

• Change i++ in the for loop in the setup() function to i += 20 such that only every 20th word is read in from the file. This is to keep the sketch speedy for now.
• Comment out noLoop() at the end of the setup function.
• Add in a functionality to turn the drawing of the word in the boxes on and off using the 'h'-key (you will need to add a keyPressed() function in Ex_2_2_1.pde file along with a global variable that you use in the WordItem class to flag whether or not to draw the words.

Next, you will add a "frame" around our treemap example so that we can later add some tabs:

• Define the following global variables: treemapWidth, treemapHeight, offsetX and offsetY, and set them to 1024, 600, 30, and 60 respectively. Change the arguments of the size() function, so that the window width is width = treemapWidth + 2*offsetX and its height is height = treemapHeight + 1.5*offsetY.
• Try running the sketch --- you should see that the size of the applet has changed, but that the treemap still fills the whole window. You must change the last four arguments of the following line in the setup() function using the previously defined variables: map = new Treemap(mapData, 0, 0, width, height);. The first two arguments define the upper left corner of the rectangle of the treemap, and the last two arguments its width and height. Make the bottom part of the frame half the width of the top part (i.e. the offsetY variable).
• Run the sketch and make sure that you get a frame around the treemap that looks like the one in the image below.



2.2.2) Layouts

In this part of the assignment you'll learn how to change the layout of a treemap by using different layout algorithms. Copy the previous sketch and rename the copy as Ex_2_2_2.

Go to the treemap documentation and search for all the classes that directly or indirectly implement the MapLayout interface. What are the names of the algorithms (Hint: there are eight if you skip AbstractMapLayout)? Include these names in your write-up.

Next, go to the documentation of the Treemap class. The following two methods are of interest: void setLayout(MapLayout algorithm) and void updateLayout(). The first method lets you change the underlying layout algorithm and the second method helps you to update to the before specified algorithm. Now, you will try out a new layout algorithm. Define a global variable mapLayout, pick an algorithm you would like to try and change the treemap layout by using setLayout() and updateLayout().

2.2.3) Good Ol' Tabs

Wouldn't it be great if we could compare the different layouts in one applet? For that we will use our old friend tabs. Copy the previous sketch and rename the copy as Ex_2_2_3.

Before we can draw different tabs we have to define an array of layouts and allocate memory for the different layout algorithms (again, eight in total). To do this, change the global mapLayout variable to an array of MapLayouts. Initialize the array in the setup() function (eight elements) and fill in the array with all the different Layout algorithms. It will also helpful to add another variable numOfMapLayouts and set it to the number of layouts. Finally, go to the documentation and find the interface MapLayout. The method void getName() will be important for displaying the name of the layout algorithm in the tabs.

NOTE: the StripTreemap is a bit buggy, so don't be too concerned if it doesn't work perfectly

Next, introduce the following global variables: tabLeft, tabRight, tabTop, tabBottom, tabPad, and current Tab. This is similar to the variables used in Chapter 4.

Introduce the following functions:

• void setCurrentTab(int tab)
• void mousePressed()
• void drawTitleTabs() --- Hint: If you use rectMode(CORNERS) and noStroke() at the beginning of the function you should add stroke(0.25f) and rectMode(CORNER) at the end to make sure that the treemaps are all drawn the same.

Finally, change between the different layout functions in the draw() function (by using the currentTab variable).

If you now click on the tab for the StripTreemap you'll notice that this is changing all the time. That's because it updates the layout every time it draws onto the screen. Let us fix that by introducing a global variable lastTab, and initialize currentTab to 0 and lastTab to 1. Go to the draw function, and test if the last drawn tab is not equal to the current tab, which means that we have to change algorithm and update the layout (and set the last tab to the current tab).

In your write-up, answer the following questions:

1. Two of the algorithm give the same layouts. Which ones?
2. What are each of the algorithms doing (you can describe this in descriptive terms based on what you observe)?
3. When would one type of layout be more effective then another? Think about types of data, characteristics of the data, etc.
4. For this dataset, which layout do you think is most effective? least effective? Why?

2.2.4) Color

Copy the previous sketch and rename the copy as Ex_2_2_4. Then, do the following:
• In WordItem: introduce a color field in the WordItem class, and initialize it in the constructor to white. In draw() (in WordItem) change the fill color fill() to this color.
• In WordMap: add a method updateColor() that updates the color of all the items. In the beginning of the updateColor() function, change the colorMode to HSB with ranges ([0,360],[0,100],[0,100]) for each of the color channels. Then, loop through all the items in WordMap and set each item's new color by mapping the index of the item in the array to the range of hue values (Hint: to set the color of an item, you will need a reference variable of type WordItem, and you will need to cast the item in the array to this variable type when storing it in the reference variable --- use this reference variable to update the color of the item). Change the color mode back to RGB at the end of the updateColor() function to keep the color state consistent for the rest of the program.

Below is a screenshot of what the range of colors should look like for one of the layouts:



In your write-up, discuss what color adds to the treemap visualization.

2.3) Treemaps (30 points)

For this part of the assignment you will be refining a treemap tool for visualizing the directories on your computer's harddrive, similar in spirit to the example in the Fry book.

2.3.1) Directories Can Be Leaves Too!

Open the Flying_Through_Files sketch and save it as Ex_2_3_1.

Replace the path in the main tab with the location of the example directory tree. Run the sketch. If you click on the "B" directory you realize that you can burrow into the directory structure even though it is an empty directory (i.e., a leaf), but that you can never get out again. Fix this by making changes to the code in the mousePressed() method of the FolderItem class. (Hint: Make changes to the part of the code which handles the mouse pressed event when the left mouse bottom is pressed.)

2.3.2) Alternating Layouts

Copy the previous sketch and rename the copy as Ex_2_3_2. Then, do the following:

Change the code in the FolderItem class so that it changes the treemap layouts based on the level. If the level is even it should be the same layout as the previous. If the level is odd you should change the layout to the slice layout.

2.3.3) Large Directory Trees and Showing Progress

For large directory trees the folder locks up until files have finished reading. We'll add the asynchronous reading mechanism described in the book, which makes it possible to show a progress bar, while the data is loading.

Copy the previous sketch and rename the copy as Ex_2_3_3. Then, do the following:

Add functions addFolder(), nextFolder() and drawStatus() to the main tab and make changes to the class FolderItem (follows the pattern of the book example). As long as the program is reading data you should display a progress bar similar to the following screenshot:



Once the reading of the directories is finished you should display the treemap (as in the previous part of this assignment). Hint: It could be that your whole tree is black at first --- think about the recursive color computation.

Change to a large directory tree (such as C:/ if you are feeling brave) to see whether your code is working.

---

Extra Credit: A memorable walk... (20 points)

Take a walk along your favorite section of the Charles, among your favorite buildings on campus, or through a favorite wooded area --- bring with you a digital camera and a means of recording you stops (if you have a GPS device, even better). Snap photos along the way and record the location of each picture well enough that you could find it again in Google Earth. If you don't have access to a digital camera, find pictures using Flickr or some other photo sharing site (NOTE: if you must download pictures, you may want to take your walk in a popular place such as the Boston Gardens to give you a better chance of finding photos online of your stops).

Write a KML file to share your walk and pictures using Google Earth. How you do this and what Google Earth features you use is entirely up to you. Explore the Google Earth Gallery for ideas, where you can also view the KML source code for the examples. We will award points based on how well you recreate your physical experience virtually.

Here's a zip file of everyone's memorable walks!

And here are some links from Doug Alan that can help make Google Earch photo mashups:
Goetagger
crosshairs
iPhotoToGoogleEarth


---

Submission Instructions

To submit your homework, create a folder named lastname_firstinitial_hw3, and place your write-up, Google Earth KML files, and Processing sketches into the directory. Compress the folder and send it as an email attachment to miriah@seas.harvard.edu.