kmlwrite
Write geographic data to KML file
Description
kmlwrite(
writes filename
,address
)address
to the file specified by filename
in KML format. address
is a string scalar or character vector
containing freeform address data, that can include street, city, state, country, and/or
postal code. To specify multiple addresses, use a cell array of character vectors or string
scalars. kmlwrite
creates a KML Placemark in the file, setting the value
of the address tag. An address is an alternative way to specify a point, instead of using
latitude and longitude.
kmlwrite(___,
specifies
name-value pairs that set additional KML feature properties. Parameter
names can be abbreviated and are case-insensitive.Name,Value
)
Examples
Write Polygon Data to KML File
Import a shapefile containing polygon data into a geospatial table. The polygons represent state boundaries.
GT = readgeotable("usastatelo.shp");
Create a colormap for the data using random, muted colors.
colors = polcmap(height(GT));
Write the polygon data to a KML file called usastatelo.kml
. Specify the labels and the colors of the polygon faces and edges using name-value arguments.
kmlwrite("usastatelo.kml",GT,"Name",GT.Name, ... "FaceColor",colors,"EdgeColor","k")
Write Point Data to KML File Using Geographic Point Vector
Import point data as a geographic point (geopoint
) vector.
places = gpxread("boston_placenames.gpx");
Specify the colors to use with the point data.
colors = jet(length(places));
Write the point data to a file called boston_placenames.kml
. Specify the point names and icon colors using name-value arguments.
kmlwrite("boston_placenames.kml",places,"Name",places.Name,"Color",colors)
Write Line Data to KML File Using Geographic Shape Vector
Read line features into a geographic shape (geoshape
) vector.
tracks = gpxread("sample_tracks.gpx","Index",1:2);
Write the line data to a KML file. Specify the colors, widths, names, and descriptions of the lines using name-value arguments.
colors = ["red" "green"]; description = tracks.Metadata.Name; name = ["track1" "track2"]; kmlwrite("sample_tracks.kml",tracks,"Color",colors,"LineWidth",2, ... "Description",description,"Name",name)
Write Geographic Data to KML File Using Geographic Structure Array
Read the names and locations of major European cities from a shapefile. The shaperead
function returns a geographic structure array (geostruct
).
latlim = [30;75]; lonlim = [-25;45]; cities = shaperead("worldcities.shp","UseGeoCoords",true, ... "BoundingBox",[lonlim, latlim]);
Convert the structure to a geographic point (geopoint
) vector.
cities = geopoint(cities);
Write the data to a KML file. Include city names in the placemarks by using the Name
name-value argument. Remove the default Description
table.
kmlwrite("european_cities.kml",cities,"Name",cities.Name,"Description",{});
Write Unstructured Address to KML File
Create a cell array of unstructured addresses. For this example, use the names of several Australian cities.
address = {'Perth, Australia', ... 'Melbourne, Australia', ... 'Sydney, Australia'};
Write the unstructured address data to a KML file called australian_cities.kml
. Include the names of the cities in the placemarks using the Name
name-value argument.
kmlwrite("australian_cities.kml",address,"Name",address);
Input Arguments
filename
— Name of output file
character vector | string scalar
Name of output file, specified as a string scalar or character vector.
kmlwrite
writes 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
S
— Geographic features to write to file
geospatial table | geopoint
vector | geoshape
vector | geographic structure array
Geographic features to write to file, specified as one of the following:
A geospatial table containing
geopointshape
,geolineshape
, orgeopolyshape
objects. Thekmlwrite
function does not support geospatial tables containing more than one type of shape object. For more information about geospatial tables, see Create Geospatial Tables.A
geopoint
vector.A
geoshape
vector. TheGeometry
field identifies the type of the data as'point'
,'line'
, or'polygon'
.A geographic structure array (
geostruct
) withLat
andLon
fields. If you specify a geographic structure array withX
andY
fields,kmlwrite
throws an error.
The attribute fields of S
appear as a table in the
Description tag of the Placemark for each element of S
. The attribute
fields appear in the table in the same order as they occur in
S
.
If S
contains valid altitude data, kmlwrite
writes the field values to the file as KML altitudes and sets the altitude
interpretation to 'relativeToSeaLevel'
. If S
does
not contain altitude data, kmlwrite
sets the altitude field in the
file to 0
and sets the altitude interpretation to
'clampToGround'
. The altitude data can be in a field named either
Elevation
, Altitude
, or
Height
. If S
contains fields with more than one
of these names, kmlwrite
issues a warning and ignores the altitude
fields.
address
— Location of KML placemark
character vector | string scalar | cell array of character vectors
Location of KML placemark, specified as a string scalar, character vector or cell array of
character vectors containing freeform address data, such as street, city, state, and
postal code. If address
is a cell array, each cell represents a
unique location.
Data Types: char
| string
| cell
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 object displayed in viewer
'Address N'
, 'Point N'
,
'Line N'
, or 'Polygon N'
, where
N
is the index of the feature. (default) | string scalar | character vector | cell array of character vectors
Label for an object displayed in viewer, specified as a string scalar, character vector, or
cell array of character vectors. If you specify a string scalar or character vector,
kmlwrite
applies the name to all objects. If a string vector or
cell array of character vectors, you must specify a name for each feature. That is,
the cell array must be the same length as S
or
address
. The following describes the default behavior for various
features.
Feature | Default Name |
---|---|
Address | 'Address N' where N is
the index of the feature. |
Point | 'Point N' where N is
the index of the feature. |
Multipoint | 'Multipoint N' where N is
the index of the feature. kmlwrite places the points
in the named folder and each point is named 'Point M' where M is
the index of the point. |
Line | 'Line N' where N is
the index of the feature. If the line data contains NaN values, kmlwrite places
the line segments in a folder named 'Segment M' ,
where M is the line segment number. |
Polygon | 'Polygon N' where N is
the index of the feature. If the polygon vertex list contains multiple
outer rings, kmlwrite places each ring in a folder labeled 'Part
M' , where M is the number for
that feature. |
Data Types: char
| string
| cell
Description
— Content to be displayed in the placemark description balloon
string scalar | character vector | cell array of character vectors | attribute specification
Content to be displayed in the placemark description balloon, specified as a string scalar or
character vector, cell array of character vectors, or an attribute specification.
kmlwrite
uses this data to set the values of the feature
description tags. The description appears in the description balloon associated with
the feature in Google Earth™.
If you specify a string scalar or character vector,
kmlwrite
applies the description to all objects.If you specify a string vector or cell array of character vectors, there must be one label for each feature; that is, it must be the same length as
S
oraddress
.
Description elements can be either plain text or tagged with HTML mark up. When in plain text, Google Earth applies basic 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 https://earth.google.com.
If you provide an attribute specification, the attribute fields
of S
display as a table in the description tag
of the placemark for each element of S
, in the
order in which the fields appear in the specification. To construct
an attribute spec, call makeattribspec
and
then modify the output to remove attributes or change the Format
field
for one or more attributes. The latitude
and longitude
coordinates
of S
are not considered to be attributes. If included
in an attribute spec, kmlwrite
ignores them.
Data Types: char
| string
| cell
Icon
— File name of custom icon
defined by viewer (default) | string scalar | character vector | cell array of character vectors
File name of custom icon, specified as a string scalar, character vector or cell array of character vectors.
If a string scalar or character vector,
kmlwrite
applies the value to all icons.If a string vector or cell array of character vectors, specify an icon for each feature; that is, the cell array must be the same length as
S
oraddress
.If the string scalar or character vector is an Internet URL, the URL must include the protocol type.
If the icon file name is not in the current folder, or in a folder on the MATLAB path, specify a full or relative path name.
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.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
Color
— Color of icons, lines, or the faces and edges of polygons
defined by viewer (default) | color name | RGB triplet | cell array of color names | string vector of color names | matrix of RGB triplets | 'none'
Color of icons, lines, or the faces and edges of polygons, specified as one of these values.
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 features, specify a single color name or RGB triplet.
To apply a different color to each feature, 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
S
oraddress
.To create a polygon
geoshape
with no fill or edge color, specify'none'
.To exclude a color specification for icons or lines, specify
'none'
. In this case, the viewer defines the icon or line color.
Note that Color
specifies the color of polygon faces and
edges if you do not specify FaceColor
and
EdgeColor
.
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, lines, or the faces and edges of polygons
1
(fully opaque) (default) | numeric scalar or vector in the range [0 1]
Transparency of the icons, lines, or the faces and edges of
polygons, specified as a numeric scalar or vector in the range [0
1]
. If a scalar, kmlwrite applies the value to all features.
If a vector, specify a value for each feature; that is, the vector
must be the same length as S
or address
.
If S
is a polygon geoshape, kmlwrite
applies
the value to all the polygon faces if FaceAlpha
is
not specified and the polygon edges if EdgeAlpha
is
not specified.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
LineWidth
— Width of lines and polygon edges in pixels
defined by viewer (default) | positive numeric scalar or vector
Width of lines and polygon edges in pixels, specified as a positive numeric scalar or vector.
If a scalar,
kmlwrite
applies the value to all polygon edges.If a vector, specify a value for each feature. That is, the vector must have the same length as
S
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
FaceColor
— Color of polygon faces
defined by viewer (default) | color name | RGB triplet | cell array of color names | string vector of color names | matrix of RGB triplets | 'none'
Color of polygon faces, specified as one of these values.
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 polygon faces, specify a single color name or RGB triplet.
To apply a different color to each face, 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
S
oraddress
.To create a polygon
geoshape
with no face color, specify'none'
.
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
FaceAlpha
— Transparency of polygon faces
1
(fully opaque) (default) | numeric scalar or vector in the range [0 1]
Transparency of polygon faces, specified as a numeric scalar
or vector in the range [0 1]
.
If a scalar,
kmlwrite
applies the value to all polygon faces.If a vector, specify a value for each polygon face; that is, the vector must be the same length as
S
oraddress
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
EdgeColor
— Color of polygon edges
defined by viewer (default) | color name | RGB triplet | cell array of color names | string vector of color names | matrix of RGB triplets | 'none'
Color of polygon edges, specified as one of these values.
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 the edges of all polygons, specify a single color name or RGB triplet.
To apply a different edge color for each polygon, 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
S
oraddress
.To create a polygon
geoshape
with no edge color, specify'none'
.
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
EdgeAlpha
— Transparency of the polygon edges
1
(fully opaque) (default) | numeric scalar or vector in the range [0 1]
Transparency of the polygon edges, specified as a numeric scalar or vector.
If a scalar,
kmlwrite
applies the value to all polygon edges.If a vector, y specify a value for each polygon edge; that is, the vector must be the same length as
S
. If you do not specifyEdgeAlpha
,kmlwrite
uses the value ofAlpha
, if specified. If you do not specify either value,kmlwrite
uses the default value1
(fully opaque).
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
Extrude
— Connect polygons to the ground
false
(default) | true
| logical or numeric scalar | logical or numeric vector
Connect polygon to the ground, specified as a logical or numeric
scalar, true
(1
) or false
(0
),
or vector. If a scalar, the values applies to all polygons. If a vector,
specify a value for each polygon; that is, the vector must be the
same length as S
or address
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
CutPolygons
— Cut polygon parts
true
(default) | false
Cut polygon parts, specified as a logical or numeric scalar true
(1
)
or false
(0
). If true
, kmlwrite
cuts
polygon parts at the PolygonCutMeridian
value.
If true
, and the polygon parts require cutting, kmlwrite
returns
an error if the altitude values are nonuniform.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| logical
PolygonCutMeridian
— Meridian where polygon parts are cut
180
(default) | scalar numeric
Meridian where polygon parts are cut, specified as a scalar numeric.
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. (Named 'absolute' in
the KML specification.) This is the default interpretation when you
specify altitude values. |
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, listed below, 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 object the camera is looking at, in degrees | Scalar double, from -90 to 90 |
Longitude | Longitude of the object the camera is looking at, in degrees | Scalar double, from −180 to 180 |
Altitude | Altitude of the object 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 object specified by latitude , longitude ,
and altitude to the location 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 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 | 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
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 R2007bR2021b: Write geospatial tables to KML format
The kmlwrite
function accepts geospatial tables as input.
R2016a: Syntaxes that accept numeric vectors are not recommended
Syntaxes of the kmlwrite
function that accept numeric vectors are
not recommended. Use the kmlwritepoint
function instead. To update your
code, replace instances of the kmlwrite
function with the
kmlwritepoint
function.
Not Recommended | Recommended |
---|---|
kmlwrite(filename,lat,lon) |
kmlwritepoint(filename,lat,lon) |
kmlwrite(filename,lat,lon,alt) |
kmlwritepoint(filename,lat,lon,alt) |
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)