EVOLUTION-MANAGER

Edit File: drv_libkml.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
 <meta http-equiv="content-type" content="text/html; charset=utf-8">
 <title>LIBKML Driver</title>
</head>

<h1>LIBKML Driver (.kml .kmz)</h1>

The LIBKML driver is a client of
 <a href="https://github.com/google/libkml">Libkml</a> from Google, a
 reference implementation of
 <a href="http://www.opengeospatial.org/standards/kml/">KML</a>
 reading and writing, in the form of a cross platform C++ library.
 You must build and install Libkml in order to use this OGR driver.
 Note: you need to build libkml from its latest SVN version (libkml 1.2 isn't
 enough).

Note that if you build and include this LIBKML driver, it will become the
 default reader of KML for ogr, overriding the previous KML driver. You can
 still specify either KML or LIBKML as the output driver via the command line

Libkml from Google provides reading services for any valid KML file.
 However, please be advised that some KML facilities do not map into the
 Simple Features specification OGR uses as its internal structure.
 Therefore, a best effort will be made by the driver to understand the
 content of a KML file read by libkml into ogr, but your mileage may vary.
 Please try a few KML files as samples to get a sense of what is understood.
 In particular, nesting of feature sets more than one deep will be flattened
 to support ogr's internal format.

<h2>Datasource</h2>

You may specify a
 <a href="http://www.gdal.org/ogr_arch.html#ogr_arch_data_source">datasource </a>
 as a kml file <code>somefile.kml</code> ,
 a directory <code>somedir/</code> , or a kmz file <code>somefile.kmz</code> .

By default on directory and kmz datasources, an index file of all the
 layers will be read from or written to doc.kml. It contains a
 <a href="https://developers.google.com/kml/documentation/kmlreference#networklink">
 &lt;NetworkLink&gt;</a> to each layer file in the datasource. This feature
 can be turned off by setting the environment variable LIBKML_USE_DOC.KML to
 "no"

<h3>StyleTable</h3>

Datasource style tables are written to the
 <a href="https://developers.google.com/kml/documentation/kmlreference#document">
 &lt;Document&gt;</a> in a .kml, style/style.kml
 in a kmz file, or style.kml in a directory, as one or more
 <a href="https://developers.google.com/kml/documentation/kmlreference#style">
 &lt;Style&gt;</a> elements. Not all of
 <a href="http://www.gdal.org/ogr_feature_style.html">OGR Feature Style</a>
 can translate into KML.

<h3>Datasource creation options</h3>

Starting with OGR 1.11, the following datasource creation options can be used to generate a
 <a href="https://developers.google.com/kml/documentation/kmlreference#atomauthor">
 &lt;atom:Author&gt;</a> element at the top Document level.
 <ul>
 <li>AUTHOR_NAME</li>
 <li>AUTHOR_URI</li>
 <li>AUTHOR_EMAIL</li>
 </ul>
 
 
 The href of an <a href="https://developers.google.com/kml/documentation/kmlreference#atomlink">
 &lt;atom:link&gt;</a> element at the top Document level can be specified with the LINK creation option.
 
 
 The <a href="https://developers.google.com/kml/documentation/kmlreference#phonenumber">
 &lt;phoneNumber&gt;</a> element at the top Document level can be specified with the PHONENUMBER creation option.
 The value must follow the syntax of <a href="http://tools.ietf.org/html/rfc3966">IETF RFC 3966</a>.

Starting with GDAL 2.2, the DOCUMENT_ID datasource creation option can be
 used to specified the id of the root &lt;Document&gt; node. The default value
 is root_doc.

<h4>Container properties</h4>

The following dataset creation options can be used to set container options :
 <ul>
 <li>NAME: <a href="https://developers.google.com/kml/documentation/kmlreference#name">&lt;name&gt;</a> element</li>
 <li>VISIBILITY: <a href="https://developers.google.com/kml/documentation/kmlreference#visibility">&lt;visibility&gt;</a> element</li>
 <li>OPEN: <a href="https://developers.google.com/kml/documentation/kmlreference#open">&lt;open&gt;</a> element</li>
 <li>SNIPPET: <a href="https://developers.google.com/kml/documentation/kmlreference#snippet">&lt;snippet&gt;</a> element</li>
 <li>DESCRIPTION: <a href="https://developers.google.com/kml/documentation/kmlreference#description">&lt;description&gt;</a> element</li>
 </ul>

