Google KML 起步教程笔记（一）基本 KML 文档

原文地址：http://code.google.com/intl/zh-CN/apis/kml/documentation/kml_tut.html#placemarks

KML 是一种文件格式，用于在 Google 地球浏览器（Google 地球、Google 地图和 Google 地图移动版）中显示地理数据。KML 使用基于标记的结构，含有嵌套的元素和属性，并符合 XML 标准。所有标记都区分大小写，而且完全如 KML 参考中列出的那样显示。该参考指出了哪些标记可选。给定元素内，标记必须按照参考中显示的顺序显示。

如果您是 KML 的新用户，请浏览该文档和附带的示例文件（SamplesInEarth 和 SamplesInMaps），开始了解 KML 文件的基本结构和最常用的标记。第一部分说明了可以用 Google 地球用户界面创建的地图项。这些地图项有：地标、说明、地面叠加层、路径和多边形。第二部分说明需要用文本编辑器编写的 KML 地图项。用 .kml 或 .kmz 扩展名保存文本文件时，Google 地球浏览器会知道如何显示它们。

1 基本 KML 文档

最简单的 KML 文档类型就是那种可直接在 Google 地球中编写的文档，—也就是说您无需在文本编辑器中编辑或创建任何 KML。地标、地面叠加层、路径和多边形都可以直接在 Google 地球中编写。

地标

地标是 Google 地球中最常用的地图项之一。它会使用黄色图钉作为图标，在地球表面标记出位置。最简单的地标只包含一个 <Point> 元素，它指定地标的位置。您可以指定地标的名称，使用自定义的图标，还可以为地标添加其他几何元素。

在 Google 地球中打开 KML Samples 文件，并展开 Placemarks 子文件夹。该文件夹包含三种不同类型的地标：简单、浮动和凸出。简单地标的 KML 代码如下：

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
  <Placemark>
    <name>简单地标</name>
    <description>连到地面。智能地将它自己置于下面的地形高度。</description>
    <Point>
      <coordinates>-122.0822035425683,37.42228990140251,0</coordinates>
    </Point>
  </Placemark>
</kml>

该文件的结构分解如下：

• XML 报头。这是每个 KML 文件的第一行。该行之前不能有空格或其他字符。
• KML 名称空间声明。这是每个 KML 2.2 文件的第 2 行。
• 包含以下元素的地标对象：
  • 用于标识地标的名称
  • 连接到地标的"球形框"中显示的说明
  • 定义地标在地球表面位置的点 － 经度、纬度及高度（可选）。

如果您想知道该地标在哪里，它就在 Google 的 41 号楼，我们开发 Google 地球的地方！

用户通常认为的 Google 地球中的“地标”，实际上是一个 <Placemark> 元素，有一个 KML 的 <Point> 子元素。点地标是您在 Google 地球的 3D 查看器中绘制图标和标签的唯一途径。默认情况下，该图标是您熟悉的黄色图钉。在 KML 中，<Placemark> 可包含一个或多个几何元素，例如 LineString、Polygon 或 Model。但只有具有点的 <Placemark> 可以有图标和标签。点用于放置图标，但点本身并无图形表示。

地标中的描述性 HTML

KML Samples 文件中有一个示例，演示了您可以对地标文本执行的几乎所有操作。您可以添加链接、字体大小、样式和颜色，并指定文本对齐和表。如果您希望看到完整的列表，请复制并粘贴 “说明性的 HTML”地标示例（在“Styles and Markup”文件夹中）至文本编辑器。

Google 地球中的自动标记（发行版 4.0 及更高版本）

Google 地球 4.0 具有自动标记功能，能将 www.google.com 这样的文本自动转换成用户可以点击的超链接。<description> 标签、<Snippet> 标签和 <BalloonStyle> 的 <text> 元素内的文本都会自动转换成标准 HTTP 超链接。您无需自行添加 <a href= ...> 标签。

使用 CDATA 元素

如果您想在 <description> 标签内编写标准的 HTML，可将它放在 CDATA 标签内。如果不想，必须写上尖括号作为实体引用，避免 Google 地球错误地对 HTML 进行语法解析（例如，符号 > 写为 &gt;，符号 < 写为 &lt;）。这是标准的 XML 并非 Google 地球独有。

请考虑带和不带 CDATA 标签的 HTML 标记的不同。首先，下面是带有 CDATA 标签的 <description>：

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
  <Document>
    <Placemark>
     <name>CDATA 示例</name>
      <description>
        <![CDATA[
            <h1>CDATA 标签很有用！</h1>
            <p><font color="red">文本<i>可读性更强，</i>并且<b>更容易编写，</b>同时您可以避免使用实体引用。</font></p>
        ]]>
      </description>
      <Point>
        <coordinates>102.595626,14.996729</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>

以下是不带 CDATA 标签的 <description>，这样特殊字符必须使用实体引用：

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
  <Document>
    <Placemark>
<name>实体引用示例</name>
      <description>
	        &lt;h1&gt;实体引用输入很麻烦！&lt;/h1&gt;
	        &lt;p&gt;&lt;font color="green"&gt;文本 
