def __init__(self, **kwargs):
super(Kml, self).__init__()
self._feature = Document(**kwargs)
self._networklinkcontrol = None
self._hint = None
self._parsetext = True
self._outputkmz = False
self._images = []
self._foundimages = []
self._namespaces = ['xmlns="http://www.opengis.net/kml/2.2"', 'xmlns:gx="http://www.google.com/kml/ext/2.2"']
self._processedstyles = []
def document(self):
"""
The top level item in the kml document.
0 or 1 top level document is required for a kml document, the default is an
instance of :class:`simplekml.Document`. This property can be set to an
instance of :class:`simplekml.Document` or :class:`simplekml.Folder` or to
remove it completely set it to None
Example::
import simplekml
kml = simplekml.Kml()
kml.document = simplekml.Folder(name = "Top Level Folder")
kml.save('Document Replacement.kml')
"""
if self._feature is None:
self._feature = Document()
return self._feature
def __init__(self, **kwargs):
super(Kml, self).__init__()
self._feature = Document(**kwargs)
self._networklinkcontrol = None
self._hint = None
self._parsetext = True
self._outputkmz = False
self._images = []
self._foundimages = []
self._namespaces = ['xmlns="http://www.opengis.net/kml/2.2"', 'xmlns:gx="http://www.google.com/kml/ext/2.2"']
self._processedstyles = []
def __init__(self, **kwargs):
"""
Creates the Kml document with a [Document] as the top level feature.
Keyword Arguments:
name (string) -- name of placemark (default None)
visibility (int) -- whether the feature is shown (default 1)
open (int) -- whether open or closed in Places (default 0)
atomauthor (string) -- author of the document (default None)
atomlink (string) -- URL containing this KML (default None)
address (string) -- standard address (default None)
xaladdressdetails(string)-- address as xAL (default None)
phonenumber (string) -- phone number for Maps mobile (default None)
snippet ([Snippet]) -- short description of feature (default None)
description (string) -- description shown in balloon (default None)
camera ([Camera]) -- camera that views the scene (default None)
lookat ([LookAt]) -- camera relative to feature (default None)
timestamp ([TimeStamp]) -- single moment in time (default None)
timespan ([TimeSpan]) -- period of time (default None)
region ([Region]) -- bounding box of features (default None)
"""
self._feature = Document(**kwargs)
def document(self):
"""
The top level item in the kml document.
0 or 1 top level document is required for a kml document, the default is an
instance of :class:`simplekml.Document`. This property can be set to an
instance of :class:`simplekml.Document` or :class:`simplekml.Folder` or to
remove it completely set it to None
Example::
import simplekml
kml = simplekml.Kml()
kml.document = simplekml.Folder(name = "Top Level Folder")
kml.save('Document Replacement.kml')
"""
if self._feature is None:
self._feature = Document()
return self._feature
def __init__(self, **kwargs):
"""
Creates the Kml document with a [Document] as the top level feature.
Keyword Arguments:
name (string) -- name of placemark (default None)
visibility (int) -- whether the feature is shown (default 1)
open (int) -- whether open or closed in Places (default 0)
atomauthor (string) -- author of the document (default None)
atomlink (string) -- URL containing this KML (default None)
address (string) -- standard address (default None)
xaladdressdetails(string)-- address as xAL (default None)
phonenumber (string) -- phone number for Maps mobile (default None)
snippet ([Snippet]) -- short description of feature (default None)
description (string) -- description shown in balloon (default None)
camera ([Camera]) -- camera that views the scene (default None)
lookat ([LookAt]) -- camera relative to feature (default None)
timestamp ([TimeStamp]) -- single moment in time (default None)
timespan ([TimeSpan]) -- period of time (default None)
region ([Region]) -- bounding box of features (default None)
"""
self._feature = Document(**kwargs)
class Kml(Kmlable):
"""The main class that represents a KML file.
This class represents a KML file, and the compilation of the KML file will
be done through this class. The base feature is a document, all arguments
passed to the class on creation are the same as that of a
:class:`simplekml.Document`. To change any properties after creation you can
do so through the :attr:`simplekml.Kml.document` property
(eg. `kml.document.name = "Test"`). For a description of what the
arguments mean see the KML reference documentation published by Google:
http://code.google.com/apis/kml/documentation/kmlreference.html
Simple Example::
from simplekml import Kml
kml = Kml(name='KmlUsage')
kml.newpoint(name="Kirstenbosch", coords=[(18.432314,-33.988862)]) # A simple Point
kml.save("KmlClass.kml") # Saving
kml.savekmz("KmlClass.kmz", format=False) # Saving as KMZ
print kml.kml() # Printing out the kml to screen
"""
def __init__(self, **kwargs):
super(Kml, self).__init__()
self._feature = Document(**kwargs)
self._networklinkcontrol = None
self._hint = None
self._parsetext = True
self._outputkmz = False
self._images = []
self._foundimages = []
self._namespaces = [
'xmlns="http://www.opengis.net/kml/2.2"',
'xmlns:gx="http://www.google.com/kml/ext/2.2"'
]
self._processedstyles = []
def __str__(self):
return "<Root KML object>"
def _getnamespaces(self):
"""Return the namespaces as a string."""
return " ".join(self._namespaces)
def addfile(self, path):
"""Adds an file to a KMZ and returns the path contained inside of the KMZ (files/...)
This is useful for including images in a KMZ that are referenced from description balloons, as these files
are not automatically included in a KMZ.
Usage::
import simplekml
kml = simplekml.Kml()
path = kml.addfile("a/path/to/somefile.file")
pnt = pnt.newpoint()
pnt.description = '<img src="' + path +'" alt="picture" width="400" height="300" align="left" />'
*New in version 1.2.0*
"""
self._images.append(path)
return os.path.join('files', os.path.split(path)[1]).replace("\\", "/")
@property
def features(self):
"""Returns a list of all the features that have been attached to the top level document."""
return self.document.features
@property
def allfeatures(self):
"""Returns a list of all the features that have been attached to the top level document, and all sub features.
*New in version 1.1.0*
"""
return self.document.allfeatures
@property
def geometries(self):
"""Returns a list of all the geometries that have been attached to the top level document.
*New in version 1.1.0*
"""
return self.document.geometries
@property
def allgeometries(self):
"""Returns a list of all the geometries that have been attached to the top level document, and all sub geometries.
*New in version 1.1.0*
"""
return self.document.allgeometries
@property
def containers(self):
"""Returns a list of all the containers that have been attached to to the top level document.
*New in version 1.1.0*
"""
return self.document.containers
@property
def allcontainers(self):
"""Returns a list of all the containers that have been attached to the top level document, and all sub containers.
*New in version 1.1.0*
"""
return self.document.allcontainers
@property
def styles(self):
"""Returns a list of all the styles that have been attached to the top level document.
*New in version 1.1.0*
"""
return self.document.styles
@property
def allstyles(self):
"""Returns a list of all the styles that have been attached to the top level document, and all sub styles.
*New in version 1.1.0*
"""
return self.document.allstyles
@property
def stylemaps(self):
"""Returns a list of all the stylemaps that have been attached to the top level document.
*New in version 1.1.0*
"""
return self.document.stylemaps
@property
def allstylemaps(self):
"""Returns a list of all the stylemaps that have been attached to the top level document, and all sub stylemaps.
*New in version 1.1.0*
"""
return self.document.allstylemaps
@property
def hint(self):
"""Assign a hint attribute to the KML tag.
Possible values to use are:
* target=moon
* target=sky
* target=mars
Usage::
from simplekml import Kml
kml = Kml()
kml.hint = 'target=moon'
print kml.kml()
Result:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<kml hint="target=moon" xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
<Document id="feat_1"/>
</kml>
*New in version 1.1.0*
"""
return self._hint
@hint.setter
def hint(self, hint):
self._hint = hint
@property
def document(self):
"""
The top level item in the kml document.
0 or 1 top level document is required for a kml document, the default is an
instance of :class:`simplekml.Document`. This property can be set to an
instance of :class:`simplekml.Document` or :class:`simplekml.Folder` or to
remove it completely set it to None
Example::
import simplekml
kml = simplekml.Kml()
kml.document = simplekml.Folder(name = "Top Level Folder")
kml.save('Document Replacement.kml')
"""
if self._feature is None:
self._feature = Document()
return self._feature
@document.setter
@check(Container, True)
def document(self, doc):
self._feature = doc
def _genkml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if format = True."""
Kmlable._compiling = True
self._processedstyles = []
kml_str = ""
if self._feature is not None:
kml_str = self._feature.__str__()
networklinkcontrol_str = ""
if self._networklinkcontrol is not None:
networklinkcontrol_str = self._networklinkcontrol.__str__()
if self._hint is not None:
hint = ' hint="{0}"'.format(self._hint)
else:
hint = ''
xml_str = u("<kml {0}{2}>{1}{3}</kml>").format(self._getnamespaces(),
kml_str, hint,
networklinkcontrol_str)
if format:
KmlElement.patch()
kml_str = xml.dom.minidom.parseString(xml_str.encode("utf-8"))
KmlElement.unpatch()
Kmlable._compiling = False
return kml_str.toprettyxml(indent=" ",
newl="\n",
encoding="UTF-8").decode("utf-8")
else:
Kmlable._compiling = False
return xml_str
def parsetext(self, parse=True):
"""Sets the behavior of how text tags are parsed.
If True the values of the text tags (<name>, <description> and <text>)
are escaped, so that the values are rendered properly. If False, the
values are left as is. In both cases the CDATA element is left unchanged.
*Changed in version 1.1.0*
"""
self._parsetext = parse
def kml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if `format = True`.
PrettyPrinted Example (default)::
import simplekml
kml = simplekml.Kml()
pnt = kml.newpoint(name='A Point')
pnt.coords = [(1.0, 2.0)]
print kml.kml()
PrettyPrinted Result:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
<Document id="feat_1">
<Placemark id="feat_2">
<name>A Point</name>
<Point id="geom_0">
<coordinates>1.0,2.0,0.0</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Single Line Example::
import simplekml
kml = simplekml.Kml()
pnt = kml.newpoint(name='A Point')
pnt.coords = [(1.0, 2.0)]
print kml.kml(False)
Single Line Result:
.. code-block:: xml
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2"><Document id="feat_1"><Placemark id="feat_2"><name>A Point</name><Point id="geom_0"><coordinates>1.0,2.0,0.0</coordinates></Point></Placemark></Document></kml>
"""
Kmlable._currentroot = self
self._outputkmz = False
return self._genkml(format)
def save(self, path, format=True):
"""Save the kml to the given file supplied by `path`.
The KML is saved to a file in one long string if `format=False` else it
gets saved "prettyprinted" (as formatted xml). This works the same as :func:`simplekml.Kml.kml`
Usage::
import simplekml
kml = simplekml.Kml()
kml.save("Saving.kml")
#kml.save("Saving.kml", False) # or this
"""
Kmlable._currentroot = self
self._outputkmz = False
out = self._genkml(format)
f = codecs.open(path, 'wb', 'utf-8')
try:
f.write(out)
finally:
f.close()
def savekmz(self, path, format=True):
"""Save the kml as a kmz to the given file supplied by `path`.
The KML is saved to a file in a long string if `format=False` else it
gets saved "prettyprinted". This works the same as :func:`simplekml.Kml.kml`
Usage::
import simplekml
kml = simplekml.Kml()
kml.savekmz("Saving.kml")
#kml.savekmz("Saving.kml", False) # or this
"""
Kmlable._currentroot = self
self._outputkmz = True
out = self._genkml(format).encode('utf-8')
kmz = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
kmz.writestr("doc.kml", out)
for image in self._images:
kmz.write(image, os.path.join('files', os.path.split(image)[1]))
for image in self._foundimages:
kmz.write(image, os.path.join('files', os.path.split(image)[1]))
kmz.close()
def newdocument(self, **kwargs):
"""
Creates a new :class:`simplekml.Document`.
The document is attached to this KML document. The arguments are the same as for :class:`simplekml.Document`.
See :class:`simplekml.Document` for usage.
"""
return self.document.newdocument(**kwargs)
def newfolder(self, **kwargs):
"""
Creates a new :class:`simplekml.Folder`.
The folder is attached to this KML document. The arguments are the same as those for :class:`simplekml.Folder`
See :class:`simplekml.Folder` for usage.
"""
return self.document.newfolder(**kwargs)
def newpoint(self, **kwargs):
"""
Creates a new :class:`simplekml.Point`.
The point is attached to this KML document. The arguments are the same as those for :class:`simplekml.Point`
See :class:`simplekml.Point` for usage.
"""
return self.document.newpoint(**kwargs)
def newlinestring(self, **kwargs):
"""
Creates a new :class:`simplekml.LineString`.
The linestring is attached to this KML document. The arguments are the same as for :class:`simplekml.LineString`
See :class:`simplekml.LineString` for usage.
"""
return self.document.newlinestring(**kwargs)
def newpolygon(self, **kwargs):
"""
Creates a new :class:`simplekml.Polygon`.
The polygon is attached to this KML document. The arguments are the same as those for :class:`simplekml.Polygon`
See :class:`simplekml.Polygon` for usage.
"""
return self.document.newpolygon(**kwargs)
def newmultigeometry(self, **kwargs):
"""
Creates a new :class:`simplekml.MultiGeometry`.
The multigeometry is attached to this KML document. The arguments are the same as
for :class:`simplekml.MultiGeometry`. See :class:`simplekml.MultiGeometry` for usage.
"""
return self.document.newmultigeometry(**kwargs)
def newgroundoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.GroundOverlay`.
The groundoverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.GroundOverlay`. See :class:`simplekml.GroundOverlay` for usage.
"""
return self.document.newgroundoverlay(**kwargs)
def newscreenoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.ScreenOverlay`.
The screenoverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.ScreenOverlay`. See :class:`simplekml.ScreenOverlay` for usage.
"""
return self.document.newscreenoverlay(**kwargs)
def newphotooverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.PhotoOverlay`.
The photooverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.PhotoOverlay`. See :class:`simplekml.PhotoOverlay` for usage.
"""
return self.document.newphotooverlay(**kwargs)
def newnetworklink(self, **kwargs):
"""
Creates a new :class:`simplekml.NetworkLink`.
The networklink is attached to this KML document. The arguments are the same as those
for :class:`simplekml.NetworkLink`. See :class:`simplekml.NetworkLink` for usage.
"""
return self.document.newnetworklink(**kwargs)
def newmodel(self, **kwargs):
"""
Creates a new :class:`simplekml.Model`.
The model is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Model`
"""
return self.document.newmodel(**kwargs)
def newschema(self, **kwargs):
"""
Creates a new :class:`simplekml.Schema`.
The schem is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Schema`
"""
return self.document.newschema(**kwargs)
def newgxtrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTrack`.
The gxtrack is attached to this KML document. The arguments are the same as those for :class:`simplekml.GxTrack`
See :class:`simplekml.GxTrack` for usage.
"""
return self.document.newgxtrack(**kwargs)
def newgxmultitrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxMultiTrack`.
The gxmultitrack is attached to this KML document. The arguments are the same as those
for :class:`simplekml.GxMultiTrack`. See :class:`simplekml.GxMultiTrack` for usage.
"""
return self.document.newgxmultitrack(**kwargs)
def newgxtour(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTour`.
The tour is attached to this KML document. The arguments are the same as those for :class:`simplekml.GxTour`
See :class:`simplekml.GxTour` for usage.
"""
return self.document.newgxtour(**kwargs)
@property
def networklinkcontrol(self):
"""Accesses/Creates the :class:`simplekml.NetworkLinkControl`.
See :class:`simplekml.NetworkLinkControl` for usage example.
*New in version 1.1.1*
"""
if self._networklinkcontrol is None:
self._networklinkcontrol = NetworkLinkControl()
return self._networklinkcontrol
@networklinkcontrol.setter
def networklinkcontrol(self, networklinkcontrol):
self._networklinkcontrol = networklinkcontrol
def __init__(self, **kwargs):
self._feature = Document(**kwargs)
self._networklinkcontrol = None
self._hint = None
class Kml(object):
"""The main class that represents a KML file.
This class represents a KML file, and the compilation of the KML file will
be done through this class. The base feature is a document, all arguments
passed to the class on creation are the same as that of a
:class:`simplekml.Document`. To change any properties after creation you can
do so through the :attr:`simplekml.Kml.document` property
(eg. `kml.document.name = "Test"`). For a description of what the
arguments mean see the KML reference documentation published by Google:
http://code.google.com/apis/kml/documentation/kmlreference.html
Simple Example::
from simplekml import Kml
kml = Kml(name='KmlUsage')
kml.newpoint(name="Kirstenbosch", coords=[(18.432314,-33.988862)]) # A simple Point
kml.save("KmlClass.kml") # Saving
kml.savekmz("KmlClass.kmz", format=False) # Saving as KMZ
print kml.kml() # Printing out the kml to screen
"""
def __init__(self, **kwargs):
self._feature = Document(**kwargs)
self._networklinkcontrol = None
self._hint = None
@property
def features(self):
"""Returns a list of all the features that have been attached to the top level document."""
return self.document.features
@property
def allfeatures(self):
"""Returns a list of all the features that have been attached to the top level document, and all sub features.
*New in version 1.1.0*
"""
return self.document.allfeatures
@property
def geometries(self):
"""Returns a list of all the geometries that have been attached to the top level document.
*New in version 1.1.0*
"""
return self.document.geometries
@property
def allgeometries(self):
"""Returns a list of all the geometries that have been attached to the top level document, and all sub geometries.
*New in version 1.1.0*
"""
return self.document.allgeometries
@property
def containers(self):
"""Returns a list of all the containers that have been attached to to the top level document.
*New in version 1.1.0*
"""
return self.document.containers
@property
def allcontainers(self):
"""Returns a list of all the containers that have been attached to the top level document, and all sub containers.
*New in version 1.1.0*
"""
return self.document.allcontainers
@property
def styles(self):
"""Returns a list of all the styles that have been attached to the top level document.
*New in version 1.1.0*
"""
return self.document.styles
@property
def allstyles(self):
"""Returns a list of all the styles that have been attached to the top level document, and all sub styles.
*New in version 1.1.0*
"""
return self.document.allstyles
@property
def stylemaps(self):
"""Returns a list of all the stylemaps that have been attached to the top level document.
*New in version 1.1.0*
"""
return self.document.stylemaps
@property
def allstylemaps(self):
"""Returns a list of all the stylemaps that have been attached to the top level document, and all sub stylemaps.
*New in version 1.1.0*
"""
return self.document.allstylemaps
@property
def hint(self):
"""Assign a hint attribute to the KML tag.
Possible values to use are:
* target=moon
* target=sky
* target=mars
Usage::
from simplekml import Kml
kml = Kml()
kml.hint = 'target=moon'
print kml.kml()
Result:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<kml hint="target=moon" xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
<Document id="feat_1"/>
</kml>
*New in version 1.1.0*
"""
return self._hint
@hint.setter
def hint(self, hint):
self._hint = hint
@property
def document(self):
"""
The top level item in the kml document.
0 or 1 top level document is required for a kml document, the default is an
instance of :class:`simplekml.Document`. This property can be set to an
instance of :class:`simplekml.Document` or :class:`simplekml.Folder` or to
remove it completely set it to None
Example::
import simplekml
kml = simplekml.Kml()
kml.document = simplekml.Folder(name = "Top Level Folder")
kml.save('Document Replacement.kml')
"""
if self._feature is None:
self._feature = Document()
return self._feature
@document.setter
@check(Container, True)
def document(self, doc):
self._feature = doc
def _genkml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if format = True."""
kml_str = ""
if self._feature is not None:
kml_str = self._feature.__str__()
networklinkcontrol_str = ""
if self._networklinkcontrol is not None:
networklinkcontrol_str = self._networklinkcontrol.__str__()
if self._hint is not None:
hint = ' hint="{0}"'.format(self._hint)
else:
hint = ''
xml_str = u("<kml {0}{2}>{1}{3}</kml>").format(Kmlable._getnamespaces(), kml_str, hint, networklinkcontrol_str)
if format:
KmlElement.patch()
kml_str = xml.dom.minidom.parseString(xml_str.encode("utf-8"))
KmlElement.unpatch()
return kml_str.toprettyxml(indent=" ", newl="\n", encoding="UTF-8").decode("utf-8")
else:
return xml_str
def parsetext(self, parse=True):
"""Sets the behavior of how text tags are parsed.
If True the values of the text tags (<name>, <description> and <text>)
are escaped, so that the values are rendered properly. If False, the
values are left as is. In both cases the CDATA element is left unchanged.
*Changed in version 1.1.0*
"""
Kmlable._parsetext(parse)
def kml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if `format = True`.
PrettyPrinted Example (default)::
import simplekml
kml = simplekml.Kml()
pnt = kml.newpoint(name='A Point')
pnt.coords = [(1.0, 2.0)]
print kml.kml()
PrettyPrinted Result:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
<Document id="feat_1">
<Placemark id="feat_2">
<name>A Point</name>
<Point id="geom_0">
<coordinates>1.0,2.0,0.0</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Single Line Example::
import simplekml
kml = simplekml.Kml()
pnt = kml.newpoint(name='A Point')
pnt.coords = [(1.0, 2.0)]
print kml.kml(False)
Single Line Result:
.. code-block:: xml
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2"><Document id="feat_1"><Placemark id="feat_2"><name>A Point</name><Point id="geom_0"><coordinates>1.0,2.0,0.0</coordinates></Point></Placemark></Document></kml>
"""
Kmlable._setkmz(False)
return self._genkml(format)
def save(self, path, format=True):
"""Save the kml to the given file supplied by `path`.
The KML is saved to a file in one long string if `format=False` else it
gets saved "prettyprinted" (as formatted xml). This works the same as :func:`simplekml.Kml.kml`
Usage::
import simplekml
kml = simplekml.Kml()
kml.save("Saving.kml")
#kml.save("Saving.kml", False) # or this
"""
Kmlable._setkmz(False)
out = self._genkml(format)
f = codecs.open(path, 'wb', 'utf-8')
try:
f.write(out)
finally:
f.close()
def savekmz(self, path, format=True):
"""Save the kml as a kmz to the given file supplied by `path`.
The KML is saved to a file in a long string if `format=False` else it
gets saved "prettyprinted". This works the same as :func:`simplekml.Kml.kml`
Usage::
import simplekml
kml = simplekml.Kml()
kml.savekmz("Saving.kml")
#kml.savekmz("Saving.kml", False) # or this
"""
Kmlable._setkmz()
out = self._genkml(format).encode('utf-8')
kmz = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
kmz.writestr("doc.kml", out)
for image in Kmlable._getimages():
kmz.write(image, os.path.join('files', os.path.split(image)[1]))
kmz.close()
Kmlable._clearimages()
def newdocument(self, **kwargs):
"""
Creates a new :class:`simplekml.Document`.
The document is attached to this KML document. The arguments are the same as for :class:`simplekml.Document`.
See :class:`simplekml.Document` for usage.
"""
return self.document.newdocument(**kwargs)
def newfolder(self, **kwargs):
"""
Creates a new :class:`simplekml.Folder`.
The folder is attached to this KML document. The arguments are the same as those for :class:`simplekml.Folder`
See :class:`simplekml.Folder` for usage.
"""
return self.document.newfolder(**kwargs)
def newpoint(self, **kwargs):
"""
Creates a new :class:`simplekml.Point`.
The point is attached to this KML document. The arguments are the same as those for :class:`simplekml.Point`
See :class:`simplekml.Point` for usage.
"""
return self.document.newpoint(**kwargs)
def newlinestring(self, **kwargs):
"""
Creates a new :class:`simplekml.LineString`.
The linestring is attached to this KML document. The arguments are the same as for :class:`simplekml.LineString`
See :class:`simplekml.LineString` for usage.
"""
return self.document.newlinestring(**kwargs)
def newpolygon(self, **kwargs):
"""
Creates a new :class:`simplekml.Polygon`.
The polygon is attached to this KML document. The arguments are the same as those for :class:`simplekml.Polygon`
See :class:`simplekml.Polygon` for usage.
"""
return self.document.newpolygon(**kwargs)
def newmultigeometry(self, **kwargs):
"""
Creates a new :class:`simplekml.MultiGeometry`.
The multigeometry is attached to this KML document. The arguments are the same as
for :class:`simplekml.MultiGeometry`. See :class:`simplekml.MultiGeometry` for usage.
"""
return self.document.newmultigeometry(**kwargs)
def newgroundoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.GroundOverlay`.
The groundoverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.GroundOverlay`. See :class:`simplekml.GroundOverlay` for usage.
"""
return self.document.newgroundoverlay(**kwargs)
def newscreenoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.ScreenOverlay`.
The screenoverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.ScreenOverlay`. See :class:`simplekml.ScreenOverlay` for usage.
"""
return self.document.newscreenoverlay(**kwargs)
def newphotooverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.PhotoOverlay`.
The photooverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.PhotoOverlay`. See :class:`simplekml.PhotoOverlay` for usage.
"""
return self.document.newphotooverlay(**kwargs)
def newnetworklink(self, **kwargs):
"""
Creates a new :class:`simplekml.NetworkLink`.
The networklink is attached to this KML document. The arguments are the same as those
for :class:`simplekml.NetworkLink`. See :class:`simplekml.NetworkLink` for usage.
"""
return self.document.newnetworklink(**kwargs)
def newmodel(self, **kwargs):
"""
Creates a new :class:`simplekml.Model`.
The model is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Model`
"""
return self.document.newmodel(**kwargs)
def newschema(self, **kwargs):
"""
Creates a new :class:`simplekml.Schema`.
The schem is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Schema`
"""
return self.document.newschema(**kwargs)
def newgxtrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTrack`.
The gxtrack is attached to this KML document. The arguments are the same as those for :class:`simplekml.GxTrack`
See :class:`simplekml.GxTrack` for usage.
"""
return self.document.newgxtrack(**kwargs)
def newgxmultitrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxMultiTrack`.
The gxmultitrack is attached to this KML document. The arguments are the same as those
for :class:`simplekml.GxMultiTrack`. See :class:`simplekml.GxMultiTrack` for usage.
"""
return self.document.newgxmultitrack(**kwargs)
def newgxtour(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTour`.
The tour is attached to this KML document. The arguments are the same as those for :class:`simplekml.GxTour`
See :class:`simplekml.GxTour` for usage.
"""
return self.document.newgxtour(**kwargs)
@property
def networklinkcontrol(self):
"""Accesses/Creates the :class:`simplekml.NetworkLinkControl`.
See :class:`simplekml.NetworkLinkControl` for usage example.
*New in version 1.1.1*
"""
if self._networklinkcontrol is None:
self._networklinkcontrol = NetworkLinkControl()
return self._networklinkcontrol
@networklinkcontrol.setter
def networklinkcontrol(self, networklinkcontrol):
self._networklinkcontrol = networklinkcontrol
def addfile(self, path):
"""Adds an file to a KMZ and returns the path contained inside of the KMZ (files/...)
This is useful for including images in a KMZ that are referenced from description balloons, as these files
are not automatically included in a KMZ.
Usage::
import simplekml
kml = simplekml.Kml()
path = kml.addfile("a/path/to/somefile.file")
pnt = pnt.newpoint()
pnt.description = '<img src="' + path +'" alt="picture" width="400" height="300" align="left" />'
*New in version 1.2.0*
"""
Kmlable._addimage(path)
return os.path.join('files', os.path.split(path)[1]).replace("\\", "/")
def __init__(self, **kwargs):
self._feature = Document(**kwargs)
class Kml(object):
"""The main class that represents a KML file.
This class represents a KML file, and the compilation of the KML file will
be done through this class. The base feature is a document, all arguments
passed to the class on creation are the same as that of a
:class:`simplekml.Document`. To change any properties after creation you can
do so through the :attr:`simplekml.Kml.document` property
(eg. `kml.document.name = "Test"`). For a description of what the
arguments mean see the KML reference documentation published by Google:
http://code.google.com/apis/kml/documentation/kmlreference.html
Usage::
from simplekml import Kml
kml = Kml(name='KmlUsage')
kml.newpoint(name="Kirstenbosch", coords=[(18.432314,-33.988862)]) # A simple Point
kml.save("KmlClass.kml") # Saving
kml.savekmz("KmlClass.kmz", format=False) # Saving as KMZ
"""
def __init__(self, **kwargs):
self._feature = Document(**kwargs)
@property
def document(self):
"""
The top level item in the kml document.
A top level document is required for a kml document, the default is an
instance of :class:`simplekml.Document`. This property can be set to an
instance of :class:`simplekml.Document` or :class:`simplekml.Folder`
"""
return self._feature
@document.setter
def document(self, doc):
self._feature = doc
def _genkml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if format = True."""
kml_str = self._feature.__str__()
xml_str = u("<kml {0}>{1}</kml>").format(Kmlable._getnamespaces(), kml_str)
if format:
KmlElement.patch()
kml_str = xml.dom.minidom.parseString(xml_str.encode("utf-8"))
KmlElement.unpatch()
return kml_str.toprettyxml(indent=" ", newl="\n", encoding="UTF-8").decode("utf-8")
else:
return xml_str
def parsetext(self, parse=True):
"""Sets the behavior of how text tags are parsed.
If True the values of the text tags (<name>, <description> and <text>)
are escaped, so that the values are rendered properly. If False, the
values are left as is. If the CDATA element is being used to escape
the text strings, them set this to False.
"""
Kmlable._parsetext(parse)
def kml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if `format = True`, see :func:`simplekml.Kml.save` for an example."""
Kmlable._setkmz(False)
return self._genkml(format)
def save(self, path, format=True):
"""Save the kml to the given file supplied by `path`.
The KML is saved to a file in one long string if `format=False` else it
gets saved "prettyprinted" (as formatted xml) as shown below:
format=False:
.. code-block:: xml
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"><Document id="feat_1"><name>KmlUsage</name><Placemark id="feat_2"><name>Kirstenbosch</name><Point id="geom_0"><coordinates>18.432314,-33.988862,0.0</coordinates></Point></Placemark></Document></kml>
format=True:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
<Document id="feat_1">
<name>KmlUsage</name>
<Placemark id="feat_2">
<name>Kirstenbosch</name>
<Point id="geom_0">
<coordinates>18.432314,-33.988862,0.0</coordinates>
</Point>
</Placemark>
</Document>
</kml>
"""
Kmlable._setkmz(False)
out = self._genkml(format)
f = codecs.open(path, 'wb', 'utf-8')
try:
f.write(out)
finally:
f.close()
def savekmz(self, path, format=True):
"""Save the kml as a kmz to the given file supplied by `path`.
The KML is saved to a file in a long string if `format=False` else it
gets saved "prettyprinted" (as formatted xml), see
:func:`simplekml.Kml.save` for an example.
"""
Kmlable._setkmz()
out = self._genkml(format).encode('utf-8')
kmz = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
kmz.writestr("doc.kml", out)
for image in Kmlable._getimages():
kmz.write(image, os.path.join('files', os.path.split(image)[1]))
kmz.close()
Kmlable._clearimages()
def newdocument(self, **kwargs):
"""
Creates a new :class:`simplekml.Document`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Document`
"""
return self.document.newdocument(**kwargs)
def newfolder(self, **kwargs):
"""
Creates a new :class:`simplekml.Folder`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Folder`
"""
return self.document.newfolder(**kwargs)
def newpoint(self, **kwargs):
"""
Creates a new :class:`simplekml.Point`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Point`
"""
return self.document.newpoint(**kwargs)
def newlinestring(self, **kwargs):
"""
Creates a new :class:`simplekml.LineString`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.LineString`
"""
return self.document.newlinestring(**kwargs)
def newpolygon(self, **kwargs):
"""
Creates a new :class:`simplekml.Polygon`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Polygon`
"""
return self.document.newpolygon(**kwargs)
def newmultigeometry(self, **kwargs):
"""
Creates a new :class:`simplekml.MultiGeometry`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.MultiGeometry`
"""
return self.document.newmultigeometry(**kwargs)
def newgroundoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.GroundOverlay`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.GroundOverlay`
"""
return self.document.newgroundoverlay(**kwargs)
def newscreenoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.ScreenOverlay`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.ScreenOverlay`
"""
return self.document.newscreenoverlay(**kwargs)
def newphotooverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.PhotoOverlay`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.PhotoOverlay`
"""
return self.document.newphotooverlay(**kwargs)
def newnetworklink(self, **kwargs):
"""
Creates a new :class:`simplekml.NetworkLink`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.NetworkLink`
"""
return self.document.newnetworklink(**kwargs)
def newmodel(self, **kwargs):
"""
Creates a new :class:`simplekml.Model`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Model`
"""
return self.document.newmodel(**kwargs)
def newschema(self, **kwargs):
"""
Creates a new :class:`simplekml.Schema`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Schema`
"""
return self.document.newschema(**kwargs)
def newgxtrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTrack`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.GxTrack`
"""
return self.document.newgxtrack(**kwargs)
def newgxmultitrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxMultiTrack`.
The document is attached to this KML document. The arguments are the
same as those for :class:`simplekml.GxMultiTrack`
"""
return self.document.newgxmultitrack(**kwargs)
def newgxtour(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTour`.
The tour is attached to this KML document. The arguments are the
same as those for :class:`simplekml.GxTour`
"""
return self.document.newgxtour(**kwargs)
def __init__(self, **kwargs):
self._feature = Document(**kwargs)
class Kml(object):
"""The main class that represents a KML file.
This class represents a KML file, and the compilation of the KML file will
be done through this class. The base feature is a document, all arguments
passed to the class on creation are the same as that of a
:class:`simplekml.Document`. To change any properties after creation you can
do so through the :attr:`simplekml.Kml.document` property
(eg. `kml.document.name = "Test"`). For a description of what the
arguments mean see the KML reference documentation published by Google:
http://code.google.com/apis/kml/documentation/kmlreference.html
Simple Example::
from simplekml import Kml
kml = Kml(name='KmlUsage')
kml.newpoint(name="Kirstenbosch", coords=[(18.432314,-33.988862)]) # A simple Point
kml.save("KmlClass.kml") # Saving
kml.savekmz("KmlClass.kmz", format=False) # Saving as KMZ
print kml.kml() # Printing out the kml to screen
"""
def __init__(self, **kwargs):
self._feature = Document(**kwargs)
@property
def document(self):
"""
The top level item in the kml document.
A top level document is required for a kml document, the default is an
instance of :class:`simplekml.Document`. This property can be set to an
instance of :class:`simplekml.Document` or :class:`simplekml.Folder`
Example::
import simplekml
kml = simplekml.Kml()
kml.document = simplekml.Folder(name = "Top Level Folder")
kml.save('Document Replacement.kml')
"""
return self._feature
@document.setter
@check(Container, True)
def document(self, doc):
self._feature = doc
def _genkml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if format = True."""
kml_str = self._feature.__str__()
xml_str = u("<kml {0}>{1}</kml>").format(Kmlable._getnamespaces(), kml_str)
if format:
KmlElement.patch()
kml_str = xml.dom.minidom.parseString(xml_str.encode("utf-8"))
KmlElement.unpatch()
return kml_str.toprettyxml(indent=" ", newl="\n", encoding="UTF-8").decode("utf-8")
else:
return xml_str
def parsetext(self, parse=True):
"""Sets the behavior of how text tags are parsed.
If True the values of the text tags (<name>, <description> and <text>)
are escaped, so that the values are rendered properly. If False, the
values are left as is. If the CDATA element is being used to escape
the text strings, them set this to False.
"""
Kmlable._parsetext(parse)
def kml(self, format=True):
"""Returns the kml as a string or "prettyprinted" if `format = True`.
PrettyPrinted Example (default)::
import simplekml
kml = simplekml.Kml()
pnt = kml.newpoint(name='A Point')
pnt.coords = [(1.0, 2.0)]
print kml.kml()
PrettyPrinted Result:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
<Document id="feat_1">
<Placemark id="feat_2">
<name>A Point</name>
<Point id="geom_0">
<coordinates>1.0,2.0,0.0</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Single Line Example::
import simplekml
kml = simplekml.Kml()
pnt = kml.newpoint(name='A Point')
pnt.coords = [(1.0, 2.0)]
print kml.kml(False)
Single Line Result:
.. code-block:: xml
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2"><Document id="feat_1"><Placemark id="feat_2"><name>A Point</name><Point id="geom_0"><coordinates>1.0,2.0,0.0</coordinates></Point></Placemark></Document></kml>
"""
Kmlable._setkmz(False)
return self._genkml(format)
def save(self, path, format=True):
"""Save the kml to the given file supplied by `path`.
The KML is saved to a file in one long string if `format=False` else it
gets saved "prettyprinted" (as formatted xml). This works the same as :func:`simplekml.Kml.kml`
Usage::
import simplekml
kml = simplekml.Kml()
kml.save("Saving.kml")
#kml.save("Saving.kml", False) # or this
"""
Kmlable._setkmz(False)
out = self._genkml(format)
f = codecs.open(path, 'wb', 'utf-8')
try:
f.write(out)
finally:
f.close()
def savekmz(self, path, format=True):
"""Save the kml as a kmz to the given file supplied by `path`.
The KML is saved to a file in a long string if `format=False` else it
gets saved "prettyprinted". This works the same as :func:`simplekml.Kml.kml`
Usage::
import simplekml
kml = simplekml.Kml()
kml.savekmz("Saving.kml")
#kml.savekmz("Saving.kml", False) # or this
"""
Kmlable._setkmz()
out = self._genkml(format).encode('utf-8')
kmz = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
kmz.writestr("doc.kml", out)
for image in Kmlable._getimages():
kmz.write(image, os.path.join('files', os.path.split(image)[1]))
kmz.close()
Kmlable._clearimages()
def newdocument(self, **kwargs):
"""
Creates a new :class:`simplekml.Document`.
The document is attached to this KML document. The arguments are the same as for :class:`simplekml.Document`.
See :class:`simplekml.Document` for usage.
"""
return self.document.newdocument(**kwargs)
def newfolder(self, **kwargs):
"""
Creates a new :class:`simplekml.Folder`.
The folder is attached to this KML document. The arguments are the same as those for :class:`simplekml.Folder`
See :class:`simplekml.Folder` for usage.
"""
return self.document.newfolder(**kwargs)
def newpoint(self, **kwargs):
"""
Creates a new :class:`simplekml.Point`.
The point is attached to this KML document. The arguments are the same as those for :class:`simplekml.Point`
See :class:`simplekml.Point` for usage.
"""
return self.document.newpoint(**kwargs)
def newlinestring(self, **kwargs):
"""
Creates a new :class:`simplekml.LineString`.
The linestring is attached to this KML document. The arguments are the same as for :class:`simplekml.LineString`
See :class:`simplekml.LineString` for usage.
"""
return self.document.newlinestring(**kwargs)
def newpolygon(self, **kwargs):
"""
Creates a new :class:`simplekml.Polygon`.
The polygon is attached to this KML document. The arguments are the same as those for :class:`simplekml.Polygon`
See :class:`simplekml.Polygon` for usage.
"""
return self.document.newpolygon(**kwargs)
def newmultigeometry(self, **kwargs):
"""
Creates a new :class:`simplekml.MultiGeometry`.
The multigeometry is attached to this KML document. The arguments are the same as
for :class:`simplekml.MultiGeometry`. See :class:`simplekml.MultiGeometry` for usage.
"""
return self.document.newmultigeometry(**kwargs)
def newgroundoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.GroundOverlay`.
The groundoverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.GroundOverlay`. See :class:`simplekml.GroundOverlay` for usage.
"""
return self.document.newgroundoverlay(**kwargs)
def newscreenoverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.ScreenOverlay`.
The screenoverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.ScreenOverlay`. See :class:`simplekml.ScreenOverlay` for usage.
"""
return self.document.newscreenoverlay(**kwargs)
def newphotooverlay(self, **kwargs):
"""
Creates a new :class:`simplekml.PhotoOverlay`.
The photooverlay is attached to this KML document. The arguments are the same as those
for :class:`simplekml.PhotoOverlay`. See :class:`simplekml.PhotoOverlay` for usage.
"""
return self.document.newphotooverlay(**kwargs)
def newnetworklink(self, **kwargs):
"""
Creates a new :class:`simplekml.NetworkLink`.
The networklink is attached to this KML document. The arguments are the same as those
for :class:`simplekml.NetworkLink`. See :class:`simplekml.NetworkLink` for usage.
"""
return self.document.newnetworklink(**kwargs)
def newmodel(self, **kwargs):
"""
Creates a new :class:`simplekml.Model`.
The model is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Model`
"""
return self.document.newmodel(**kwargs)
def newschema(self, **kwargs):
"""
Creates a new :class:`simplekml.Schema`.
The schem is attached to this KML document. The arguments are the
same as those for :class:`simplekml.Schema`
"""
return self.document.newschema(**kwargs)
def newgxtrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTrack`.
The gxtrack is attached to this KML document. The arguments are the same as those for :class:`simplekml.GxTrack`
See :class:`simplekml.GxTrack` for usage.
"""
return self.document.newgxtrack(**kwargs)
def newgxmultitrack(self, **kwargs):
"""
Creates a new :class:`simplekml.GxMultiTrack`.
The gxmultitrack is attached to this KML document. The arguments are the same as those
for :class:`simplekml.GxMultiTrack`. See :class:`simplekml.GxMultiTrack` for usage.
"""
return self.document.newgxmultitrack(**kwargs)
def newgxtour(self, **kwargs):
"""
Creates a new :class:`simplekml.GxTour`.
The tour is attached to this KML document. The arguments are the same as those for :class:`simplekml.GxTour`
See :class:`simplekml.GxTour` for usage.
"""
return self.document.newgxtour(**kwargs)
class Kml(object):
"""
The main class that represents a KML file.
This class represents a KML file, and the compilation of the KML file will
be done through this class. The base feature is a document, all arguments
passed to the class on creation are the same as that of a [Document]. To
change any properties after creation you can do so through the `document`
property (eg. `kml.document.name = "Test"`). For a description of what the
arguments mean see the KML reference documentation published by Google:
http://code.google.com/apis/kml/documentation/kmlreference.html
Keyword Arguments:
name (string) -- name of placemark (default None)
visibility (int) -- whether the feature is shown (default 1)
open (int) -- whether open or closed in Places (default 0)
atomauthor (string) -- author of the document (default None)
atomlink (string) -- URL containing this KML (default None)
address (string) -- standard address (default None)
xaladdressdetails (string) -- address as xAL (default None)
phonenumber (string) -- phone number for Maps mobile (default None)
snippet ([Snippet]) -- short description of feature (default None)
description (string) -- description shown in balloon (default None)
camera ([Camera]) -- camera that views the scene (default None)
lookat ([LookAt]) -- camera relative to feature (default None)
timestamp ([TimeStamp]) -- single moment in time (default None)
timespan ([TimeSpan]) -- period of time (default None)
region ([Region]) -- bounding box of features (default None)
Properties:
document ([Document]) -- [Document] or [Folder] (default [Document])
Public Methods:
newpoint -- Creates a new [Point]
newlinestring -- Creates a new [LineString]
newpolygon -- Creates a new [Polygon]
newmultigeometry -- Creates a new [MultiGeometry]
newgroundoverlay -- Creates a new [GroundOverlay]
newscreenoverlay -- Creates a new [ScreenOverlay]
newphotooverlay -- Creates a new [PhotoOverlay]
newnetworklink -- Creates a new [NetworkLink]
newmodel -- Creates a new [Model]
newschema -- Creates a new [Schema]
newgxtrack -- Creates a new [GxTrack]
newgxmultitrack -- Creates a new [GxMultiTrack]
kml -- Returns the generated kml as a string
save -- Saves to a KML file
savekmz -- Saves to a KMZ file
"""
def __init__(self, **kwargs):
"""
Creates the Kml document with a [Document] as the top level feature.
Keyword Arguments:
name (string) -- name of placemark (default None)
visibility (int) -- whether the feature is shown (default 1)
open (int) -- whether open or closed in Places (default 0)
atomauthor (string) -- author of the document (default None)
atomlink (string) -- URL containing this KML (default None)
address (string) -- standard address (default None)
xaladdressdetails(string)-- address as xAL (default None)
phonenumber (string) -- phone number for Maps mobile (default None)
snippet ([Snippet]) -- short description of feature (default None)
description (string) -- description shown in balloon (default None)
camera ([Camera]) -- camera that views the scene (default None)
lookat ([LookAt]) -- camera relative to feature (default None)
timestamp ([TimeStamp]) -- single moment in time (default None)
timespan ([TimeSpan]) -- period of time (default None)
region ([Region]) -- bounding box of features (default None)
"""
self._feature = Document(**kwargs)
@property
def document(self):
"""
The top level item in the kml document.
A top level document is required for a kml document, the default is an
instance of the [Document] class. This property can be set to an
instance of a container class: [Document] or [Folder]
"""
return self._feature
@document.setter
def document(self, doc):
self._feature = doc
def _genkml(self, format=True):
"""
Returns the kml as a string or as a single line or formatted.
Keyword arguments:
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
kml_tag = 'xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"'
xmlstr = u"<kml {0}>{1}</kml>".format(kml_tag, self._feature.__str__())
if format:
KmlElement.patch()
kmlstr = xml.dom.minidom.parseString(xmlstr.encode("utf-8"))
KmlElement.unpatch()
return kmlstr.toprettyxml(indent=" ",
newl="\n",
encoding="UTF-8").decode("utf-8")
else:
return xmlstr
def parsetext(self, parse=True):
"""
Sets the behavior of how text tags are parsed.
If True the values of the text tags (<name>, <description> and <text>)
are escaped, so that the values are rendered properly. If False, the
values are left as is. If the CDATA element is being used to escape
the text strings, them set this to False.
Keyword arguments:
parse (bool) -- whether to parse text values
"""
Kmlable._parsetext(parse)
def kml(self, format=True):
"""
Returns a string containing the KML.
Keyword arguments:
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
Kmlable._setkmz(False)
return self._genkml(format)
def save(self, path, format=True):
"""
Save the kml to the given file supplied by path.
Keyword arguments:
path (string) -- the path of the kml file to be saved
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
Kmlable._setkmz(False)
out = self._genkml(format)
f = codecs.open(path, 'wb', 'utf-8')
try:
f.write(out)
finally:
f.close()
def savekmz(self, path, format=True):
"""
Save the kml as a kmz file to the given file supplied by `path`.
Keyword arguments:
path (string) -- the path of the kmz file to be saved
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
Kmlable._setkmz()
out = self._genkml(format)
kmz = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
kmz.writestr("doc.kml", out)
for image in Kmlable._getimages():
kmz.write(image, os.path.join('files', os.path.split(image)[1]))
kmz.close()
Kmlable._clearimages()
def newdocument(self, **kwargs):
"""
Creates a new [Document] and attaches it to this KML document.
Returns an instance of [Document] class.
Keyword Arguments:
Same as [Document].
"""
return self.document.newdocument(**kwargs)
def newfolder(self, **kwargs):
"""
Creates a new [Folder] and attaches it to this KML document.
Returns an instance of [Folder] class.
Keyword Arguments:
Same as [Folder].
"""
return self.document.newfolder(**kwargs)
def newpoint(self, **kwargs):
"""
Creates a new [Point] and attaches it to this KML document.
Returns an instance of [Point] class.
Keyword Arguments:
Same as [Point].
"""
return self.document.newpoint(**kwargs)
def newlinestring(self, **kwargs):
"""
Creates a new [LineString] and attaches it to this KML document.
Returns an instance of [LineString] class.
Keyword Arguments:
Same as [LineString].
"""
return self.document.newlinestring(**kwargs)
def newpolygon(self, **kwargs):
"""
Creates a new [Polygon] and attaches it to this KML document.
Returns an instance of [Polygon] class.
Keyword Arguments:
Same as [Polygon].
"""
return self.document.newpolygon(**kwargs)
def newmultigeometry(self, **kwargs):
"""
Creates a new [MultiGeometry] and attaches it to this KML document.
Returns an instance of [MultiGeometry] class.
Keyword Arguments:
Same as [MultiGeometry].
"""
return self.document.newmultigeometry(**kwargs)
def newgroundoverlay(self, **kwargs):
"""
Creates a new [GroundOverlay] and attaches it to this KML document.
Returns an instance of [GroundOverlay] class.
Keyword Arguments:
Same as [GroundOverlay].
"""
return self.document.newgroundoverlay(**kwargs)
def newscreenoverlay(self, **kwargs):
"""
Creates a new [ScreenOverlay] and attaches it to this KML document.
Returns an instance of [ScreenOverlay] class.
Keyword Arguments:
Same as [ScreenOverlay].
"""
return self.document.newscreenoverlay(**kwargs)
def newphotooverlay(self, **kwargs):
"""
Creates a new [PhotoOverlay] and attaches it to this KML document.
Returns an instance of [PhotoOverlay] class.
Keyword Arguments:
Same as [PhotoOverlay].
"""
return self.document.newphotooverlay(**kwargs)
def newnetworklink(self, **kwargs):
"""
Creates a new [NetworkLink] and attaches it to the this KML document.
Returns an instance of [NetworkLink] class.
Keyword Arguments:
Same as [NetworkLink].
"""
return self.document.newnetworklink(**kwargs)
def newmodel(self, **kwargs):
"""
Creates a new [Model] and attaches it to this KML document.
Returns an instance of [Model] class.
Keyword Arguments:
Same as [Model].
"""
return self.document.newmodel(**kwargs)
def newschema(self, **kwargs):
"""
Creates a new [Schema] and attaches it to this KML document.
Returns an instance of [Schema] class.
Keyword Arguments:
Same as [Schema].
"""
return self.document.newschema(**kwargs)
def newgxtrack(self, **kwargs):
"""
Creates a new [GxTrack] and attaches it to this KML document.
Returns an instance of [GxTrack] class.
Keyword Arguments:
Same as [GxTrack].
"""
return self.document.newgxtrack(**kwargs)
def newgxmultitrack(self, **kwargs):
"""
Creates a new [GxMultiTrack] and attaches it to this KML document.
Returns an instance of [GxMultiTrack] class.
Keyword Arguments:
Same as [GxMultiTrack].
"""
return self.document.newgxmultitrack(**kwargs)
def __init__(self, name_as_id=False, **kwargs):
self._feature = Document(name_as_id, **kwargs)
self._networklinkcontrol = None
self._hint = None
class Kml(object):
"""
The main class that represents a KML file.
This class represents a KML file, and the compilation of the KML file will
be done through this class. The base feature is a document, all arguments
passed to the class on creation are the same as that of a [Document]. To
change any properties after creation you can do so through the `document`
property (eg. `kml.document.name = "Test"`). For a description of what the
arguments mean see the KML reference documentation published by Google:
http://code.google.com/apis/kml/documentation/kmlreference.html
Keyword Arguments:
name (string) -- name of placemark (default None)
visibility (int) -- whether the feature is shown (default 1)
open (int) -- whether open or closed in Places (default 0)
atomauthor (string) -- author of the document (default None)
atomlink (string) -- URL containing this KML (default None)
address (string) -- standard address (default None)
xaladdressdetails (string) -- address as xAL (default None)
phonenumber (string) -- phone number for Maps mobile (default None)
snippet ([Snippet]) -- short description of feature (default None)
description (string) -- description shown in balloon (default None)
camera ([Camera]) -- camera that views the scene (default None)
lookat ([LookAt]) -- camera relative to feature (default None)
timestamp ([TimeStamp]) -- single moment in time (default None)
timespan ([TimeSpan]) -- period of time (default None)
region ([Region]) -- bounding box of features (default None)
Properties:
document ([Document]) -- [Document] or [Folder] (default [Document])
Public Methods:
newpoint -- Creates a new [Point]
newlinestring -- Creates a new [LineString]
newpolygon -- Creates a new [Polygon]
newmultigeometry -- Creates a new [MultiGeometry]
newgroundoverlay -- Creates a new [GroundOverlay]
newscreenoverlay -- Creates a new [ScreenOverlay]
newphotooverlay -- Creates a new [PhotoOverlay]
newnetworklink -- Creates a new [NetworkLink]
newmodel -- Creates a new [Model]
newschema -- Creates a new [Schema]
newgxtrack -- Creates a new [GxTrack]
newgxmultitrack -- Creates a new [GxMultiTrack]
kml -- Returns the generated kml as a string
save -- Saves to a KML file
savekmz -- Saves to a KMZ file
"""
def __init__(self, **kwargs):
"""
Creates the Kml document with a [Document] as the top level feature.
Keyword Arguments:
name (string) -- name of placemark (default None)
visibility (int) -- whether the feature is shown (default 1)
open (int) -- whether open or closed in Places (default 0)
atomauthor (string) -- author of the document (default None)
atomlink (string) -- URL containing this KML (default None)
address (string) -- standard address (default None)
xaladdressdetails(string)-- address as xAL (default None)
phonenumber (string) -- phone number for Maps mobile (default None)
snippet ([Snippet]) -- short description of feature (default None)
description (string) -- description shown in balloon (default None)
camera ([Camera]) -- camera that views the scene (default None)
lookat ([LookAt]) -- camera relative to feature (default None)
timestamp ([TimeStamp]) -- single moment in time (default None)
timespan ([TimeSpan]) -- period of time (default None)
region ([Region]) -- bounding box of features (default None)
"""
self._feature = Document(**kwargs)
@property
def document(self):
"""
The top level item in the kml document.
A top level document is required for a kml document, the default is an
instance of the [Document] class. This property can be set to an
instance of a container class: [Document] or [Folder]
"""
return self._feature
@document.setter
def document(self, doc):
self._feature = doc
def _genkml(self, format=True):
"""
Returns the kml as a string or as a single line or formatted.
Keyword arguments:
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
kml_tag = 'xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"'
xmlstr = u"<kml {0}>{1}</kml>".format(kml_tag, self._feature.__str__())
if format:
KmlElement.patch()
kmlstr = xml.dom.minidom.parseString(xmlstr.encode("utf-8"))
KmlElement.unpatch()
return kmlstr.toprettyxml(indent=" ", newl="\n", encoding="UTF-8").decode("utf-8")
else:
return xmlstr
def parsetext(self, parse=True):
"""
Sets the behavior of how text tags are parsed.
If True the values of the text tags (<name>, <description> and <text>)
are escaped, so that the values are rendered properly. If False, the
values are left as is. If the CDATA element is being used to escape
the text strings, them set this to False.
Keyword arguments:
parse (bool) -- whether to parse text values
"""
Kmlable._parsetext(parse)
def kml(self, format=True):
"""
Returns a string containing the KML.
Keyword arguments:
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
Kmlable._setkmz(False)
return self._genkml(format)
def save(self, path, format=True):
"""
Save the kml to the given file supplied by path.
Keyword arguments:
path (string) -- the path of the kml file to be saved
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
Kmlable._setkmz(False)
out = self._genkml(format)
f = codecs.open(path, 'wb', 'utf-8')
try:
f.write(out)
finally:
f.close()
def savekmz(self, path, format=True):
"""
Save the kml as a kmz file to the given file supplied by `path`.
Keyword arguments:
path (string) -- the path of the kmz file to be saved
format (bool) -- format the resulting kml "prettyprint" (default True)
"""
Kmlable._setkmz()
out = self._genkml(format)
kmz = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
kmz.writestr("doc.kml", out)
for image in Kmlable._getimages():
kmz.write(image, os.path.join('files', os.path.split(image)[1]))
kmz.close()
Kmlable._clearimages()
def newdocument(self, **kwargs):
"""
Creates a new [Document] and attaches it to this KML document.
Returns an instance of [Document] class.
Keyword Arguments:
Same as [Document].
"""
return self.document.newdocument(**kwargs)
def newfolder(self, **kwargs):
"""
Creates a new [Folder] and attaches it to this KML document.
Returns an instance of [Folder] class.
Keyword Arguments:
Same as [Folder].
"""
return self.document.newfolder(**kwargs)
def newpoint(self, **kwargs):
"""
Creates a new [Point] and attaches it to this KML document.
Returns an instance of [Point] class.
Keyword Arguments:
Same as [Point].
"""
return self.document.newpoint(**kwargs)
def newlinestring(self, **kwargs):
"""
Creates a new [LineString] and attaches it to this KML document.
Returns an instance of [LineString] class.
Keyword Arguments:
Same as [LineString].
"""
return self.document.newlinestring(**kwargs)
def newpolygon(self, **kwargs):
"""
Creates a new [Polygon] and attaches it to this KML document.
Returns an instance of [Polygon] class.
Keyword Arguments:
Same as [Polygon].
"""
return self.document.newpolygon(**kwargs)
def newmultigeometry(self, **kwargs):
"""
Creates a new [MultiGeometry] and attaches it to this KML document.
Returns an instance of [MultiGeometry] class.
Keyword Arguments:
Same as [MultiGeometry].
"""
return self.document.newmultigeometry(**kwargs)
def newgroundoverlay(self, **kwargs):
"""
Creates a new [GroundOverlay] and attaches it to this KML document.
Returns an instance of [GroundOverlay] class.
Keyword Arguments:
Same as [GroundOverlay].
"""
return self.document.newgroundoverlay(**kwargs)
def newscreenoverlay(self, **kwargs):
"""
Creates a new [ScreenOverlay] and attaches it to this KML document.
Returns an instance of [ScreenOverlay] class.
Keyword Arguments:
Same as [ScreenOverlay].
"""
return self.document.newscreenoverlay(**kwargs)
def newphotooverlay(self, **kwargs):
"""
Creates a new [PhotoOverlay] and attaches it to this KML document.
Returns an instance of [PhotoOverlay] class.
Keyword Arguments:
Same as [PhotoOverlay].
"""
return self.document.newphotooverlay(**kwargs)
def newnetworklink(self, **kwargs):
"""
Creates a new [NetworkLink] and attaches it to the this KML document.
Returns an instance of [NetworkLink] class.
Keyword Arguments:
Same as [NetworkLink].
"""
return self.document.newnetworklink(**kwargs)
def newmodel(self, **kwargs):
"""
Creates a new [Model] and attaches it to this KML document.
Returns an instance of [Model] class.
Keyword Arguments:
Same as [Model].
"""
return self.document.newmodel(**kwargs)
def newschema(self, **kwargs):
"""
Creates a new [Schema] and attaches it to this KML document.
Returns an instance of [Schema] class.
Keyword Arguments:
Same as [Schema].
"""
return self.document.newschema(**kwargs)
def newgxtrack(self, **kwargs):
"""
Creates a new [GxTrack] and attaches it to this KML document.
Returns an instance of [GxTrack] class.
Keyword Arguments:
Same as [GxTrack].
"""
return self.document.newgxtrack(**kwargs)
def newgxmultitrack(self, **kwargs):
"""
Creates a new [GxMultiTrack] and attaches it to this KML document.
Returns an instance of [GxMultiTrack] class.
Keyword Arguments:
Same as [GxMultiTrack].
"""
return self.document.newgxmultitrack(**kwargs)
