Package upoints :: Module kml :: Class Placemarks
[hide private]
[frames] | no frames]

Class Placemarks

   object --+        
            |        
         dict --+    
                |    
point.KeyedPoints --+
                    |
                   Placemarks

Class for representing a group of Placemark objects

Since: 0.6.0

Instance Methods [hide private]
new empty dictionary

__init__(self, kml_file=None)
Initialise a new Placemarks object
dict
import_locations(self, kml_file, kml_version=None)
Import KML data files
ET.ElementTree
export_kml_file(self, kml_version='2.2', human_namespace=False)
Generate KML element tree from Placemarks

Inherited from point.KeyedPoints: __repr__, bearing, destination, distance, final_bearing, forward, inverse, midpoint, range, sun_events, sunrise, sunset, to_grid_locator

Inherited from dict: __cmp__, __contains__, __delitem__, __eq__, __ge__, __getattribute__, __getitem__, __gt__, __hash__, __iter__, __le__, __len__, __lt__, __ne__, __new__, __setitem__, clear, copy, fromkeys, get, has_key, items, iteritems, iterkeys, itervalues, keys, pop, popitem, setdefault, update, values

Inherited from object: __delattr__, __reduce__, __reduce_ex__, __setattr__, __str__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, kml_file=None)
(Constructor)

 
Initialise a new Placemarks object
Parameters:
  • points - Point objects to wrap
  • parse - Whether to attempt import of points
  • units - Unit type to be used for distances when parsing string locations
Returns:
new empty dictionary

Overrides: object.__init__

import_locations(self, kml_file, kml_version=None)

 

Import KML data files

import_locations() returns a dictionary with keys containing the section title, and values consisting of Placemark objects.

It expects data files in KML format, as specified in KML Reference, which is XML such as:

<?xml version="1.0" encoding="utf-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
    <Document>
        <Placemark id="Home">
            <name>Home</name>
            <Point>
                <coordinates>-0.221,52.015,60</coordinates>
            </Point>
        </Placemark>
        <Placemark id="Cambridge">
            <name>Cambridge</name>
            <Point>
                <coordinates>0.390,52.167</coordinates>
            </Point>
        </Placemark>
    </Document>
</kml>

The reader uses Python's ElementTree module, so should be very fast when importing data. The above file processed by import_locations() will return the following dict object:

{"Home": Placemark(52.015, -0.221, 60),
 "Cambridge": Placemark(52.167, 0.390, None)}
>>> locations = Placemarks(open("kml"))
>>> for value in sorted(locations.values(),
...                     key=lambda x: x.name.lower()):
...     print(value)
Cambridge (52°10'01"N, 000°23'24"E)
Home (52°00'54"N, 000°13'15"W alt 60m)

The kml_version parameter allows the caller to specify the specific KML version that should be processed, this allows the caller to process inputs which contain entries in more than one namespace without duplicates resulting from entries in being specified with different namespaces.

Parameters:
  • kml_file (file, list or str) - KML data to read
  • kml_version (str) - Specific KML version entities to import
Returns: dict
Named locations with optional comments
Overrides: point.KeyedPoints.import_locations

export_kml_file(self, kml_version='2.2', human_namespace=False)

 

Generate KML element tree from Placemarks

>>> from sys import stdout
>>> locations = Placemarks(open("kml"))
>>> xml = locations.export_kml_file()
>>> xml.write(stdout)
<ns0:kml xmlns:ns0="http://earth.google.com/kml/2.2"><ns0:Document><ns0:Placemark id="Home"><ns0:name>Home</ns0:name><ns0:Point><ns0:coordinates>-0.221,52.015,60</ns0:coordinates></ns0:Point></ns0:Placemark><ns0:Placemark id="Cambridge"><ns0:name>Cambridge</ns0:name><ns0:Point><ns0:coordinates>0.39,52.167</ns0:coordinates></ns0:Point></ns0:Placemark></ns0:Document></ns0:kml>
>>> xml = locations.export_kml_file("2.0")
>>> xml.write(stdout)
<ns0:kml xmlns:ns0="http://earth.google.com/kml/2.0"><ns0:Document><ns0:Placemark id="Home"><ns0:name>Home</ns0:name><ns0:Point><ns0:coordinates>-0.221,52.015,60</ns0:coordinates></ns0:Point></ns0:Placemark><ns0:Placemark id="Cambridge"><ns0:name>Cambridge</ns0:name><ns0:Point><ns0:coordinates>0.39,52.167</ns0:coordinates></ns0:Point></ns0:Placemark></ns0:Document></ns0:kml>
Parameters:
  • kml_version (str) - KML version to generate
  • human_namespace (bool) - Whether to generate output using human readable namespace prefixes
Returns: ET.ElementTree
KML element tree depicting Placemarks