kmlwrite

Write geographic data to KML file

collapse all in page

The following syntaxes, while still supported, are not recommended. Use kmlwritepoint instead.

  • kmlwrite(filename,lat,lon)

  • kmlwrite(filename,lat,lon,alt)

Syntax

kmlwrite(filename,S)
kmlwrite(filename,address)
kmlwrite(___,Name,Value)

Description

example

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. S is a geopoint vector, a geoshape vector, or geostruct. kmlwrite 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.

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

Open Live Script

Return point data in geopoint vector. 

placenames = gpxread('boston_placenames');

Define the name of the KML file you want to create.

filename = 'Boston_Placenames.kml';

Define the colors you want to use with the point data.

colors = jet(length(placenames));

Write the point data to the file, using optional parameters to specify names for the points and define the colors used for the icons.

kmlwrite(filename, placenames, 'Name', placenames.Name,'Color',colors );
Open Live Script

Read line features into a geoshape vector.

tracks = gpxread('sample_tracks', 'Index', 1:2);

Define the name of the KML file you want to create.

filename = 'tracks.kml';

Write the line data to the file, using several optional parameters to specify the color and width of the lines, and their names and descriptions.

colors = {'red', 'green'};
description = tracks.Metadata.Name;
name = {'track1', 'track2'};

kmlwrite(filename, tracks, 'Color', colors, 'LineWidth', 2, ...
         'Description', description, 'Name', name);
Open Live Script

Read geographic data (locations of major European cities) from a shape file, including the names of the cities. This returns a structure.

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

Convert the structure to a geopoint vector.

cities = geopoint(cities);

Define the name of the KML file you want to create.

filename = 'European_Cities.kml';

Write the geographic data to a KML file. Use the optional Name parameter to include the names of the cities in the placemarks. Remove the default Description table.

kmlwrite(filename, cities, 'Name', cities.Name, 'Description',{});
Open Live Script

Create a cell array of unstructured addresses (the names of several Australian cities).

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

Define the name of the KML file you want to create.

filename = 'Australian_Cities.kml';

Write the unstructured address data to a KML file, using the optional Name parameter to include the names of the cities in the placemarks.

kmlwrite(filename, address, 'Name', address);
Open Live Script

Read polygon data from file, returned in a structure.

S = shaperead('usastatelo','UseGeoCoords',true);

Convert the structure to a geoshape vector.

S = geoshape(S);

Write the polygon data to a KML file, using optional parameters to specify the colors of the polygon faces and edges.

filename = 'usastatelo.kml';
colors = polcmap(length(S));
kmlwrite(filename,S,'Name',S.Name,'FaceColor',colors,'EdgeColor','k')

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 a geopoint vector, a geoshape vector, or geostruct. 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 is a geoshape vector, the Geometry field identifies the type of the data: 'point', 'line', or 'polygon'.

  • If S is a geostruct with X and Y fields, kmlwrite returns an error.

  • 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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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 asS 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 a MATLAB Color Specification (ColorSpec), which can be a character vector, cell array, or double array with values in the range [0 1].

  • If a string scalar or character vector, kmlwrite applies the color to all features

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

  • If a double array, specify an M-by-3 array, where M is the same length as S or address.

  • If S is a polygon geoshape, you can specify 'none', which indicates that the polygon is not filled and has no edge. Also, for polygons, Color specifies the color of polygon faces if FaceColor is not specified and polygon edges if EdgeColor is not specified.

Data Types: double | char | cell

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 edges, specified as a MATLAB Color Specification (ColorSpec). A color specification can be a character vector, cell array or character vectors, or a double array with values in the range[0 1]. If a character vector, kmlwrite applies the value to all faces. If a cell array of character vectors, specify a value for each face. That is, the cell array must be the same length as S or address. If the value is a numeric array, it is size M-by-3 where M is the length of S or address. If S is a polygon geoshape, you may specify the value 'none' to indicate that the polygon has no outline.

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 a MATLAB Color Specification (ColorSpec). A color specification can be a character vector, a cell array of character vectors, or a double array with values in the range [0 1].

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

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

  • If you specify a double array, the size must be M-by-3 where M is the length of S.

The value 'none' indicates that polygons have no edges.

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

See Also

| | | |

Introduced in R2007b

Mapping Toolbox Documentation

Support