Exporting KML to Google Earth

This is a long topic because it shows every detail for beginners. An experienced Manifold user could do this topic in about five minutes.

Google users may find it odd that this tutorial is written using Microsoft Virtual Earth to provide imagery backgrounds instead of Google Earth. The substitution of Microsoft Virtual Earth images for Google Earth images was done at Google's request to ensure that the numerous images that appear in this topic when it is posted to the manifold.net website do not show what Google regards as copyrighted imagery. See the note at the end of this topic for more information.

The Tutorial

This topic shows how to open the base map project and how to zoom into a location. We then add points showing the locations of our favorite restaurants and we export the points to Google Earth. The topic assumes that the StarterPack.zip file has been downloaded and installed, that the computer has an Internet connection and that Google Earth has also been installed on the computer.

The StarterPack.zip file contains a starter .map project as well as DLLs for open source image server drivers, including a Microsoft Virtual Earth image server driver. It should be unzipped into the Manifold System installation folder (C:\Program Files\Manifold System by default). If you have not downloaded and installed the StarterPack.zip file this tutorial will not make any sense because the US Base Map.map project file it mentions will not be available to you.

The StarterPack.zip archive must be downloaded from links on the manifold.net web site or from whatever web site you prefer to get your Manifold open source modules

Note: The usage of Microsoft Virtual Earth image servers, as seen in this tutorial, requires installation of open source software written using the Manifold Image Server Interface. There are many third parties providing free image server modules for image servers like Microsoft Virtual Earth, Yahoo! Maps and others. You can even write your own! Manifold does not supply or support such third party software, but it is really, really cool to know that you can do such things with Manifold and that there is an active open source community supporting Manifold.

The StarterPack.zip archive provides open source software that was contributed to the Manifold user community. The base map was created and contributed by Manifold users as well. The amazing thing is that you don't need to know anything about Manifold internals to do such stuff, nor do you have to have more than ordinary user skills to create things like the base map.

Step 1:Open the base map project

In Windows Explorer, browse into the Manifold System installation folder (C:\Program Files\Manifold System by default) and double-click on the US Base Map.map project file.

Manifold will launch. If this is the first time you have launched Manifold, an Activation dialog will pop up. You must enter at least the Manifold System serial number that was sent to you with your license. If it is longer than 30 days from the date the serial number was issued, you must activate your license as well. See the Activation Keys and Serial Numbers topic in Help.

Manifold launches with a Project pane open on the right that lists all components in that project. There are no windows open in the workspace. The main menu appears at the top and toolbars appear just below the main menu. The illustration above has been reduced.

If we take a closer look at the project pane, we see that each component has an icon next to it depending on what it is. Drawings have a little pencil in the icon. Images have blue lines in the icon, like raster lines on a monitor. Items that linked in from some external data source, like a database or a web server have a little yellow database cylinder in the icon. Comments have a book.

All these items can participate as layers in a map. There is only one map in this project, called "Map" so that beginners don't have to guess what it is. Double click on Map to open the map.

Note: The "Local" tool tip that pops up for many items in the project pane is Manifold's way of telling you that item is stored locally, inside the project .map file. Items also can be linked into a project from elsewhere, just like the linked images from the Microsoft image servers. In that case, the data for those items is not stored inside the project file.

When the map pops open Manifold automatically pops open a default set of toolbars for use with that map and adjusts the main menu with appropriate entries. A map window can be resized and moved around in the Manifold workspace. We can pop open as many windows as we like in the workspace. If we like, we can right click on the Map item in the project pane and choose Open in New Window and Manifold will merrily pop open that same item in a second window for us. That second window can be panned and zoomed independently of the first.

It's not easy to show the entire Manifold workspace in a tutorial like this without using reduced images that are difficult to read. From here on, this tutorial will not show the entire workspace but will just show the main windows as needed in full size illustrations. Let's take a closer look at the map window that we've just opened.

There, that's better! The beautiful background image we see has been browsed automatically for us from Microsoft Virtual Earth. A hallmark of Virtual Earth is the superior, smooth, beautifully realistic quality of the image even at larger scales, as though we are actually hovering over the planet and viewing the scene in real life. The equivalent Google image, which we are not allowed to show you, appears as a patchwork mosaic of annoyingly varied tones without the sense of true reality conveyed by Virtual Earth.

