Launch HyperCities

Author Archive

Landing View of a Collection
Image 1: Landing view of a HyperCities Collection.  The column on the right is called “Narrative View.”  The dark panel at the top is the main collection header, containing a brief general overview or introduction to the collection as a whole.  In the yellow band, you can operate the “Next” and “Previous” buttons to advance forward or backward through the objects.  In this collection, the objects are all contained inside subcollection folders.  Clicking on the subcollection folders opens those folders and reveals the objects and sometimes other subcollections.

Image 2: After opening a sub-collection, the map will re-locate to the site associated with the first object, which is highlighted. Use the Left-pointing arrow at the top of Narrative View, in the dark-colored sub-collection header, to return to the main collection.  Click on objects directly to view them and to re-locate the associated maps, or advance with the “Next” and “Prev” buttons.

Collection options

Image 3: Various options are available while viewing a collection.  A, B, C and D operate on the Google Maps/Google Earth navigation and mode.  The “x” box labeled “E” in this image will close the current collection and return you to the general HyperCities environment.  You can return to this collection from there by clicking on the “back” button on your browser.

Image 4: Click the center button (F) to center the map on the selected object’s default view. Click the checkbox (G) to turn that rich object on. Clicking anywhere on the textual description of an object will switch to that rich object and check the checkbox; clicking on the checkbox of an object other than the one that you are currently viewing will turn on the objects and maps in addition to the objects and maps of the object you are currently viewing.

Image 5: If Sync Map (H) is on, HyperCities will attempt to find a historical map for the object you are viewing if the object does not already have a historical map connected to it. This is off by default because many objects already have historical maps associated with them. Time format (I) adjusts the format of the time displayed in each object; it defaults to “date.” Auto ZoomIn (J) changes the map view to the view associated with each object as it is selected; this is on by default. 3D buildings (K) controls whether Google Earth’s own provided 3D buildings are displayed in Earth mode, and defaults to off.

If you have a map hosted on an ArcGIS Server, it’s possible to display that as part of a rich object in HyperCities. These maps will show up when a user views the rich object as part of the narrative. Here’s how:
1) Get the URL of the map’s MapServer service. This always ends in /MapServer. In the example below, this is You can find this by browsing the ArcGIS Server Services Directory:
A picture of a map service in the ArcGIS Server Services Directory
2) To add the map to HyperCities, create an object as normal. In the Add Media frame, click on the maps tab.
3) You will see a text box in the middle of the pane to enter the URL you just copied from the ArcGIS Server.
Type in or paste the URL of the map service here:
4) If you would like to use specific layers from the map service, add a slash (“/”) to the URL, then the layer numbers, each one separated by a comma. For example,,17.
5) Click on the “Plus” icon next to it. A map marked “WS Map” (for “webservice map”) will show up in the frame above it. If this was the correct URL, the map will then be overlaid on top of the HyperCities map. Loading the actual images of the map may take some time, up to 30 seconds. Please wait for the map image to be overlaid onto the map before moving onto the next step.
6) To remove the map or adjust its opacity, click on the arrow next to the map URL in the frame above the text box. This will show a box with controls for doing both of these things.
7) To add another map service, follow the same steps. You can delete the text in the URL bar once you’ve added the first map, but this is not necessary.
Please note: Maps entered this way are not added to HyperCities’ map database, but linked to the individual objects users add them to. This feature may be implemented later.

Yesterday, an NBC news crew visited UCLA to do a story about HyperCities Egypt. Today, the story was featured on <a href="" target="_blank”>NBC LA. The story contains a video interview with Yoh Kawano explaining the project. This has resulted in coverage for HyperCities from as far away as the Times of India. We are grateful to NBC for covering our project and for generating so much attention for HyperCities, and are excited that people continue to find the project exciting and informative.

HyperCities has released a new project for mapping tweets sent by protesters in Cairo during the recent crisis. The project, “HyperCities Egypt: Voices from Cairo through Social Media,” tracks tweets since January 30, and continues to collect tweets sent from within Cairo that mention hashtags relevant to the protests, such as #jan25 or #egypt. We hope that this project will both make the experience of the protests more immediate to users in other parts of the world, and provide an archive useful for historians, political scientists and scholars in media and communication studies. The project has been featured in a UCLA Newsroom article and has received attention from the Twitter community.

Screenshot of HyperCities Egypt

The tweets’ location is based on the locations that Twitter users provide in their profiles, or GPS coordinates supplied by mobile devices. To protect users, coordinates supplied by mobile devices are truncated so that they are only accurate to about a kilometer when they are displayed. The database stores more accurate locations, but these are currently not visible to the public.

The project is the brainchild of Todd Presner, Yoh Kawano, and David Shepard. It is based on a tool Kawano had previously developed for mapping tweets, which Shepard and Kawano modified to display tweets from a specific area relating to specific topics, and added the archiving feature. Source code will be available for download and modification soon.

