kmlwriteline

Write geographic line data to KML file

collapse all in page

Syntax

kmlwriteline(filename,latitude,longitude)
kmlwriteline(filename,latitude,longitude,altitude)
kmlwriteline(___,Name,Value)

Description

example

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'.

example

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

Examples

collapse all

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

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

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

collapse all

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

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

Data Types: single | double

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

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 of line, specified as a MATLAB® Color Specification (ColorSpec). You can specify a character vector, scalar cell array, or a numeric vector with values in the range [0 1].

  • If you specify a character vector, the value specifies the name of a color (see ColorSpec). If you specify 'none', or do not specify this parameter, kmwriteline does not include a color specification in the file and leaves the color choice up to the viewer.

  • If you specify a cell array, it must be scalar.

  • If you specify a numeric array, it must be a 1-by-3 vector of class double.

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

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

Interpretation of altitude values, specified as one of the following:

ValueDescription
'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

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 NameDescriptionData Type
LatitudeLatitude of the line the camera is looking at, in degreesScalar double, from -90 to 90
LongitudeLongitude of the line the camera is looking at, in degreesScalar double, from −180 to 180
AltitudeAltitude of the line 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 point specified by latitude, longitude, and altitude to the position 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 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 NameDescriptionData Type
LatitudeLatitude of the virtual camera (eye), in degreesScalar double, in the range [-90 90]
LongitudeLongitude of the virtual camera, in degrees, Scalar 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

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

See Also

| | |

Introduced in R2013a

Mapping Toolbox Documentation

Support