&lt;i&gt;可读性更强&lt;/i&gt; 
并且&lt;b&gt;更容易编写&lt;/b&gt; 
同时您可以避免使用实体引用。&lt;/font&gt;&lt;/p&gt;
      </description>
      <Point>
        <coordinates>102.594411,14.998518</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>

地面叠加层

地面叠加层可让您在 Google 地球的地形上"叠加"图像。<Icon> 元素包含了指向叠加图像 .jpg 文件的链接。以下是 KML Samples 文件中的地面叠加层示例，展示 2001 年喷发的埃特纳火山：

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Folder>
    <name>地面叠加层</name>
    <description>地面叠加层示例</description>
    <GroundOverlay>
      <name>地形上的大尺度叠加层</name>
      <description>叠加层显示 2001 年 7 月 13 日喷发的埃特纳火山。</description>
      <Icon>
        <href>D:\TDDOWNLOAD\etna.jpg</href>
      </Icon>
      <LatLonBox>
        <north>37.91904192681665</north>
        <south>37.46543388598137</south>
        <east>15.35832653742206</east>
        <west>14.60128369746704</west>
        <rotation>-0.1556640799496235</rotation>
      </LatLonBox>
    </GroundOverlay>
  </Folder>
</kml>

请注意，文件开始两行与第一个示例相同：XML 报头和 KML 名称空间声明。

该示例使用文件夹<Folder>（倾斜的"地面叠加层"）作为分组和标记其内容的机制。请注意您将 KML Samples 文件载入 Google 地球中时，文件夹是如何在“位置”面板中显示的。

地面叠加层<GroundOverlay>的定位由 <LatLonBox> 标签控制。边框值以南纬、北纬和东经、西经形式给出。此外，旋转值是针对 y-轴与网格北端不重合的图像而给出的。该示例对叠加层使用 JPEG 图像。Google 地球还支持 BMP、GIF、TIFF、TGA 和 PNG 格式。

路径

Google 地球中可创建许多不同类型的路径，而且可以毫不费力地创造性地使用您的数据。在 KML 中，路径是用 <LineString> 元素创建的。看一看 Paths 文件夹中“Absolute Extruded”示例，您就会明白如何用以下代码来生成形状：

格式如下：西经,北纬,高度

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Document>
    <name>路径</name>
    <description>路径示例。请注意，tessellate 标签默认
      设置为 0。如果您想创建 tessellate 线，它们必须直接用 KML 
      编写（或编辑）。</description>
    <Style id="yellowLineGreenPoly">
      <LineStyle>
        <color>7f00ffff</color>
        <width>4</width>
      </LineStyle>
      <PolyStyle>
        <color>7f00ff00</color>
      </PolyStyle>
    </Style>
<Placemark>
      <name>Absolute Extruded</name>
      <description>具有黄色轮廓且透明的绿墙</description>
      <styleUrl>#yellowLineGreenPoly</styleUrl>
      <LineString>
        <extrude>1</extrude>
        <tessellate>1</tessellate>
        <altitudeMode>absolute</altitudeMode>
        <coordinates> -112.2550785337791,36.07954952145647,2357
          -112.2549277039738,36.08117083492122,2357
          -112.2552505069063,36.08260761307279,2357
          -112.2564540158376,36.08395660588506,2357
          -112.2580238976449,36.08511401044813,2357
          -112.2595218489022,36.08584355239394,2357
          -112.2608216347552,36.08612634548589,2357
          -112.262073428656,36.08626019085147,2357
          -112.2633204928495,36.08621519860091,2357
          -112.2644963846444,36.08627897945274,2357
          -112.2656969554589,36.08649599090644,2357 
        </coordinates>
      </LineString>
    </Placemark>
  </Document>
</kml>

请注意，它其实只是高于地面的一条线。<tessellate> 标签把线切成小段，而 <extrude> 标签将线向下延伸到地面。

多边形

您可以使用多边形来创建简单的建筑物及其他图形。示例在 KML 示例文件的 Polygons 文件夹中。

五角大楼的示例是通过绘制简单的内外壳，然后将它们向下凸出到地面生成的。代码如下：

格式如下：西经,北纬,高度，<altitudeMode>relativeToGround</altitudeMode>是一个枚举值

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Placemark>
    <name>五角大楼</name>
    <Polygon>
      <extrude>1</extrude>
      <altitudeMode>relativeToGround</altitudeMode>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            -77.05788457660967,38.87253259892824,100 
            -77.05465973756702,38.87291016281703,100 
            -77.05315536854791,38.87053267794386,100 
            -77.05552622493516,38.868757801256,100 
            -77.05844056290393,38.86996206506943,100 
            -77.05788457660967,38.87253259892824,100
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
      <innerBoundaryIs>
        <LinearRing>
          <coordinates>
            -77.05668055019126,38.87154239798456,100 
            -77.05542625960818,38.87167890344077,100 
            -77.05485125901024,38.87076535397792,100 
            -77.05577677433152,38.87008686581446,100 
            -77.05691162017543,38.87054446963351,100 
            -77.05668055019126,38.87154239798456,100
          </coordinates>
        </LinearRing>
      </innerBoundaryIs>
    </Polygon>
  </Placemark>
</kml>