kmlwritepolygon

Write geographic polygon to KML file

Syntax

kmlwritepolygon(filename,latitude,longitude)

kmlwritepolygon(filename,latitude,longitude,altitude)

kmlwritepolygon(___,Name,Value)

Description

kmlwritepolygon(filename,latitude,longitude) writes the geographic latitude and longitude data that define polygon vertices to the file specified by filename in Keyhole Markup Language (KML) format. kmlwritepolygon creates a KML Placemark element for each polygon. By default, kmlwritepolygon sets the altitude value associated with the vertices to 0 and sets the altitude interpretation to 'clampToGround'.

kmlwritepolygon(filename,latitude,longitude,altitude) writes the polygon data to a KML file, including altitude values for each vertex. altitude can be a scalar value, in which case kmlwritepolygon uses it as the value for every vertex. If altitude is a vector, you must specify a value for every vertex; that is, altitude must be the same length as latitude and longitude. By default, when you specify altitude values, kmlwritepolygon sets the altitude interpretation to'relativeToSeaLevel'.

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

Examples

Write Coastlines to KML File as Polygon

Load latitude and longitude data that defines the coastlines of the continents.

load coastlines

Specify the name of output KML file that you want to create.

filename = 'coastlines.kml';

Write the coastline data to the file as a polygon.

kmlwritepolygon(filename,coastlat,coastlon)

Create Polygon with Inner Ring

Define the latitude and longitude coordinates of the center of the rings. For this example, the coordinates specify the Eiffel Tower.

lat0 = 48.858288;
lon0 = 2.294548;

Define the inner radius and the outer radius of two small circles. The examples calls poly2ccw to change the direction of the vertex order of the second circle to counter-clockwise. This change of direction is needed to define the space between the two circles as a ring-shaped polygon.

outerRadius = .02;
innerRadius = .01;
[lat1,lon1] = scircle1(lat0,lon0,outerRadius);
[lat2,lon2] = scircle1(lat0,lon0,innerRadius);
[lon2,lat2] = poly2ccw(lon2,lat2);
lat = [lat1; NaN; lat2];
lon = [lon1; NaN; lon2];
alt = 500;

Specify name of output KML file and write the data to the file.

filename = 'EiffelTower.kml';
kmlwritepolygon(filename,lat,lon,alt, ...
      'EdgeColor','g','FaceColor','c','FaceAlpha',.5)

Create Polygon That Spans the 180 Degree Meridian

Specify latitude and longitude coordinates that define the vertices of the polygon. For this example, specify longitude values that span the 180 degree meridian.

lat = [0 1 1 0 0];
lon = [179.5 179.5 -179.5 -179.5 179.5];
h = 5000;
alt = ones(1,length(lat)) * h;
filename = 'cross180.kml';
kmlwritepolygon(filename,lat,lon,alt,'EdgeColor','r','FaceColor','w')

By default, the polygon contains a seam at the 180 degree mark. To remove this seam, set PolygonCutMeridian to 0.

filename = 'noseam.kml';
kmlwritepolygon(filename,lat,lon,alt,'EdgeColor','r', ...
       'FaceColor','w','PolygonCutMeridian',0);

To display a ramp without a seam, wrap the longitude values to the range [0 360], and set CutPolygon to false. Use the Extrude parameter to connect the polygon to the ground for better visibility.

filename = 'ramp.kml';
lon360 = wrapTo360(lon);
altramp = [0 0 h h 0];
kmlwritepolygon(filename,lat,lon360,altramp,'EdgeColor','r', ...
       'FaceColor','w','CutPolygons',false,'Extrude',true);

Input Arguments

filename — Name of output file

string scalar | character vector

Name of output file, specified as a string scalar or character vector. kmlwritepolygon 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 polygon vertices

vector in the range [-90 90]

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

Data Types: single | double

longitude — Longitude of polygon vertices

vector in the range [-180, 180]

Longitude of polygon vertices, specified as a vector in the range [-180, 180].

Data Types: single | double

altitude — Altitude of polygon vertices

0 (default) | scalar or vector

Altitude of polygon vertices, specified as a scalar or vector. Unit of measure is meters.

• If a scalar, kmlwritepolygon applies the value to each point.

• If a vector, you must specify an altitude value for each vertex. That is, the vector altitude must be 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: kmlwritepolygon(filename,lat,lon,alt,'EdgeColor','g','FaceColor','c','FaceAlpha',.5)

Name — Label displayed in the viewer for the polygon

'Polygon 1' (default) | string scalar | character vector

Label displayed in the viewer for the polygon, specified as the comma-separated pair consisting of 'Name' and a string scalar or character vector. If the vertex list contains multiple outer rings, kmlwritepolygon creates a folder with the value of Name and each outer ring labeled 'Part N' where N varies from 1 to the number of outer rings.

Data Types: char | string

Description — Content to be displayed in the polygon description balloon

character vector | string scalar

Content to be displayed in the polygon description balloon, specified as the comma-separated pair consisting of 'Description' and a string scalar or character vector. The content appears in the description balloon when you click either the feature name in the Google Earth Places panel or the polygon in the viewer window.