<h4>List style</h4>

The following dataset creation options can be used to control how the main folder
 (folder of layers) appear in the Places panel of the Earth browser, trough a
 <a href="https://developers.google.com/kml/documentation/kmlreference#liststyle">&lt;ListStyle&gt;</a> element:
 <ul>
 <li>LISTSTYLE_TYPE: can be one of "check", "radioFolder", "checkOffOnly" or "checkHideChildren". Sets the
 <a href="https://developers.google.com/kml/documentation/kmlreference#listItemType">&lt;listItemType&gt;</a> element.</li>
 <li>LISTSTYLE_ICON_HREF: URL of the icon to display for the main folder. Sets the href element of the
 <a href="https://developers.google.com/kml/documentation/kmlreference#itemicon">&lt;ItemIcon&gt;</a> element.</li>
 </ul>

<h4>Balloon style</h4>

If a style foo is defined, it is possible to add a
 <a href="https://developers.google.com/kml/documentation/kmlreference#balloonstyle">&lt;BalloonStyle&gt;</a> element to it,
 by specifying the foo_BALLOONSTYLE_BGCOLOR and/or foo_BALLOONSTYLE_TEXT elements.

<h4>NetworkLinkControl</h4>

A <a href="https://developers.google.com/kml/documentation/kmlreference#networklinkcontrol">
 &lt;NetworkLinkControl&gt;</a> element can be defined if at least one of the following dataset creation option
 is specified:
 <ul>
 <li>NLC_MINREFRESHPERIOD : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#minrefreshperiod">
 &lt;minRefreshPeriod&gt;</a> element</li>
 <li>NLC_MAXSESSIONLENGTH : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#maxsessionlength">
 &lt;maxSessionLength&gt;</a> element</li>
 <li>NLC_COOKIE : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#cookie">
 &lt;cookie&gt;</a> element</li>
 <li>NLC_MESSAGE : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#message">
 &lt;message&gt;</a> element</li>
 <li>NLC_LINKNAME : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#linkname">
 &lt;linkName&gt;</a> element</li>
 <li>NLC_LINKDESCRIPTION : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#linkdescription">
 &lt;linkDescription&gt;</a> element</li>
 <li>NLC_LINKSNIPPET : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#linksnippet">
 &lt;linkSnippet&gt;</a> element</li>
 <li>NLC_EXPIRES : to set the <a href="https://developers.google.com/kml/documentation/kmlreference#expires">
 &lt;expires&gt;</a> element</li>
 </ul>

<h4>Update documents</h4>

When defining the dataset creation option UPDATE_TARGETHREF, a NetworkLinkControl KML
 file with an <a href="https://developers.google.com/kml/documentation/kmlreference#update">
 &lt;Update&gt;</a> element will be generated.
 See the <a href="https://developers.google.com/kml/documentation/updates">tutorial about update</a>.

The CreateFeature() operation on a layer will be translated as a
 <a href="https://developers.google.com/kml/documentation/kmlreference#create">&lt;Create&gt;</a> element.

The SetFeature() operation on a layer will be translated as a
 <a href="https://developers.google.com/kml/documentation/kmlreference#change">&lt;Change&gt;</a> element.

The DeleteFeature() operation on a layer will be translated as a
 <a href="https://developers.google.com/kml/documentation/kmlreference#delete">&lt;Delete&gt;</a> element.

<h2>Layer</h2>

<a href="http://www.gdal.org/ogr_arch.html#ogr_arch_layer">
 Layers</a> are mapped to kml files as a
 <a href="https://developers.google.com/kml/documentation/kmlreference#document">
 &lt;Document&gt;</a>
 or
 <a href="https://developers.google.com/kml/documentation/kmlreference#folder">
 &lt;Folder&gt;</a>, and in kmz files or directories as a separate kml file.

