kmlwrite

Write geographic data to KML file

Syntax

kmlwrite(filename,S)

kmlwrite(filename,address)

kmlwrite(___,Name,Value)

Description

kmlwrite(filename,S) writes the geographic point, line, or polygon data stored in S to the file specified by filename in Keyhole Markup Language (KML) format. The kmlwrite function creates a KML Placemark in the file and populates the tags in the placemark with the data in S.

kmlwrite(filename,address) writes address to the file specified by filename in KML format. address is a string scalar or character vector containing freeform address data, that can include street, city, state, country, and/or postal code. To specify multiple addresses, use a cell array of character vectors or string scalars. kmlwrite creates a KML Placemark in the file, setting the value of the address tag. An address is an alternative way to specify a point, instead of using latitude and longitude.

kmlwrite(___,Name,Value) specifies name-value pairs that set additional KML feature properties. Parameter names can be abbreviated and are case-insensitive.

Examples

Write Polygon Data to KML File

Import a shapefile containing polygon data into a geospatial table. The polygons represent state boundaries.

GT = readgeotable("usastatelo.shp");

Create a colormap for the data using random, muted colors.

colors = polcmap(height(GT));

Write the polygon data to a KML file called usastatelo.kml. Specify the labels and the colors of the polygon faces and edges using name-value arguments.

kmlwrite("usastatelo.kml",GT,"Name",GT.Name, ...
    "FaceColor",colors,"EdgeColor","k") 

Write Point Data to KML File Using Geographic Point Vector

Import point data as a geographic point (geopoint) vector.

places = gpxread("boston_placenames.gpx");

Specify the colors to use with the point data.

colors = jet(length(places));

Write the point data to a file called boston_placenames.kml. Specify the point names and icon colors using name-value arguments.

kmlwrite("boston_placenames.kml",places,"Name",places.Name,"Color",colors)

Write Line Data to KML File Using Geographic Shape Vector

Read line features into a geographic shape (geoshape) vector.

tracks = gpxread("sample_tracks.gpx","Index",1:2);

Write the line data to a KML file. Specify the colors, widths, names, and descriptions of the lines using name-value arguments.

colors = ["red" "green"];
description = tracks.Metadata.Name;
name = ["track1" "track2"];

kmlwrite("sample_tracks.kml",tracks,"Color",colors,"LineWidth",2, ...
         "Description",description,"Name",name)

Write Geographic Data to KML File Using Geographic Structure Array

Read the names and locations of major European cities from a shapefile. The shaperead function returns a geographic structure array (geostruct).

latlim = [30;75];
lonlim = [-25;45];
cities = shaperead("worldcities.shp","UseGeoCoords",true, ...
                   "BoundingBox",[lonlim, latlim]);

Convert the structure to a geographic point (geopoint) vector.

cities = geopoint(cities);

Write the data to a KML file. Include city names in the placemarks by using the Name name-value argument. Remove the default Description table.

kmlwrite("european_cities.kml",cities,"Name",cities.Name,"Description",{});

Write Unstructured Address to KML File

Create a cell array of unstructured addresses. For this example, use the names of several Australian cities.

address = {'Perth, Australia', ...
           'Melbourne, Australia', ...
           'Sydney, Australia'};

Write the unstructured address data to a KML file called australian_cities.kml. Include the names of the cities in the placemarks using the Name name-value argument.

kmlwrite("australian_cities.kml",address,"Name",address);

Input Arguments

filename — Name of output file

character vector | string scalar

Name of output file, specified as a string scalar or character vector. kmlwrite writes the file in the current folder, unless you specify a full or relative path name. If the file name includes an extension, it must be .kml.

Data Types: char | string

S — Geographic features to write to file

geospatial table | geopoint vector | geoshape vector | geographic structure array

Geographic features to write to file, specified as one of the following:

• A geospatial table containing geopointshape, geolineshape, or geopolyshape objects. The kmlwrite function does not support geospatial tables containing more than one type of shape object. For more information about geospatial tables, see Create Geospatial Tables.

• A geopoint vector.

• A geoshape vector. The Geometry field identifies the type of the data as 'point', 'line', or 'polygon'.

• A geographic structure array (geostruct) with Lat and Lon fields. If you specify a geographic structure array with X and Y fields, kmlwrite throws an error.

The attribute fields of S appear as a table in the Description tag of the Placemark for each element of S. The attribute fields appear in the table in the same order as they occur in S.

If S contains valid altitude data, kmlwrite writes the field values to the file as KML altitudes and sets the altitude interpretation to 'relativeToSeaLevel'. If S does not contain altitude data, kmlwrite sets the altitude field in the file to 0 and sets the altitude interpretation to 'clampToGround'. The altitude data can be in a field named either Elevation, Altitude, or Height. If S contains fields with more than one of these names, kmlwrite issues a warning and ignores the altitude fields.

