Beginners Guide
Introduction
This project started because of a need to generate KML/KMZ documents from a C#.NET
application. In my initial searches I was unable to find a suitable native
.NET class that would help to produce these documents. Sure, you can use the
COM objects that come with the Google Earth application, but who likes working with
COM in the .NET environment? Luckily Google does provide a pretty good documentation
of their API here, so I started creating
my own classes.
Using this API, I have started to construct .NET
classes that will generate a properly formatted KML document that the Google
Earth and Google Maps* application can understand. The purpose
of these objects are to help the developer to easily construct their desired KML
document heierarchy. These objects will not help the developer decide what
heierarchy is best for their application. Unfortunately you'll will still
need to know how to structure your KML.
Getting Started
The most important class you'll need to use every time, is the geKML class.
This class will be the one responsible for writing the proper KML header information,
and it will also kick off the generation of the rest of the KML objects.
To instantiate the geKML object, you will first need to decide what your "root"
KML object will be. It can be any object that Google Earth will recognize
as a root object. Popular choices are the Feature classes (NetworkLink, Placemark,
ScreenOverlay, GroundOverlay, Folder, Document). For simplicity sake, I recommend
starting with the geDocument or geFolder object.
Since most of the Google Earth classes are optional, you'll have to instantiate
most of these objects as you want to use them and then add them to any properties
or collections.
Once you have added all of the objects into your geKML.kmlRoot property, you will
want to call the geKML.ToKML() method which will return a properly formatted KML
byte array, which you can then save to a file or stream from a web server.
Below is a simple example of a basic document (root) and a placemark that exists
within that document. For simplicity sake this example uses hard coded values
for properties, but in practice you will probably use values from some dynamic data
source.
Example 1: Basic Document with a Placemark
using System;
using System.Collections.Generic;
using System.Text;
using System.IO;
using Google.KML;
namespace Examples
{
public static class Example1
{
public static
void
RunExample(string FileName)
{
// Use a Document as the root of the KML
geDocument
doc = new geDocument();
doc.Name = "My Root Document";
//Create a Placemark
to put in the document
//This placemark is going to be a point
//but it could be anything
in the Geometry class
gePlacemark
pm = new gePlacemark();
//Create some coordinates
for the point at which
//this placemark will sit. (Lat / Lon)
geCoordinates
coords
= new geCoordinates(
new geAngle90(37.422067),
new geAngle180(-122.084437));
//Create a point
with these new coordinates
gePoint
point = new gePoint(coords);
//Assign
the point to the Geometry property of the
//placemark.
pm.Geometry = point;
//Now
lets add some other properties to our placemark
pm.Name = "My Placemark";
pm.Snippet
= "This is where I put my Placemark";
pm.Description = "I wonder where this is...";
//Finally, add the placemark to the document
doc.Features.Add(pm);
//Now that we
have our document, lets create our KML
geKML
kml = new geKML(doc);
//And our results...
File.WriteAllBytes(FileName,
kml.ToKML());
}
}
}
Obviously this is a very hard coded and over simplified example, but it demonstrates
the basic flow of how these classes are to be used. More advanced examples
will be provided soon.
Conclusion
This should get you stared with using the ge-kml classes, if you have any questions
or have found any bugs, please submit them in the appropriate place on
SourceForge.Net
* Google Maps currently only supports certain parts of the KML API.
For more details click here.