KML is a standard XML file, where the schema defines GE objects. You've seen several important node types that define placemarks, points, lines, and polygons. Collectively, you can call them "GeoObject" nodes. The KML schema defines some other nodes that help organize and display the GeoObject nodes, such as the <Folder>
node and style-related nodes.
At the root of a KML document, you can define a folder, a GeoObject, or a style object. <Folder>
nodes can contain other <Folder>
nodes, GeoObject nodes, and so on, letting you create a hierarchy.
When you create a KML file, you'll use folders to arrange GeoObjects. You define folders with a set of child nodes that control how GE will render the folder. Here's an example:
A folder is a container that can hold multiple other objects
<name>Folder object 1 (Point)</name>
<name>Folder object 2 (Polygon)</name>
<name>Folder object 3 (Line)</name>
The simple <Folder>
node above has a name and a description that will be visible to the user in the GE object tree—the sidebar panel that appears on the left side of the GE interface. The <open>
node defines the default status of the folder when the KML is loaded; folders can initially appear either open (1
) or closed (0
). This folder contains several placemarks, but remember, folders can contain other folders as well. You can create any folder hierarchy you need. For example:
Creating KML Files Programmatically
This is a main folder and can contain points,
lines, polygons or other folders
<description>This is a subfolder that is closed by default,
and can contain points, lines, polygons or other
The simplest way to create an XML file with .NET is to use the XmlWriter object. XmlWriter provides methods that help you write well-formed XML documents easily and efficiently. You can output the created XML to a standard file or stream it on the web.
This next example uses a MemoryStream to write XML to memory (see Listing 1
). ASP.NET can direct the XML stream XML to an OutputStream. This sample will create a valid KML file that will contain a point placemark. Coordinates are received as input parameters, and XML is returned as string output parameter.
Most of the code in Listing 1
is quite easy to understand, but here are the important points:
object controls how the ToString()
function formats the latitude, longitude, and altitude values. The code ensures that the decimal separator is a period and that the NumberGroupSeparator is a null string, conforming to KML specifications.
After creating the KML, the code rewinds the MemoryStream (memStream.Seek(0, IO.SeekOrigin.Begin
), sets an encoding, and then reads the entire stream as the return value—in other words, the function returns a text string containing the created KML document. You could also return the MemoryStream itself or work with an ASP.NET OutputStream to write the KML directly to a browser.
The attached code contains a simple working program that uses the GetKML
function in Listing 1
to create a KML document and display that to users. By extending the methods shown in this sample you can create any KML file you need, adding code to insert Folders, Lines, or other valid node types to the stream.
As you've seen, it's easy to create KML files programmatically, but you can improve on that model by creating a class that "maps" a KML file in an object-oriented manner. That way you can work with typed data and with a reusable resource library without worrying about the details of the KML format and without having to rewrite similar code to produce other KML documents. A KML wrapper class would expose methods and properties such as:
Public Function ToKml() as String
Public Property Title() As String
Public Property Folders() As FoldersCollection
You could define other classes that map the KML basic structures such as Point, Line, Shape, and Coordinate classes as well as Style and Folder classes.
GE and KML Files
GE can open KML files from your hard disk or download them from the web, so you can publish your data on your web site or from your web application. To publish simple static data that doesn't require user interaction, all you need to do is create the KML files and make them available. People can download the files and load them into GE through the File → Open menu. If you output a content-type
metatag that specifies "application/vnd.google-earth.kml+xml
," the user's browser will open it with GE, without any user interaction.
|Author's Note: from a web browser's point of view, GE is a standard external plug-in, meaning that if GE hasn't been installed on that machine, the browser will not show any content for downloaded KML documents, because it won't know which helper application handles the KML format.