address — Location of KML placemark

character vector | string scalar | cell array of character vectors

Location of KML placemark, specified as a string scalar, character vector or cell array of character vectors containing freeform address data, such as street, city, state, and postal code. If address is a cell array, each cell represents a unique location.

Data Types: char | string | cell

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Name','Point Reyes'

Name — Label of object displayed in viewer

'Address N', 'Point N', 'Line N', or 'Polygon N', where N is the index of the feature. (default) | string scalar | character vector | cell array of character vectors

Label for an object displayed in viewer, specified as a string scalar, character vector, or cell array of character vectors. If you specify a string scalar or character vector, kmlwrite applies the name to all objects. If a string vector or cell array of character vectors, you must specify a name for each feature. That is, the cell array must be the same length as S or address. The following describes the default behavior for various features.

Feature	Default Name
Address	'Address N' where N is the index of the feature.
Point	'Point N' where N is the index of the feature.
Multipoint	'Multipoint N' where N is the index of the feature. kmlwrite places the points in the named folder and each point is named 'Point M' where M is the index of the point.
Line	'Line N' where N is the index of the feature. If the line data contains NaN values, kmlwrite places the line segments in a folder named 'Segment M', where M is the line segment number.
Polygon	'Polygon N' where N is the index of the feature. If the polygon vertex list contains multiple outer rings, kmlwrite places each ring in a folder labeled 'Part M', where M is the number for that feature.

Data Types: char | string | cell

Description — Content to be displayed in the placemark description balloon

string scalar | character vector | cell array of character vectors | attribute specification

Content to be displayed in the placemark description balloon, specified as a string scalar or character vector, cell array of character vectors, or an attribute specification. kmlwrite uses this data to set the values of the feature description tags. The description appears in the description balloon associated with the feature in Google Earth™.

• If you specify a string scalar or character vector, kmlwrite applies the description to all objects.

• If you specify a string vector or cell array of character vectors, there must be one label for each feature; that is, it must be the same length as S or address.

Description elements can be either plain text or tagged with HTML mark up. When in plain text, Google Earth applies basic HTML formatting automatically. For example, Google Earth replaces newlines with line break tags and encloses valid URLs in anchor tags to make them hyperlinks. To see examples of HTML tags that are recognized by Google Earth, view https://earth.google.com.

If you provide an attribute specification, the attribute fields of S display as a table in the description tag of the placemark for each element of S, in the order in which the fields appear in the specification. To construct an attribute spec, call makeattribspec and then modify the output to remove attributes or change the Format field for one or more attributes. The latitude and longitude coordinates of S are not considered to be attributes. If included in an attribute spec, kmlwrite ignores them.

Data Types: char | string | cell

Icon — File name of custom icon

defined by viewer (default) | string scalar | character vector | cell array of character vectors

File name of custom icon, specified as a string scalar, character vector or cell array of character vectors.

• If a string scalar or character vector, kmlwrite applies the value to all icons.

• If a string vector or cell array of character vectors, specify an icon for each feature; that is, the cell array must be the same length as S or address.

• If the string scalar or character vector is an Internet URL, the URL must include the protocol type.

• If the icon file name is not in the current folder, or in a folder on the MATLAB path, specify a full or relative path name.

Data Types: char | string | cell

IconScale — Scaling factor for icon

positive numeric scalar or vector

Scaling factor for the icon, specified as a positive numeric scalar or vector.

• If a scalar, kmlwrite applies the value to all objects

• If a vector, specify a scale factor for each feature. That is, the cell array must be the same length as S or address.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32

Color — Color of icons, lines, or the faces and edges of polygons

defined by viewer (default) | color name | RGB triplet | cell array of color names | string vector of color names | matrix of RGB triplets | 'none'

Color of icons, lines, or the faces and edges of polygons, specified as one of these values.

• A color name such as 'red' or a short name such as 'r'.

• An RGB triplet, which is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A cell array of color names such as {'red','green','blue'} or {'r','g','b'}.

• A string vector of color names such as ["red" "green" "blue"] or ["r" "g" "b"].

• A matrix of RGB triplets, which is a three-column matrix in which each row is an RGB triplet.

The way you specify the color depends on the desired color scheme.

• To apply the same color to all features, specify a single color name or RGB triplet.

• To apply a different color to each feature, specify a cell array of color names, a string vector of color names, or a matrix of RGB triplets. The number of colors and RGB triplets must match the length of S or address.

• To create a polygon geoshape with no fill or edge color, specify 'none'.

