

  {extends file="main.tpl"}
    <!DOCTYPE head PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><head xmlns="http://www.w3.org/1999/xhtml">
  {block name=title}GPSBabel development:Google Earth (Keyhole) Markup Language (kml){/block}
  {block name=body}
                       
  <div xmlns="http://www.w3.org/1999/xhtml" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Google Earth (Keyhole) Markup Language (kml)</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="fmt_googledir.html">Prev</a> </td><th width="60%" align="center">Chapter 3. The Formats</th><td width="20%" align="right"> <a accesskey="n" href="fmt_google.html">Next</a></td></tr></table><hr /></div><div xmlns="http://www.w3.org/1999/xhtml" class="section"><div class="titlepage"><div><div><h2 class="title" ><a id="fmt_kml"></a>Google Earth (Keyhole) Markup Language (kml)</h2></div></div></div><p class="fmtcapshdr">
    This format can...
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="fmtcapsitem">
          read and write waypoints
        </p></li><li class="listitem"><p class="fmtcapsitem">
          read and write tracks
        </p></li><li class="listitem"><p class="fmtcapsitem">
          read and write routes
        </p></li></ul></div><p>This format has the following options: <a class="link" href="fmt_kml.html#fmt_kml_o_deficon" title="deficon option">deficon</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_lines" title="lines option">lines</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_points" title="points option">points</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_line_width" title="line_width option">line_width</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_line_color" title="line_color option">line_color</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_floating" title="floating option">floating</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_extrude" title="extrude option">extrude</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_track" title="track option">track</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_trackdata" title="trackdata option">trackdata</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_trackdirection" title="trackdirection option">trackdirection</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_units" title="units option">units</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_labels" title="labels option">labels</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_max_position_points" title="max_position_points option">max_position_points</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_rotate_colors" title="rotate_colors option">rotate_colors</a>, <a class="link" href="fmt_kml.html#fmt_kml_o_prec" title="prec option">prec</a> .</p><p> 
KML, the Keyhole Markup Language format, was used by Keyhole and is used by 
<a class="ulink" href="http://earth.google.com" target="_top">Google Earth</a>.  
</p><p>There are concepts in KML that GPSBabel can't support very well on 
read because they don't map well into other programs.  For example, KML has
ideas of camera views and names and descriptions can have arbitrarily 
complicated HTML in them.   KML files may have tiered "Styles" which
can identify sizing info and URLs of associated icons.   Reading such
files with GPSBabel - even if your goal it to write it back out as KML - can often
have surprising results.  Simple files with waypoints and paths (which
GPSBabel represents internally as tracks) work fine.
</p><p>
Google Earth also uses GPSBabel internally for receiver communications
and several file format imports and exports.
</p><p>
In general, GPSBabel's KML writer is relatively strong.  GPSBabel handles simple KML on read fairly well, but if you're dealing with handcrafted KML that uses extensive features that have no analog in other formats like nested folders, ringgeometry, camera angles, and such, don't expect GPSBabel to do well with them on read.
</p><p>
  Google Earth 4.0 and later have a feature that can surprise users of this 
  format.   Earth's "time slider" feature controls what timestamped data
  gets displayed.  If you're using data that has timestampes (e.g. GPX 
  points that contain time or almost any track data) this will be important
  to you.  The time slider defaults to the far left position and fully closed.
  This means that only the first data point will be displayed.  You can
  tweak Earth's settings to "view-&gt;show time-&gt;never" or
  you can widen the time slider to show the range of data of interest.
</p><p>
  See <a class="ulink" href="http://earth.google.com/userguide/v4/ug_gps.html#timeline" target="_top">Google Earth's documentation on timelines</a> for more info.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_deficon"></a><code class="option">deficon</code> option</h3></div></div></div><p>
      Default icon name.
    </p><p>
This option specifies the default name for waypoint icons
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_lines"></a><code class="option">lines</code> option</h3></div></div></div><p>
      Export linestrings for tracks and routes.
    </p><p>
When this option is nonzero, GPSBabel draws lines between points in
tracks and routes.  The default value for this option is 1, which causes
lines to be drawn by default.  To disable line-drawing, specify 
<code class="option">lines=0</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_points"></a><code class="option">points</code> option</h3></div></div></div><p>
      Export placemarks for tracks and routes.
    </p><p>
When this option is nonzero, GPSBabel draws placemarks for tracks and routes.
The default value for this option is 1, which causes placemarks to be drawn.
To disable drawing of placemarks, specify <code class="option">points=0</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_line_width"></a><code class="option">line_width</code> option</h3></div></div></div><p>
      Width of lines, in pixels.
    </p><p>
