Models

In KML, you can import 3D models—such as buildings, bridges, monuments, and statues—in the COLLADA interchange file format. Models are defined independently of Google Earth in their own coordinate space, using applications such as SketchUp, 3D Studio Max, Softimage XSI, or Maya. When a 3D model is imported into Google Earth, it is translated, rotated, and scaled to fit into the Earth coordinate system. Models already loaded into Google Earth can be repositioned and resized using the <Update> element.

Sample Model

A model is used in Google Earth just as any other geometry object (point, linestring, or polygon). Here is a simple example of a KML file that imports a textured model.

The <Link> reference to the model can be an an absolute or relative file specification, or a URL.

To view this model, load the file MackyBldg.kmz, which is an archive that contains all the necessary texture and overlay files as well as this doc.kml file containing the Model:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Placemark>
  <name>SketchUp Model of Macky Auditorium</name>
  <description>University of Colorado, Boulder; model created by Noël Nemcik.</description>
  <LookAt>
    <longitude>-105.2727379358738</longitude>
    <latitude>40.01000594412381</latitude>
    <altitude>0</altitude>
    <range>127.2393107680517</range>
    <tilt>65.74454495876547</tilt>
    <heading>-27.70337734057933</heading>
  </LookAt>
  <Model id="model_4">
    <altitudeMode>relativeToGround</altitudeMode>
    <Location>
      <longitude>-105.272774533734</longitude>
      <latitude>40.009993372683</latitude>
      <altitude>0</altitude>
    </Location>
    <Orientation>
      <heading>0</heading>
      <tilt>0</tilt>
      <roll>0</roll>
    </Orientation>
    <Scale>
      <x>1</x>
      <y>1</y>
      <z>1</z>
    </Scale>
  <Link>
    <href>MackyBldg.kmz/files/CU Macky.dae</href>
  </Link>
  <ResourceMap id="resourcemap_for_model_4">
    <Alias>
      <sourceHref>../files/CU-Macky---Center-StairsnoCulling.jpg</sourceHref>
      <targetHref>C:/DOCUME~1/josiew/LOCALS~1/Temp/MackyBldg.kmz/files/CU-Macky---Center-StairsnoCulling.jpg</targetHref>
    </Alias>
    <Alias>
      <sourceHref>../files/CU-Macky-4sideturretnoCulling.jpg</sourceHref>
      <targetHref>../files/CU-Macky-4sideturretnoCulling.jpg</targetHref>
    </Alias>
    <Alias>
      <sourceHref>../files/CU-Macky-Back-NorthnoCulling.jpg</sourceHref>
      <targetHref>../files/CU-Macky-Back-NorthnoCulling.jpg</targetHref>
    </Alias>
    <Alias>
      <sourceHref>../files/CU-Macky-BrickwallnoCulling.jpg</sourceHref>
      <targetHref>../files/CU-Macky-BrickwallnoCulling.jpg</targetHref>
    </Alias>
.
.
.
    </ResourceMap>
  </Model>
</Placemark>
</kml>

The model is positioned geographically with the Location element's latitude, longitude, and altitude specifications. This example uses default values for the Orientation and Scale elements, which are included here for completeness.

The Orientation element specifies rotations of the model around the x (tilt), y (roll) and z (heading) axes. The y axis points North and is parallel to longitude lines, and the x axis points East and is parallel to latitude lines. Rotations are specified in degrees, with positive rotations as shown in the following diagram.

The ResourceMap element maps the texture files from the location specified in the original Collada file (<sourceHref>) to a location in the KML or KMZ file (<targetHref>) that contains the Model.

Note: In releases prior to Google Earth Release 4.2, this mapping function was performed by the textures.txt file (an external file included in the KMZ archive). Google Earth 4.2 accepts KML and KMZ files that refer to a textures.txt file and processes them correctly. When such files are written out by Google Earth 4.2 clients and later, the information in the textures.txt file is translated into the <ResourceMap> and <Alias> elements, which are children of <Model>.

Creating a .kmz Archive

A KMZ archive is collection of files used to create a single KML presentation. This archive includes all the local files that are referenced in the .kml file, such as images, textures, and models. A KMZ archive is a self-contained package that does not need to be hosted on a network server and can easily be e-mailed and stored as a single unit. Google Earth can read .kml and .kmz files directly.

The doc.kml file and the local files it references are compressed into an archive using the ZIP file format. Many applications can produce this format. WinZip on Windows systems, Stuffit on Macintosh systems, and zip on Linux or Macintosh systems are popular applications that can read and write the ZIP format. You can also work with zip archives using the Windows Explorer or Mac Finder directly.

After you have created the .zip file, change the file extension to .kmz.

The KMZ archive containing the complete textured model for the Macky Building includes these files:

  • doc.kml - the KML file shown above, which imports the COLLADA (.dae) model and places it in Google Earth. Place this file in the root directory of the KMZ (ZIP) file.
  • files/ directory - contains the COLLADA files that define the geometry, textures, and material of the model. In the Macky Building example, this directory contains the COLLADA file (CU Macky.dae) as well as the numerous files containing the JPEG images used to texture the building (CU-Macky-BrickwallnoCulling.jpg, CU-Macky--Center-StairsnoCulling.jpg, CU_Macky-EastdetaildoornoCulling.jpg, and so on).

This example illustrates one way to structure the files in a KMZ archive. Actually, you can arrange the files in any structure that seems logical to you, just as you organize the files into folders or directories on your computer. For example, it might be useful to put all the images in an images/ directory. Relative references (such as the files referred to in the <href> element that is used in NetworkLink, Link, Overlay/Icon, and Model) are specified relative to the doc.kml file. If you include an images directory, then the <href> specification for your images would be: images/myBrickTexture.jpg, images/myMountainOverlay.png, and so on).

Back to top