To view the project, visit

Visualizing Statues in the Late Antique Roman Forum, a new HyperCities project, has just been released. Funded by a grant from the National Endowment for the Humanities, the project explores the purpose and use of statues of Roman emperors in the fourth and fifth centuries CE. These statues were located at precise spots in the urban landscape, and depended greatly on the surrounding terrain for effect; they illustrated continuities across the generations of rulers, and processions through the area implicitly brought absent rulers into the company of their predecessors, preserving memories of the political and military roles played by emperors.

The late antique statues of the emperors from the Roman Forum have disappeared over the millennia; this project returns each statue to its original context, within a large model of the Roman Forum. The project includes a map of all the statues and a database of all the inscriptions upon each statue; it also uses HyperCities’ guided tours to take the user through the statues from different perspectives, including a set of views that illustrates the significance of emperor Honorius’ procession at ground level.

Visualizing Statues in the Late Antique Roman Forum is the result of collaborative efforts among faculty members, and builds on other research done at UCLA. It uses the “Digital Roman Forum“, a model of the forum developed by the UCLA Experiential Technologies Center, which was completed in 2005. The Digital Roman Forum project led to an NEH-supported Summer Institute at UCLA entitled “Models of Ancient Rome,” taught by Professor Diane Favro together with Sander Goldberg and Chris Johanson. One outcome of the seminar was a series of discussions about ways to continue the research on the Roman Forum by focusing on the experiential issues raised by statues and the ritual use of public space during late antiquity. Through the Fellowships at Digital Humanities Centers program, the NEH funded Gregor Kalas’s year-long research at UCLA’s Experiential Technologies Center to pursue this research in collaboration with Favro and Johanson.

To view the project, please visit

Many users compose descriptive text in another program and then copy and paste it into HyperCities. This is actually a good option, because it allows you to do multiple drafts of the text before displaying it in HyperCities. If you do this, though, it’s best to use a plain text editor like Notepad (Windows) or TextWrangler (Mac), and do your formatting using the HyperCities editor, unless you know HTML. Avoid word processing programs like Microsoft Word; Word generates HTML that looks strange in HyperCities, so HyperCities edits most of this formatting out. In other words, doing the formatting in HyperCities saves you time.
If you would like to write your own HTML, here are some guidelines:
  • Only use tags that normally appear in the <body> portion of an HTML document. Anything in the <head> portion is discarded.
  • Use inline styles. CSS blocks (<style> tags) are removed by HyperCities for appearance and security. In the past, some cut-and-paste text from Word has changed the entire appearance of HyperCities because of conflicting style names or styles applied globally to all tags, e.g. <p>.
  • Links in HyperCities always open new windows. Anchor tags do not work in HyperCities content.
  • Clicking on images in HyperCities always opens them in our special photo viewer, which allows a user to see them in a larger size.
  • The following tags will be filtered out, and everything inside of them will be removed:
    • <head>
    • <script>
    • <style>
    • <iframe>
    • <form>
    • <input>
    • <select>
    • <blink>
  • For security reasons, all Javascript is filtered out.

HyperCities Geo-Scribe, a project proposal by the HyperCities team, has been selected to receive one of the first Google Digital Humanities Research Awards. Geo-Scribe will be an extension to HyperCities, a mark-up tool that brings together books and maps in a collaborative authoring environment for exploring the spatial dimensions of literature. The tool will allow users to create maps of places related to books, and each point on each map will be linked back to specific pages in the books. Users will be able to browse all books that mention a certain time and place, and to browse all the maps created by users that are linked to a specific book. Geo-Scribe emphasizes multiple mappings and multiple perspectives and will add a social, participatory component to the mapping projects that have already been undertaken by Google Book Search.

Below is a hypothetical screenshot of what the project might look like, taken from the proposal:


For more information, please see the announcement from the Official Google Blog:

When preparing a KML file produced by Google Earth, Google Maps, or by hand, it’s important to ensure that it’s compatible with HyperCities before uploading it. HyperCities supports most, but not all, of the standard KML tags. The following is a diagram of all the tags that HyperCities supports:

Tags recognized by HyperCities in a KML file.

Tags recognized by HyperCities in a KML file.

This diagram does not include elements that describe placemarks and folders, like “title”, but these should be interpreted correctly.

Please also note that the link, location, scale, and orientation tags onlywork if they are associated with a model, not a 2D object.

On the web, like in Project Muse or Wikipedia, citations generally take the form of endnotes: clicking on a note in a piece of text scrolls your browser to the bottom of the page, where the corresponding endnote is contained. This doesn’t work in Hypercities, unfortunately, but Hypercitities has something better: citations that open a new window with the text inside them. The procedure for creating these is a little bit complex, but it’s easy once you get the hang of it.

