Altitude Modes

Many KML features can contain an <altitude> element or coordinate, which specifies a distance above the ground level, sea level, or sea floor for that particular feature. <AbstractView> elements also can contain altitude.

Any altitude value should be accompanied by an <altitudeMode> element, which tells Google Earth how to read the altitude value. Altitudes can be measured:

  • from the surface of the Earth (relativeToGround),
  • above sea level (absolute), or
  • from the bottom of major bodies of water (relativeToSeaFloor).

It can also be ignored (clampToGround and clampToSeaFloor)

SeaFloor altitude modes and the KML extension namespace

Sea floor-related altitude modes are contained within a set of extensions to the KML standard, using the gx prefix. To use them, you must first add the correct namespace URI to the opening <kml> element in your KML file:

<kml xmlns="http://www.opengis.net/kml/2.2"
     xmlns:gx="http://www.google.com/kml/ext/2.2">

Then, substitute <gx:altitudeMode> for <altitudeMode> when using either clampToSeaFloor or relativeToSeaFloor.

Note that the gx-prefixed extension namespace may not be supported by all geo-browsers. It is supported by Google Earth 5.0.

Altitude mode reference

absolute

The absolute altitude mode measures altitude relative to sea level, regardless of the actual elevation of the terrain beneath the feature. In this way, features can be placed underground, and will not be visible. Portions of a feature can extend underground, as in the example below. Negative values are accepted, to place features below sea level.

This altitude mode is useful in situations where the altitude value is known precisely. GPS tracks, for example, can use the absolute altitude mode to display paths created while flying or diving.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 
<GroundOverlay>
  <name>absolute Example</name>
  <Icon>
    <href>rectangle.jpg</href>
    <viewBoundScale>0.75</viewBoundScale>
  </Icon>
  <altitude>2744.0</altitude>
  <altitudeMode>absolute</altitudeMode>
  <LatLonBox>
    <north>48.783</north>
    <south>48.751</south>
    <east>-121.75</east>
    <west>-121.89</west>
    <rotation>-30</rotation>
  </LatLonBox>
</GroundOverlay>

</kml>

clampToGround

This mode ignores any altitude value, and places the KML feature on the surface of the ground, following the terrain. In this way, GroundOverlays can, for example, be 'draped' over the surface of the Earth. If the feature is positioned over a major body of water, clampToGround will place the feature at sea level.

Any KML feature with no altitude mode specified will default to clampToGround.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 
<GroundOverlay>
  <name>clampToGround example</name>
  <Icon>
    <href>rectangle.jpg</href>
    <viewBoundScale>0.75</viewBoundScale>
  </Icon>
  <altitude>2744.0</altitude>
  <altitudeMode>clampToGround</altitudeMode>
  <LatLonBox>
    <north>48.783</north>
    <south>48.751</south>
    <east>-121.75</east>
    <west>-121.89</west>
    <rotation>-30</rotation>
  </LatLonBox>
</GroundOverlay>
</kml>

clampToSeaFloor

Contained within the extension namespace. See SeaFloor altitude modes and the KML extension namespace for important information.

As with clampToGround, this mode ignores the altitude value. It places the feature on the bottom of any major body of water; if the feature is located away from a body of water, the feature will be clamped to the ground level, instead.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">   <!-- required when using gx-prefixed elements -->
 
<Placemark>
  <name>clampToSeaFloor example</name>		
  <Polygon>
    <tessellate>1</tessellate>
    <gx:altitudeMode>clampToSeaFloor</gx:altitudeMode>
    <outerBoundaryIs>
      <LinearRing>
        <coordinates>
          146.793,12.213,0
          146.803,12.202,0 
          146.829,12.218,0 
          146.807,12.226,0 
          146.793,12.213,0 
        </coordinates>
      </LinearRing>
    </outerBoundaryIs>
  </Polygon>
</Placemark>

</kml>

relativeToGround

Measures the altitude from the ground level directly below the coordinates.

As an example, this altitude mode can be used to place the tops of powerline poles as they climb up and over a hill. If each pole is 20m tall, the location of each pole's top will move up and down with the elevation of the Earth.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 
<Placemark>
  <name>relativeToGround Example</name>
  <LineString>
    <extrude>1</extrude>
    <altitudeMode>relativeToGround</altitudeMode>
    <coordinates>
      -121.835,48.754,700
      -121.828,48.764,700
      -121.818,48.776,700
      -121.794,48.787,700
      -121.778,48.781,700
      -121.766,48.771,700
      -121.768,48.757,700
      -121.773,48.747,700
    </coordinates>
  </LineString>
</Placemark>
 
</kml>

relativeToSeaFloor

Contained within the extension namespace. See SeaFloor altitude modes and the KML extension namespace for important information.

Meaures the altitude from the sea floor directly below the feature, if the feature is placed over a major body of water. If not over water, the altitude will be measured from the ground level.

Example

<?xml version="1.0" encoding="UTF-8"?> <kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">   <!-- required when using gx-prefixed elements -->

<Placemark>
  <name>relativeToSeaFloor Example</name>
  <LineString>
    <extrude>1</extrude>
    <gx:altitudeMode>relativeToSeaFloor</gx:altitudeMode>
    <coordinates>
      146.825,12.233,400
      146.820,12.222,400
      146.812,12.212,400
      146.796,12.209,400
      146.788,12.205,400
    </coordinates>
  </LineString>
</Placemark>

</kml>