Description elements can be either plain text or HTML markup. 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, see https://earth.google.com.

Data Types: char | string

FaceColor — Color of polygon face

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

Color of the polygon face, specified as the comma-separated pair of 'FaceColor' and one of these options.

• A color name — A color name such as 'red' or a short name such as 'r'.

• An RGB triplet — 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].

• 'none' — No fill color.

If you do not specify a face color, then the kmlwritepolygon 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

FaceAlpha — Transparency of the polygon face

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

Transparency of the polygon face, specified as the comma-separated pair consisting of 'FaceAlpha' and a numeric scalar in the range [0 1]. The default value, 1, indicates that the face is fully opaque.

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

EdgeColor — Color of polygon edges

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

Color of polygon edges, specified as the comma-separated pair of 'EdgeColor' and 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].

• 'none' — No edge color.

If you do not specify an edge color, then the kmlwritepolygon 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

EdgeAlpha — Transparency of polygon edges

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

Transparency of polygon edge, specified as the comma-separated pair consisting of 'EdgeAlpha' and a numeric scalar in the range [0 1]. The default value, 1, indicates that the edge is fully opaque.

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

LineWidth — Width of the polygon edge in pixels

determined by viewer (default)

Width of the polygon edge in pixels, specified as the comma-separated pair consisting of 'LineWidth' and a positive numeric scalar.

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

Extrude — Connect polygon to the ground

false (default) | true

Connect polygon to the ground, specified as the comma-separated pair consisting of 'Extrude' and a logical scalar or numeric value true (1) or false (0).

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 the comma-separated pair consisting of 'CutPolygons' and a logical scalar or numeric value true (1) or false (0). If true, kmlwritepolygon cuts polygons at the meridian specified by PolygonCutMeridian. kmlwritepolygon returns an error if you set this to true, the polygon parts require cutting, and the altitude values are nonuniform.

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

PolygonCutMeridian — Meridian where polygon parts are cut

180 (default) | scalar numeric

Meridian where polygon parts are cut, specified as the comma-separated pair consisting of 'PolygonCutMeridian' and a scalar numeric value.

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

AltitudeMode — Interpretation of altitude values

'clampToGround' | 'relativeToGround' | 'relativeToSeaLevel'

Interpretation of altitude values, specified as the comma-separated pair consisting of 'AltitudeMode' and any of the following values:

Value	Meaning
'clampToGround'	Ignore the altitude values and set the feature on the ground. This value 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 value is the default interpretation when you specify altitude values. In KML terminology, this interpretation is called 'absolute'.

Data Types: char

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

geopoint vector

Position of virtual camera (eye) relative to object being viewed, specified as the comma-separated pair consisting of 'PLookAt' and a geopoint vector. The LookAt parameter defines the virtual camera that views the polygon. The fields of the geopoint vector define the view, outlined in the table below. LookAt can only look down at a feature. To tilt the virtual camera to look above the horizon into the sky, use the Camera parameter.

Field	Meaning	Value
'Latitude'	Latitude of the point the camera is looking at, in degrees	Scalar double
'Longitude'	Longitude of the point the camera is looking at, in degrees	Scalar double
'Altitude'	Altitude of the point the camera is looking at, in meters (optional)	Scalar numeric default: 0
'Heading'	Camera direction (azimuth), in degrees (optional)	Scalar numeric [0 360] default 0
'Tilt'	Angle between the direction of the LookAt position and the normal to the surface of the Earth (optional)	Scalar numeric [0 90] default: 0
'Range'	Distance in meters from the point to the LookAt position	Scalar numeric
'AlititudeMode'	Specifies how the altitude is interpreted for the LookAt point (optional)	'relativeToSeaLevel', 'clampToGround', (default), 'relativeToGround'

Camera — Position and viewing direction of the virtual camera relative to the Earth's surface

geopoint vector

Position and viewing direction of the camera relative to the Earth's surface, specified as the comma-separated pair consisting of 'Camera' and a geopoint vector. The vector contains the following fields. The camera value 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. Most importantly, you can tilt the camera view to look above the horizon into the sky.

Field	Meaning	Value
'Latitude'	Latitude of the eye point (virtual camera), specified in degrees	Scalar double
'Longitude'	Longitude of the eye point (virtual camera), specified in degrees	Scalar double
'Altitude'	Distance of the camera from the Earth's surface, specified in meters	Scalar numeric default: 0
'Heading'	Camera direction (azimuth) in degrees (Optional)	Scalar numeric [0 360] default 0
'Tilt'	Camera rotation around the X axis, specified in degrees (Optional)	Scalar numeric [0 180] default: 0
'Roll'	Camera rotation around the Z axis, specified in degrees (Optional)	Scalar numeric, default: 0
'AlititudeMode'	Specifies how kmlwritepolygon interprets camera altitude values. (Optional)	'relativeToSeaLevel', 'clampToGround', (default), 'relativeToGround'

Version History

Introduced in R2016a