kmlwritepoint

Write geographic point data to KML file

Syntax

kmlwritepoint(filename,latitude,longitude)

kmlwritepoint(filename,latitude,longitude,altitude)

kmlwritepoint(___,Name,Value)

Description

kmlwritepoint(filename,latitude,longitude) writes the geographic point data specified by latitude and longitude to the file specified by filename in Keyhole Markup Language (KML) format. kmlwritepoint creates a KML Placemark element for each point, using the latitude and longitude values as coordinates of the points. kmlwritepoint sets the altitude values associated with the points to 0 and sets the altitude interpretation to 'clampToGround'.

kmlwritepoint(filename,latitude,longitude,altitude) writes latitude,longitude, and altitude data as point coordinates. When you specify an altitude value, kmlwritepoint sets the AltitudeMode attribute to 'relativeToSeaLevel'.

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

Examples

Write Data to KML File that Includes HTML Format Tags

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', ...
       'https://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.

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

Retrieve Point Data from Shape File and Write Data to KML File

Read the locations of major cities from a shape file into a geostruct.

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

Get the latitudes, longitudes, and names of the cities from the geostruct.

lat = [cities.Lat];
lon = [cities.Lon];
name = {cities.Name};

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

filename = 'European_Cities.kml';

Write the geographic data to the file, specifying the names of the cities and the size of the icon.

kmlwritepoint(filename, lat, lon, 'Name', name, 'IconScale', 2);

Write Point Data to KML File Using Camera to Specify View

Create a geopoint object to specify the viewing options available through the Camera parameter. The example sets up a view of the Washington Monument in Washington D.C.

camlat = 38.889301;
camlon = -77.039731;
camera = geopoint(camlat,camlon);
camera.Altitude = 500;
camera.Heading = 90;
camera.Tilt = 45;
camera.Roll = 0;
name = 'Camera ground location';

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

filename = 'WashingtonMonument.kml';

Write the point data to the file with the view specification. Place a marker at the ground location of the camera.

lat = camera.Latitude;
lon = camera.Longitude;
kmlwritepoint(filename,lat,lon,'Camera',camera,'Name',name);

Write Point Data to KML File Using LookAt to Specify View

Specify the latitude, longitude, and altitude values that define a point. In this example, the location is the Machu Picchu ruins in Peru.

lat = -13.163111;
lon = -72.544945;
alt = 2430;

Create a geopoint object to specify the viewing options available through the LookAt parameter.

lookAt = geopoint(lat,lon);
lookAt.Range = 1500;
lookAt.Heading = 260;
lookAt.Tilt = 67;
name = 'LookAt location parameters';

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

filename = 'Machu_Picchu.kml';

Write the point data to the file, using the LookAt parameter to specify the view.

kmlwritepoint(filename,lat,lon,alt,'Name',name,'LookAt',lookAt)

Use Camera Parameter to Specify View

Specify the latitude and longitude values that define the point that you want to view. In this example, the location is Mount Rainier.

lat_rainier = 46.8533;
lon_rainier = -121.7599;

Create a geopoint vector to specify the position of the virtual camera (eye) you will use to view the location 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_Rainier.kml';

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

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

Input Arguments

filename — Name of output file

string scalar | character vector

Name of output file, specified as a string scalar or character vector. kmlwritepoint creates 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

latitude — Latitudes of points

vector in the range [-90 90]

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

Data Types: single | double

longitude — Longitudes of points

vector

Longitudes of points, specified as a vector. Longitude values automatically wrap to the range [-180 180], in compliance with the KML specification.

Data Types: single | double

altitude — Altitude of points in meters

0 (default) | scalar or vector

Altitude of points in meters, specified as a scalar or vector.

• If a scalar, kmlwritepoint 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

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: kmlwritepoint(filename,lat,lon,'Name','Point Reyes','IconScale',2);

Name — Label of point displayed in viewer

'Point N' where N is the index of the point (default) | string scalar | string array | character vector | cell array of character vectors

Label of point displayed in viewer, specified as a string scalar or character vector or cell array of character vectors.

• If a string scalar or character vector, kmlwritepoint applies the name to all points.

