Features

Reference

Features

The placemark builders: point, search_poi, line, and polygon. Each returns a KML element ready to drop into a folder or kml document.

point

Builds a point placemark from a single coordinate pair in [x, y, z] or [lng, lat, elev] order.

point(coords, name, *, headers=None, attrs=None, desc=None,
      snip=None, z_mode="CTG", style_to_use=None, hidden=False,
      extrude=False, cam=None) -> Element

Parameter	Type	Default	Description
`coords`	`list[float]`	required	`[longitude, latitude]` or `[longitude, latitude, elevation]`; elevation is optional and defaults to `0` (placed on the ground under the default `'CTG'` mode).
`name`	`str`	required	Placemark name.
`headers`	`list`	`None`	Attribute names, paired positionally with `attrs`.
`attrs`	`list`	`None`	Attribute values shown in the description balloon and `ExtendedData`.
`desc`	`str`	`None`	Free text/HTML for the description balloon, rendered above the `headers`/`attrs` table.
`snip`	`str`	`None`	Short summary shown beneath the name in Google Earth's places list. Emitted only when provided.
`z_mode`	`str`	`'CTG'`	Altitude mode: CTG (clampToGround, on the ground; the default), RTG (relativeToGround, above ground level), ABS (absolute, above sea level), CSF (clampToSeaFloor, on the sea floor), or RSF (relativeToSeaFloor, above the sea floor). See Altitude modes.
`style_to_use`	`str`	`None`	Name/ID of a `point_style` to reference.
`hidden`	`bool`	`False`	`True` makes the point start hidden.
`extrude`	`bool`	`False`	Draw a vertical tether line from the point down to the ground. Visible only when the point is raised (a non-`CTG` altitude mode with a non-zero altitude).
`cam`	`Element`	`None`	A `look_at` element for a default view.

Returns

Element: a KML Placemark containing a Point.

Examples

The simplest point: a coordinate and a name

kmlb.point([-71.0589, 42.3601], "Boston")

Raise it off the ground with an elevation

kmlb.point([-71.0589, 42.3601, 60], "Boston", z_mode="RTG")

Add a description balloon

# desc: the balloon shown when you click the placemark
kmlb.point([-71.0589, 42.3601], "Boston", desc="Capital of Massachusetts.")

Add a places-list snippet

# snip: a short summary under the name in the Places list (not the balloon)
kmlb.point([-71.0589, 42.3601], "Boston", snip="State capital")

Add an attribute table

kmlb.point([-71.0589, 42.3601], "Boston",
           headers=["Population", "Founded"], attrs=[654776, 1630])

Reference a custom style

city = kmlb.point_style("city", icon="triangle", color="red", scale=1.4)
kmlb.point([-71.0589, 42.3601], "Boston", style_to_use="city")

Extrude a raised point with a tether to the ground

kmlb.point([-71.0589, 42.3601, 150], "Boston",
           z_mode="RTG", extrude=True)

Everything together

city = kmlb.point_style("city", icon="triangle", color="red", scale=1.4)
view = kmlb.look_at([-71.0589, 42.3601, 0], distance=600, azimuth=210, tilt=55)
kmlb.point([-71.0589, 42.3601, 150], "Boston",
           desc="Capital of Massachusetts.", snip="State capital",
           headers=["Population"], attrs=[654776],
           z_mode="RTG", extrude=True,
           style_to_use="city", cam=view)

search_poi

Builds a placemark whose location is resolved by Google Earth from a search string. Instead of fixed coordinates, the placemark carries an <address> element; Google Earth geocodes that address when the file is opened and places the point accordingly.

search_poi(poi, name=None, *, headers=None, attrs=None,
           desc=None, snip=None,
           style_to_use=None, hidden=False) -> Element

Parameter	Type	Default	Description
`poi`	`str`	required	What you would type into a search bar: a place name or address.
`name`	`str`	`None`	Placemark name. Defaults to `poi` when omitted.
`headers`	`list`	`None`	Attribute names.
`attrs`	`list`	`None`	Attribute values.
`desc`	`str`	`None`	Free text/HTML for the description balloon, rendered above the `headers`/`attrs` table.
`snip`	`str`	`None`	Short summary shown beneath the name in Google Earth's places list. Emitted only when provided.
`style_to_use`	`str`	`None`	Name/ID of a point style to reference.
`hidden`	`bool`	`False`	`True` makes the point start hidden.

Returns

Element: a KML Placemark carrying an <address> rather than coordinates.

Note

The address is geocoded by Google Earth at display time, so an internet connection is required when the KML is opened.

Examples

The simplest search: a place or address

kmlb.search_poi("Fenway Park, Boston")

Give it a custom name

kmlb.search_poi("4 Jersey St, Boston", "Fenway Park")

Add a balloon, a snippet, and a style

kmlb.search_poi("Fenway Park, Boston", snip="MLB ballpark",
                desc="Home of the Boston Red Sox", style_to_use="redTriangle")

line

Builds a line/polyline placemark from an ordered list of coordinates.

line(coords, name, *, headers=None, attrs=None,
     desc=None, snip=None, z_mode="CTG",
     style_to_use=None, hidden=False, follow_terrain=True,
     extrude=False, cam=None) -> Element

