Merge pull request #41 from heltonbiker/master

Interactive usage examples added as standalone scripts - Thanks a lot :-)

docs/usage_guide.rst

@@ -4,6 +4,8 @@ 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
 ------------------------

examples/CreateKml.py

+# Import the library
+from fastkml import kml
+from shapely.geometry import Point, LineString, 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)
+
+expected = """<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>"""
\ No newline at end of file

examples/ReadKml.py

+from fastkml import kml
+
+# 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())
+print len(features)
+
+# Check that we can access the features as a generator
+# (The two Placemarks of the Document)
+print features[0].features()
+
+f2 = list(features[0].features())
+print len(f2)
+
+
+# Check specifics of the first Placemark in the Document
+print f2[0]
+print f2[0].description
+print f2[0].name
+
+# Check specifics of the second Placemark in the Document
+print f2[1].name
+f2[1].name = "ANOTHER NAME"
+print f2[1].name
+
+# Verify that we can print back out the KML object as a string
+print k.to_string(prettyprint=True)
+
+expected = """<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>"""
\ No newline at end of file