Documentation

kmlwrite

Write geographic data to KML file

Syntax

  • kmlwrite(filename,S)
  • kmlwrite(filename,latitude,longitude)
  • kmlwrite(filename,latitude,longitude,altitude)
  • kmlwrite(filename,address)
  • kmlwrite(___,Name,Value)

Description

kmlwrite(filename,S) writes the geographic point or line 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.

kmlwrite(filename,latitude,longitude) writes the geographic point data, latitude and longitude, to the file specified by filename in KML format. kmlwrite sets the third coordinate value (altitude) to 0.

kmlwrite(filename,latitude,longitude,altitude) uses the values of latitude,longitude, and altitude to set the three values in the Placemark coordinates tag. When you specify an altitude value, kmlwrite sets the AltitudeMode attribute to relativeToSeaLevel .

kmlwrite(filename,address) writes address to the file specified by filename in KML format. address is a text string containing freeform address data, that can include street, city, state, country, and/or postal code. To specify multiple addresses, use a cell array of strings. kmlwrite creates a KML Placemark in the file, setting the address tag to the value specified by address. 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

expand all

Write Point Data to KML File Using geopoint Vector

Read point data into a geopoint vector.

placenames = gpxread('boston_placenames');

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

filename = 'Boston_Placenames.kml';

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', jet(length(placenames)));

Write Line Data to KML File Using geoshape Vector

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.

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

kmlwrite(filename, tracks, 'Color', color, 'Width', 2, ...
         'Description', description, 'Name', name);

Write Geographic Data to KML File Using geostruct

Read geographic data (locations of major European cities) from a shape file, including the names of the cities, and remove the default description table.

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

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

filename = 'European_Cities.kml';

Write the geographic data to a KML file, using several optional parameters to include the names of the cities in the placemarks.

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

Write Unstructured Address to KML File

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

Include HTML Format Tags in Description

Define a point by latitude and longitude.

lat =  42.299827;
lon = -71.350273;

Specify the description text used with the placemark, including HTML tags for formatting.

description = sprintf('%s<br>%s</br><br;>%s</br>', ...
       '3 Apple Hill Drive', 'Natick, MA. 01760', ...
       'http://www.mathworks.com');
name = 'The MathWorks, Inc.';
iconDir = fullfile(matlabroot,'toolbox','matlab','icons');
iconFilename = fullfile(iconDir, 'matlabicon.gif');

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

filename = 'MathWorks.kml';

Write the data to a KML file, using the Description parameter to include the names of the cities in the placemarks.

kmlwrite(filename, lat, lon, ...
       'Description', description, 'Name', name, 'Icon', iconFilename);

Write Point Data to a KML file Using Camera to Specify the View

Specify the latitude and longitude values that define a point. In this example, the location is Mount Ranier.

lat_rainier = 46.8533
lon_rainier = -121.7599

Create a geopoint vector to specify the position of the virtual camera (eye) using the Camera parameter.

myview = geopoint(46.7, -121.7,'Altitude',2500,'Tilt',85,'Heading',345)

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

filename = 'Mt_Ranier.kml';

Write the point data to the file, specifying a name and a custom color for the icon

kmlwrite(filename,lat_rainier,lon_rainier,'Name','Mt Rainier',...
         'Color','red','IconScale',2,'Camera',myview)

Input Arguments

expand all

filename — Name of KML file to createcharacter string

Name of KML file to create, specified as a character string. 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

S — Geographic features to write to filegeopoint vector, geoshape vector, or geostruct

Geographic features to write to file, specified as a geopoint vector, a geoshape vector, or geostruct.

  • If a geoshape vector, the Geometry field must be set to 'point' or 'line'.

  • If a geostruct (with Lat and Lon fields), the Geometry field must be set to either 'Point', 'MultiPoint', or 'Line'.

  • If you include additional attribute fields in S, kmlwrite writes the data to the description tag of the placemark for each feature, formatted as an HTML table. The attribute fields appear in the table in the same order as they occur in S.

  • If S contains a field named either Elevation, Altitude, or Height, kmlwrite writes the field values to the file as KML altitudes and sets the altitude interpretation to 'relativeToSeaLevel'. If S contains fields with more than one of these names, kmlwrite issues a warning and ignores the altitude fields.

latitude — Latitude of pointsnumeric vector in the range [-90 90]

Latitude of points, specified as a numeric vector in the range [-90 90].

Data Types: single | double

longitude — Longitude of pointsnumeric vector automatically wrapped to the range [-180, 180]

