fastkml package¶

Module contents¶

Fastkml is a library to read, write and manipulate kml files.

It aims to keep it simple and fast (using lxml if available). Fast refers to the time you spend to write and read KML files as well as the time you spend to get acquainted to the library or to create KML objects. It provides a subset of KML and is aimed at documents that can be read from multiple clients such as openlayers and google maps rather than to give you all functionality that KML on google earth provides.

Return the names one author of the feed/entry.

A feed/entry may have multiple authors.

Specifies how the description balloon for placemarks is drawn.

The <bgColor>, if specified, is used as the background color of the balloon.

https://developers.google.com/kml/documentation/kmlreference#balloonstyle

bg_color: str | None

display_mode: DisplayMode | None

text: str | None

text_color: str | None

Defines the virtual camera that views the scene. This element defines the position of the camera relative to the Earth’s surface as well as the viewing direction of the camera. The camera position is defined by <longitude>, <latitude>, <altitude>, and either <altitudeMode> or <gx:altitudeMode>. The viewing direction of the camera is defined by <heading>, <tilt>, and <roll>. <Camera> can be a child element of any Feature or of <NetworkLinkControl>. A parent element cannot contain both a <Camera> and a <LookAt> at the same time.

<Camera> provides full six-degrees-of-freedom control over the view, so you can position the Camera in space and then rotate it around the X, Y, and Z axes. Most importantly, you can tilt the camera view so that you’re looking above the horizon into the sky.

<Camera> can also contain a TimePrimitive (<gx:TimeSpan> or <gx:TimeStamp>). Time values in Camera affect historical imagery, sunlight, and the display of time-stamped features. For more information, read Time with AbstractViews in the Time and Animation chapter of the Developer’s Guide.

roll: float | None

Return the names one contributor to the feed/entry.

A feed/entry may have multiple contributor elements.

Represents an untyped name/value pair with optional display name.

display_name: str | None

name: str | None

value: str | None

A Document is a container for features and styles. This element is required if your KML file uses shared styles or schemata for typed extended data.

get_style_by_url(style_url: str) → Style | StyleMap | None

schemata: List[Schema]

Represents a list of untyped name/value pairs. See docs:

-> ‘Adding Untyped Name/Value Pairs’: https://developers.google.com/kml/documentation/extendeddata

elements: List[Data | SchemaData]