<h3>Style</h3>
 
 Layer style tables can not be read from or written to a kml layer that is a
 <a href="https://developers.google.com/kml/documentation/kmlreference#folder">
 &lt;Folder&gt;</a>, otherwise they are in the
 <a href="https://developers.google.com/kml/documentation/kmlreference#document">
 &lt;Document&gt;</a> that is the layer.

<h3>Schema</h3>

Read and write of
 <a href="https://developers.google.com/kml/documentation/kmlreference#schema">
 &lt;Schema&gt;</a> is supported for .kml files, .kmz files, and
 directories.

<h3>Layer creation options</h3>

Starting with OGR 1.11, the following layer creation options can be used to generate a
 <a href="https://developers.google.com/kml/documentation/kmlreference#lookat">
 &lt;LookAt&gt;</a> element at the layer level.
 <ul>
 <li>LOOKAT_LONGITUDE (required)</li>
 <li>LOOKAT_LATITUDE (required)</li>
 <li>LOOKAT_RANGE (required)</li>
 <li>LOOKAT_HEADING</li>
 <li>LOOKAT_TILT</li>
 <li>LOOKAT_ALTITUDE</li>
 <li>LOOKAT_ALTITUDEMODE</li>
 </ul>

Alternatively, a <a href="https://developers.google.com/kml/documentation/kmlreference#camera">
 &lt;Camera&gt;</a> element can be generated.
 <ul>
 <li>CAMERA_LONGITUDE (required)</li>
 <li>CAMERA_LATITUDE (required)</li>
 <li>CAMERA_ALTITUDE (required)</li>
 <li>CAMERA_ALTITUDEMODE (required)</li>
 <li>CAMERA_HEADING</li>
 <li>CAMERA_TILT</li>
 <li>CAMERA_ROLL</li>
 </ul>

A <a href="https://developers.google.com/kml/documentation/kmlreference#region">
 &lt;Region&gt;</a> element can be generated to control when objects of the layer are visible or not.
 If REGION_XMIN, REGION_YMIN, REGION_XMAX and REGION_YMAX, the region coordinates are determined from
 the spatial extent of the features being written in the layer.
 <ul>
 <li>ADD_REGION=YES/NO : defaults to NO</li>
 <li>REGION_XMIN (optional) : defines the west coordinate of the region.</li>
 <li>REGION_YMIN (optional) : defines the south coordinate of the region.</li>
 <li>REGION_XMAX (optional) : defines the east coordinate of the region.</li>
 <li>REGION_YMAX (optional) : defines the north coordinate of the region.</li>
 <li>REGION_MIN_LOD_PIXELS (optional) : minimum size in pixels of the region so that it is displayed. Defaults to 256.</li>
 <li>REGION_MAX_LOD_PIXELS (optional) : maximum size in pixels of the region so that it is displayed. Defaults to -1 (infinite).</li>
 <li>REGION_MIN_FADE_EXTENT (optional) : distance over which the geometry fades, from fully opaque to fully transparent. Defaults to 0.</li>
 <li>REGION_MAX_FADE_EXTENT (optional) : distance over which the geometry fades, from fully transparent to fully opaque. Defaults to 0.</li>
 </ul>

A <a href="https://developers.google.com/kml/documentation/kmlreference#screenoverlay">
 &lt;ScreenOverlay&gt;</a> element can be added to display a logo, a legend, etc...
 <ul>
 <li>SO_HREF (required) : URL of the image to display.</li>
 <li>SO_NAME (optional)</li>
 <li>SO_DESCRIPTION (optional)</li>
 <li>SO_OVERLAY_X (optional)</li>
 <li>SO_OVERLAY_Y (optional)</li>
 <li>SO_OVERLAY_XUNITS (optional)</li>
 <li>SO_OVERLAY_YUNITS (optional)</li>
 <li>SO_SCREEN_X (optional). Defaults to 0.05</li>
 <li>SO_SCREEN_Y (optional). Defaults to 0.05</li>
 <li>SO_SCREEN_XUNITS (optional). Defaults to Fraction</li>
 <li>SO_SCREEN_YUNITS (optional). Defaults to Fraction</li>
 <li>SO_SIZE_X (optional)</li>
 <li>SO_SIZE_Y (optional)</li>
 <li>SO_SIZE_XUNITS (optional)</li>
 <li>SO_SIZE_YUNITS (optional)</li>
 </ul>