A map window shows a stack of other items as layers. The layer tabs at the bottom of the map window show what layers are in the map and which layers are turned on for display. A layer tab with disabled text means that layer is not turned on for display. In the illustration above, the Drawing layer and the USA layer are turned on. The Drawing layer is empty (for now) and the USA layer just shows outlines of states in the US using green lines.

The Drawing layer tab has a white background. This is the active layer, the one in which any editing commands will take effect. Click on a layer tab to make that layer the active layer. Double-click a layer tab to turn it off or on for display.

In this example we will add a few points to the Drawing layer and then we will export the Drawing layer as a Google Earth KML file. All the other layers in the map are just there in case we want to use them as reference points or to otherwise help us draw whatever we want into the Drawing layer.

There are too many layers in this map to show all of them at once as layer tabs, so we can use the scroll buttons in the lower left of the map window to scroll through the layer tabs. There is one more layer that is turned on for display, the Virtual Earth Satellite Image layer. This layer automatically fetches an image from the Microsoft Virtual Earth servers at the required zoom and resolution.

Step 2:Open the layers pane

The layer tabs are very handy for simple maps, but when maps have very many layers it is usually easier to work with layers by opening the Layers pane.

We open the Layers pane by choosing View - Panes - Layers from the main menu.

The layers pane pops open by default underneath the project pane. It will be too small to show all the layers initially, so we can resize the pane by clicking and dragging on the boundary between the layers pane and the project pane as seen above.

The layers pane shows all the layers in whatever window has the focus (that is, the last window we clicked on) in the workspace. A checked box indicates that layer is turned on for display. We can turn layers off and on by un-checking or checking their boxes.

The map window now shows the Virtual Earth Satellite Image layer as the lowest layer, "behind" all the other layers.

Un-checking the Virtual Earth Satellite Image layer box in the layers pane will turn off that layer.

The result in the map window is the USA layer seen by itself against the default white Background layer.

Back in the layers pane, let's check the Virtual Earth Street Map Image to see what that is all about.

It appears in the map window. Note that the USA layer is still turned on. The USA layer just contains lines with "empty space" between the lines. Any layer below the USA lines will show through the empty space.

The Microsoft image servers basically have two modes of operation as a web service. They can show street maps like the Virtual Earth Street Map Image layer or they can show mosaics of satellite photos like the Virtual Earth Satellite Image layer. The starter base map contains both as layers because sometimes it is more convenient to use a satellite image as a background and some times we would prefer to use a street map image.

Step 3:Zoom into a desired location

In the layers pane, please un-check the Virtual Earth Street Map Image layer checkbox and check the Virtual Earth Satellite Image layer checkbox so that the satellite image layer is displayed. This step is not illustrated.

Let's now zoom into a region of interest. For that, we will use the Zoom Box tool.

Click on the Zoom Box tool to make it the command mode for the mouse. Until we unclick the tool, the mouse will be in Zoom Box mode when we use it in the map window.