First, each citation must have a reference code unique within that particular piece of content. This code can be something as simple as ’1′ for the first one, ’2′ for the second, and so on, but the important thing is that they must be unique within the description of that particular object. You can reuse the same codes in different objects, even if they’re within the same collection. Codes are used to link the links (the piece of text you click on) to the text that is displayed in the window when it pops up. They can contain letters and numbers, but please avoid other characters or spaces.

Once you have your list of codes, you can begin to enter them. If the content is already in Hypercities, you enter it using the editor. You can also add them to a KML file if you’re planning to upload your collection as a KML file.

Using the edit window:


1) Open the edit window. Once it’s open, click on the HTML button.

Your text should look different now, with a lot of codes you didn’t see before between greater-than and less-than characters. This is because you are now editing the HTML code that controls how your text is displayed.


2) Find the piece of text you would like the user to click on to display the footnote.


3) Just before this piece of text, without a space, insert the following code:

<citation refcode=”ref1“>

Replace “ref1″ with the code for this citation.


4) After the text the user will click on to display the citation, you must close the tag. Again, right after that text, enter the following text:


Do this for all your citations.


5) At the very end of the document, you enter the text that will be displayed for each citation.

If not, what this means is that you need to create another list of all the text you want to create. Use the following template.

<CitationList> (This needs to appear before the first citation)

<citation refcode=”ref1“>Here is the text to be displayed</citation>

<citation refcode=”ref2“>Here is the text to be displayed for your second footnote</citation>

(Put more citations here)

</CitationList> (This needs to appear after the last citation)


HTML is allowed within the <citation> elements, but don’t put anything else between the <CitationList> and the <citation> tags inside it.

If you know XML, we are creating a CitationList element with citation children that have “ref” attributes with the same refcodes that you used before. The text of these children will be what is displayed in the new window when the user clicks on the link.

Please note: the text that the user clicks on to display the citation will automatically appear blue, superscripted, and underlined. Do not apply these styles yourself. In fact, if you put a <sup> tag around the text, it will be double-superscripted.

If you’re uploading a KML file, just follow steps 2-5, and make sure these all of this appears in the CDATA section of the description element of each object. The CitationList must also appear inside the CDATA element at the end of it.


Uploading a KML file is a relatively simple process. Reproducing a complex collection structure is less simple, however, but still fairly easy. Since each KML file you upload becomes its own collection, it takes some time to reproduce a complex collection structure. This article attempts to explain how to do this with the least pain possible:

1. Outline your collection hierarchy.

While it’s easy to change the hierarchy once your items are already in Hypercities, creating the hierarchy first will save you some time. For our example, let’s suppose we’re working on a project called “The Programmer and the Author,” and we have four files, houseofleaves.kml, infinitejest.kml, whitenoise.kml, and neuromancer.kml. Let’s also suppose we want to have the following hierarchy:

  • The Programmer and the Author
    • The 1980s
      • William Gibson, Neuromancer (neuromancer.kml)
      • Don DeLillo, White Noise (whitenoise.kml)
    • The 1990s
      • David Foster Wallace, Infinite Jest (infinitejest.kml)
      • Mark Z. Danielewski, House of Leaves (houseofleaves.kml)

2. Create the top-level collection.

This is the “meta-collection.” Once you’re logged in, go to “My Profile” and click on “Create a New Collection.”

how to create a new collection

how to create a new collection

Fill in the required information. In this case, the collection is called “The Programmer and the Author.” This collection may not show up in Hypercities yet because it doesn’t have anything in it.


3. Create any subcollections that will contain more than one collection.

Collections with more than one collection should be the next thing you add. Click on “Create a New Collection” again and enter the appropriate name, e.g. “The 1980s.” Be sure when you do this to add the collection to the collection it will be inside on the “Add To …” tab.


Here, we would add “The 1980s” to “The Programmer and the Author.” Again, these collections may not show up in Collection List view (though they will show up in the Add To … tab) if they have nothing in them.

4. Upload the KML into the appropriate place.

Now is when the real fun begins. Once you have created the collections, upload your first KML file. Click on the Add Media button.


The bottom button is the “Import K ML” button. Click on this.


In the window that pops up, fill in the required information. You must fill in a title, but this will be ignored if a name is specified in the file.


Once you have entered the appropriate information on the first two tabs, click on the Add To tab. Put this in the appropriate collection. Here, we would be putting whitenoise.kml into “The 1980s.”


Click the “submit” button.

Repeat the process for all the files. 5 critical keys to kill your cellulite

Helpful tips:

  • Before uploading your files, check them by opening them in Google Earth. This will validate that your KML is correct. If there’s a problem, it will frequently give you a more accurate assessment of what is wrong than Hypercities.
  • If you only want your sub-collections to appear as collections of the collection that contains them, be sure that the containing collection is the only collection checked in the “Add To …” tab. Otherwise, they will show up under any collections that have been checked.