Advanced Search

feature

How to contribute to the IPY KML layer

We’re building a KML layer that collects geospatial information produced by IPY-endorsed projects. This short manual shows you how to format your project’s data in a KML file for inclusion in the IPY layer.

To help tell the IPY story as effectively as possible, we’ve created a standard set of icons, as well as standard popup window styles, which all contributors to the IPY layer can share. There are 8 different icons depicting different kinds of data, in 4 different colors; that’s 32 icon variations. In addition, we have 2 different styles of popup window for each icon — totalling 64 different style permutations.

Here are the icons:

image

Here are the two popup window styles:

image

image

By using common elements, we avoid a cacophony of styles, keep things simple, make it easier to update styles centrally, and in general save everybody a lot of time. All narrow popup windows sport the IPY logo at the top, and all wide popup windows sport the IPY logo and links in the sidebar.

Let’s take a look at how to style the simplest kind of content — annotated placemarks.

First, create a text file. At the start, place <Folder>. At the end, </Folder> (this is case sensitive). Between these tags, you can add as many placemarks as you like, and you can group series together in successive layers of folders using <Folder> tags.

A simple placemark for the IPY KML file looks like this:

<Placemark>
    <name>Placemark name (visible as the icon label)</name>
    <Snippet maxLines="0"></Snippet>
    <description>
        <![CDATA[
            <table border=0 width=’100%’>
                <tr>
                    <td>
                        <p>Sample main text.</p>
                    </td>
                </tr>
            </table>
        ]]>
    </description>
    <address>
        <![CDATA[
            <p>Sample sidebar text I.</p>
            <p>Sample sidebar text II.</p>
        ]]>
    </address>
    <styleUrl>#stylename</styleUrl>
    <Point>
        <coordinates>0,50,0</coordinates>
    </Point>
</Placemark>


Let’s go through each element in succession:

<name>Placemark name (visible as the icon label)</name>

This is where the icon’s label resides, visible when the placemark is visible. You should change the name of each placemark so that it accurately describes its contents — for example a date, or a name of a location, or a measurement value.

<Snippet maxLines="0"></Snippet>

This is a hack to keep the Places sidebar in Google Earth clean. You don’t need to change anything here.

<description>
    <![CDATA[
        <table border=0 width=’100%’>
            <tr>
                <td>
                    <p>Sample main text.</p>
                </td>
            </tr>
        </table>
    ]]>
</description>


This is where you put the main content related to the placemark. The HTML code for the table is a technique for keeping the popup window well structured, and doesn’t need to change. You can put as much content as you like between the <td> tags. Text should go inside <p> tags, but you can also add images. Most simple HTML markup works here. You can add <img> tags — images should not be more than 500 pixels wide.

<address>
    <![CDATA[
        <p>Sample sidebar text I.</p>
        <p>Sample sidebar text II.</p>
    ]]>
</address>


We are repurposing the <address> tag so that you can put extra information into the sidebar of the popup window below the IPY logo, if you want to. Important: Only some placemark styles show the sidebar in the popup window. (See below for more on style names.)

Note to that you can add <img> tags in the sidebar, for example for a project logo. Sidebar images should not be wider than 135 pixels.

<styleUrl>#stylename</styleUrl>

This is the line where you choose a style, which determines the kind and color of the placemark, and the kind of popup you want for the placemark .

There are 4 colors to choose from: “gray”, “green”, “blue” and “lightblue”.
There are 8 icons to choose from: “animals”, “camp”, “flag”, “measure”, “person”, “photo”, “target” and “x”.
There are two popup styles to choose from. There is the normal style, and then there is the “mini” style.

You create a style by combining these names into hyphen-delimited names, like one of the following:

<styleUrl>#green-camp-mini</styleUrl>
<styleUrl>#blue-flag</styleUrl>
<styleUrl>#lightblue-person-mini</styleUrl>
<styleUrl>#gray-animals</styleUrl>
<styleUrl>#gray-animals-mini</styleUrl>

All styles names ending in “-mini” do not show the sidebar, and hence do not show content placed inside the <address> tags, even if <address> tags are present. If you are using the “-mini” style for a placemark, then there is no need to have an <address> tag in your placemark.

In a style name, the color always comes first, followed by the icon name, followed by “mini” if you want the narrow popup — separated by hyphens. There are 32 “#color-icon” combinations, and 2 popup window styles, for a total of 64 permutations.

<Point>
    <coordinates>0,50,0</coordinates>
</Point>


This is the coordinate data for a placemark. The first element is the longitude, then latitude, then height, in meters. It’s common to keep height at 0.

How to use Styles:
It is recommended to use the different colors to represent different series of placemarks: for example, different expeditions, or different measurement series. The icons are there to help differentiate placemark functions: “animals”, for example, is suitable for animal tracking data; “camp” is suitable for successive camp locations; “measure” can be used for depicting measurement data, etc…

As for the popup windows: The “mini” styles provide a narrower popup window, which means that less of the screen is obscured when an icon is clicked. One suggestion is to use the “mini” styles for the bulk of a series, and to use popups with the sidebars for folders.

Here is how to give folders a popup window:

<Folder>
    <name>Folder name that appears in the Places sidebar</name>
    <visibility>1</visibility>
    <Snippet maxLines="0"></Snippet>
    <description>
        <![CDATA[
            <table border=0 width=’100%’>
                <tr>
                    <td>
                        <p>Sample main text.</p>
                    </td>
                </tr>
            </table>
        ]]>
    </description>
    <address>
        <![CDATA[
            <p>Sample sidebar text I.</p>
            <p>Sample sidebar text II.</p>
        ]]>
    </address>
    <styleUrl>#stylename</styleUrl>
    
    <Placemark> ... </Placemark>    
    <Placemark> ... </Placemark>
    
</Folder>


You can give a folder any of the possible style names; the only aspect of a style that matters to a <Folder> tag is whether the popup window is narrow ("mini") or contains a sidebar.

If a placemark contains a <LineString> or other line geometry instead of a <Point>, then this line will be depicted as being 4 pixels wide, and of a color equal to the color of the corresponding style name — “green” styles produce green lines. Remember to use “green” or “lightblue” styles for line geometry drawn over oceans, to enhance the contrast.

Send the completed file to ipy.ipo@gmail.com for inclusion in the IPY KML layer.

If you’ve made it this far, consider joining the Geobrowsers for IPY Google Group, for polar scientists interested in publishing their data to a geospatial layer.

Questions? Feedback? Email stefan.geens@gmail.com. If you want to create something more complex, such as a dynamically created network link or a frequently updated dataset, contact us.