KML, KMZ Google

KML is an XML-based format with a three-letter file name extension of .kml originally used for annotations in Google Earth displays.  KMZ is exactly the same format compressed using "zip" compression with a three-letter file name extension of .kmz.    Manifold automatically decompresses KMZ to get the resulting KML.   In this documentation we use KML as a term to mean either KML or KMZ.   KML can be used for points, lines or areas with typically two text attributes, a Name field and a Description field, per object.

New Data Source Dialog

A quick way to import a .kml file into a project is to use File - Import.   For better control over the resulting import, most Manifold users will import a .kml using File - Create - New Data Source, since the  New Data Source dialog provides a Merge layers option.


.kml drawings will often include "folders," that is, layers.  Each layer will be imported into Manifold as a separate drawing so that they can appear within a map as layers. A map component containing all the layers will also be created.   Some .kml files may contain a bewildering number of layers that are best organized within a single drawing.   Checking the Merge layers option box in the New Data Source dialog will create a single drawing that contains all such layers


To import from kml format:


  1. Choose File - Create - New Data Source from the main menu.

  2. In the dropdown menu, choose More... to launch the New Data Source dialog.

  3. Choose File: kml as the Type.

  4. In the Source box, use the [...] browse button to find and to open the .kml file desired.

  5. Check the Merge layers box if desired (almost always).

  6. Press Create Data Source

  7. Expand the new data source hierarchy, highlight the linked components within, and choose Copy.

  8. Click into a blank part of the project outside of the data source hierarchy and choose Paste.


New Data Source Dialog and Controls

In the main menu, choose File - Create - New Data Source.   The dropdown menu provides a list of favorites to choose from as well as a More... option.  



Choose More... to launch the New Data Source dialog.   Choose File: kml in the Type box.




Name for the new data source, "Data Source" by default.  Specify a more  memorable name as desired.


Choose File: kml to connect to a .kml or a .kmz file.


The path to the .kml file.  Use the [...] browse button to navigate to, and to open the desired .kml file.

[...] Browse button

Click to populate the Source box.  Browse the Windows file system to locate and open the desired file using a Select File dialog modeled on the standard Windows File - Open dialog.  The type of file will be pre-loaded into the dialog depending on what was selected in the Type box

Open as read-only

Open the data source read-only.  Not checked by default so that if we want to open a .kml file read/write we can do so.   .kml format will lock out other users if we connect to a .kml file read/write.  Therefore, if we would like to allow other users to be able to simultaneously connect to this same .kml file and we do not need to write to it, we can check this box.  We can also check the read-only box if we would like to protect against accidental changes to the  .kml file

Cache data

Create and utilize an accessory .MAPCACHE file for improved performance. Checked by default.

Save cached data between sessions

Save the cached data for the next time this project is opened, either within the .MAPCACHE file or within the .map project itself within a Cache subfolder within the System Data hierarchy.  Not checked, and not recommended for .kml.

Cache only data that is expensive to compute dynamically

If there is significant overhead in computing data to be displayed, cache the results.  Uncheck this option.

Merge layers

Bring data from all folders within the .kml into a single drawing and table. Add a field for each record in the table giving the name of the original folder.   Most Manifold users will check this option, since it is usually easier to manipulate data within a single drawing in tasks such as styling the data than it is to work with a large number of layers (the usual case with .kml files).

Create Data Source

Create the new data source in the project pane and close the dialog.

Edit Query

Launch the Command Window loaded with a query that creates the data source using the given settings.  A great way to learn how to use SQL to create data sources.


 Exit the dialog without doing anything.


KML files can contain GroundOverlay references to images that are stored in other files and which are intended to be used as part of the KML.  Manifold will automatically import GroundOverlay images that are stored on the local machine or which are accessible through local network references as part of the KML import.  Manifold will not automatically import images from Internet URLs embedded within the KML, since such silent connections across the web pose a significant risk to user privacy and can be very costly, depending on the type of connection.  See the Example: Import KML with GroundOverlay Image topic for an example and discussion.