• To exclude a color specification for icons or lines, specify 'none'. In this case, the viewer defines the icon or line color.

Note that Color specifies the color of polygon faces and edges if you do not specify FaceColor and EdgeColor.

This table contains the color names and equivalent RGB triplets for some common colors.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

Data Types: char | string | cell | double

Alpha — Transparency of the icons, lines, or the faces and edges of polygons

1 (fully opaque) (default) | numeric scalar or vector in the range [0 1]

Transparency of the icons, lines, or the faces and edges of polygons, specified as a numeric scalar or vector in the range [0 1]. If a scalar, kmlwrite applies the value to all features. If a vector, specify a value for each feature; that is, the vector must be the same length as S or address. If S is a polygon geoshape, kmlwrite applies the value to all the polygon faces if FaceAlpha is not specified and the polygon edges if EdgeAlpha is not specified.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32

LineWidth — Width of lines and polygon edges in pixels

defined by viewer (default) | positive numeric scalar or vector

Width of lines and polygon edges in pixels, specified as a positive numeric scalar or vector.

• If a scalar, kmlwrite applies the value to all polygon edges.

• If a vector, specify a value for each feature. That is, the vector must have the same length as S.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32

FaceColor — Color of polygon faces

defined by viewer (default) | color name | RGB triplet | cell array of color names | string vector of color names | matrix of RGB triplets | 'none'

Color of polygon faces, specified as one of these values.

• A color name such as 'red' or a short name such as 'r'.

• An RGB triplet, which is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A cell array of color names such as {'red','green','blue'} or {'r','g','b'}.

• A string vector of color names such as ["red" "green" "blue"] or ["r" "g" "b"].

• A matrix of RGB triplets, which is a three-column matrix in which each row is an RGB triplet.

The way you specify the color depends on the desired color scheme.

• To apply the same color to all polygon faces, specify a single color name or RGB triplet.

• To apply a different color to each face, specify a cell array of color names, a string vector of color names, or a matrix of RGB triplets. The number of colors and RGB triplets must match the length of S or address.

• To create a polygon geoshape with no face color, specify 'none'.

This table contains the color names and equivalent RGB triplets for some common colors.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

Data Types: char | string | cell | double

FaceAlpha — Transparency of polygon faces

1 (fully opaque) (default) | numeric scalar or vector in the range [0 1]

Transparency of polygon faces, specified as a numeric scalar or vector in the range [0 1].

• If a scalar, kmlwrite applies the value to all polygon faces.

• If a vector, specify a value for each polygon face; that is, the vector must be the same length as S or address.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32

EdgeColor — Color of polygon edges

defined by viewer (default) | color name | RGB triplet | cell array of color names | string vector of color names | matrix of RGB triplets | 'none'

Color of polygon edges, specified as one of these values.

• A color name such as 'red' or a short name such as 'r'.

• An RGB triplet, which is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A cell array of color names such as {'red','green','blue'} or {'r','g','b'}.

• A string vector of color names such as ["red" "green" "blue"] or ["r" "g" "b"].

• A matrix of RGB triplets, which is a three-column matrix in which each row is an RGB triplet.

The way you specify the color depends on the desired color scheme.

• To apply the same color to the edges of all polygons, specify a single color name or RGB triplet.

• To apply a different edge color for each polygon, specify a cell array of color names, a string vector of color names, or a matrix of RGB triplets. The number of colors and RGB triplets must match the length of S or address.

• To create a polygon geoshape with no edge color, specify 'none'.

This table contains the color names and equivalent RGB triplets for some common colors.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

Data Types: char | string | cell | double

EdgeAlpha — Transparency of the polygon edges

1 (fully opaque) (default) | numeric scalar or vector in the range [0 1]

Transparency of the polygon edges, specified as a numeric scalar or vector.

• If a scalar, kmlwrite applies the value to all polygon edges.

• If a vector, y specify a value for each polygon edge; that is, the vector must be the same length as S. If you do not specify EdgeAlpha, kmlwrite uses the value of Alpha, if specified. If you do not specify either value, kmlwrite uses the default value 1 (fully opaque).

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32

Extrude — Connect polygons to the ground

false (default) | true | logical or numeric scalar | logical or numeric vector

Connect polygon to the ground, specified as a logical or numeric scalar, true (1) or false (0), or vector. If a scalar, the values applies to all polygons. If a vector, specify a value for each polygon; that is, the vector must be the same length as S or address.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

CutPolygons — Cut polygon parts

true (default) | false

Cut polygon parts, specified as a logical or numeric scalar true (1) or false (0). If true, kmlwrite cuts polygon parts at the PolygonCutMeridian value. If true, and the polygon parts require cutting, kmlwrite returns an error if the altitude values are nonuniform.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | logical

