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

example

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

example

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

example

Examples

collapse all

Write Coastlines to KML File as Polygon

Open Live Script

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

Open Live Script

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

Open Live Script

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

collapse all

`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
`"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.

`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
`"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.

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

`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).

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

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

`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

kmlwritepolygon

Syntax

Description

Examples

Write Coastlines to KML File as Polygon

Create Polygon with Inner Ring

Create Polygon That Spans the 180 Degree Meridian

Input Arguments

`filename` — Name of output file
string scalar | character vector

`latitude` — Latitudes of polygon vertices
vector in the range `[-90 90]`

`longitude` — Longitude of polygon vertices
vector in the range `[-180, 180]`

`altitude` — Altitude of polygon vertices
0 (default) | scalar or vector

Name-Value Arguments

`Name` — Label displayed in the viewer for the polygon
`'Polygon 1'` (default) | string scalar | character vector

`Description` — Content to be displayed in the polygon description balloon
character vector | string scalar

`FaceColor` — Color of polygon face
defined by viewer (default) | color name | RGB triplet | `'none'`

`FaceAlpha` — Transparency of the polygon face
`1` (default) | numeric scalar in the range `[0 1]`

`EdgeColor` — Color of polygon edges
defined by viewer (default) | color name | RGB triplet | `'none'`

`EdgeAlpha` — Transparency of polygon edges
1 (default) | numeric scalar in the range `[0 1]`

`LineWidth` — Width of the polygon edge in pixels
determined by viewer (default)

`Extrude` — Connect polygon to the ground
`false` (default) | `true`

`CutPolygons` — Cut polygon parts
`true` (default) | `false`

`PolygonCutMeridian` — Meridian where polygon parts are cut
`180` (default) | scalar numeric

`AltitudeMode` — Interpretation of altitude values
`'clampToGround'` | `'relativeToGround'` | `'relativeToSeaLevel'`

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

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

Version History

See Also

Topics

kmlwritepolygon

Syntax

Description

Examples

Write Coastlines to KML File as Polygon

Create Polygon with Inner Ring

Create Polygon That Spans the 180 Degree Meridian

Input Arguments

filename — Name of output file string scalar | character vector

latitude — Latitudes of polygon vertices vector in the range [-90 90]

longitude — Longitude of polygon vertices vector in the range [-180, 180]

altitude — Altitude of polygon vertices 0 (default) | scalar or vector

Name-Value Arguments

Name — Label displayed in the viewer for the polygon 'Polygon 1' (default) | string scalar | character vector

Description — Content to be displayed in the polygon description balloon character vector | string scalar

FaceColor — Color of polygon face defined by viewer (default) | color name | RGB triplet | 'none'

FaceAlpha — Transparency of the polygon face 1 (default) | numeric scalar in the range [0 1]

EdgeColor — Color of polygon edges defined by viewer (default) | color name | RGB triplet | 'none'

EdgeAlpha — Transparency of polygon edges 1 (default) | numeric scalar in the range [0 1]

LineWidth — Width of the polygon edge in pixels determined by viewer (default)

Extrude — Connect polygon to the ground false (default) | true

CutPolygons — Cut polygon parts true (default) | false

PolygonCutMeridian — Meridian where polygon parts are cut 180 (default) | scalar numeric

AltitudeMode — Interpretation of altitude values 'clampToGround' | 'relativeToGround' | 'relativeToSeaLevel'

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

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

Version History

See Also

Topics

`filename` — Name of output file
string scalar | character vector

`latitude` — Latitudes of polygon vertices
vector in the range `[-90 90]`

`longitude` — Longitude of polygon vertices
vector in the range `[-180, 180]`

`altitude` — Altitude of polygon vertices
0 (default) | scalar or vector

`Name` — Label displayed in the viewer for the polygon
`'Polygon 1'` (default) | string scalar | character vector

`Description` — Content to be displayed in the polygon description balloon
character vector | string scalar

`FaceColor` — Color of polygon face
defined by viewer (default) | color name | RGB triplet | `'none'`

`FaceAlpha` — Transparency of the polygon face
`1` (default) | numeric scalar in the range `[0 1]`

`EdgeColor` — Color of polygon edges
defined by viewer (default) | color name | RGB triplet | `'none'`

`EdgeAlpha` — Transparency of polygon edges
1 (default) | numeric scalar in the range `[0 1]`

`LineWidth` — Width of the polygon edge in pixels
determined by viewer (default)

`Extrude` — Connect polygon to the ground
`false` (default) | `true`

`CutPolygons` — Cut polygon parts
`true` (default) | `false`

`PolygonCutMeridian` — Meridian where polygon parts are cut
`180` (default) | scalar numeric

`AltitudeMode` — Interpretation of altitude values
`'clampToGround'` | `'relativeToGround'` | `'relativeToSeaLevel'`

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

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