kmlwriteline

Write geographic line data to KML file

Syntax

kmlwriteline(filename,latitude,longitude)

kmlwriteline(filename,latitude,longitude,altitude)

kmlwriteline(___,Name,Value)

Description

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

kmlwriteline(filename,latitude,longitude,altitude) uses the values of latitude, longitude, and altitude to set the coordinates of the points that define the line. When you specify an altitude value, kmlwriteline sets the AltitudeMode attribute to 'relativeToSeaLevel'.

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

Examples

Write Line Data to KML File

Load geographic data describing coast lines.

load coastlines 

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

 filename = 'coastlines.kml';

Write the line data to the file, specifying the color and width of the line.

kmlwriteline(filename, coastlat, coastlon, 'Color','black', ...
       'LineWidth', 3);

Retrieve GPS Track Log from GPX File and Write Data to KML File

Read the track log from a GPX file. gpxread returns the data as a geopoint vector.

points = gpxread('sample_tracks');

Get the latitude, longitude, and altitude values from the data.

lat = points.Latitude;
lon = points.Longitude;
alt = points.Elevation;

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

filename = 'track.kml';

Write the geographic line data to the file, specifying a description and a name.

kmlwriteline(filename,lat, lon, alt, ...
       'Description', points.Metadata.Name, 'Name', 'Track Log');

Display Equally Spaced Waypoints Along Two Great Circle Tracks

Read the track data into a geopoint vector.

cities = geopoint(shaperead('worldcities','UseGeoCoords',true));

Get the latitude, longitude, and altitude values from the data. The example uses London and New York.

city1 = 'London';
city2 = 'New York';
pt1 = cities(strcmp(city1,cities.Name));
pt2 = cities(strcmp(city2,cities.Name));
lat1 = pt1.Latitude;
lon1 = pt1.Longitude;
lat2 = pt2.Latitude;    
lon2 = pt2.Longitude;
nlegs = 20;
[lat,lon] = gcwaypts(lat1,lon1,lat2,lon2,nlegs);
midpoint = nlegs/2;
altscale = 5000;
alt = [0:midpoint midpoint-1:-1:0] * altscale;

Specify the view using LookAt parameter values.

lookLat = 49.155804;
lookLon = -56.698494;
lookAt = geopoint(lookLat, lookLon);
lookAt.Range = 2060400;
lookAt.Heading = 10;
lookAt.Tilt = 70;

Write the geographic line data to two KML files, specifying color, width, and view. One track displays altitude values and the other has the track clamped to the ground.

width = 4;
filename1 = 'altitudetrack.kml';
kmlwriteline(filename1,lat,lon,alt,'Color','k','LineWidth',width)

filename2 = 'groundtrack.kml';
kmlwriteline(filename2,lat,lon,alt,'Color','w','LineWidth',width, ...
       'LookAt',lookAt,'AltitudeMode','clampToGround')

Input Arguments

filename — Name of output file

character vector | string scalar

Name of output file, specified as a string scalar or character vector. kmlwriteline 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 that define the line

vector in the range [-90 90]

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

Data Types: single | double

longitude — Longitudes of points that define the line

vector

Longitudes of points that define the line, specified as a vector. Longitude values automatically wrap to the range [-180, 180].

Data Types: single | double

altitude — Altitude of points that define the line

0 (default) | scalar or vector

Altitude of points that define the line, specified as a scalar or vector. Unit of measure is meters.

• If a scalar, kmlwriteline 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: 'Name','Point Reyes'

Name — Label of line displayed in viewer

'Line N' where N is the index of the line (default) | string scalar | character vector

Label of line displayed in viewer, specified as a string scalar or character vector.

If the line contains NaN values, kmlwriteline places the line segments in a folder labeled 'Line 1'. kmlwriteline labels the line segments 'Segment N', where N is the index value of the line segment.

Data Types: char | string

Description — Content to be displayed in the line description balloon

string scalar | character vector

Content to be displayed in the line description balloon, specified as a string scalar or character vector. The description appears in the description balloon when the user clicks either the feature name in the Google Earth Places panel or the line in the viewer window.

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 recognized by Google Earth, view https://earth.google.com.

Data Types: char | string

Color — Line color

defined by viewer (default) | color name | RGB triplet | 'none'

Line 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].

If you do not specify a line color, or specify 'none', then the kmlwriteline function does not include a color specification in the file and the viewer defines the 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 | double

Alpha — Transparency of line

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

Transparency of line, specified as a numeric scalar in the range [0 1]. The default value, 1, indicates that the line is fully opaque.

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

LineWidth — Width of line in pixels

defined by viewer (default) | positive numeric scalar

Width of line in pixels, specified as a positive numeric scalar. If you do not specify a width, kmlwriteline does not include width information in the file and the viewer defines the line width.

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:

Value	Description
'clampToGround'	Ignore altitude values and set the feature on the ground. 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. The default interpretation when you specify altitude values. Called 'absolute' in KML terminology.

Data Types: char | string

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

geopoint vector

Position of the virtual camera (eye) relative to the object being viewed, specified as a geopoint vector. The fields of the geopoint vector 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 Name	Description	Data Type
Latitude	Latitude of the line the camera is looking at, in degrees	Scalar double, from -90 to 90
Longitude	Longitude of the line the camera is looking at, in degrees	Scalar double, from −180 to 180
Altitude	Altitude of the line the camera is looking at from the Earth's surface, in meters	Scalar numeric
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 position of the camera.	Scalar numeric, default 0
AltitudeMode	Interpretation of the camera altitude value (optional)	'relativeToSeaLevel', 'clampToGround', (default) 'relativeToGround'

Camera — Position of virtual camera relative to surface of Earth

geopoint 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 6 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	Scalar double, in the range [-90 90]
Longitude	Longitude of the virtual camera, in degrees,	Scalar double, in the range [-180 180].
Altitude	Distance of the virtual camera from the Earth's surface, 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 how camera altitude is interpreted (optional)	'relativeToSeaLevel', 'clampToGround', 'relativeToGround' (default)

Tips

• If you do not see your line, set AltitudeMode to 'clampToGround'. If the line appears, then you may have a problem with your altitude value.

• 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