This option specifies the width of the drawn lines in pixels.  The default
value is six pixels.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_line_color"></a><code class="option">line_color</code> option</h3></div></div></div><p>
      Line color, specified in hex AABBGGRR.
    </p><p>
This option specifies the line color as a hexadecimal number in 
AABBGGRR format, where A is alpha, B is blue, G is green, and R is red.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_floating"></a><code class="option">floating</code> option</h3></div></div></div><p>
      Altitudes are absolute and not clamped to ground.
    </p><p>
When this option is nonzero, altitudes are allowed to float above or below
the ground surface.  By default, this option is zero so that altitudes are
clamped to the ground.  Specify <code class="option">floating=1</code> to allow them to
float.
</p><p>
This option is more useful to pilots than to hikers.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_extrude"></a><code class="option">extrude</code> option</h3></div></div></div><p>
      Draw extrusion line from trackpoint to ground.
    </p><p>
This option is a boolean flag to specify whether Google Earth should
draw lines from trackpoints to the ground.   It defaults to '0', which
means no extrusion lines are drawn.   The option of '1' is, of course,
most useful for points that aren't actually on the ground such as those
be captured from planes.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_track"></a><code class="option">track</code> option</h3></div></div></div><p>
      Write KML track (default = 0).
    </p><p>
  This is a boolean flag, defaulting to '0', that controls whether GPSBabel
  writes the &lt;Track&gt; tag that Google introduced in Earth 5.2 for tracks. You
    may need to turn this off if you have a KML reader that's confused by new
    tags or if size is critical.
</p><p>
  Routes and tracks without sufficient time data are always drawn as
  Linestrings and never Tracsks.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_trackdata"></a><code class="option">trackdata</code> option</h3></div></div></div><p>
      Include extended data for trackpoints (default = 1).
    </p><p>
This is a boolean flag that controls
whether GPSBabel writes extensive data for each trackpoint generated.
By default computed speed, timestamps, and so on are written with the default
of '1' for this option.   If you are writing large tracks and do not value
this information, you can reduce the size of the generated file substantially
by turning this flag off by setting it to '0'.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_trackdirection"></a><code class="option">trackdirection</code> option</h3></div></div></div><p>
      Indicate direction of travel in track icons (default = 0).
    </p><p>
  If set, this options creates directional icons for trackpoints.   Arrows 
  will show the direction of travel on drawn tracks and routes.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_units"></a><code class="option">units</code> option</h3></div></div></div><p>
      Units used when writing comments ('s'tatute, 'm'etric,' 'n'autical, 'a'viation).
    </p><p>
Units is a simple option.  Specify 's' for "statute" (miles, feet, and 
other things that don't sensibly convert to each other, but are craved
by Americans), 'm' for "metric", 'n' for "nautical" or 'a' for "aviation". Default is 's'.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_labels"></a><code class="option">labels</code> option</h3></div></div></div><p>
      Display labels on track and routepoints  (default = 1).
    </p><p>
When this option is zero, no labels are added for track and route points.
This option defaults to one, so labels are added by default.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_max_position_points"></a><code class="option">max_position_points</code> option</h3></div></div></div><p>
      Retain at most this number of position points  (0 = unlimited).
    </p><p>
	This option allows you to specify the number of points kept
	in the 'snail trail' generated in the realtime tracking mode.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_rotate_colors"></a><code class="option">rotate_colors</code> option</h3></div></div></div><p>
      Rotate colors for tracks and routes (default automatic).
    </p><p>
With this option GPSBabel uses different colors for each track or route.
If this option is used without a value then the colors are automatically selected such
that the spectrum will be rotated through once for all the tracks and once for all the routes.
If this option is used with a positive value then the value is interpreted as the number of degrees
in the color circle between adjacent tracks or routes. 
This option takes precedence over line_color.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="fmt_kml_o_prec"></a><code class="option">prec</code> option</h3></div></div></div><p>
      Precision of coordinates, number of decimals.
    </p><p>
This option specifies the number of digits to be used when
writing coordinate values.
Precision is the number of digits after the decimal point.  The default
precision is 6.  We limit the number of places we write to improve the
fidelity when round-tripping thata, reduce file size, and reduce 
silliness in files caused by repeating decimals in insignificant 
digits.
</p><p>
As a guideline, at the equator, five decimal places is about 1.1 m, 
placing it below the accuracy of commodity consumer GPS gear. Six places
is 0.11 m, achievable via surveyor grade and differential corrected GPS.
Seven is 11 millimeters.
</p><p>
This value is ignored on read and has no impact on the internal 
representation of data.
</p></div></div><div xmlns="http://www.w3.org/1999/xhtml" class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fmt_googledir.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="The_Formats.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fmt_google.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Google Directions XML (googledir) </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Google Maps XML (google)</td></tr></table></div>
  
      {/block}
  