Launch HyperCities

Archive for the ‘ How To ’ Category

KML (Draft)

by | August 1, 2013 | In How To No Comments

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 and create any subcollections that will contain more than one collection.

For more information on how to add a new collection, see http://hypercities.com/blog/2010/08/12/how-to-create-new-collection/

3. 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 KML” button. Click on this.

In the ‘Add Media” frame, 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 “My Collections” tab found at the bottom. Put this in the appropriate collection. Here, we would be putting the KML file into “The 1980′s.”

Click the “submit” button.

Repeat the process for all the files.

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 “My Collection” tab. Otherwise, they will show up under any collections that have been checked.
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 akbash.ats.ucla.edu:8399/arcgis/rest/services/Haynes/Mayoral_Election_2005/MapServer. 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, akbash.ats.ucla.edu:8399/arcgis/rest/services/Haynes/Mayoral_Election_2005/MapServer/6,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.

How to Create a Rich Object

by | September 10, 2010 | In How To No Comments

Unlike a regular object, a Rich Object isn’t just a specific region in space and time. A Rich Object is more useful for storytelling. It allows the creator to configure the viewport in a specific way to show the reader a particular configuration of maps and objects. Its real power emerges in narrative mode.

To understand the difference, let’s go through the features of a regular object. It has:

  • A defined region on the map
  • A specific timespan
  • A title
  • Descriptive text, images, video, etc.

To this, a rich object adds:

  • A specific view in the viewport (center point and zoom level in 2D mode; tilt, pan, etc. in 3D mode).
  • One or two historic maps, whose transparency can be set
  • A specific base map (such as a satellite map or a blank map); you may also set it to open in Earth mode
  • A set of objects or collections that are turned on
  • The ability to set which object has a bubble on over it, and the state (minimized or maximized) of that bubble

Creating a rich object uses the same interface as creating a regular object; it just requires using more features. It can be any of the basic types of objects (point, line, polygon) or even a KML link. This tutorial will cover features common to creating all rich objects. Here’s how to do it.

First, without clicking the Add Media Button, use the Map List to select the maps you would like to have on in the background. You can change which maps you have on later, but you can’t change their transparency. As usual with HyperCities, you may select up to two maps. The maps will always show up with the last one you selected on top.

Once the map is on, set the transparency using the transparency slider, or leave it totally opaque.

Now, using the Collection List, you may also select the objects you want to turn on with your rich object. You have the option to change this later.

Now, click on the Add Media button as you would regularly to create a normal object. Once you draw the shape you would like to have, the Add Media panel will pop up. Fill in the fields as you would normally; if you’re creating a KML network link, paste the URL into the appropriate field.

In addition to the regular options, you will see the options “Select Base Map” and “Select Other Items” here (hover over the buttons if you’re unsure which is which). You can see both of these in the picture below. The “Select Base Map” button allows you to delete or add more map to your object; however, you can no longer set the transparency of the maps you choose from this point. This has to be done in the Map List.

The “Select Other Items” button lets you select more items you want to turn on with your rich object. You can also uncheck items that you have chosen earlier.

If you would like to have an object show up with its info bubble open, click on the object. You may also expand the info bubble.

Also, adjust the viewport as you would like your reader to see it, as you would normally with Google Maps or Google Earth. The view will be preserved exactly as you leave it. You may also choose whether the object will be viewed on Satellite, Map, Hybrid, Terrain, Earth, or even on a completely blank map; do this using the map type selector in the upper-right hand corner of the map (it says “Earth” in the picture below).

Once you’re finished making these adjustments, select one or more collections to put your new Rich Object inside, and click the “Save” button. When you click “Save”, the entire state of the object at that point — maps, viewport, objects, etc. — will be saved.

To view the rich object you have created, view the collection where it was saved in “Narrative Mode.” Each object should open the view exactly as you left it.

