Main Content

kmlwrite

Write geographic data to KML file

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.

example

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.

example

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

Examples

collapse all

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") 

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)

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)

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",{});

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

collapse all

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

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.

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'

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.

FeatureDefault 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

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

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

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 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 NameShort NameRGB TripletAppearance
"red""r"[1 0 0]

Sample of the color red

"green""g"[0 1 0]

Sample of the color green

"blue""b"[0 0 1]

Sample of the color blue

"cyan" "c"[0 1 1]

Sample of the color cyan

"magenta""m"[1 0 1]

Sample of the color magenta

"yellow""y"[1 1 0]

Sample of the color yellow

"black""k"[0 0 0]

Sample of the color black

"white""w"[1 1 1]

Sample of the color white

Data Types: char | string | cell | double

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

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

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 NameShort NameRGB TripletAppearance
"red""r"[1 0 0]

Sample of the color red

"green""g"[0 1 0]

Sample of the color green

"blue""b"[0 0 1]

Sample of the color blue

"cyan" "c"[0 1 1]

Sample of the color cyan

"magenta""m"[1 0 1]

Sample of the color magenta

"yellow""y"[1 1 0]

Sample of the color yellow

"black""k"[0 0 0]

Sample of the color black

"white""w"[1 1 1]

Sample of the color white

Data Types: char | string | cell | double

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

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 NameShort NameRGB TripletAppearance
"red""r"[1 0 0]

Sample of the color red

"green""g"[0 1 0]

Sample of the color green

"blue""b"[0 0 1]

Sample of the color blue

"cyan" "c"[0 1 1]

Sample of the color cyan

"magenta""m"[1 0 1]

Sample of the color magenta

"yellow""y"[1 1 0]

Sample of the color yellow

"black""k"[0 0 0]

Sample of the color black

"white""w"[1 1 1]

Sample of the color white

Data Types: char | string | cell | double

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

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

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

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

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

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

ValueDescription
'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

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 NameDescriptionData Type
LatitudeLatitude of the object the camera is looking at, in degreesScalar double, from -90 to 90
LongitudeLongitude of the object the camera is looking at, in degreesScalar double, from −180 to 180
AltitudeAltitude of the object the camera is looking at from the Earth's surface, in metersScalar numeric
HeadingCamera direction (azimuth), in degrees (optional) Scalar numeric [0 360], default 0 (true North)
TiltAngle 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)
RangeDistance in meters from the object specified by latitude, longitude, and altitude to the location of the camera.Scalar numeric, default 0
AltitudeModeInterpretation of the camera altitude value (optional)'relativeToSeaLevel', 'clampToGround', (default) 'relativeToGround'

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 NameDescriptionData Type
LatitudeLatitude of the virtual camera (eye), in degreesScalar double, in the range [-90 90]
LongitudeLongitude of the virtual camera, in degreesScalar double, in the range [-180 180].
AltitudeDistance of the virtual camera from the Earth's surface, in metersScalar numeric
HeadingDirection (azimuth) in degrees (optional) Scalar numeric [0 360], default 0 (true North)
TiltCamera rotation around the X-axis, in degrees (optional) Scalar numeric [0 180], default 0 (directly above)
RollCamera rotation in degrees around the Z-axis (optional) Scalar numeric, in the range [-180 180], default 0
AltitudeModeSpecifies 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

expand all