Mapping Toolbox™

km2nm, km2sm, nm2km, nm2sm, sm2km, sm2nm

kmlwrite - Write geographic data to KML file

Syntax

kmlwrite(filename, lat, lon) kmlwrite(filename, S) kmlwrite(filename, address) kmlwrite(..., param1, val1, param2, val2, ...)

Description

kmlwrite(filename, lat, lon) writes the latitude and longitude points lat and lon to disk in KML format. KML stands for Keyhole Markup Language. It is an XML dialect used by the Google Earth and Google Maps mapping services and similar applications. lat and lon are numeric vectors, specified in degrees. lat must be in the range [-90, 90]. There is no range constraint on lon; all longitudes are automatically wrapped to the range [-180, 180], to adhere to the KML specification. filename must be a character string specifying the output file name and location. If an extension is included, it must be .kml.

kmlwrite(filename, S) writes a point or multipoint geostruct to disk in KML format. The Geometry field of S must be either 'Point' or 'Multipoint'. S must include Lat and Lon fields. (If S includes X and Y fields an error is issued). The attribute fields of S are presented as a table in the description tag of the placemark displayed for each element of S, in the same order as they appear in S.

kmlwrite(filename, address) specifies the location of a KML Placemark via an address string or cell array of strings. Each string represents an unstructured address with city, state, and/or postal code. If address is a cell array, each cell contains the address of a unique point.

kmlwrite(..., param1, val1, param2, val2, ...) specifies parameter-value pairs that set additional KML feature properties. Parameter names can be abbreviated and are case-insensitive.

The parameter-value pairs are listed below:

Name — A string or cell array of strings that specifies a name displayed in the viewer as the label for the object. If the value is a string, the name is applied to all objects. If the value is a cell array, it must match in size to lat and lon, S, or address.
Description — A string, cell array of strings, or an attribute spec, that specifies the contents to be displayed in the feature's description tag(s). The description appears in the description balloon when the user clicks either the feature name in the Google Earth application Places panel or clicks the placemark icon in the viewer window. If the value is a string, the description is applied to all objects. If the value is a cell array, it must match the size of lat and lon, S, or address. Use a cell array to customize descriptive tags for different placemarks.
Description elements can be either plain text or marked up with HTML. When it is plain text, the Google Earth application applies basic formatting, replacing each newline with <br> and giving anchor tags to all valid URLs for the World Wide Web. The URL strings are converted to hyperlinks. This means that you do not need to surround a URL with <A HREF> tags in order to create a simple link. Examples of HTML tags recognized by the Google Earth application are provided on its Web site, http://earth.google.com.
Icon — A string or cell array of strings that specifies a custom icon filename. If the value is a string, the value is applied to all objects. If the value is a cell array, it must have the same size as lat and lon, S, or address. If the icon filename is not in the current directory, or in a directory on the MATLAB path, specify a full or relative path name. The string can be an Internet URL. The URL must include the protocol prefix (e.g., http://).
IconScale — A positive numeric scalar or array that specifies a scaling factor for the icon. If the value is a scalar, the value is applied to all objects. If the value is an array, it must have the same size as lat and lon, S, or address.

Remarks

Using an Attribute Spec to Control Formatting of Attributes

An attribute spec is a structure with field names of attributes that controls how the table is displayed in its description balloon. In it, each field name you want to display has two fields, Format and AttributeLabel.

When you provide geostruct, S, to kmlwrite, then the Description parameter can be an attribute spec. In this case, the attribute fields of S are displayed as a table in the description tag of the placemark for each element of S. (If you specify an attribute spec with lat and lon input syntax, the attribute spec is ignored.) The attribute spec can control:

Which attributes are included in the table
The name for the attribute
The order in which attributes appear
The formatting of attributes

The easiest way to construct an attribute spec is to call makeattribspec, and then modify the output to remove attributes or change the Format field for one or more attributes. The lat and lon fields of S are never treated as attributes.

Viewing the KML file with the Google Earth browser

A KML file may be displayed in a Google Earth browser. The Google Earth application must be installed on the system. On Microsoft Windows platforms you can display the KML file with:

winopen(filename)

For Unix and MAC users, display the KML file with:

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

Viewing the KML file with a Web Browser

You can view KML files using the Google Maps mapping service in addition to using an installed Google Earth application. To do so, the file must be located on a web server that is accessible from the Internet. A private intranet server will not suffice, because the Google Maps server must be able to access the URL that you provide to it. Here is a template for viewing your KML in a browser window via the Google Maps mapping service:

GMAPS_URL = 'http://maps.google.com/maps?q=';
KML_URL = 'http://<your web server and path to your KML file>';
web([GMAPS KML_URL])

You can only display a limited number of placemarks on a Google Maps page, and all placemarks must be geolocated using latitude-longitude coordinates (address-based placemarks are not supported). Google Mobile has further restrictions. See the Google KML documentation for more information.

Examples

Example 1 — Write a single point to a KML file

Add a description containing HTML markup, a name, and provide the location of an icon to display. Specifying an icon as a URL from the Web (as opposed to specifying one from a local file) makes the icon accessible to users of Google Maps service as well as to Google Earth users.

% Write a single point to a KML file.
% Add a description containing HTML, a name and an icon.
lat =  42.299827;
lon = -71.350273;
description = sprintf('%s<br>%s</br><br>%s</br>', ...
       '3 Apple Hill Drive', 'Natick, MA. 01760', ...
       'http://www.mathworks.com');
name = 'The MathWorks, Inc.';
filename = 'The_MathWorks.kml';
kmlwrite(filename, lat, lon, ...
       'Description', description, 'Name', name, 'Icon', ...
'http://www.mathworks.com/products/product_listing/images/ml_icon.gif');

Example 2 — Write the locations of major European cities to a KML file

Include 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]);
filename = 'European_Cities.kml';
kmlwrite(filename, cities, 'Name', {cities.Name}, 'Description',{});

Example 3 — Write the locations of several Australian cities to a KML file

List the addresses to be displayed in a cell array:

address = {'Perth, Australia', ...
           'Melbourne, Australia', ...
           'Sydney, Australia'};
filename = 'Australian_Cities.kml';
kmlwrite(filename, address, 'Name', address);

Example 4 — Unproject locations of Boston landmarks and write to a KML file

The Boston placenames file contains points stored in projected coordinates of meters, but Earth browsers require geographic coordinates (latitudes and longitudes). Begin by converting coordinates from meters to survey feet, inverting the projection to latitudes and longitudes, and then adding the latitudes and longitudes to the geostruct. To unproject properly, use the projection information extracted from the GeoTIFF file boston.tif:

S = shaperead('boston_placenames');
proj = geotiffinfo('boston.tif');
surveyFeetPerMeter = unitsratio('sf','meter');
for k=1:numel(S)
    x =  surveyFeetPerMeter * S(k).X;
    y =  surveyFeetPerMeter * S(k).Y;
    [S(k).Lat, S(k).Lon] = projinv(proj, x, y);
end
filename = 'Boston_Placenames.kml';
kmlwrite(filename, S, 'Name', {S.NAME});

If you have the Google Earth application installed, you can view the file on Microsoft Windows as follows:

winopen(filename)

On UNIX or MAC, use:

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

For a different view of this location and placename data, see Tour Boston with the Map Viewer.