We're going to go to Palo Alto, California, so we'll click and drag open a zoom box around the green squiggles that indicate San Francisco Bay, on the California coast. [Readers who don't know which state is California without a label should be ashamed, deeply ashamed... It's not like it's a hard state to remember, like one of those square states in the middle that all look alike! ]

Manifold zooms in for us and automatically fetches higher resolution imagery from the Virtual Earth server. Let's zoom farther into the San Francisco Bay region.

Excellent. Let's do that one more time, using the Zoom Box about where we think Palo Alto is located.

Manifold keeps loading ever more detailed imagery from the Microsoft Virtual Earth server. The problem now is that we're not sure exactly what we are looking at. There's a bridge there, but darned if we're not exactly sure where to zoom now. Now is a good time to switch to using the street map image.

In the layers pane we un-check the Virtual Earth Satellite Image layer and we check the Virtual Earth Street Map Image layer.

In the map window we can see we zoomed into a region too far northwest. We've zoomed into San Mateo and Hillsborough, and not Palo Alto. That's easy to fix.

Click on the Grabber tool to make that the command mode for the mouse.

In the map window, click in the lower right corner and then drag to the upper left and release. We are telling Manifold to grab the portion of the view from the lower right corner and move it up to the upper left part of the window. This scrolls the entire window in the desired direction.

Manifold obliges, scrolling the window as we wanted. There's Palo Alto near the center of the display.

We click back onto the Zoom Box tool and then zoom into the Palo Alto section of the map.

We keep zooming until we reach the downtown portion of Palo Alto where dozens of restaurants cater to Silicon Valley yuppies and Stanford University students and faculty. Stanford is about a half mile out of view to the lower left in the above map.

Step 4:Add a point

We are now zoomed into the map and are ready to add some points that show the locations of our favorite restaurants.

Before we continue, if you have been fooling around with the map outside of the sequence of steps in this tutorial, click on the Drawing layer tab to make sure it is the active layer. We will be adding points to the Drawing layer.

Next, a little housekeeping: We are going to turn on Instant Data mode so that when we click to add a point we can easily also add some data for that point.

We do that in the main menu by clicking Edit - Instant Data. This puts a check mark next to the Instant Data entry on the menu to let us know that Instant Data mode has been turned on. We'll see what this mode does in an instant.

To begin adding points we click the Insert Point tool in the drawing toolbar. This puts the mouse into Insert Point command mode.

Position the cursor at the corner of the intersection of University Avenue and High Street as seen above and click.

If we didn't have Instant Data mode on, a dot would have instantly appeared. If we just wanted to do something really simple and click to create points we could do that all day without using Instant Data mode. But because we're using Manifold and not some retarded "sketch" program, we want to do more than just click and create dots. We want those dots to be connected with some data, like the names of restaurants, that Google Earth can then use as a label or a description. Using Instant Data makes that especially easy to do.

With Instant Data mode turned on, a dot appears and a dialog pops open that allows us to enter data for the point. The dialog pops open with a field already opened and the text cursor in the box ready for us to enter text.

All drawings in Manifold have a table that's connected to that drawing. Every object in a Manifold drawing, that is every point, every line and every area, has a record in the drawing's table. Tables can have all kinds of data fields in them. It's a cool way of having data associated with things we see in a drawing, like points.

The drawing called "Drawing" in this project has only two fields in its table, as that is how it was created when the starter map project was made. These are called Name and Description. It takes only a second or two to add fields or otherwise change the structure of a table. For now, we'll use the table as is.

With Instant Data mode turned on Manifold immediately sets us up to add data whenever we create a new object. In this case we clicked using the Insert Point tool to create a point, so Manifold pops open the dialog to allow us to enter the data we want associated with that point.

We enter the name Miyake for this point and we enter the URL for this restaurant into the description field. Press Enter or click OK.

A new point appears using gray default color and default size. That gray color is boring, so let's change the color to bright green.

We do that by clicking on the Point Background color well..

...and choosing a nice bright green color.

The point appears in bright green. This particular point style (shown in the Point Style well that's just to the right of the Point Background color well we changed) uses foreground color for the border of the circle and background color for the fill color. If we wanted the points to be bigger we could click the Point Size well and make the size larger than the default size of 3.

There are two interesting things to note about the above illustration: first, by default the format color settings apply throughout an entire layer. When we make the Point Background color bright green, all points in that Drawing layer will be bright green. There are ways of changing this so that different points have different colors but since this is a beginner's tutorial we won't get into that.

The second interesting thing is that Google's first Palo Alto offices were about 100 feet to the lower right of that green dot in the illustration above. What is now one of the most valuable businesses in the planet started in cramped, second floor offices behind a video rental store near that green dot. Even more interesting is that the original offices of Facebook are just across High Street from the green dot. Amazing! ...Over one hundred billion dollars in wealth created on either side of a small sushi restaurant in Palo Alto.

Step 5:Add another point

Let's add some more restaurants.

The mouse is still in Insert Point command mode, so we will click on the corner of Emerson Street and University Avenue.

Instant Data mode is still on, so the dialog pops open again. Instant Data repeats the last data entered and positions the cursor within the last entered box ready to go. This is a big help with repetitive data entry. For example, if a city employee were marking the locations of different types of city assets and marking all hydrants, it is a real time saver to not have to manually type "hydrant" thousands of times.

In this case, we're marking the location of a sushi restaurant that does not have a web site so we'll just enter Japanese as the description...

...and then enter the name of the restaurant in the Name field. Press Enter or OK.

Manifold creates a new point at the location clicked. Note that since formatting works by default for all objects in a drawing, all the points in this drawing layer will be green, use the same style and be the default point size of 3.

We can continue to add as many points as we like. The above procedure is very fast, so it's easy to add points. It's also easy to add URLs. We like to keep an Internet Explorer browser session open so that we can find the URLs for those restaurants that have a web page. We can then Copy the URL from the browser window with a CTRL-C and then switch into Manifold and Paste the URL into the Description box with a CTRL-V. Fast and easy!

Step 6:Correcting errors

Suppose we get a little too excited about all this and click to create a point in the wrong spot? There are two ways of dealing with this.

Consider the point shown above with a red arrow. We accidentally added it in the wrong location. The first way to remedy the error is to select the point and delete it and then create a new point in the correct location.

Choose the Select Box tool.

Click and drag to make a selection box around the point. The Select Box tool selects all objects that are entirely within the box.

The point is shown using red selection color for foreground color to show it is selected.

If we choose Edit - Delete in the main menu or press the Delete key the point is deleted. For that matter, we could also have chosen Edit - Cut or CTRL-X to use Windows Cut to delete the point and simultaneously copy it to the Windows Clipboard (Yes, Manifold can copy objects into the windows Clipboard . These can then be pasted as new drawings or pasted into other drawings.)

Suppose, however, that we've entered some really long text into the Description box and we don't want to re-enter it. In that case, instead of deleting the point we can just move it to the desired location.

To do that, we first make sure the mouse is not in any command mode. For example, if we have the Insert Points toolbar button pushed in, we first click it out. When the mouse isn't busy with some command mode it can be used for smart editing in Manifold, that is, a streamlined, simple, default editing regime.

CTRL-ALT click on the point to be moved. That is, while holding down the CTRL key and the ALT key, click on the point.

This selects the point for editing, and a square box editing handle appears at the point's location. The editing handle can be clicked and dragged, moving the object as well.

We can click and drag the point to the desired location.

After we release to move the point to a new location, it still stays selected for editing in case we want to do anything else with it.

Deselect it by clicking the Select None button. (There are many other shortcuts which we will not get into here).

The point appears in its new location at the corner of Ramona Street and Hamilton Avenue. Many Google employees will immediately recognize this as the location of the Osteria restaurant, a great spot for osso buco with a nice Chianti classico.

Step 7:Preview our work before export

So far we've added points using Virtual Earth street map imagery as a background. That's very cool and useful but it is not the satellite imagery used by default in either Virtual Earth or Google Earth.

If we show the entire map window again, we can see that several additional restaurant locations have been added. Each one also has had a name and description provided. Let's see how these points appear with a satellite image background.

In the layers pane we uncheck the street map image layer and check the satellite image layer.

OK, that's very cool. The green dots are harder to see with all that photographic imagery clutter (easy to fix, see below) but the screenshot above shows us how Manifold can preview what will appear in Google Earth by using satellite imagery from image servers, in this case using imagery from Microsoft.

This is also a chance for us to move points around using the photograph as a visual reference instead of the street map image. If a point appears, say, in a parking lot just next to a restaurant instead of on the building itself we could move it using the procedure given above.

This is one reason why it is so valuable to prepare KML files in Manifold, because you can see where the data is going to appear using either street map imagery or overhead aerial photos like the one seen above.

Now would be a good time to save the project using File - Save to some safe location.

We right-click on the Drawing in the project pane and in the menu that pops up...

...we choose Export.

In the Export Drawing dialog that pops open we choose KML / KMZ Files in the Save as type box and we provide a file name. If the file name we provide ends in .kmz Manifold will create a KMZ file. If the file name ends in .kml Manifold will create a KML file. The two are the same thing except that KMZ is a compressed form of KML using "zip" style compression.

For this example, we create a KMZ file using the name sample restaurants.kmz. Press Save.

The Export KML File dialog pops open to allow us to choose which fields we want to use for Google Earth Name and Description fields.

The pull down boxes for the Name and Description fields show all the fields available in the drawing's table, including all sorts of weird internal fields that are used by Manifold experts. We ignore all those and simply choose the Name and Description fields we have used to store restaurant names and descriptions. The Drawing layer in the starter project uses these two names for the fields it contains to make life easier for beginners. Press OK.

If we pop out of Manifold and take a look with Windows Explorer, we seen that Manifold has created a new file for us called sample restaurants.kmz. We can double-click this file to launch it in Google Earth.

Google Earth will fire up, do the "zoom in from space" thing and, Voila! There are our points. Note that Google Earth by default will take the contents of the Name field and use it to label each point. Note also that the imagery used by Google Earth is indeed just like the satellite imagery the image servers streamed into Manifold as the background for our map.

The Google Earth Places pane shows both the Name and the Description values for each point. We obviously didn't have a lot of URLs for the restaurants of interest. What's cool about this Places pane is that if you do have a URL as the description, clicking on that URL in the Places pane will launch it in a mini-browser in Google Earth.

There are many ways of using URLs. For example, suppose we snapped pictures of each restaurant and then uploaded them to a public photo viewing site. For each restaurant we could put the URL to the photo in our drawing's Description field and then it would have been uploaded to Google Earth so that people could click to see what the restaurant looks like. This would be especially useful if our business was real estate sales and we were marking locations of houses for sale as opposed to our favorite restaurants.

Step 9:Useful Manifold Features

There are thousands of Manifold features useful in various situations. Here are a handful out of those thousands.

Opacity: Suppose we don't like the visual clutter of the photographic image in our map but we still want to have it available as a visual guide in the background. That's easy to do by adjusting the opacity of that image layer.

In the layers pane we click the Opacity button to turn on the Opacity column in the pane. This shows the opacity (that is degree of transparency) for each layer. We double-click into the Opacity cell for the Virtual Earth Satellite Image layer and change it to 40%.

The result is that the layer fades out as part of the white background layer shows through. This makes it easier to see the points.

Labels: Suppose we have trouble remembering which green dot is which restaurant and we would like to add labels in the Manifold map, one for each point that gives the Name. That's easy also:

We right-click on the Drawing component in the project pane and we choose Create.

In the Create menu that pops up we choose Labels to create labels.

In the Create Labels dialog that pops up we choose a name for the new Labels layer we are creating.

To create the text automatically for each label, we double-click on the Name field in the Columns pane. That adds it to the Text box to be used as the text for each label. Press OK.

This creates a new labels component, called MyLabels just as we wanted, in the project pane. It is shown indented under the Drawing drawing because it is created automatically using the data in that drawing's table. To add this layer to the map we drag and drop it into the map.

First, we click on the Drawing layer tab in the map to make it the active layer. Now, when we drag and drop the MyLabels layer from the project pane into the map it will appear just above the Drawing layer.

Using the mouse, click on the MyLabels item in the project pane and then drag the mouse cursor over into the map window and release.

The MyLabels layers pane appears in the map window as a new layer and the labels appear using default formatting, positioning and font. It's a big uglier than we would like.

For starters, we would like to change positioning so that instead of being on top of each point the labels are below and to the left. This is easy to do.

When a labels layer is the active layer in a map, Manifold configures the toolbars with controls for labels. We can change the alignment settings (seen above) from centered to appearing to the left and below.

That's better. However, it would be cool if we could adjust the formatting of the labels so that they use black text with a bit of white outline color for better legibility.

To do that we click on the Label Style well in the formatting toolbar.

We choose a style with a bit of background color.

We then click into the Label Background color well...

...and we change the background color to white.

The result is a subtle change but highly useful when labels are to appear before a background that varies in color from light to dark. Note that these label changes appear within the Manifold project. Google Earth uses its own fonts, so these changes are not exported into Google Earth. But they are nonetheless highly useful because if we want to manipulate sophisticated data within Manifold we will often want to use labels in sophisticated ways to help keep our bearings.

Changing Data for Descriptions: Suppose we would like to update the data for each point, say, by changing the description? That's easy to do by editing the drawing's table.

Double-click the drawing's table to open it in a table window.

There's the data we entered for each point. We can change a value by double-clicking into the cell.

Here we've changed the name of Pizza My Heart to Pizza A Go Go, the name under which they do business for deliveries. We've also changed the Description for that record to include a totally off the wall and useless reference to the manifold.net home page.

The changes take immediate effect in the Manifold project. For example, the label for that restaurant (which automatically uses text from the Name field) instantly changes to show the new name. Note, by the way, that Manifold by default will "clip" labels that get in the way of each other. This can be turned off if desired.

If we export the drawing to a kmz file and open that file in Google Earth, we see that the new name is now used for a label in Google Earth. Google Earth doesn't like to clip labels, and will try to move them around to show as many as it can no matter what.

In the above case, Google Earth tries too hard to show all labels because it has moved the Sushi Tomo label to the right and the Pizza A Go Go label to the left when in reality the two points are on opposite sides of the street the other way around.

If we zoom farther into Google Earth so there is more room for labels then Google Earth will show the labels in correct position nearer to the actual points they label.

The description in Google Earth's Places pane has also changed. Note that Google Earth is smart enough to know a URL when it sees one, so we can embed URLs within other description text and still be able to launch the URL with a click.

Notes

Why Palo Alto in the example? That's where Stanford University is located and where Google was founded. The restaurants mentioned are all places our friends at Google know. It's also amusing that the surprisingly muscular new CloudMade startup which is challenging Google Maps by leveraging the community intelligence of the OpenStreetMaps project is right next door, in Menlo Park.

Isn't there a faster way of finding a place in Manifold than using Zoom Box? Sure. If you have the Geocoding Tools extension installed you can GoTo an address, city name, ZIP code, etc. Even without the Geocoding Tools extension you could select a city name using the selection toolbar and then jump to that selection. There are often very many ways of doing something in Manifold so that an experienced user can always pick a method that is just right for the job.

It's fun to export points, lines and areas and to extrude them into 3D shapes. Extruding areas is a great way to make simple "buildings" that will appear in 3D when Google Earth is viewed with an inclined view. See the Export Drawing - KML, KMZ topic for an illustration.

Legal Note

This topic originally used Google Earth imagery because our writers felt that people interested in exporting KML to Google Earth would probably feel most comfortable with Google Earth imagery as the background layers used to create such KML. Makes sense, right?

However, Google lawyers (much to the horror of some of our technical Google friends) contacted manifold.net to complain that Google Earth imagery was being shown on the Manifold web site, including within this topic in the web version of Help. Google complained such images showed no Google watermarks or copyrights. Google commended our support for KML but objected to illustrations showing Google imagery. Bizarre, but true.

Because this user manual automatically gets published to the web, the only way to assure that Google imagery does not get published is not to use Google imagery in the screenshots. We have therefore replaced the background imagery from Google Earth in this topic with imagery from Microsoft Virtual Earth. It is a crazy world when Google lawyers convince software developers to feature Microsoft products instead of Google products, but that's the way it is.

As it turns out, Microsoft Virtual Earth actually works better in such applications than Google Earth, so using Virtual Earth in this topic makes most images look better.

Microsoft Virtual Earth imagery is very similar to that produced by Google Earth with several notable improvements: Microsoft Virtual Earth imagery has no "throttles" in it like Google to prevent active usage, it is not artificially disfigured with watermarks, it provides a far smoother and more realistic appearance in larger scales and in many cases it is more detailed than Google imagery. These are such significant benefits that most Manifold users have switched to using Virtual Earth for KML authoring even if the ultimate target of their authoring efforts is Google Earth.

Microsoft Virtual Earth is also very convenient because it is widely available within other geographic browsers besides Google Earth. For example, a plug in for NASA World Wind allows use of Virtual Earth in World Wind. Since KML/KMZ format is now used in very many applications besides Google Earth, it could be that a consequence of Google's bizarre lawyering is that Microsoft's Virtual Earth ends up being the de facto standard for image registration for KML files in all applications, even Google's.

In any event don't let the antics of lawyers distract you from having fun creating KML files for export to Google Earth and other applications. Whatever source you choose to use as background layers when authoring KML, it's easy to create dramatic and useful KML files with Manifold as this tutorial shows.