kmlwritepoint

Write geographic point data to KML file

collapse all in page

Syntax

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

Description

example

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

example

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

Examples

collapse all

Open Live Script

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);
Open Live Script

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);
Open Live Script

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);
Open Live Script

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)
Open Live Script

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

collapse all

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

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

Data Types: single | double

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

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

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

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

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

  • If a character vector, kmlwritepoint applies the color to all points. If you specify 'none', kmwritepoint does not include a color specification in the file and leaves the color choice up to the viewer.

  • 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 an array, it must be an M-by-3 array where M is the length of latitude and longitude.

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

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

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

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) 'relativeToSeaLevel', 'clampToGround', (default) 'relativeToGround'

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 surface of the Earth, 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 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])

See Also

| | |

Introduced in R2013a

Mapping Toolbox Documentation

Support