Usage Guide¶
You can find more examples in the included test_main.py
file or in
collective.geo.fastkml, here is a quick overview:
(The examples below are available as standalone scripts in the examples
folder.)
Build a KML from Scratch¶
Example how to build a simple KML file from the Python interpreter.
# Import the library
>>> from fastkml import kml
>>> from pygeoif.geometry import Polygon
# Create the root KML object
>>> k = kml.KML()
>>> ns = '{http://www.opengis.net/kml/2.2}'
# Create a KML Document and add it to the KML root object
>>> d = kml.Document(ns, 'docid', 'doc name', 'doc description')
>>> k.append(d)
# Create a KML Folder and add it to the Document
>>> f = kml.Folder(ns, 'fid', 'f name', 'f description')
>>> d.append(f)
# Create a KML Folder and nest it in the first Folder
>>> nf = kml.Folder(ns, 'nested-fid', 'nested f name', 'nested f description')
>>> f.append(nf)
# Create a second KML Folder within the Document
>>> f2 = kml.Folder(ns, 'id2', 'name2', 'description2')
>>> d.append(f2)
# Create a Placemark with a simple polygon geometry and add it to the
# second folder of the Document
>>> p = kml.Placemark(ns, 'id', 'name', 'description')
>>> p.geometry = Polygon([(0, 0, 0), (1, 1, 0), (1, 0, 1)])
>>> f2.append(p)
# Print out the KML Object as a string
>>> print k.to_string(prettyprint=True)
'<kml:kml xmlns:ns0="http://www.opengis.net/kml/2.2">
<kml:Document id="docid">
<kml:name>doc name</kml:name>
<kml:description>doc description</kml:description>
<kml:visibility>1</kml:visibility>
<kml:open>0</kml:open>
<kml:Folder id="fid">
<kml:name>f name</kml:name>
<kml:description>f description</kml:description>
<kml:visibility>1</kml:visibility>
<kml:open>0</kml:open>
<kml:Folder id="nested-fid">
<kml:name>nested f name</kml:name>
<kml:description>nested f description</kml:description>
<kml:visibility>1</kml:visibility>
<kml:open>0</kml:open>
</kml:Folder>
</kml:Folder>
<kml:Folder id="id2">
<kml:name>name2</kml:name>
<kml:description>description2</kml:description>
<kml:visibility>1</kml:visibility>
<kml:open>0</kml:open>
<kml:Placemark id="id">
<kml:name>name</kml:name>
<kml:description>description</kml:description>
<kml:visibility>1</kml:visibility>
<kml:open>0</kml:open>
<kml:Polygon>
<kml:outerBoundaryIs>
<kml:LinearRing>
<kml:coordinates>
0.000000,0.000000,0.000000
1.000000,1.000000,0.000000
1.000000,0.000000,1.000000
0.000000,0.000000,0.000000
</kml:coordinates>
</kml:LinearRing>
</kml:outerBoundaryIs>
</kml:Polygon>
</kml:Placemark>
</kml:Folder>
</kml:Document>
</kml:kml>'
Read a KML File/String¶
You can create a KML object by reading a KML file as a string
# Start by importing the kml module
>>> from fastkml import kml
#Read file into string and convert to UTF-8 (Python3 style)
>>> with open(kml_file, 'rt', encoding="utf-8") as myfile:
... doc=myfile.read()
# OR
# Setup the string which contains the KML file we want to read
>>> doc = """<?xml version="1.0" encoding="UTF-8"?>
... <kml xmlns="http://www.opengis.net/kml/2.2">
... <Document>
... <name>Document.kml</name>
... <open>1</open>
... <Style id="exampleStyleDocument">
... <LabelStyle>
... <color>ff0000cc</color>
... </LabelStyle>
... </Style>
... <Placemark>
... <name>Document Feature 1</name>
... <styleUrl>#exampleStyleDocument</styleUrl>
... <Point>
... <coordinates>-122.371,37.816,0</coordinates>
... </Point>
... </Placemark>
... <Placemark>
... <name>Document Feature 2</name>
... <styleUrl>#exampleStyleDocument</styleUrl>
... <Point>
... <coordinates>-122.370,37.817,0</coordinates>
... </Point>
... </Placemark>
... </Document>
... </kml>"""
# Create the KML object to store the parsed result
>>> k = kml.KML()
# Read in the KML string
>>> k.from_string(doc)
# Next we perform some simple sanity checks
# Check that the number of features is correct
# This corresponds to the single ``Document``
>>> features = list(k.features())
>>> len(features)
1
# Check that we can access the features as a generator
# (The two Placemarks of the Document)
>>> features[0].features()
<generator object features at 0x2d7d870>
>>> f2 = list(features[0].features())
>>> len(f2)
2
# Check specifics of the first Placemark in the Document
>>> f2[0]
<fastkml.kml.Placemark object at 0x2d791d0>
>>> f2[0].description
>>> f2[0].name
'Document Feature 1'
# Check specifics of the second Placemark in the Document
>>> f2[1].name
'Document Feature 2'
>>> f2[1].name = "ANOTHER NAME"
# Verify that we can print back out the KML object as a string
>>> print k.to_string(prettyprint=True)
<kml:kml xmlns:ns0="http://www.opengis.net/kml/2.2">
<kml:Document>
<kml:name>Document.kml</kml:name>
<kml:visibility>1</kml:visibility>
<kml:open>1</kml:open>
<kml:Style id="exampleStyleDocument">
<kml:LabelStyle>
<kml:color>ff0000cc</kml:color>
<kml:scale>1.0</kml:scale>
</kml:LabelStyle>
</kml:Style>
<kml:Placemark>
<kml:name>Document Feature 1</kml:name>
<kml:visibility>1</kml:visibility>
<kml:open>0</kml:open>
<kml:Point>
<kml:coordinates>-122.371000,37.816000,0.000000</kml:coordinates>
</kml:Point>
</kml:Placemark>
<kml:Placemark>
<kml:name>ANOTHER NAME</kml:name>
<kml:visibility>1</kml:visibility>
<kml:open>0</kml:open>
<kml:Point>
<kml:coordinates>-122.370000,37.817000,0.000000</kml:coordinates>
</kml:Point>
</kml:Placemark>
</kml:Document>
</kml:kml>