kmlwritepolygon

Write geographic polygon to KML file

collapse all in page

Syntax

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

Description

example

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.

Examples

collapse all

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

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

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

Data Types: single | double

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

Data Types: single | double

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 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: kmlwritepolygon(filename,lat,lon,alt,'EdgeColor','g','FaceColor','c','FaceAlpha',.5)

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

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

Color of the polygon face, specified as the comma-separated pair consisting of 'FaceColor' and a MATLAB® Color Specification (ColorSpec). You can specify a character vector, scalar cell array containing a character vector, or a 1-by-3 vector of doubles with values in the range [0 1]. To create a polygon that is not filled, specify the value 'none'.

Data Types: double | char | cell

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

Color of the polygon edge, specified as the comma-separated pair consisting of 'EdgeColor' and a MATLAB Color Specification (ColorSpec). You can specify a character vector, scalar cell array containing a character vector, or a 1-by-3 vector of doubles with values between 0 and 1. To indicate that the polygon has no outline, specify the value 'none'.

Data Types: double | char | cell

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

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

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

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

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

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

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'

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'

See Also

| | |

Introduced in R2016a

Mapping Toolbox Documentation

Support