• If a string array or cell array of character vectors, you must include a label for each point; that is, the cell array must have the same length as latitude and longitude.

Data Types: char | string | cell

Description — Content to be displayed in the point description balloon

string scalar | character vector | cell array of character vectors

Content to be displayed in the point description balloon, specified as a string scalar or character vector or a cell array of character vectors. The content appears in the description balloon when you click either the feature name in the Google Earth Places panel or the point in the viewer window.

• If a string scalar or character vector, kmlwritepoint applies the description to all points.

• If a string array or cell array of character vectors, you must include description information for each point; that is, the cell array must be the same length as latitude and longitude.

Description elements can be either plain text or marked up with HTML. When it is plain text, Google Earth applies basic formatting, replacing newlines with line break tags and enclosing valid URLs with anchor tags to make them hyperlinks. To see examples of HTML tags that Google Earth recognizes, view https://earth.google.com.

Data Types: char | string | cell

Icon — File name of a custom icon

defined by viewer, for example, Google Earth uses an image of a push pin. (default) | string scalar | string array | character vector | cell array of character vectors

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

• If a string scalar or character vector, kmlwritepoint uses the icon for all points.

• If a string array or cell array of character vectors, you must specify an icon for each point. That is, the cell array must be the same length as latitude and longitude.

If the icon file name is not in the current folder, or in a folder on the MATLAB path, you must specify a full or relative path name. If the file name is an Internet URL, the URL must include the protocol type.

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, kmlwritepoint applies the scaling factor to the icon for all points.

• If a vector, you must specify a scaling factor for each icon. That is, the vector must be the same length as latitude and longitude.

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

Color — Icon color

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

Icon color, specified as one of these options.

• 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 icons, specify a single color name or RGB triplet.

• To apply a different color to each icon, 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 latitude and longitude.

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

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

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

Transparency of the icons, specified as a numeric scalar or vector in the range [0 1]. The default value, 1, indicates fully opaque.

• If a scalar, kmlwritepoint applies the value to all icons.

• If a vector, you must specify a value for each icon. That is, the vector must be the same length as latitude and longitude.

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. This is the default interpretation when you specify altitude values. Called 'absolute' in KML terminology.

Data Types: char | string

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

geopoint vector

Position of the virtual camera (eye) relative to the object being viewed, specified as a geopoint vector. The view is defined by the fields of the geopoint vector, listed in the table below. LookAt is limited to looking down at a feature, you cannot tilt the virtual camera to look above the horizon into the sky. 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 point the camera is looking at, in degrees north or south of the Equator (0 degrees)	Scalar double, from -90 to 90
Longitude	Longitude of the point the camera is looking at, in degrees, specifying angular distance relative to the Prime Meridian	Scalar double, in the range [-180 180]. Values west of the Meridian range from -180 to 0 degrees. Values east of the Meridian range from 0 to 180 degrees
Altitude	Altitude of the point the camera is looking at from the Earth's surface, in meters	Scalar numeric, default 0
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 point specified by latitude, longitude, and altitude to the point where the camera is positioned—theLookAt position.	Scalar numeric, default: 0
AltitudeMode	Interpretation of camera altitude value (optional)	'relativeToSeaLevel', 'clampToGround', (default) 'relativeToGround'

Camera — Position of the virtual camera relative to the surface of the Earth

geopoint vector

Position of the camera relative to the 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 north or south of the Equator (0 degrees)	Scalar double in the range [-90 90]
Longitude	Longitude of the virtual camera, in degrees, specifying angular distance relative to the Prime Meridian	Scalar double, in the range [-180 180]. Values west of the Meridian range from -180 to 0 degrees. Values east of the Meridian range from 0 to 180 degrees
Altitude	Distance of the virtual camera from the surface of the Earth, 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 the interpretation of camera altitude. (optional)	'relativeToSeaLevel', 'clampToGround' , (default) 'relativeToGround'

• If a scalar, kmlwritepoint applies the value to all the points.

• If a vector, you must include an item for each point; that is, the length must be the same length as latitude and longitude.

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 R2013a