kmlwritepoint

Write geographic point data to KML file

Syntax

  • kmlwritepoint(filename,latitude,longitude) example
  • kmlwritepoint(filename,latitude,longitude,altitude)
  • kmlwritepoint(___,Name,Value) example

Description

example

kmlwritepoint(filename,latitude,longitude) writes the geographic data, 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 third coordinate value (altitude) to 0.

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.

example

kmlwritepoint(___,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 a Point Data to KML File with Description and Custom Icon

Specify the latitude and longitude values that define a point.

lat =  42.299827;
lon = -71.350273;

Define the description, name, and icon for the point.

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 point data to the file, with the description, name, and icon.

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

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

Read point data from a GPX file into a geopoint object.

S = 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, specifying a name for each location.

kmlwritepoint(filename, S.Latitude, S.Longitude, 'Name', S.Name);

Write Point Data to KML File Using LookAt to Specify View

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

lat =  42.299827;
lon = -71.350273;

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

lookAt = geopoint(-13.209676, -72.503364, 'Range', 14794.88, ...
                  'Heading', 71.13, 'Tilt', 66.77);

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

filename = 'Machu_Picchu.kml';

Write the point data to the file, specifying a name.

kmlwritepoint(filename, lat, lon, 'LookAt', lookAt, ...
              'Name', 'Machu Picchu');

Write Point Data to KML File Using Camera to Specify 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.

kmlwritepoint(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. 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

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 pointnumeric vector in 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, 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 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32

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 point displayed in viewer'Point N' where N is the index value of the point (default) | character string or cell array of strings

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

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

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

Example: ‘Name', ‘Mount Rainier'

Data Types: char | cell

'Description' — Content to be displayed in the point's description ballooncharacter string or cell array of strings

Content to be displayed in the point's description balloon, specified as a character string or a cell array of strings. 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, kmlwritepoint applies the description to all points.

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

You can include basic HTML mark up in description, 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.

Example: 'Description', sprintf('%s<br>%s</br><br>%s</br>', '3 Apple Hill Drive', 'Natick, MA. 01760', 'http://www.mathworks.com');

Data Types: char | cell

'Icon' — File name of a custom icondefined by viewer, for example, Google Earth uses an image of a push pin. (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, kmlwritepoint uses the icon for all points.

  • If a cell array, 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 filename is not in the current folder, or in a folder on the MATLAB path, you must specify a full or relative pathname. If the string is an Internet URL, the URL must include the protocol type.

Example: ‘Icon', ‘my_icon.jpg'

Data Types: char | cell

'IconScale' — Scaling factor for icon (default) | 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.

Example: ‘Iconscale', 2

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

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

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

  • If a character string, kmlwritepoint applies the color to all points.

  • If a cell array, you must specify a color for each point. That is, the cell array must be the same length as latitude and longitude.

  • If a numeric array, it must be an m-by-3 array where m is the length of latitiude and longitude.

Example: 'Color', ‘red'

'AltitudeMode' — Interpretation of altitude values'clampToGround', if you do not specify altitude values, otherwise,'relativeToSeaLevel' (default) | 'clampToGround', 'relativeToGround', or 'relativeToSeaLevel'

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

ValueDescription
'clampToGround'Ignore altitude values and set the feature on the ground
'relativeToGround'Sets altitude values relative to the actual ground elevation of a particular feature
'relativeToSeaLevel'Sets altitude values relative to sea level, regardless of the actual elevation values of the terrain beneath the feature. Called ‘absolute' in KML terminology.

Example: ‘altitudeMode', ‘relativeToGround'

Data Types: char

'LookAt' — Position of the virtual camera (eye) relative to the object being viewedgeopoint 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 NameDescriptionData Type
LatitudeLatitude of the point the camera is looking at, in degrees north or south of the Equator (0 degrees)Scalar double, from -90 to 90
LongitudeLongitude of the point the camera is looking at, in degrees, specifying angular distance relative to the Prime MeridianScalar 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
AltitudeAltitude of the point the camera is looking at from the Earth's surface, in metersScalar numeric, default 0
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 point where the camera is positioned—theLookAt position.Scalar numeric, default: 0
AltitudeModeInterpretation of camera altitude value (optional) String with value: 'relativeToSeaLevel', 'clampToGround', (default) 'relativeToGround'

Example: 'LookAt',geopoint(-13.209676, -72.503364,'Range', 14794.88,'Heading', 71.13, 'Tilt',66.77)

'Camera' — Position of the virtual camera relative to the surface of the Earthgeopoint 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 NameDescriptionData Type
LatitudeLatitude of the virtual camera (eye), in degrees north or south of the Equator (0 degrees)Scalar double in the range [-90 90]
LongitudeLongitude of the virtual camera, in degrees, specifying angular distance relative to the Prime MeridianScalar 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
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' , (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.

Example: 'Camera', geopoint(46.7, -121.7,'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?