class fastkml.Folder(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, name: str | None = None, visibility: bool | None = None, isopen: bool | None = None, atom_link: Link | None = None, atom_author: Author | None = None, address: str | None = None, phone_number: str | None = None, snippet: Snippet | None = None, description: str | None = None, view: Camera | LookAt | None = None, times: TimeSpan | TimeStamp | None = None, style_url: StyleUrl | None = None, styles: Iterable[Style | StyleMap] | None = None, region: Region | None = None, extended_data: ExtendedData | None = None, features: Iterable[_Feature] | None = None, **kwargs: Any): A Folder is used to arrange other Features hierarchically (Folders, Placemarks, #NetworkLinks, or #Overlays).

This element draws an image overlay draped onto the terrain. The <href> child of <Icon> specifies the image to be used as the overlay. This file can be either on a local file system or on a web server. If this element is omitted or contains no <href>, a rectangle is drawn using the color and LatLonBox bounds defined by the ground overlay.

https://developers.google.com/kml/documentation/kmlreference#groundoverlay

altitude: float | None

altitude_mode: AltitudeMode | None

lat_lon_box: LatLonBox | None

Specifies how icons for point Placemarks are drawn.

The <Icon> element specifies the icon image. The <scale> element specifies the x, y scaling of the icon. The color specified in the <color> element of <IconStyle> is blended with the color of the <Icon>.

https://developers.google.com/kml/documentation/kmlreference#iconstyle

heading: float | None

hot_spot: HotSpot | None

icon_href: str | None

scale: float | None

represents a KML File.

append(kmlobj: Folder | Document | Placemark | GroundOverlay | PhotoOverlay) → None: Append a feature.

classmethod class_from_string(string: str, *, ns: str | None = None, name_spaces: Dict[str, str] | None = None, strict: bool = True) → Self: Create a kml object from a string.

Args:¶

string: String representation (serialized XML) of the kml object ns: Namespace of the element (default: None) name_spaces: Dictionary of namespace prefixes and URIs (default: None) strict: Whether to enforce strict parsing (default: True)

Returns:¶

Geometry object

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element: Return an Element object representing the KML element.

Args:¶

precision (Optional[int]): The precision used for floating-point values. verbosity (Verbosity): The verbosity level for generating the KML element.

Returns:¶

Element: The etree Element object representing the KML element.

classmethod get_tag_name() → str: Return the tag name.

ns: str

Specifies how the <name> of a Feature is drawn in the 3D viewer.

A custom color, color mode, and scale for the label (name) can be specified.

https://developers.google.com/kml/documentation/kmlreference#labelstyle

scale: float | None

The drawing style (color, color mode, and line width) for all line geometry.

Line geometry includes the outlines of outlined polygons and the extruded “tether” of Placemark icons (if extrusion is enabled). https://developers.google.com/kml/documentation/kmlreference#linestyle

width: float | None

Identifies a related Web page. The rel attribute defines the type of relation. A feed is limited to one alternate per type and hreflang. <link> is patterned after html’s link element. It has one required attribute, href, and five optional attributes: rel, type, hreflang, title, and length.

href: str | None

hreflang: str | None

length: int | None

rel: str | None

title: str | None

type: str | None

range: float | None

The <PhotoOverlay> element allows you to geographically locate a photograph on the Earth and to specify viewing parameters for this PhotoOverlay. The PhotoOverlay can be a simple 2D rectangle, a partial or full cylinder, or a sphere (for spherical panoramas). The overlay is placed at the specified location and oriented toward the viewpoint.

Because <PhotoOverlay> is derived from <Feature>, it can contain one of the two elements derived from <AbstractView>—either <Camera> or <LookAt>. The Camera (or LookAt) specifies a viewpoint and a viewing direction (also referred to as a view vector). The PhotoOverlay is positioned in relation to the viewpoint. Specifically, the plane of a 2D rectangular image is orthogonal (at right angles to) the view vector. The normal of this plane—that is, its front, which is the part with the photo—is oriented toward the viewpoint.

The URL for the PhotoOverlay image is specified in the <Icon> tag, which is inherited from <Overlay>. The <Icon> tag must contain an <href> element that specifies the image file to use for the PhotoOverlay. In the case of a very large image, the <href> is a special URL that indexes into a pyramid of images of varying resolutions (see ImagePyramid).

https://developers.google.com/kml/documentation/kmlreference#photooverlay

image_pyramid: ImagePyramid | None

point: Point | None

rotation: float | None

shape: Shape | None

view_volume: ViewVolume | None

A Placemark is a Feature with associated Geometry. In Google Earth, a Placemark appears as a list item in the Places panel. A Placemark with a Point has an icon associated with it that marks a point on the Earth in the 3D viewer.

property geometry: Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection | None

kml_geometry: Point | LineString | LinearRing | Polygon | MultiGeometry | MultiTrack | Track | None

Drawing style for polygons.

Specifies the drawing style for all polygons, including polygon extrusions (which look like the walls of buildings) and line extrusions (which look like solid fences).

https://developers.google.com/kml/documentation/kmlreference#polystyle

fill: bool | None

outline: bool | None

Specifies a custom KML schema that is used to add custom data to KML Features.

The “id” attribute is required and must be unique within the KML file. <Schema> is always a child of <Document>.

https://developers.google.com/kml/documentation/extendeddata#declare-the-schema-element

append(field: SimpleField) → None: Append a field.

fields: List[SimpleField]

name: str | None

<SchemaData schemaUrl=”anyURI”> This element is used in conjunction with <Schema> to add typed custom data to a KML Feature. The Schema element (identified by the schemaUrl attribute) declares the custom data type. The actual data objects (“instances” of the custom data) are defined using the SchemaData element. The <schemaURL> can be a full URL, a reference to a Schema ID defined in an external KML file, or a reference to a Schema ID defined in the same KML file.

append_data(data: SimpleData) → None

data: List[SimpleData]

schema_url: str | None

A Style defines an addressable style group.

It can be referenced by StyleMaps and Features. Styles affect how Geometry is presented in the 3D viewer and how Features appear in the Places panel of the List view. Shared styles are collected in a <Document> and must have an id defined for them so that they can be referenced by the individual Features that use them.

https://developers.google.com/kml/documentation/kmlreference#style

A <StyleMap> maps between two different Styles. Typically a <StyleMap> element is used to provide separate normal and highlighted styles for a placemark, so that the highlighted version appears when the user mouses over the icon in Google Earth.

https://developers.google.com/kml/documentation/kmlreference#stylemap

property highlight: StyleUrl | Style | None

property normal: StyleUrl | Style | None

pairs: List[Pair]

URL of a <Style> or <StyleMap> defined in a Document.

If the style is in the same file, use a # reference. If the style is defined in an external file, use a full URL along with # referencing.

https://developers.google.com/kml/documentation/kmlreference#styleurl

classmethod get_tag_name() → str: Return the tag name.

url: str | None

Represents an extent in time bounded by begin and end dateTimes.

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element: Return the KML Object as an Element.

Represents a single moment in time.

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element: Return the KML Object as an Element.

Submodules¶

fastkml.about module¶

About fastkml.

The only purpose of this module is to provide a version number for the package.

fastkml.atom module¶

KML 2.2 supports new elements for including data about the author and related website in your KML file. This information is displayed in geo search results, both in Earth browsers such as Google Earth, and in other applications such as Google Maps. The ascription elements used in KML are as follows:

atom:author element - parent element for atom:name atom:name element - the name of the author atom:link element - contains the href attribute href attribute - URL of the web page containing the KML/KMZ file

These elements are defined in the Atom Syndication Format. The complete specification is found at http://atompub.org.

This library only implements a subset of Atom that is useful with KML

Bases: _Person

Return the names one author of the feed/entry.

A feed/entry may have multiple authors.

Bases: _Person

Return the names one contributor to the feed/entry.

A feed/entry may have multiple contributor elements.

Bases: _AtomObject

Identifies a related Web page. The rel attribute defines the type of relation. A feed is limited to one alternate per type and hreflang. <link> is patterned after html’s link element. It has one required attribute, href, and five optional attributes: rel, type, hreflang, title, and length.

href: str | None¶

hreflang: str | None¶

length: int | None¶

name_spaces: Dict[str, str]¶

ns: str¶

rel: str | None¶

title: str | None¶

type: str | None¶

fastkml.base module¶

Abstract base classes.

fastkml.config module¶

Frequently used constants and configuration options.

fastkml.config.register_namespaces(**namespaces: str) → None¶: Register namespaces for use in etree.ElementTree.parse().

fastkml.config.set_default_namespaces() → None¶: Register the default namespaces for use in etree.ElementTree.parse().

fastkml.config.set_etree_implementation(implementation: ModuleType) → None¶: Set the etree implementation to use.

fastkml.data module¶

Add Custom Data.

https://developers.google.com/kml/documentation/extendeddata#example

Bases: _BaseObject

Represents an untyped name/value pair with optional display name.

display_name: str | None¶

name: str | None¶

name_spaces: Dict[str, str]¶

ns: str¶

value: str | None¶

Bases: _BaseObject

Represents a list of untyped name/value pairs. See docs:

-> ‘Adding Untyped Name/Value Pairs’: https://developers.google.com/kml/documentation/extendeddata

elements: List[Data | SchemaData]¶

name_spaces: Dict[str, str]¶

ns: str¶

Bases: _BaseObject

Specifies a custom KML schema that is used to add custom data to KML Features.

The “id” attribute is required and must be unique within the KML file. <Schema> is always a child of <Document>.

https://developers.google.com/kml/documentation/extendeddata#declare-the-schema-element

append(field: SimpleField) → None¶: Append a field.

fields: List[SimpleField]¶

name: str | None¶

name_spaces: Dict[str, str]¶

ns: str¶

Bases: _BaseObject

<SchemaData schemaUrl=”anyURI”> This element is used in conjunction with <Schema> to add typed custom data to a KML Feature. The Schema element (identified by the schemaUrl attribute) declares the custom data type. The actual data objects (“instances” of the custom data) are defined using the SchemaData element. The <schemaURL> can be a full URL, a reference to a Schema ID defined in an external KML file, or a reference to a Schema ID defined in the same KML file.

append_data(data: SimpleData) → None¶

data: List[SimpleData]¶

name_spaces: Dict[str, str]¶

ns: str¶

schema_url: str | None¶

Bases: _BaseObject

A SimpleField always has both name and type attributes.

The declaration of the custom field, must specify both the type and the name of this field. If either the type or the name is omitted, the field is ignored.

The type can be one of the following:

string
int
uint
short
ushort
float
double
bool

The displayName, if any, to be used when the field name is displayed to the Google Earth user. Use the [CDATA] element to escape standard HTML markup.

display_name: str | None¶

name: str | None¶

type: DataType | None¶

fastkml.enums module¶

Enums for the fastkml package.

This module contains the enums used in the fastkml package.

https://developers.google.com/kml/documentation/kmlreference#kml-fields

class fastkml.enums.AltitudeMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Enum to represent the different altitude modes.

Specifies how altitude components in the <coordinates> element are interpreted. Possible values are

clampToGround - (default) Indicates to ignore an altitude specification (for example, in the <coordinates> tag).

relativeToGround - Sets the altitude of the element relative to the actual ground elevation of a particular location. For example, if the ground elevation of a location is exactly at sea level and the altitude for a point is set to 9 meters, then the elevation for the icon of a point placemark elevation is 9 meters with this mode. However, if the same coordinate is set over a location where the ground elevation is 10 meters above sea level, then the elevation of the coordinate is 19 meters. A typical use of this mode is for placing telephone poles or a ski lift.

absolute - Sets the altitude of the coordinate relative to sea level, regardless of the actual elevation of the terrain beneath the element. For example, if you set the altitude of a coordinate to 10 meters with an absolute altitude mode, the icon of a point placemark will appear to be at ground level if the terrain beneath is also 10 meters above sea level. If the terrain is 3 meters above sea level, the placemark will appear elevated above the terrain by 7 meters. A typical use of this mode is for aircraft placement.

relativeToSeaFloor - Interprets the altitude as a value in meters above the sea floor. If the point is above land rather than sea, the altitude will be interpreted as being above the ground.

clampToSeaFloor - The altitude specification is ignored, and the point will be positioned on the sea floor. If the point is on land rather than at sea, the point will be positioned on the ground.

The Values relativeToSeaFloor and clampToSeaFloor are not part of the KML definition but of the <gx:altitudeMode> a KML extension in the Google extension namespace, allowing altitudes relative to the sea floor.

absolute = 'absolute'¶

clamp_to_ground = 'clampToGround'¶

clamp_to_sea_floor = 'clampToSeaFloor'¶

relative_to_ground = 'relativeToGround'¶

relative_to_sea_floor = 'relativeToSeaFloor'¶

class fastkml.enums.ColorMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Enum to represent the different color modes.

Specifies how the color is applied to the geometry.

normal = 'normal'¶

random = 'random'¶

class fastkml.enums.DataType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

bool_ = 'bool'¶

double = 'double'¶

float_ = 'float'¶

int_ = 'int'¶

short = 'short'¶

string = 'string'¶

uint = 'uint'¶

ushort = 'ushort'¶

class fastkml.enums.DateTimeResolution(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Enum to represent the different date time resolutions.

date = 'date'¶

datetime = 'dateTime'¶

year = 'gYear'¶

year_month = 'gYearMonth'¶

class fastkml.enums.DisplayMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

DisplayMode for BalloonStyle.

If <displayMode> is default, Google Earth uses the information supplied in <text> to create a balloon . If <displayMode> is hide, Google Earth does not display the balloon. In Google Earth, clicking the List View icon for a Placemark whose balloon’s <displayMode> is hide causes Google Earth to fly to the Placemark.

default = 'default'¶

hide = 'hide'¶

class fastkml.enums.GridOrigin(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

GridOrigin for GroundOverlay.

Specifies where to begin numbering the tiles in each layer of the pyramid. A value of lowerLeft specifies that row 1, column 1 of each layer is in the bottom left corner of the grid.

lower_left = 'lowerLeft'¶

upper_left = 'upperLeft'¶

class fastkml.enums.PairKey(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Key for Pair.

highlight = 'highlight'¶

normal = 'normal'¶

class fastkml.enums.RefreshMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Enum to represent the different refresh modes.

Specifies how the link is refreshed when the “camera” changes.

on_change = 'onChange'¶

on_expire = 'onExpire'¶

on_interval = 'onInterval'¶

class fastkml.enums.RelaxedEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Enum with relaxed string value matching.

This class provides an enum with relaxed value matching, allowing case-insensitive comparison of enum values. If a value is not found in the enum, it will attempt to find a case-insensitive match. If no match is found, a ValueError is raised.

Usage:: To use this enum, simply subclass RelaxedEnum and define your enum values.

Example:¶

class MyEnum(RelaxedEnum):
VALUE1 = “value1” VALUE2 = “value2”

my_value = MyEnum(“VALUE1”) # Case-insensitive match print(my_value) # Output: MyEnum.VALUE1

The subclass must define all values as strings.

class fastkml.enums.Shape(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Shape for PhotoOverlay.

The PhotoOverlay is projected onto the <shape>. The <shape> can be one of the following:

rectangle (default) - for an ordinary photo

cylinder - for panoramas, which can be either partial or full cylinders

sphere - for spherical panoramas

cylinder = 'cylinder'¶

rectangle = 'rectangle'¶

sphere = 'sphere'¶

class fastkml.enums.Units(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Units for ScreenOverlay and Hotspot.

Specifies how the <x>, <y> values are interpreted.

fraction = 'fraction'¶

inset_pixels = 'insetPixels'¶

pixels = 'pixels'¶

class fastkml.enums.Verbosity(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Enum to represent the different verbosity levels.

normal = 1¶

quiet = 0¶

verbose = 2¶

class fastkml.enums.ViewRefreshMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: RelaxedEnum

Enum to represent the different view refresh modes.

Specifies how the link is refreshed when the “camera” changes.

never = 'never'¶

on_region = 'onRegion'¶

on_request = 'onRequest'¶

on_stop = 'onStop'¶

fastkml.exceptions module¶

Exceptions for the fastkml package.

exception fastkml.exceptions.FastKMLError¶

Bases: Exception

Base class for all fastkml exceptions.

exception fastkml.exceptions.KMLParseError¶

Bases: FastKMLError

Raised when there is an error parsing KML.

exception fastkml.exceptions.KMLSchemaError¶

Bases: FastKMLError

Raised when there is an error with the KML Schema.

exception fastkml.exceptions.KMLWriteError¶

Bases: FastKMLError

Raised when there is an error writing KML.

fastkml.geometry module¶

Bases: _Geometry

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element¶: Return the KML Object as an Element.

class fastkml.geometry.LinearRing(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: LinearRing, **kwargs: Any)¶: Bases: LineString

Bases: _Geometry

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element¶: Return the KML Object as an Element.

map_to_kml = {<class 'pygeoif.geometry.LineString'>: <class 'fastkml.geometry.LineString'>, <class 'pygeoif.geometry.LinearRing'>: <class 'fastkml.geometry.LinearRing'>, <class 'pygeoif.geometry.Point'>: <class 'fastkml.geometry.Point'>, <class 'pygeoif.geometry.Polygon'>: <class 'fastkml.geometry.Polygon'>}¶

multi_geometries = (<class 'pygeoif.geometry.MultiPoint'>, <class 'pygeoif.geometry.MultiLineString'>, <class 'pygeoif.geometry.MultiPolygon'>, <class 'pygeoif.geometry.GeometryCollection'>)¶

Bases: _Geometry

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element¶: Return the KML Object as an Element.

Bases: _Geometry

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element¶: Return the KML Object as an Element.

fastkml.geometry.create_multigeometry(geometries: Sequence[Polygon | LineString | LinearRing | Point | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection]) → MultiPoint | MultiLineString | MultiPolygon | GeometryCollection | None¶: Create a MultiGeometry from a sequence of geometries.

Args:¶

geometries: Sequence of geometries.

Returns:¶

MultiGeometry

fastkml.gx module¶

With the launch of Google Earth 5.0, Google has provided extensions to KML to support a number of new features. These extensions use the gx prefix and the following namespace URI:

xmlns:gx="http://www.google.com/kml/ext/2.2"

This namespace URI must be added to the <kml> element in any KML file using gx-prefixed elements:

<kml
    xmlns="http://www.opengis.net/kml/2.2"
    xmlns:gx="http://www.google.com/kml/ext/2.2"
>

Extensions to KML may not be supported in all geo-browsers. If your browser doesn’t support particular extensions, the data in those extensions should be silently ignored, and the rest of the KML file should load without errors.

Elements that currently use the gx prefix are:

gx:altitudeMode
gx:altitudeOffset
gx:angles
gx:AnimatedUpdate
gx:balloonVisibility
gx:coord
gx:delayedStart
gx:drawOrder
gx:duration
gx:FlyTo
gx:flyToMode
gx:h
gx:horizFov
gx:interpolate
gx:labelVisibility
gx:LatLonQuad
gx:MultiTrack
gx:vieweroptions
gx:outerColor
gx:outerWidth
gx:physicalWidth
gx:Playlist
gx:playMode
gx:SoundCue
gx:TimeSpan
gx:TimeStamp
gx:Tour
gx:TourControl
gx:TourPrimitive
gx:Track
gx:ViewerOptions
gx:w
gx:Wait
gx:x
gx:y

The complete XML schema for elements in this extension namespace is located at http://developers.google.com/kml/schema/kml22gx.xsd.

class fastkml.gx.Angle(heading: float = 0.0, tilt: float = 0.0, roll: float = 0.0)¶

Bases: object

The gx:angles element specifies the heading, tilt, and roll.

The angles are specified in degrees, and the default values are 0 (heading and tilt) and 0 (roll). The angles are specified in the following order: heading, tilt, roll.

heading: float = 0.0¶

roll: float = 0.0¶

tilt: float = 0.0¶

Bases: _Geometry

property geometry: MultiLineString | None¶

tracks: List[Track]¶

Bases: _Geometry

A track describes how an object moves through the world over a given time period.

This feature allows you to create one visible object in Google Earth (either a Point icon or a Model) that encodes multiple positions for the same object for multiple times. In Google Earth, the time slider allows the user to move the view through time, which animates the position of the object.

Tracks are a more efficient mechanism for associating time data with visible Features, since you create only one Feature, which can be associated with multiple time elements as the object moves through space.

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal, name_spaces: Dict[str, str] | None = None) → Element¶: Return the KML Object as an Element.

property geometry: LineString | None¶

track_items: List[TrackItem]¶

classmethod track_items_kwargs_from_element(*, ns: str, element: Element, strict: bool) → List[TrackItem]¶

class fastkml.gx.TrackItem(when: datetime | None = None, coord: Point | None = None, angle: Angle | None = None)¶

Bases: object

A track item describes an objects position and heading at a specific time.

angle: Angle | None = None¶

coord: Point | None = None¶

etree_elements(*, precision: int | None = None, verbosity: Verbosity = Verbosity.normal, name_spaces: Dict[str, str] | None = None) → Iterator[Element]¶

when: datetime | None = None¶

fastkml.gx.linestring_to_track_items(linestring: LineString) → List[TrackItem]¶

fastkml.gx.multilinestring_to_tracks(multilinestring: MultiLineString, ns: str | None) → List[Track]¶

fastkml.gx.track_items_to_geometry(track_items: Iterable[TrackItem]) → LineString¶

fastkml.gx.tracks_to_geometry(tracks: Iterable[Track]) → MultiLineString¶

fastkml.helpers module¶

Helper functions for fastkml.

fastkml.helpers.attribute_enum_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, Enum]¶

fastkml.helpers.attribute_float_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, float]¶

fastkml.helpers.attribute_int_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, int]¶

fastkml.helpers.attribute_text_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, str]¶

fastkml.helpers.bool_subelement(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute from a subelement with a text node.

Args:¶

obj (_XMLObject): The object from which to retrieve the attribute value. element (Element): The parent element to add the subelement to. attr_name (str): The name of the attribute to retrieve the value from. node_name (str): The name of the subelement to create. precision (Optional[int]): The precision of the attribute value. verbosity (Optional[Verbosity]): The verbosity level.

Returns:¶

None

fastkml.helpers.enum_attribute(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute.

fastkml.helpers.enum_subelement(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute from a subelement with a text node.

fastkml.helpers.float_attribute(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute.

fastkml.helpers.float_subelement(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute from a subelement with a text node.

fastkml.helpers.handle_error(*, error: Exception, strict: bool, element: Element, node: Element, expected: str) → None¶: Handle an error.

Args:¶

error (Exception): The exception that occurred. strict (bool): A flag indicating whether to raise an exception or log a warning. element (Element): The XML element being parsed. node (Element): The XML node that caused the error. expected (str): The expected format or value.

Raises:¶

KMLParseError: If strict is True, the function raises a KMLParseError with the error message.

fastkml.helpers.int_attribute(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute.

Args:¶

obj (_XMLObject): The object from which to retrieve the attribute value. element (Element): The parent element to add the subelement to. attr_name (str): The name of the attribute to retrieve the value from. node_name (str): The name of the attribute to be set. precision (Optional[int]): The precision of the attribute value. verbosity (Optional[Verbosity]): The verbosity level.

Returns:¶

None: This function does not return anything.

fastkml.helpers.int_subelement(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute from a subelement with a text node.

Args:¶

obj (_XMLObject): The object from which to retrieve the attribute value. element (Element): The parent element to add the subelement to. attr_name (str): The name of the attribute to retrieve the value from. node_name (str): The name of the subelement to create. precision (Optional[int]): The precision of the attribute value. verbosity (Optional[Verbosity]): The verbosity level.

Returns:¶

None: This function does not return anything.

fastkml.helpers.node_text(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶

fastkml.helpers.node_text_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, str]¶

fastkml.helpers.subelement_bool_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, bool]¶

fastkml.helpers.subelement_enum_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, Enum]¶

fastkml.helpers.subelement_float_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, float]¶

fastkml.helpers.subelement_int_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, int]¶

fastkml.helpers.subelement_text_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, str]¶

fastkml.helpers.text_attribute(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute from a subelement with a text node.

Args:¶

obj (_XMLObject): The object from which to retrieve the attribute value. element (Element): The parent element to add the subelement to. attr_name (str): The name of the attribute to retrieve the value from. node_name (str): The name of the attribute to be set. precision (Optional[int]): The precision of the attribute value. verbosity (Optional[Verbosity]): The verbosity level.

Returns:¶

None

fastkml.helpers.text_subelement(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶: Set the value of an attribute from a subelement with a text node.

Args:¶

obj (_XMLObject): The object from which to retrieve the attribute value. element (Element): The parent element to add the subelement to. attr_name (str): The name of the attribute to retrieve the value from. node_name (str): The name of the subelement to create. precision (Optional[int]): The precision of the attribute value. verbosity (Optional[Verbosity]): The verbosity level.

Returns:¶

None

fastkml.helpers.xml_subelement(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶

fastkml.helpers.xml_subelement_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, _XMLObject]¶

fastkml.helpers.xml_subelement_list(obj: _XMLObject, *, element: Element, attr_name: str, node_name: str, precision: int | None, verbosity: Verbosity | None) → None¶

fastkml.helpers.xml_subelement_list_kwarg(*, element: Element, ns: str, name_spaces: Dict[str, str], node_name: str, kwarg: str, classes: Tuple[Type[_XMLObject] | Type[Enum] | Type[bool] | Type[int] | Type[str] | Type[float], ...], strict: bool) → Dict[str, List[_XMLObject]]¶

fastkml.kml module¶

KML is an open standard officially named the OpenGIS KML Encoding Standard (OGC KML).

It is maintained by the Open Geospatial Consortium, Inc. (OGC). The complete specification for OGC KML can be found at http://www.opengeospatial.org/standards/kml/.

The complete XML schema for KML is located at http://schemas.opengis.net/kml/.

Bases: _XMLObject

represents a KML File.

append(kmlobj: Folder | Document | Placemark | GroundOverlay | PhotoOverlay) → None: Append a feature.

classmethod class_from_string(string: str, *, ns: str | None = None, name_spaces: Dict[str, str] | None = None, strict: bool = True) → Self: Create a kml object from a string.

Args:¶

string: String representation (serialized XML) of the kml object ns: Namespace of the element (default: None) name_spaces: Dictionary of namespace prefixes and URIs (default: None) strict: Whether to enforce strict parsing (default: True)

Returns:¶

Geometry object

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element: Return an Element object representing the KML element.

Args:¶

precision (Optional[int]): The precision used for floating-point values. verbosity (Verbosity): The verbosity level for generating the KML element.

Returns:¶

Element: The etree Element object representing the KML element.

classmethod get_tag_name() → str: Return the tag name.

name_spaces: Dict[str, str]

ns: str

fastkml.mixins module¶

Mixins for the KML classes.

class fastkml.mixins.TimeMixin¶

Bases: object

property begin: KmlDateTime | None¶

property end: KmlDateTime | None¶

property time_stamp: KmlDateTime | None¶: This just returns the datetime portion of the timestamp.

times: TimeSpan | TimeStamp | None = None¶

fastkml.styles module¶

Once you’ve created features within Google Earth and examined the KML code Google Earth generates, you’ll notice how styles are an important part of how your data is displayed.

Bases: _BaseObject

Specifies how the description balloon for placemarks is drawn.

The <bgColor>, if specified, is used as the background color of the balloon.

https://developers.google.com/kml/documentation/kmlreference#balloonstyle

bg_color: str | None¶

display_mode: DisplayMode | None¶

name_spaces: Dict[str, str]¶

ns: str¶

text: str | None¶

text_color: str | None¶

Bases: _ColorStyle

Specifies how icons for point Placemarks are drawn.

The <Icon> element specifies the icon image. The <scale> element specifies the x, y scaling of the icon. The color specified in the <color> element of <IconStyle> is blended with the color of the <Icon>.

https://developers.google.com/kml/documentation/kmlreference#iconstyle

color_mode: ColorMode | None¶

heading: float | None¶

hot_spot: HotSpot | None¶

icon_href: str | None¶

name_spaces: Dict[str, str]¶

ns: str¶

scale: float | None¶

Bases: _ColorStyle

Specifies how the <name> of a Feature is drawn in the 3D viewer.

A custom color, color mode, and scale for the label (name) can be specified.

https://developers.google.com/kml/documentation/kmlreference#labelstyle

color_mode: ColorMode | None¶

name_spaces: Dict[str, str]¶

ns: str¶

scale: float | None¶

Bases: _ColorStyle

The drawing style (color, color mode, and line width) for all line geometry.

Line geometry includes the outlines of outlined polygons and the extruded “tether” of Placemark icons (if extrusion is enabled). https://developers.google.com/kml/documentation/kmlreference#linestyle

color_mode: ColorMode | None¶

name_spaces: Dict[str, str]¶

ns: str¶

width: float | None¶

Bases: _ColorStyle

Drawing style for polygons.

Specifies the drawing style for all polygons, including polygon extrusions (which look like the walls of buildings) and line extrusions (which look like solid fences).

https://developers.google.com/kml/documentation/kmlreference#polystyle

color_mode: ColorMode | None¶

fill: bool | None¶

name_spaces: Dict[str, str]¶

ns: str¶

outline: bool | None¶

Bases: _StyleSelector

A Style defines an addressable style group.

It can be referenced by StyleMaps and Features. Styles affect how Geometry is presented in the 3D viewer and how Features appear in the Places panel of the List view. Shared styles are collected in a <Document> and must have an id defined for them so that they can be referenced by the individual Features that use them.

https://developers.google.com/kml/documentation/kmlreference#style

Bases: _StyleSelector

A <StyleMap> maps between two different Styles. Typically a <StyleMap> element is used to provide separate normal and highlighted styles for a placemark, so that the highlighted version appears when the user mouses over the icon in Google Earth.

https://developers.google.com/kml/documentation/kmlreference#stylemap

property highlight: StyleUrl | Style | None¶

name_spaces: Dict[str, str]¶

property normal: StyleUrl | Style | None¶

ns: str¶

pairs: List[Pair]¶

Bases: _BaseObject

URL of a <Style> or <StyleMap> defined in a Document.

If the style is in the same file, use a # reference. If the style is defined in an external file, use a full URL along with # referencing.

https://developers.google.com/kml/documentation/kmlreference#styleurl

classmethod get_tag_name() → str¶: Return the tag name.

name_spaces: Dict[str, str]¶

ns: str¶

url: str | None¶

fastkml.times module¶

Date and time handling in KML.

class fastkml.times.KmlDateTime(dt: date | datetime, resolution: DateTimeResolution | None = None)¶

Bases: object

A KML DateTime object.

This class is used to parse and format KML DateTime objects.

A KML DateTime object is a string that conforms to the ISO 8601 standard for date and time representation. The following formats are supported:

yyyy-mm-ddThh:mm:sszzzzzz
yyyy-mm-ddThh:mm:ss
yyyy-mm-dd
yyyy-mm
yyyy

The T is the separator between the date and the time, and the time zone is either Z (for UTC) or zzzzzz, which represents ±hh:mm in relation to UTC. Additionally, the value can be expressed as a date only.

The precision of the DateTime is dictated by the DateTime value which can be one of the following:

dateTime gives second resolution
date gives day resolution
gYearMonth gives month resolution
gYear gives year resolution

The KmlDateTime class can be used to parse a KML DateTime string into a Python datetime object, or to format a Python datetime object into a KML DateTime string.

The KmlDateTime class is used by the TimeStamp and TimeSpan classes.

classmethod parse(datestr: str) → KmlDateTime | None¶: Parse a KML DateTime string into a KmlDateTime object.

Bases: _TimePrimitive

Represents an extent in time bounded by begin and end dateTimes.

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element¶: Return the KML Object as an Element.

Bases: _TimePrimitive

Represents a single moment in time.

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element¶: Return the KML Object as an Element.

fastkml.types module¶

Types for fastkml.

class fastkml.types.Element(*args, **kwargs)¶

Bases: Protocol

Protocol for Element.

append(element: Element) → None¶: Append an element to the current element.

find(tag: str) → Element | None¶: Find the first element with the given tag.

findall(tag: str) → Iterable[Element]¶: Find all elements with the given tag.

get(tag: str) → str¶: Get the value of the tag.

remove(element: Element) → None¶: Remove an element from the current element.

set(tag: str, value: str) → None¶: Set the value of the tag.

tag: str¶

text: str¶

fastkml.views module¶

KML Views.

Bases: _AbstractView

Defines the virtual camera that views the scene. This element defines the position of the camera relative to the Earth’s surface as well as the viewing direction of the camera. The camera position is defined by <longitude>, <latitude>, <altitude>, and either <altitudeMode> or <gx:altitudeMode>. The viewing direction of the camera is defined by <heading>, <tilt>, and <roll>. <Camera> can be a child element of any Feature or of <NetworkLinkControl>. A parent element cannot contain both a <Camera> and a <LookAt> at the same time.

<Camera> provides full six-degrees-of-freedom control over the view, so you can position the Camera in space and then rotate it around the X, Y, and Z axes. Most importantly, you can tilt the camera view so that you’re looking above the horizon into the sky.

<Camera> can also contain a TimePrimitive (<gx:TimeSpan> or <gx:TimeStamp>). Time values in Camera affect historical imagery, sunlight, and the display of time-stamped features. For more information, read Time with AbstractViews in the Time and Animation chapter of the Developer’s Guide.

altitude: float | None¶

altitude_mode: AltitudeMode | None¶

heading: float | None¶

latitude: float | None¶

longitude: float | None¶

name_spaces: Dict[str, str]¶

ns: str¶

roll: float | None¶

tilt: float | None¶

Bases: _AbstractView

altitude: float | None¶

altitude_mode: AltitudeMode | None¶

heading: float | None¶

latitude: float | None¶

longitude: float | None¶

name_spaces: Dict[str, str]¶

ns: str¶

range: float | None¶

tilt: float | None¶

Bases: _BaseObject

A <Region> contains a bounding box (<LatLonAltBox>) that describes an area of interest defined by geographic coordinates and altitudes.

In addition, a Region contains an LOD (level of detail) extent (<Lod>), which is a pair of projected coordinate bounding boxes that describe the area that should be loaded in the viewport corresponding to a given level of detail.

https://developers.google.com/kml/documentation/kmlreference#region

lat_lon_alt_box: LatLonAltBox | None¶

lod: Lod | None¶

fastkml package¶

Module contents¶

Args:¶

Returns:¶

Args:¶

Returns:¶

Submodules¶

fastkml.about module¶

fastkml.atom module¶

fastkml.base module¶

fastkml.config module¶

fastkml.data module¶

fastkml.enums module¶

Example:¶

fastkml.exceptions module¶

fastkml.geometry module¶

Args:¶

Returns:¶

fastkml.gx module¶

fastkml.helpers module¶

Args:¶

Returns:¶

Args:¶

Raises:¶

Args:¶

Returns:¶

Args:¶

Returns:¶

Args:¶

Returns:¶

Args:¶

Returns:¶

fastkml.kml module¶

Args:¶

Returns:¶

Args:¶

Returns:¶

fastkml.mixins module¶

fastkml.styles module¶

fastkml.times module¶

fastkml.types module¶

fastkml.views module¶