Tips for how to write in KML (for the by pgh12747

VIEWS: 50 PAGES: 10

									                Tips for how to write KML files for the polar regions
                       Written by: Lisa Ballagh and Ross Swick

What is KML?

KML stands for Keyhole Markup Language. Google has created web pages that explain
how to use KML and the site provides several examples using the KML syntax. Visit the
KML documentation for further details: http://earth.google.com/kml/.

How to use KML example

For starters, download Google Earth to your local computer (http://earth.google.com).

You can open a KML file with any text editor, such as Microsoft Word on a Windows
computer or vi on a Unix system. If you copy and paste the sample KML code below
into a text editor and save the file with a .kml extension with UTF-8 encoding, then you
will have a KML file. Double click the KML file to launch Google Earth.

Sample KML code:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.0">
<Document>
<name>NSIDC</name>
<description>http://nsidc.org</description>
<LookAt>
      <longitude>-90</longitude>
      <latitude>45</latitude>
</LookAt>
<Folder>
<name><a href="http://nsidc.org/data/ggd318.html">Circum-Arctic
Permafrost</a></name>
<GroundOverlay>
  <name>Permafrost Map</name>
  <color>aaffffff</color>
  <visibility>1</visibility>
  <LookAt>
      <longitude>-90</longitude>
      <latitude>60</latitude>
  </LookAt>
  <Icon>
    <href>http://nsidc.org/cryosphere/images/google_pf_map.png
</href>
  </Icon>
  <LatLonBox id="ipa_map">
    <north>90</north>
    <south>24.999</south>
    <east>180</east>
    <west>-180</west>
    <rotation>0</rotation>
  </LatLonBox>
</GroundOverlay>
<ScreenOverlay>
  <name>Permafrost Legend</name>
  <color>aaffffff</color>
  <visibility>1</visibility>
  <Icon>
  <href>http://nsidc.org/cryosphere/images/permafrost_legend.png</href>
  </Icon>
  <overlayXY x="0" y="0" xunits="fraction" yunits="fraction"/>
    <screenXY x="5" y="25" xunits="pixels" yunits="pixels"/>
</ScreenOverlay>
</Folder>
</Document>
</kml>

The KML code above will make the permafrost image appear on the Earth shown below:




Brainstorming

Before you start writing KML code, think about the polar data you plan to put into
Google Earth. Ask questions such as:
What type of data do you have?
       If you have point data use KML’s Placemark tag.
       If you have vector (line) data use KML’s Geometry tags.
       If you have raster data use ground overlays (using KML’s GroundOverlay),
       reprojected to a cylindrical equidistant (CE) projection.

       If you have ancillary information to display on the screen (logo, legend, etc.) use
       KML’s ScreenOverlay tag.

Will the KML be updated frequently?
       If so consider using a network link (using KML’s NetworkLink tag).

Will the image(s) change frequently?
       If yes consider using the refresh tag (using KML’s refreshInterval tag).

Is there a web server the images could be posted to?
        If yes, you can reference the images on the Web.
        If not, you can zip the image with the KML into a self contained KMZ file.

What projection are the data in?
      Polar data are generally distributed in a polar projection. However, Google Earth,
      and many other virtual globes, only work with images in a CE projection. You
      will probably have to reproject your data.

What format is the data in?
      If you are working with raster data, you will probably need to convert your data to
      an image.

Differences between “data” and “image”

Data refer to actual data, such as air temperatures at a specific point. The term image
refers to an image made from data.

KML syntax and examples

The following sections explain how to use GroundOverlay, ScreenOverlay and
Placemark syntax. Sample images are shown in addition to KML code used to reference
the image.

“GroundOverlay”

A GroundOverlay wraps an image over the Earth. For example, the image below shows
a GroundOverlay of sea ice extent in September 2005 (in white) along with the median
ice edge (in pink) for 1979-2000. Notice how the sea ice looks overlaid on the Earth.
Here is a portion of KML code that generated the ground overlays of sea ice extent and
the median sea ice line in the image above.

<GroundOverlay>
<name>Data</name>
<visibility>0</visibility>
<Icon>
<href>http://nsidc.org/data/google_earth/seaice/extent_0905.png</href>
</Icon>
<LatLonBox id="sie_all">
   <north>90</north>
   <south>-90</south>
   <east>180</east>
   <west>-180</west>
   <rotation>0</rotation>
 </LatLonBox>
</GroundOverlay>

<GroundOverlay>
<name>Median</name>
<visibility>1</visibility>
<Icon>
<href>http://nsidc.org/data/google_earth/seaice/median_09.png</href>
</Icon>
<drawOrder>2
</drawOrder>
  <LatLonBox id="sie_sep">
   <north>90</north>
  <south>-90</south>
  <east>180</east>
  <west>-180</west>
  <rotation>0</rotation>
 </LatLonBox>
</GroundOverlay>

Images used as ground overlays must be in a cylindrical equidistant projection. This
cylindrical projection ensures that the coverage area is well defined by a lat/lon bounding
box as in the example above. Having the image in this projection simplifies the task of
wrapping the image onto the globe. A commonly used cylindrical equidistant projection
is the Equatorial Cylindrical Equidistant (ECE) projection, also known as the lat/lon,
geographic, and Cartesian projection.

Once in a suitable projection the data needs to be reformatted to an acceptable image
format. Google Earth accepts images in specific image formats, such as PNG, JPG, TIFF
or GIF formats (see the KML documentation for more information:
http://earth.google.com/kml/). We recommend PNG or GIF as these image formats
allow for making some areas of the image transparent. We also suggest making the areas
of the image with no data transparent so the underlying default layer in Google Earth can
show through.


“ScreenOverlay”

A ScreenOverlay allows you to place images on the screen. The following KML places
the National Snow and Ice Data Center’s (NSIDC) logo, the title and legend graphic, and
the date graphic in the upper left corner of the image above.

<ScreenOverlay>
<name>NSIDC logo</name>
<color>ffffffff</color>
<visibility>1</visibility>
<Icon>
<href>http://nsidc.org/images/logo_nsidc_115x90.jpg</href>
</Icon>
<overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<screenXY x="5" y="5" xunits="pixels" yunits="insetPixels"/>
<size x="115" y="90" xunits="pixel" yunits="pixel"/>
</ScreenOverlay>

<ScreenOverlay>
 <name>Legend</name>
 <color>ffffffff</color>
 <visibility>1</visibility>
 <Icon>
 <href>http://nsidc.org/images/data_title.png</href>
 </Icon>
 <overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
 <screenXY x="125" y="5" xunits="pixels" yunits="insetPixels"/>
<size x="250" y="70" xunits="pixel" yunits="pixel"/>
</ScreenOverlay>
<ScreenOverlay>
<name>Date</name>
<color>ffffffff</color>
<visibility>1</visibility>
<Icon>
<href>http://nsidc.org/data/google_earth/seaice/extent_label_0905.png</href>
</Icon>
<overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<screenXY x="125" y="75" xunits="pixels" yunits="insetPixels"/>
<size x="250" y="20" xunits="pixel" yunits="pixel"/>
</ScreenOverlay>

“Placemark”

A placemark allows you to designate a point on the globe. Typically the point is marked
with an icon of a pushpin. Clicking the mouse on the icon opens a pop-up that includes
the name and description of the placemark. If either the name or the description contains
html code, that information will be properly displayed in the pop-up. The picture below
shows a placemark for a buoy in the Arctic Ocean. The pop-up contains the data the
buoy recorded at 8:00 PM the night of May 7, 2003




Here is the KML code that generated the placemark above:

<Placemark>
<name>2003-5-7 20:00</name>
<description>2003-5-7 20:00
<br></br> Location: (89.0840, 75.1330)
<br></br> Air Temp 1: -14.12
<br></br> Air Temp 2: -13.93
<br></br> Pressure: 1017.95
<br></br> Wind vector (u): -6.96
<br></br> Wind vector (v): -11.05
<br></br> Wind Speed: 13.06
<br></br> Wind Direction: 212.2
<br></br>
</description>

<LookAt>
<longitude>75.1330</longitude>
<latitude>89.0840</latitude>
<altitude>1000</altitude>
<range>350000</range>
<tilt>0</tilt>
<heading>212.2</heading>
</LookAt>

<IconStyle>
<Icon>
<href>http://maps.google.com/mapfiles/kml/pal5/icon13.png</href>
</Icon>
</IconStyle>

<Point>
<coordinates>75.1330, 89.0840, 0</coordinates>
</Point>
</Placemark>

Note the coordinates contain longitude, latitude, and altitude (in this order) in the
<coordinates> line above. Altitude is an optional parameter.

The same method can be used to show an image from a web page in a pop-up. Any html
included within the <description> tags of a placemark will be displayed in the pop-up for
that placemark. This includes <img> tags. The image blow shows a pair of photographs
of the Harvard Glacier, Alaska, in the pop-up window obtained by clicking on the
pushpin for the Harvard Glacier.
The code that generated this placemark and pop-up appears below. Note the use of the
CDATA tag. If more complex html is to appear in the description it is useful to
encapsulate it in a CDATA tag. Also note the <Snippet> tag, this prevents the
description from appearing in the left hand menu in Google Earth.

  <Placemark>
    <name>Harvard</name>
    <Snippet></Snippet><description><![CDATA[
      <table border="0" cellspacing="2" width="350" align="center">
      <tr align="left"><td colspan="2"><a href="http://nsidc.org/"><img
src="http://nsidc.org/images/home_banner2.gif" width="435" height="82"
/></a></td></tr>
      <tr align="center"><td colspan="2"><hr /><font
size="6"><b>Harvard Glacier</b></font><br /><font size="5"><b>Alaska
(USA)</b></font></td></tr><tr align="center"><td colspan="2"><font
size="4">Latitude: 61.6944&deg;N, Longitude: -147.7&deg;W</font></tr>
      <tr align="center"><td colspan="1" border="1"><a
href="http://nsidc.org/cgi-
bin/gpd_deliver_jpg.pl?harvard1909070102"><img
src="http://nsidc.org/data/glacier_photo/thumbnails/harvard1909070102.j
pg" width="150" height="100"
/></a></td><td colspan="1"><a href="http://nsidc.org/cgi-
bin/gpd_deliver_jpg.pl?harvard2000090301"><img
src="http://nsidc.org/data/glacier_photo/thumbnails/harvard2000090301.j
pg" width="150" height="100"
/></a></td></tr>
      <tr align="justify">
             <td width="50%" align="center">
                   <b>Photographer:</b> Ulysses Sherman Grant<br />
                   <b>Photograph date:</b> 1909
             </td>
          <td width="50%" align="center">
                   <b>Photographer:</b> Bruce F. Molnia<br />
                   <b>Photograph date:</b> 2000
             </td>
      </tr>
      <tr height="6"><td colspan="2"><hr /></td></tr>
      </table>
      <table border="0" cellspacing="0" cellpadding="0" width="450"
align="center">
      <tr align="center">
             <td width="45%"><a
href="http://nsidc.org/sotc/glacier_balance.html">Glaciers and climate
change</a></td>
             <td width="10%"><a href="http://nsidc.org/glaciers/">All
about glaciers</a></td>
             <td width="45%"><a
href="http://nsidc.org/data/g00472.html">Online Glacier Photograph
Database</a></td>
      </tr>
      </table>]]></description>
  <Point>
      <coordinates>-147.7,61.6944,0</coordinates>
  </Point>
  </Placemark>

Note that the values between the <coordinate> tags are comma separated with no spaces.
This is important when/if you wish to create lines, polygons or complex geometries in
KML. Lines and polygons are a series of space separated points, where points are
comma separated values, all within the same coordinates tags. For more information see
the KML documentation at: http://earth.google.com/kml/kml_tags_21.html#geometry

Network Links

If the data are going to get updated, we recommend using NetworkLinks in your file.
NetworkLinks are tags used in KML to point to other KML files. For example, if you are
updating a data set, you can update one KML file and others viewing the KML with
NetworkLinks will always have the latest information. The following code is a complete
KML file that references another KML file on the web.
<?xml version="1.0"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<NetworkLink>
<name>National Snow and Ice Data Center</name>
<visibility>0</visibility>
<open>0</open>
<Snippet maxLines="0"/>
<Url><href>http://newice.colorado.edu:8000/data/google_earth/sea_ice/si
etl.kml</href></Url>
</NetworkLink>
</kml>

Save the KML file in the UTF-8 encoding with a .kml extension.

If you add this file to the “My Places” directory in Google Earth, every time you open the
folder the KML file on the Web will get referenced. This way you will always have the
latest copy of the KML automatically.

Acronyms used throughout the document

KML = keyhole markup language
KMZ = compressed keyhole markup language file
NSIDC = National Snow and Ice Data Center

								
To top