1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2
"http://www.w3.org/TR/html4/loose.dtd">
5
<meta http-equiv="content-type" content="text/html; charset=utf-8">
6
<title>LIBKML Driver</title>
9
<body bgcolor="#ffffff">
11
<h1>LIBKML Driver (.kml .kmz)</h1>
14
The LIBKML driver is a client of
15
<a href="http://code.google.com/p/libkml/">Libkml</a> from Google, a
16
reference implementation of
17
<a href="http://www.opengeospatial.org/standards/kml/">KML</a>
18
reading and writing, in the form of a cross platform C++ library.
19
You must build and install Libkml in order to use this OGR driver.
23
Note that if you build and include this LIBKML driver, it will become the
24
default reader of KML for ogr, overriding the previous KML driver. You can
25
still specify either KML or LIBKML as the ouput driver via the command line
29
Libkml from Google provides reading services for any valid KML file.
30
However, please be advised that some KML facilities do not map into the
31
Simple Features specification ogr uses as its internal structure.
32
Therefore, a best effort will be made by the driver to understand the
33
content of a KML file read by libkml into ogr, but your mileage may vary.
34
Please try a few KML files as samples to get a sense of what is understood.
35
In particular, nesting of feature sets more than one deep will be flattened
36
to support ogr's internal format.
43
<a href="http://www.gdal.org/ogr/ogr_arch.html#ogr_arch_data_source">datasource </a>
44
as a kml file <code>somefile.kml</code> ,
45
a directory <code>somedir/</code> , or a kmz file <code>somefile.kmz</code> .
49
By default on directory and kmz datasources, an index file of all the
50
layers will be read from or written to doc.kml. It conatains a
51
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#networklink">
52
<NetworkLink></a> to each layer file in the datasource. This feature
53
can be turned off by setting the enviroment variable LIBKML_USE_DOC.KML to
60
Datasource style tables are written to the
61
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#document">
62
<Document></a> in a .kml, style/style.kml
63
in a kmz file, or style.kml in a directory, as one or more
64
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#style">
65
<Style></a> elements. Not all of
66
<a href="http://www.gdal.org/ogr/ogr_feature_style.html">OGR Feature Style</a>
67
can translate into KML.
73
<a href="http://www.gdal.org/ogr/ogr_arch.html#ogr_arch_layer">
74
Layers</a> are mapped to kml files as a
75
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#document">
78
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#folder">
79
<Folder></a>, and in kmz files or directorys as a seperate kml file.
84
Layer style tables can not be read from or written to a kml layer that is a
85
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#folder">
86
<Folder></a>, otherwise they are in the
87
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#document">
88
<Document></a> that is the layer.
95
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#schema">
96
<Schema></a> is supported for .kml files , .kmz files, and
103
An OGR <a href="http://www.gdal.org/ogr/ogr_arch.html#ogr_arch_feature">feature</a>
104
translates to kml as a
105
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#placemark">
106
<Placemark></a>.
112
Style Strings at the feature level are Mapped to KML as either a
113
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#style">
115
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#styleurl">
116
<StyleUrl></a> in each
117
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#placemark">
118
<Placemark></a>.
121
When reading a kml feature and the enviroment variable LIBKML_RESOLVE_STYLE
122
is set to yes, styleurls are looked up in the style tables and the features
123
style string is set to the style from the table. This is to allow reading
124
of shared styles by applications, like mapserver, that do not read style
129
When reading a kml feature and the enviroment variable LIBKML_EXTERNAL_STYLE
130
is set to yes, a styleurl that is external to the datasource is read from
131
disk or fetched from the server and parsed into the datasource style table.
132
If the style kml can not be read or LIBKML_EXTERNAL_STYLE is set to no then
133
the styleurl is copyed to the style string.
138
<p> OGR fields (feature atributes) are mapped to kml with
139
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#schema">
140
<Schema></a>; and
141
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#simpledata">
142
<SimpleData></a>, except for some special fields as noted below.
146
A rich set of environment variables are available to define how fields in
147
input and output, map to a KML
148
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#placemark">
149
<Placemark></a>. For example, if you want a field called 'Cities'
151
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#name">
152
<name></a>; tag in KML, you can set an
153
environment variable.
159
This String field maps to the kml tag
160
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#name">
161
<name></a>. The name of the ogr field can be changed with the
162
enviroment variable LIBKML_NAME_FIELD .
165
<dd>This String field maps to the kml tag
166
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#description">
167
<description></a>. The name of the ogr field can be changed with the
168
enviroment variable LIBKML_DESCRIPTION_FIELD .
171
<dd>This string or datetime or date and/or time field maps to the kml tag
172
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#timestamp">
173
<timestamp></a>. The name of the ogr field can be changed with the
174
enviroment variable LIBKML_TIMESTAMP_FIELD .
177
<dd>This string or datetime or date and/or time field maps to the kml tag
178
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#begin">
179
<begin></a>. The name of the ogr field can be changed with the
180
enviroment variable LIBKML_BEGIN_FIELD .
183
<dd>This string or datetime or date and/or time field maps to the kml tag
184
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#end">
185
<end></a>. The name of the ogr field can be changed with the
186
enviroment variable LIBKML_END_FIELD .
188
<dt>altitudeMode</dt>
189
<dd>This string field maps to the kml tag
190
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#altitudemode">
191
<altitudeMode></a> or
192
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#gxaltitudemode">
193
<gx:altitudeMode></a>. The name of the ogr field can be changed
194
with the enviroment variable LIBKML_ALTITUDEMODE_FIELD .
197
<dd>This integer field maps to the kml tag
198
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#tessellate">
199
<tessellate></a>. The name of the ogr field can be changed with the
200
enviroment variable LIBKML_TESSELLATE_FIELD .
203
<dd>This integer field maps to the kml tag
204
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#extrude">
205
<extrude></a>. The name of the ogr field can be changed with the
206
enviroment variable LIBKML_EXTRUDE_FIELD .
209
<dd>This integer field maps to the kml tag
210
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#visibility">
211
<visibility></a>. The name of the ogr field can be changed with the
212
enviroment variable LIBKML_VISIBILITY_FIELD .
215
<dd>This string feild maps to a features style string, OGR reads this field
216
if there is no style string set on the feature.
224
<a href="http://www.gdal.org/ogr/ogr_arch.html#ogr_arch_geometry">
225
Geometry</a> to KML Geometry is pretty strait forwards with only a couple
226
of exceptions. Point to
227
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#point">
228
<Point></a>, LineString to
229
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#linestring">
230
<LineString></a>, LinearRing to
231
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#linearring">
232
<LinearRing></a>, and Polygon to
233
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#polygon">
234
<Polygon></a>. In OGR a polygon contains an array of LinearRings,
235
the first one being the outer ring. KML has the tags
236
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#outerboundaryis">
237
<outerBoundaryIs></a> and
238
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#innerboundaryis">
239
<innerBoundaryIs></a> to differentiate between the two. OGR has
240
several Multi types of geometry : GeometryCollection, MultiPolygon,
241
MultiPoint, and MultiLineString. When possible, OGR will try to map
242
<a href="http://code.google.com/apis/kml/documentation/kmlreference.html#multigeometry">
243
<MultiGeometry></a> to the more precise OGR geometry type (MultiPoint, MultiLineString or MultiPolygon),
244
and default to GeometryCollection in case of mixed content.
248
Sometimes kml geometry will span the dateline, In applications like qgis or
249
mapserver this will create horizontal lines all the way around the globe.
250
Setting the enviroment variable LIBKML_WRAPDATELINE to "yes" will cause the
251
libkml driver to split the geometry at the dateline when read.
254
<h2>VSI Virtual File System API support</h2>
256
(Some features below might require OGR >= 1.9.0)<p>
258
The driver supports reading and writing to files managed by VSI Virtual File System API, which include
259
"regular" files, as well as files in the /vsizip/ (read-write) , /vsigzip/ (read-write) , /vsicurl/ (read-only) domains.<p>
261
Writing to /dev/stdout or /vsistdout/ is also supported.<p>
266
The following bash script will build a
267
<a href="http://www.gdal.org/ogr/drv_csv.html">csv</a> file and a
268
<a href="http://www.gdal.org/ogr/drv_vrt.html">vrt</a> file, and then
269
translate them to KML using
270
<a href="http://www.gdal.org/ogr2ogr.html">ogr2ogr</a> into a .kml file with
271
timestamps and styling.
278
# Copyright (c) 2010, Brian Case
280
# Permission is hereby granted, free of charge, to any person obtaining a
281
# copy of this software and associated documentation files (the "Software"),
282
# to deal in the Software without restriction, including without limitation
283
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
284
# and/or sell copies of the Software, and to permit persons to whom the
285
# Software is furnished to do so, subject to the following conditions:
287
# The above copyright notice and this permission notice shall be included
288
# in all copies or substantial portions of the Software.
290
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
291
# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
292
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
293
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
294
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
295
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
296
# DEALINGS IN THE SOFTWARE.
299
icon="http://maps.google.com/mapfiles/kml/shapes/shaded_dot.png"
311
while read Date Time Lat Lon Mag Dep
313
ts=$(echo $Date | sed 's:/:-:g')T${Time%%.*}Z
316
if [[ $rgba == "" ]] && [[ $Dep -lt 33 ]]
321
if [[ $rgba == "" ]] && [[ $Dep -lt 70 ]]
326
if [[ $rgba == "" ]] && [[ $Dep -lt 150 ]]
331
if [[ $rgba == "" ]] && [[ $Dep -lt 300 ]]
336
if [[ $rgba == "" ]] && [[ $Dep -lt 500 ]]
348
style="\"SYMBOL(s:$Mag,id:\"\"$icon\"\",c:$rgba)\""
350
echo $Date,$Time,$Lat,$Lon,$Mag,$Dep,$ts,"$style"
356
wget http://neic.usgs.gov/neis/gis/qed.asc -O /dev/stdout |\
357
tail -n +2 > qed.asc
359
echo Date,TimeUTC,Latitude,Longitude,Magnitude,Depth,timestamp,OGR_STYLE > qed.csv
361
docsv < qed.asc >> qed.csv
363
cat > qed.vrt << EOF
364
<OGRVRTDataSource>
365
<OGRVRTLayer name="qed">
366
<SrcDataSource>qed.csv</SrcDataSource>
367
<GeometryType>wkbPoint</GeometryType>
368
<LayerSRS>WGS84</LayerSRS>
369
<GeometryField encoding="PointFromColumns" x="Longitude" y="Latitude"/>
371
</OGRVRTDataSource>
375
ogr2ogr -f libkml qed.kml qed.vrt
added
removed
ogr/ogrsf_frmts/libkml/drv_libkml.html