We will import a .kmz file that provides historic data for tracks of hurricanes in the Atlantic ocean.  Launch File - Create - New Data Source.  



Choose More... to launch the New Data Source dialog.



Enter hurricanes as the name and for the Type choose File: kml.  No need to cache, so we uncheck the sub-boxes under Cache data.   


This particular .kml uses a spectacularly messy set of folders, one for each hurricane, so we will check the Merge layers box to consolidate those many folders into a single drawing.  Click the [...] browse button



In the Select File dialog, navigate to the desired .kml file, click on it, and choose Open.



Press Create Data Source.




In the Project pane we expand the new hurricanes data source and we ctrl-click on the four components within to highlight them.   We press Ctrl-C to copy them.   We click into an empty part of the Project pane outside of the data source hierarchy and press Ctrl-V to paste.    We can now click on the hurricanes data source and choose Delete to delete it.



What we have just done is to link to the .kml file and to then copy the data in it and paste that into the local .map project.   That is the same as using File - Import, except that we accomplished the import using the New Data Source dialog that gave us the option of merging many folders within the .kml into a single drawing that is much easier to work with.


We double-click the Map component to open it.



The result is a typical KML drawing, with a labels layer above, that is brought in from a .kml.   We will remove the labels layer from the map since this particular KML does not use labels.



We color the drawing layer with lighter colors using Style as seen above.   The Folder field in the table specifies the name of the layer from which a particular object was imported.  We can use that in a thematic format to color each object by the layer from which it originated, which usually results in a comprehensible display.   We have applied the CB Paired palette, using a method of unique values.



The result is a much more comprehensible display, seen above a Google satellite web server layer in a map.

Without Merge Layers

Using the Merge layers command makes a big difference.



Simply importing the same .kmz file without using Merge layers results in each track having its own folder.



The map that is created includes the labels component and the drawing within each folder as layers, resulting in many layers, each one of which must be styled individually.   



In the map illustration above we have used the Layers pane to apply partial opacity to the Google background layer to make it lighter, so the default black color of the hurricane tracks is more visible.  Even using the Layers pane to organize layers, having dozens of layers in a map with one layer for each line is extremely tedious.  It is far easier to use Merge layers to create a single layer.


KML and KMZ always provide data in Latitude / Longitude projection using WGS84 datum.   Manifold will automatically assign Latitude / Longitude coordinate system to drawings imported from KML.

Multi-type Geometry

KML, like GML, GeoJSON, and similar formats, can include geometry data for each object that mixes one or more geometry types.  Geometry values declared as multi-type (In KML, using the tag <MultiGeometry>) but with all parts having the same underlying type, such as all areas, all lines, or all points, will preserve that underlying type. Geometry values declared as multi-type that mix different types are converted as follows:



For example, if a KML file contains multi-type geometry with the same object defined both as a point and as a line, such as:







               <coordinates>135.13128666,48.42547611 134.99108892,46.64727784 131.96051024,43.13012695</coordinates>




The above object will be read as a line.



The use of multi-type geometry is surprisingly popular, an example being the above data set, imported from KML, showing world pipelines downloaded from the site.



Selection and Viewing Attributes in the Drawing - As imported, the drawing does not have any index so neither selection nor alt-clicking on an object in the drawing will work.   A drawing's table must have a key field with an index in it for selection or for Alt-click or Shift-Alt-click to work in the drawing.  If the table does not have an index, choosing an object by alt-clicking will not be available.  To add an index to the table, see the Add an Index to a Table topic.


See Also



Web Servers


Example: Import KML with GroundOverlay Image - files can contain GroundOverlay references to images that are stored in other files and which are intended to be used as part of the KML.  Manifold will automatically import GroundOverlay images that are stored on the local machine or which are accessible through local network references as part of the KML import.