Parameter	Type	Default	Description
`coords`	`list[list[float]]`	required	Ordered `[lon, lat]` or `[lon, lat, elev]` vertices; elevation is optional and defaults to `0`.
`name`	`str`	required	Placemark name.
`headers`	`list`	`None`	Attribute names.
`attrs`	`list`	`None`	Attribute values.
`desc`	`str`	`None`	Free text/HTML for the description balloon, rendered above the `headers`/`attrs` table.
`snip`	`str`	`None`	Short summary shown beneath the name in Google Earth's places list. Emitted only when provided.
`z_mode`	`str`	`'CTG'`	Altitude mode: CTG (clampToGround, on the ground; the default), RTG (relativeToGround, above ground level), ABS (absolute, above sea level), CSF (clampToSeaFloor, on the sea floor), or RSF (relativeToSeaFloor, above the sea floor). See Altitude modes.
`style_to_use`	`str`	`None`	Name/ID of a `line_style`.
`hidden`	`bool`	`False`	`True` makes the line start hidden.
`follow_terrain`	`bool`	`True`	Tessellate so the line follows terrain (only with `'CTG'`).
`extrude`	`bool`	`False`	Drop vertices to the ground with extruded walls.
`cam`	`Element`	`None`	A `look_at` element for a default view.

Returns

Element: a KML Placemark containing a LineString.

Examples

The simplest line: a list of coordinates

kmlb.line([[-71.060, 42.360], [-71.050, 42.370]], "Trail")

A 3D line, extruded to the ground: a runway takeoff

# 'extrude' drops walls from the flight path to the ground,
#   showing the climb profile as a curtain.
kmlb.line([[-71.01259, 42.35582, 4],    # runway start
           [-71.00035, 42.358, 4],      # liftoff (mid-runway)
           [-70.9763, 42.36227, 150]],  # airborne, climbing
          "Takeoff", z_mode="ABS", extrude=True)

Reference a custom style

trail = kmlb.line_style("trail", color="gold", width=4)
kmlb.line([[-71.060, 42.360], [-71.050, 42.370]], "Trail", style_to_use="trail")

polygon

Builds a polygon placemark. The first ring in coords is the outer boundary; any additional rings become inner boundaries (holes).

polygon(coords, name, *, headers=None, attrs=None,
        desc=None, snip=None, z_mode="CTG",
        style_to_use=None, hidden=False, follow_terrain=True,
        extrude=False, cam=None) -> Element

Parameter	Type	Default	Description
`coords`	`list[list[list[float]]]`	required	A list of rings; each ring is a list of `[lon, lat]` or `[lon, lat, elev]` vertices (elevation optional, defaults to `0`). Ring 0 is the outer boundary; the rest are holes.
`name`	`str`	required	Placemark name.
`headers`	`list`	`None`	Attribute names.
`attrs`	`list`	`None`	Attribute values.
`desc`	`str`	`None`	Free text/HTML for the description balloon, rendered above the `headers`/`attrs` table.
`snip`	`str`	`None`	Short summary shown beneath the name in Google Earth's places list. Emitted only when provided.
`z_mode`	`str`	`'CTG'`	Altitude mode: CTG (clampToGround, on the ground; the default), RTG (relativeToGround, above ground level), ABS (absolute, above sea level), CSF (clampToSeaFloor, on the sea floor), or RSF (relativeToSeaFloor, above the sea floor). See Altitude modes.
`style_to_use`	`str`	`None`	Name/ID of a `polygon_style`.
`hidden`	`bool`	`False`	`True` makes the polygon start hidden.
`follow_terrain`	`bool`	`True`	Tessellate so the polygon follows terrain (only with `'CTG'`).
`extrude`	`bool`	`False`	Extrude vertices toward the ground.
`cam`	`Element`	`None`	A `look_at` element for a default view.

Returns

Element: a KML Placemark containing a Polygon.

Examples

The simplest polygon: one ring of coordinates

ring = [[-71.06, 42.36], [-71.05, 42.36], [-71.05, 42.37], [-71.06, 42.36]]
kmlb.polygon([ring], "Lot")

Add an inner ring to cut a hole

outer = [[-71.06, 42.36], [-71.05, 42.36], [-71.05, 42.37], [-71.06, 42.36]]
hole  = [[-71.058, 42.362], [-71.054, 42.362], [-71.054, 42.366], [-71.058, 42.362]]
kmlb.polygon([outer, hole], "Block with courtyard")

Reference a custom style

fill = kmlb.polygon_style("fill", fill_color=("#03cafc", 40))
ring = [[-71.06, 42.36], [-71.05, 42.36], [-71.05, 42.37], [-71.06, 42.36]]
kmlb.polygon([ring], "Lot", style_to_use="fill")

Extrude a raised polygon into a 3D shape

roof = [[-71.0590, 42.3600, 30], [-71.0585, 42.3600, 30],
        [-71.0585, 42.3604, 30], [-71.0590, 42.3600, 30]]
kmlb.polygon([roof], "Canopy", z_mode="RTG", extrude=True)