Kml

object Kml

KML 2.2, the format of Google Earth, read into and written from the library's shapes.

Reading (decode) finds every Placemark however deeply it sits in Documents and Folders. A Point becomes a marker, a LineString a polyline, a Polygon a polygon (outerBoundaryIs and every innerBoundaryIs are its rings), and a MultiGeometry one shape per point or line in it and ONE polygon of all its polygons' rings (the model keeps parts and holes together under the even-odd rule, see DrawnPolygon). The placemark's id attribute is the shape's id (made unique when it isn't), its description the shape's description, and for a marker its name is the label (that is what Google Earth shows beside a point); a polygon or a line has no label, so its name stands in for a missing description. The name is also kept as the property name.

The shape's properties are its ExtendedData (Data and the SimpleData of a SchemaData; an entry called zIndex is the drawing order instead), its name, the time it holds for (TimeSpan as timeBegin and timeEnd, TimeStamp as timeStamp, the text kept as KML has it) and the names of the Folders it lies in, outermost first (folder, joined with " / ").

The look comes from Style (inline, or shared and found by styleUrl="#id", also through a StyleMap's normal pair): PolyStyle is the fill (<fill>0</fill> no fill), LineStyle the outline of a polygon and the colour and width of a line (<outline>0</outline> no outline), IconStyle the colour, scale (16 px at 1) and, for an http/https Icon, the picture of a marker, LabelStyle the colour and scale (14 pt at 1) of its label. KML colours are written aabbggrr, alpha first and blue before red, and each of these has KML's own default when missing (white, a width of 1).

What is not read, with a line in ImportResult.warnings and counted by kind in ImportResult.leftOut: GroundOverlay, ScreenOverlay, NetworkLink, Tour, gx:Track and the like (the model has nothing to put them in), icons that aren't a web address (relative paths and .kmz contents), styles in other files, and the region and camera elements, which are ignored silently. A .kmz is a zip of a KML: unzip it first.

Writing (encode) is lossy like GeoJson.encode: no pictures (except a marker's web-address picture, written as its Icon), no hatching, no vertex ids. Kept are the id, the description, the colours (as KML's aabbggrr), widths, a marker's label (as its name, with its colour and size as LabelStyle) and size (as scale), zIndex and the properties (the name, timeBegin/timeEnd/timeStamp as the time elements, the rest as ExtendedData; the folders are not rebuilt, folder is just a property). A polygon of several parts becomes a MultiGeometry, each part's outline counter-clockwise and its holes clockwise. For a lossless file use DrawJson.

Coordinates are longitude,latitude[,altitude], as in GeoJSON.

Functions

Link copied to clipboard

The shapes in text, and what was left out.

Link copied to clipboard
fun encode(entities: List<DrawableEntity>, pretty: Boolean = false): String

A KML document of entities, in their order. pretty adds line breaks and indentation; the content is the same.