PolygonCutMeridian — Meridian where polygon parts are cut

180 (default) | scalar numeric

Meridian where polygon parts are cut, specified as a scalar numeric.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32

AltitudeMode — Interpretation of altitude values

'clampToGround' | 'relativeToGround' | 'relativeToSeaLevel'

Interpretation of altitude values, specified as one of the following values:

Value	Description
'clampToGround'	Ignore altitude values and set the feature on the ground. This is the default interpretation when you do not specify altitude values.
'relativeToGround'	Set altitude values relative to the actual ground elevation of a particular feature
'relativeToSeaLevel'	Set altitude values relative to sea level, regardless of the actual elevation values of the terrain beneath the feature. (Named 'absolute' in the KML specification.) This is the default interpretation when you specify altitude values.

Data Types: char | string

LookAt — Position of virtual camera (eye) relative to object being viewed

geopoint vector

Position of the virtual camera (eye) relative to the object being viewed, specified as a geopoint vector. The fields of the geopoint vector, listed below, define the view. LookAt is limited to looking down at a feature. To tilt the virtual camera to look above the horizon into the sky, use the Camera parameter.

Property Name	Description	Data Type
Latitude	Latitude of the object the camera is looking at, in degrees	Scalar double, from -90 to 90
Longitude	Longitude of the object the camera is looking at, in degrees	Scalar double, from −180 to 180
Altitude	Altitude of the object the camera is looking at from the Earth's surface, in meters	Scalar numeric
Heading	Camera direction (azimuth), in degrees (optional)	Scalar numeric [0 360], default 0 (true North)
Tilt	Angle between the direction of the LookAt position and the normal to the surface of the Earth, in degrees (optional)	Scalar numeric [0 90], default 0 (directly above)
Range	Distance in meters from the object specified by latitude, longitude, and altitude to the location of the camera.	Scalar numeric, default 0
AltitudeMode	Interpretation of the camera altitude value (optional)	'relativeToSeaLevel', 'clampToGround', (default) 'relativeToGround'

Camera — Position of virtual camera relative to surface of Earth

geopoint vector

Position of virtual camera (eye) relative to Earth's surface, specified as a geopoint vector. The fields of the geopoint vector, listed below, define the view. 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. You can tilt the camera view so that you're looking above the horizon into the sky.

Property Name	Description	Data Type
Latitude	Latitude of the virtual camera (eye), in degrees	Scalar double, in the range [-90 90]
Longitude	Longitude of the virtual camera, in degrees	Scalar double, in the range [-180 180].
Altitude	Distance of the virtual camera from the Earth's surface, in meters	Scalar numeric
Heading	Direction (azimuth) in degrees (optional)	Scalar numeric [0 360], default 0 (true North)
Tilt	Camera rotation around the X-axis, in degrees (optional)	Scalar numeric [0 180], default 0 (directly above)
Roll	Camera rotation in degrees around the Z-axis (optional)	Scalar numeric, in the range [-180 180], default 0
AltitudeMode	Specifies how camera altitude is interpreted (optional)	'relativeToSeaLevel', 'clampToGround', 'relativeToGround' (default)

Tips

• You can view KML files with the Google Earth browser, which must be installed on your computer.

  For Windows, use the winopen function:

  winopen(filename)
  

  For Linux, if the file name is a partial path, use the following commands:

  cmd = 'googleearth ';
  fullfilename = fullfile(pwd, filename);   
  system([cmd fullfilename])
  

  For Mac, if the file name is a partial path, use the following commands:

  cmd = 'open -a Google\ Earth '
  fullfilename = fullfile(pwd, filename);   
  system([cmd fullfilename])
  

• You can also view KML files with a Google Maps™ browser. The file must be located on a web server that is accessible from the Internet. A private intranet server will not suffice because Google’s server must be able to access the URL that you provide. The following is a template for using Google Maps. Replace your-web-server-path with a real value.

  GMAPS_URL = 'http://maps.google.com/maps?q=';
  KML_URL = 'http://your-web-server-path';
  web([GMAPS_URL KML_URL])
  

Version History

Introduced in R2007b

R2021b: Write geospatial tables to KML format

The kmlwrite function accepts geospatial tables as input.

R2016a: Syntaxes that accept numeric vectors are not recommended

Syntaxes of the kmlwrite function that accept numeric vectors are not recommended. Use the kmlwritepoint function instead. To update your code, replace instances of the kmlwrite function with the kmlwritepoint function.

Not Recommended	Recommended
kmlwrite(filename,lat,lon)	kmlwritepoint(filename,lat,lon)
kmlwrite(filename,lat,lon,alt)	kmlwritepoint(filename,lat,lon,alt)