By default, layers are written as
 <a href="https://developers.google.com/kml/documentation/kmlreference#document">
 &lt;Document&gt;</a> elements. By settings the FOLDER layer creation option
 to YES, it is also possible to write them as <a href="https://developers.google.com/kml/documentation/kmlreference#folder">
 &lt;Folder&gt;</a> elements (only in .kml files).

The following layer creation options can be used to set container options :
 <ul>
 <li>NAME: <a href="https://developers.google.com/kml/documentation/kmlreference#name">&lt;name&gt;</a> element</li>
 <li>VISIBILITY: <a href="https://developers.google.com/kml/documentation/kmlreference#visibility">&lt;visibility&gt;</a> element</li>
 <li>OPEN: <a href="https://developers.google.com/kml/documentation/kmlreference#open">&lt;open&gt;</a> element</li>
 <li>SNIPPET: <a href="https://developers.google.com/kml/documentation/kmlreference#snippet">&lt;snippet&gt;</a> element</li>
 <li>DESCRIPTION: <a href="https://developers.google.com/kml/documentation/kmlreference#description">&lt;description&gt;</a> element</li>
 </ul>

The following layer creation options can be used to control how the folder
 of a layer appear in the Places panel of the Earth browser, trough a
 <a href="https://developers.google.com/kml/documentation/kmlreference#liststyle">&lt;ListStyle&gt;</a> element:
 <ul>
 <li>LISTSTYLE_TYPE: can be one of "check", "radioFolder", "checkOffOnly" or "checkHideChildren". Sets the
 <a href="https://developers.google.com/kml/documentation/kmlreference#listItemType">&lt;listItemType&gt;</a> element.</li>
 <li>LISTSTYLE_ICON_HREF: URL of the icon to display for the layer folder. Sets the href element of the
 <a href="https://developers.google.com/kml/documentation/kmlreference#itemicon">&lt;ItemIcon&gt;</a> element.</li>
 </ul>

<h2>Feature</h2>

An OGR <a href="http://www.gdal.org/ogr_arch.html#ogr_arch_feature">feature</a>
 generally translates to kml as a
 <a href="https://developers.google.com/kml/documentation/kmlreference#placemark">
 &lt;Placemark&gt;</a>, and vice-versa.

If the model field is defined, a <a href="https://developers.google.com/kml/documentation/kmlreference#model">
 &lt;Model&gt;</a> object within the Placemark will be generated.

If the networklink field is defined, a <a href="https://developers.google.com/kml/documentation/kmlreference#networklink">
 &lt;NetworkLink&gt;</a> will be generated. Other networklink fields are optional.