To edit the object, edit it as you would a regular object (find it in a collection, check it on, and click the edit button). The viewport will adjust to reflect the way you left it. Please note that any adjustments you make to the viewport will be saved at the moment you click “Save.”

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.

How to Create an Object

by | August 19, 2010 | In How To No Comments

On the upper left corner of Hypercities, click on the “Add Media” button. Clicking it shows the three types of objects that HyperCities allows: points, lines, and polygons.
<img class="alignnone size-full wp-image-360" src="http://hypercities.com/files/2010/08/add-buttons2.jpg” alt=”add buttons2″ width=”500″ />

A point is just a single place on a map, which can be represented by an (x,y) coordinate pair.

A line is used to trace a path. It can contain many vertices, and can be used to form shapes.

A polygon is a shape. Clicking inside a shape activates the polygon; this is the difference between a polygon and a line. Clicking inside a closed line does not activate the info bubble for that object. Clicking inside a polygon does.

Once you have chosen what kind of object you want to create and its location, you will see the “Add Media” frame on the right.

addmediainterface

Here you can set the title of your object, timespan,  license, and description of the object.

Author name is automatically filled in from the nickname you supplied when you registered. The author name can be changed individually for any object.

To set the time, you can type the year, month and date by either clicking on the fields or tabbing between them. You can also use the arrow keys to change these numbers. Typing “-” (the minus sign) toggles between “BCE” and CE (when “BCE” is not displayed). The date on the right must always be later than the date on the left; HyperCities will prevent you from entering an end date earlier than the start date, and vice versa.

The description field allows rich formatted text. To edit the HTML source, click on the “HTML” icon.

A note: many users compose the descriptive text in another program and then copy and paste the text into HyperCities. If you do this, it’s best to use a plain text editor like Notepad (Windows) or TextEdit (Mac), and do your formatting in HyperCities itself, unless you know HTML. Avoid word processing programs like Microsoft Word; Word generates HTML that look stranges when it is displayed in HyperCities. HyperCities also edits out some formatting that Word puts in, so generally, it’s best to write the text in Notepad (or TextEdit), without formatting, and use HyperCities to do the formatting. The HyperCities text editor is WYSIWYG (what you see is what you get).

Add images by clicking the “Insert/Upload Image” icon. Videos, however, must be hosted on other video websites such as YouTube, Vimeo, etc., and they can be embedded on Hypercities by copying and pasting the embed code from the hosting service.

To display base maps with your object, click on the “Select Base Map” button. This shows a list of maps that are visible in the current viewport and timespan. To select a map, just click on it. Use the “x” near the map to remove it.

basemap

If you want other objects to show up with your object, click on the “Select Other Items” button. You can use this window just like the regular collection list. Just check the items on that you want to appear.

selectotheritems

Once you’re done, save your object by clicking “SAVE” on the lower right corner.

Click here to see how to add your object in a collection.

This tutorial is about creating a new collection and editing an already

existing collection or a new one.

     

  • Creating a New Collection

Creating a new collection requires you to go to the add media interface.

 

At the bottom of the “add media” frame, click the “My Collection” box and click on “Create New.”

 

Type in the desired new collection name, and click OK.
create collection name

 

Once you click OK, your collection will be inside “My Collections.”

 

  • Editing a Collection

To add your collection into an already existing collection, edit your collection by viewing it in Narrative mode. To do this, click on the Narrative Mode Button.

 

In the Narrative Mode, you will see different options such as “Expanded View,” List View,

” “Edit Collection Info,” and “Delete Collection.” To edit the collection, click the “Edit Collection Info” button.

 

Click “My Collection” box at the bottom of the “Edit” frame. Then search for and select the name of the collection you want to put your new collection into.

 

Click SAVE and your new collection will be added automatically into the collection you just selected.

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:

</citation>

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.

Sample:

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.

Nested-2

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.

Nested-3

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.

Nested-4

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

Nested-5

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.

Nested-6

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.”

Nested-7

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.