Longitude of points, specified as a numeric vector in the range [-180, 180].

Data Types: single | double

altitude — Altitude of points0 (default) | numeric vector or scalar.

Altitude of points, specified as a numeric vector or scalar. Unit of measure is meters.

  • If a scalar, kmlwrite applies the value to each point.

  • If a vector, you must specify an altitude value for each point. That is, the vector must have the same length as latitude and longitude.

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

address — Location of pointscharacter string or cell array

Location of points, specified as a character string or cell array of strings containing freeform address data, such as street, city, state, and/or postal code. If address is a cell array, each cell represents a unique location.

Example: 'MathWorks, Inc, 3 Apple Hill Drive, Natick, MA 01760-2098'

Data Types: char | 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 single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: ‘Name','Point Reyes'

'Name' — Label of object displayed in viewer'Address N', 'Point N', or 'Line N', where N is the index of the address, point, or line (default) | character string or cell array of strings

Label for an object displayed in viewer, specified as a character string or cell array of strings.

  • If a string, kmlwrite applies the name to all objects

  • If a cell array, you must specify one string for each point, line, or address. That is, the cell array must be the same length as latitude and longitude, S, or address.

  • If you are writing multipoint data, kmlwrite places the points in a folder labeled with the name value you specified, or, if no name is specified, 'Multipoint N'. In the folder, each point is labeled 'Point N', where N is the index of the point.

  • If you are writing a line and the lines contains NaN values, kmlwrite places the line segments in a folder labeled with the corresponding Name value or, if no name is specified, 'Line N'. In the folder, each line segments is labeled 'Segment N', where N is the segment number.

Data Types: char | cell

'Description' — Content to be displayed in the placemark's description ballooncharacter string or cell array of strings | attribute specification

Content to be displayed in the placemark's description balloon, specified as a text string, cell array of strings, or attribute specification. kmlwrite uses this data to sets the values of the feature's description tag(s). The description appears in the description balloon when the user clicks on either the feature name in the Google Earth Places panel or clicks the placemark icon in the viewer window.

  • If a string, kmlwrite applies the description to all objects.

  • If a cell array, there must be one label for each point, that is, it must be the same length as latitude and longitude, S, or address.

You can include basic HTML mark up, however, Google Earth applies some 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 http://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, they are ignored. If you specify latitude and longitude, kmlwrite ignores the attribute specification.

Example: 'Description','My Description'

Data Types: char | cell

'Icon' — File name of a custom icondefined by viewer (default) | character string or cell array of strings

File name of a custom icon, specified as character string or cell array of strings.

  • If a string, kmlwrite applies the value to all objects.

  • If a cell array, you must specify an icon for each point or line. That is, it must be the same length as latitude and longitude, S, or address.

  • If the string is an Internet URL, the URL must include the protocol type.

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

Data Types: char | cell

'IconScale' — Scaling factor for iconpositive 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, you must specify a value for each icon. That is, the vector must be the same length as latitude and longitude, S, or address.

Example: 'Iconscale', 2

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

'Color' — Color of lines or iconsdefined by viewer (default) | ColorSpec

Color of lines or icons, specified as a MATLAB® Color Specification (ColorSpec).

Example: 'Color','red'

'Width' — Width of the line, in pixels1 (default) | positive numeric scalar or vector

Width of the line in pixels, specified as a positive numeric scalar or vector.

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

  • If a vector, you must specify the width of each line. That is, the vector must be the same length as S.

Example: 'Width',2

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

'AltitudeMode' — Interpretation of altitude values'clampToGround' (default) | 'relativeToGround' | 'relativeToSeaLevel'

Interpretation of altitude values, specified as one of the following text strings.

ValueDescription
'clampToGround'Ignore altitude values and set the feature on the ground. This is the default value 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 when you specify altitude values.

Example: 'AltitudeMode','relativeToGround'

Data Types: char

'LookAt' — Position of virtual camera (eye) relative to object being viewedgeopoint 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 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'

Example: 'LookAt', geopoint(lat,lon,'Range',14794.88,'Heading',71.13,'Tilt',66.77)

'Camera' — Position of virtual camera relative to surface of Earthgeopoint 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 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)

Example: 'Camera',geopoint(lat,lon,'Altitude',2500,'Tilt',85,'Heading',345)

More About

expand all

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 filename is a partial path, use the following commands:

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

    For Mac, if the filename 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. A template for using Google Maps is listed below:

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