If the photooverlay field is defined, a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a> will be generated (provided that the camera_longitude,
 camera_latitude, camera_altitude, camera_altitudemode, head and/or tilt and/or roll,
 leftfov, rightfov, bottomfov, topfov, near fields are also set. The shape field is optional.
 
 In case the PhotoOverlay is a big image, it is highly recommended to tile it and
 generate overview levels, as explained in the <a href="https://developers.google.com/kml/documentation/photos">
 PhotoOverlay tutorial</a>. In which case, the URL should contain the "$[level]", "$[x]" and "$[y]"
 sub-strings in the photooverlay field, and the imagepyramid_tilesize,
 imagepyramid_maxwidth, imagepyramid_maxheight and imagepyramid_gridorigin fields should be set.

Placemark, Model, NetworkLink and PhotoOverlay objects can have an associated camera
 if the camera_longitude, camera_latitude, camera_altitude, camera_altitudemode, head and/or tilt and/or roll
 fields are defined.

Starting with OGR 1.10, KML
 <a href="https://developers.google.com/kml/documentation/kmlreference#groundoverlay">
 &lt;GroundOverlay&gt;</a> elements are supported for reading (unless the
 LIBKML_READ_GROUND_OVERLAY configuration option is set to FALSE). For such elements, there
 are icon and drawOrder fields.

<h3>Style</h3>

Style Strings at the feature level are Mapped to KML as either a
 <a href="https://developers.google.com/kml/documentation/kmlreference#style">
 &lt;Style&gt;</a> or
 <a href="https://developers.google.com/kml/documentation/kmlreference#styleurl">
 &lt;StyleUrl&gt;</a> in each
 <a href="https://developers.google.com/kml/documentation/kmlreference#placemark">
 &lt;Placemark&gt;</a>.
 
 
 When reading a kml feature and the environment variable LIBKML_RESOLVE_STYLE
 is set to yes, styleurls are looked up in the style tables and the features
 style string is set to the style from the table. This is to allow reading
 of shared styles by applications, like mapserver, that do not read style
 tables.

When reading a kml feature and the environment variable LIBKML_EXTERNAL_STYLE
 is set to yes, a styleurl that is external to the datasource is read from
 disk or fetched from the server and parsed into the datasource style table.
 If the style kml can not be read or LIBKML_EXTERNAL_STYLE is set to no then
 the styleurl is copied to the style string.

When reading a kml StyleMap the default mapping is set to normal. If you
 wish to use the highlighted styles set the environment variable
 LIBKML_STYLEMAP_KEY to "highlight"

When writing a kml, if there exist 2 styles of the form "astylename_normal"
 and "astylename_highlight" (where astylename is any string), then a StyleMap
 object will be creating from both styles and called "astylename".

<h2>Fields</h2>

OGR fields (feature attributes) are mapped to kml with
 <a href="https://developers.google.com/kml/documentation/kmlreference#schema">
 &lt;Schema&gt;</a>; and
 <a href="https://developers.google.com/kml/documentation/kmlreference#simpledata">
 &lt;SimpleData&gt;</a>, except for some special fields as noted below.

Note: it is also possible to export fields as
 <a href="https://developers.google.com/kml/documentation/kmlreference#data">
 &lt;Data&gt;</a> elements if the LIBKML_USE_SCHEMADATA configuration option is
 set to NO.

A rich set of environment variables are available to define how fields in
 input and output, map to a KML
 <a href="https://developers.google.com/kml/documentation/kmlreference#placemark">
 &lt;Placemark&gt;</a>. For example, if you want a field called 'Cities'
 to map to the
 <a href="https://developers.google.com/kml/documentation/kmlreference#name">
 &lt;name&gt;</a>; tag in KML, you can set an
 environment variable.

<dl>
 <dt>Name</dt>
 <dd>
 This String field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#name">
 &lt;name&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_NAME_FIELD .
 </dd>
 <dt>description</dt>
 <dd>This String field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#description">
 &lt;description&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_DESCRIPTION_FIELD .
 </dd>
 <dt>timestamp</dt>
 <dd>This string or datetime or date and/or time field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#timestamp">
 &lt;timestamp&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_TIMESTAMP_FIELD .
 </dd>
 <dt>begin</dt>
 <dd>This string or datetime or date and/or time field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#begin">
 &lt;begin&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_BEGIN_FIELD .
 </dd>
 <dt>end</dt>
 <dd>This string or datetime or date and/or time field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#end">
 &lt;end&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_END_FIELD .
 </dd>
 <dt>altitudeMode</dt>
 <dd>This string field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#altitudemode">
 &lt;altitudeMode&gt;</a> or
 <a href="https://developers.google.com/kml/documentation/kmlreference#gxaltitudemode">
 &lt;gx:altitudeMode&gt;</a>. The name of the ogr field can be changed
 with the environment variable LIBKML_ALTITUDEMODE_FIELD .
 </dd>
 <dt>tessellate</dt>
 <dd>This integer field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#tessellate">
 &lt;tessellate&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_TESSELLATE_FIELD .
 </dd>
 <dt>extrude</dt>
 <dd>This integer field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#extrude">
 &lt;extrude&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_EXTRUDE_FIELD .
 </dd>
 <dt>visibility</dt>
 <dd>This integer field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#visibility">
 &lt;visibility&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_VISIBILITY_FIELD .
 </dd>
 <dt>icon</dt>
 <dd>This string field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#icon">
 &lt;icon&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_ICON_FIELD .
 </dd>
 <dt>drawOrder</dt>
 <dd>This integer field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#draworder">
 &lt;drawOrder&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_DRAWORDER_FIELD .
 </dd>
 <dt>snippet</dt>
 <dd>This integer field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#snippet">
 &lt;snippet&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_SNIPPET_FIELD .
 </dd>
 <dt>heading</dt>
 <dd>This real field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#heading">
 &lt;heading&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_HEADING_FIELD. When reading, this field is present only if a Placemark has
 a Camera with a heading element.
 </dd>
 <dt>tilt</dt>
 <dd>This real field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#tilt">
 &lt;tilt&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_TILT_FIELD. When reading, this field is present only if a Placemark has
 a Camera with a tilt element.
 </dd>
 <dt>roll</dt>
 <dd>This real field maps to the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#roll">
 &lt;roll&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_ROLL_FIELD. When reading, this field is present only if a Placemark has
 a Camera with a roll element.
 </dd>

<dt>model</dt>
 <dd>This string field can be used to define the URL of a 3D
 <a href="https://developers.google.com/kml/documentation/kmlreference#model">
 &lt;model&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_MODEL_FIELD.
 </dd>
 <dt>scale_x</dt>
 <dd>This real field maps to the x element of the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#scale">
 &lt;scale&gt;</a> for a 3D model. The name of the ogr field can be changed with the
 environment variable LIBKML_SCALE_X_FIELD.
 </dd>
 <dt>scale_y</dt>
 <dd>This real field maps to the y element of the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#scale">
 &lt;scale&gt;</a>for a 3D model. The name of the ogr field can be changed with the
 environment variable LIBKML_SCALE_Y_FIELD.
 </dd>
 <dt>scale_z</dt>
 <dd>This real field maps to the z element of the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#scale">
 &lt;scale&gt;</a>for a 3D model. The name of the ogr field can be changed with the
 environment variable LIBKML_SCALE_Z_FIELD.
 </dd>

<dt>networklink</dt>
 <dd>This string field maps to the href element of the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#href">
 &lt;href&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_FIELD.
 </dd>

<dt>networklink_refreshvisibility</dt>
 <dd>This integer field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#refreshvisibility">
 &lt;refreshVisibility&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_REFRESHVISIBILITY_FIELD.
 </dd>

<dt>networklink_flytoview</dt>
 <dd>This integer field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#flytoview">
 &lt;flyToView&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_FLYTOVIEW_FIELD.
 </dd>

<dt>networklink_refreshmode</dt>
 <dd>This string field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#refreshmode">
 &lt;refreshMode&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_REFRESHMODE_FIELD.
 </dd>

<dt>networklink_refreshinterval</dt>
 <dd>This real field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#refreshinterval">
 &lt;refreshInterval&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_REFRESHINTERVAL_FIELD.
 </dd>

<dt>networklink_viewrefreshmode</dt>
 <dd>This string field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#viewrefreshmode">
 &lt;viewRefreshMode&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_VIEWREFRESHMODE_FIELD.
 </dd>

<dt>networklink_viewrefreshtime</dt>
 <dd>This real field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#viewrefreshtime">
 &lt;viewRefreshTime&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_VIEWREFRESHTIME_FIELD.
 </dd>

<dt>networklink_viewboundscale</dt>
 <dd>This real field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#viewboundscale">
 &lt;viewBoundScale&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_VIEWBOUNDSCALE_FIELD.
 </dd>

<dt>networklink_viewformat</dt>
 <dd>This string field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#viewformat">
 &lt;viewFormat&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_VIEWFORMAT_FIELD.
 </dd>

<dt>networklink_httpquery</dt>
 <dd>This string field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#httpquery">
 &lt;httpQuery&gt;</a> of a NetworkLink. The name of the ogr field can be changed with the
 environment variable LIBKML_NETWORKLINK_HTTPQUERY_FIELD.
 </dd>

<dt>camera_longitude</dt>
 <dd>This real field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#longitude">
 &lt;longitude&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#camera">
 &lt;Camera&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_CACameraMERA_LONGITUDE_FIELD.
 </dd>

<dt>camera_latitude</dt>
 <dd>This real field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#latitude">
 &lt;latitude&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#camera">
 &lt;Camera&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_CAMERA_LATITUDE_FIELD.
 </dd>

<dt>camera_altitude</dt>
 <dd>This real field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#altitude">
 &lt;altitude&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#camera">
 &lt;Camera&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_CAMERA_ALTITUDE_FIELD.
 </dd>

<dt>camera_altitudemode</dt>
 <dd>This real field maps to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#altitudemode">
 &lt;altitudeMode&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#camera">
 &lt;Camera&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_CAMERA_ALTITUDEMODE_FIELD.
 </dd>

<dt>photooverlay</dt>
 <dd>This string field maps to the href element of the kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#href">
 &lt;href&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_PHOTOOVERLAY_FIELD.
 </dd>

<dt>leftfov</dt>
 <dd>This real field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#leftfov">
 &lt;LeftFov&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_LEFTFOV_FIELD.
 </dd>

<dt>rightfov</dt>
 <dd>This real field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#rightfov">
 &lt;RightFov&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_RightFOV_FIELD.
 </dd>

<dt>bottomfov</dt>
 <dd>This real field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#bottomfov">
 &lt;BottomFov&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_BOTTOMTFOV_FIELD.
 </dd>

<dt>topfov</dt>
 <dd>This real field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#topfov">
 &lt;TopFov&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_TOPFOV_FIELD.
 </dd>

<dt>near</dt>
 <dd>This real field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#leftfov">
 &lt;Near&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_NEAR_FIELD.
 </dd>

<dt>shape</dt>
 <dd>This string field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#shape">
 &lt;shape&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#photooverlay">
 &lt;PhotoOverlay&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_SHAPE_FIELD.
 </dd>

<dt>imagepyramid_tilesize</dt>
 <dd>This integer field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#tilesize">
 &lt;tileSize&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#imagepyramid">
 &lt;ImagePyramid&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_IMAGEPYRAMID_TILESIZE.
 </dd>

<dt>imagepyramid_maxwidth</dt>
 <dd>This integer field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#maxwidth">
 &lt;maxWidth&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#imagepyramid">
 &lt;ImagePyramid&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_IMAGEPYRAMID_MAXWIDTH.
 </dd>

<dt>imagepyramid_maxheight</dt>
 <dd>This integer field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#maxheight">
 &lt;maxHeight&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#imagepyramid">
 &lt;ImagePyramid&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_IMAGEPYRAMID_MAXHEIGHT.
 </dd>

<dt>imagepyramid_gridorigin</dt>
 <dd>This string field maps to to kml tag
 <a href="https://developers.google.com/kml/documentation/kmlreference#maxheight">
 &lt;gridOrigin&gt;</a> of a <a href="https://developers.google.com/kml/documentation/kmlreference#imagepyramid">
 &lt;ImagePyramid&gt;</a>. The name of the ogr field can be changed with the
 environment variable LIBKML_IMAGEPYRAMID_GRIDORIGIN.
 </dd>

<dt>OGR_STYLE</dt>
 <dd>This string field maps to a features style string, OGR reads this field
 if there is no style string set on the feature.
 </dd>
 </dl>

<h2>Geometry</h2>

Translation of OGR
 <a href="http://www.gdal.org/ogr_arch.html#ogr_arch_geometry">
 Geometry</a> to KML Geometry is pretty strait forwards with only a couple
 of exceptions. Point to
 <a href="https://developers.google.com/kml/documentation/kmlreference#point">
 &lt;Point&gt;</a> (unless heading and/or tilt and/or roll field names are found, in
 which case a <a href="https://developers.google.com/kml/documentation/kmlreference#camera">Camera</a> object will be generated), LineString to
 <a href="https://developers.google.com/kml/documentation/kmlreference#linestring">
 &lt;LineString&gt;</a>, LinearRing to
 <a href="https://developers.google.com/kml/documentation/kmlreference#linearring">
 &lt;LinearRing&gt;</a>, and Polygon to
 <a href="https://developers.google.com/kml/documentation/kmlreference#polygon">
 &lt;Polygon&gt;</a>. In OGR a polygon contains an array of LinearRings,
 the first one being the outer ring. KML has the tags
 &nbsp;<a href="https://developers.google.com/kml/documentation/kmlreference#outerboundaryis">
 &lt;outerBoundaryIs&gt;</a>&nbsp;and&nbsp;
 <a href="https://developers.google.com/kml/documentation/kmlreference#innerboundaryis">
 &lt;innerBoundaryIs&gt;</a>&nbsp;to differentiate between the two. OGR has
 several Multi types of geometry : GeometryCollection, MultiPolygon,
 MultiPoint, and MultiLineString. When possible, OGR will try to map
 <a href="https://developers.google.com/kml/documentation/kmlreference#multigeometry">
 &lt;MultiGeometry&gt;</a> to the more precise OGR geometry type (MultiPoint, MultiLineString or MultiPolygon),
 and default to GeometryCollection in case of mixed content.

Sometimes kml geometry will span the dateline, In applications like qgis or
 mapserver this will create horizontal lines all the way around the globe.
 Setting the environment variable LIBKML_WRAPDATELINE to "yes" will cause the
 libkml driver to split the geometry at the dateline when read.

<h2>VSI Virtual File System API support</h2>

(Some features below might require OGR >= 1.9.0)

The driver supports reading and writing to files managed by VSI Virtual File System API, which include
"regular" files, as well as files in the /vsizip/ (read-write) , /vsigzip/ (read-write) , /vsicurl/ (read-only) domains.

Writing to /dev/stdout or /vsistdout/ is also supported.

<h2>Example</h2>

The following bash script will build a
 <a href="http://www.gdal.org/drv_csv.html">csv</a> file and a
 <a href="http://www.gdal.org/drv_vrt.html">vrt</a> file, and then
 translate them to KML using
 <a href="http://www.gdal.org/ogr2ogr.html">ogr2ogr</a> into a .kml file with
 timestamps and styling.

<pre>

#!/bin/bash
# Copyright (c) 2010, Brian Case
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.

icon="http://maps.google.com/mapfiles/kml/shapes/shaded_dot.png"
rgba33="#FF9900"
rgba70="#FFFF00"
rgba150="#00FF00"
rgba300="#0000FF"
rgba500="#9900FF"
rgba800="#FF0000"

function docsv {

IFS=','

while read Date Time Lat Lon Mag Dep
    do
        ts=$(echo $Date | sed 's:/:-:g')T${Time%%.*}Z
        rgba=""

if [[ $rgba == "" ]] && [[ $Dep -lt 33 ]]
        then
            rgba=$rgba33
        fi

if [[ $rgba == "" ]] && [[ $Dep -lt 70 ]]
        then
            rgba=$rgba70
        fi

if [[ $rgba == "" ]] && [[ $Dep -lt 150 ]]
        then
            rgba=$rgba150
        fi

if [[ $rgba == "" ]] && [[ $Dep -lt 300 ]]
        then
            rgba=$rgba300
        fi

if [[ $rgba == "" ]] && [[ $Dep -lt 500 ]]
        then
            rgba=$rgba500
        fi

if [[ $rgba == "" ]]
        then
            rgba=$rgba800
        fi

style="\"SYMBOL(s:$Mag,id:\"\"$icon\"\",c:$rgba)\""

echo $Date,$Time,$Lat,$Lon,$Mag,$Dep,$ts,"$style"
    done

}

wget http://neic.usgs.gov/neis/gis/qed.asc -O /dev/stdout |\
 tail -n +2 &gt; qed.asc

echo Date,TimeUTC,Latitude,Longitude,Magnitude,Depth,timestamp,OGR_STYLE &gt; qed.csv

docsv &lt; qed.asc &gt;&gt; qed.csv

cat &gt; qed.vrt &lt;&lt; EOF
&lt;OGRVRTDataSource&gt;
    &lt;OGRVRTLayer name="qed"&gt;
        &lt;SrcDataSource&gt;qed.csv&lt;/SrcDataSource&gt;
        &lt;GeometryType&gt;wkbPoint&lt;/GeometryType&gt;
        &lt;LayerSRS&gt;WGS84&lt;/LayerSRS&gt;
        &lt;GeometryField encoding="PointFromColumns" x="Longitude" y="Latitude"/&gt;
    &lt;/OGRVRTLayer&gt;
&lt;/OGRVRTDataSource&gt;

EOF

ogr2ogr -f libkml qed.kml qed.vrt

</pre>

</body>
</html>