Overview

The KML parser 2 BETA allows you to import and export kml and kmz files to and from 3ds Max. These files can be used with google earth or sketchup for instance. KML parser 2 BETA also supports 3D models. So you can exchange not only flat shapes but also buildings for instance and put them in google earth.

Map projection

The script uses the transverse mercator map projection to calculate between lon/lat coordinates and x/y coordinates. There still are some hickups in how I implemented these calculations which mean that sometimes there are some deviations. If you encounter issues with the map projection, please get in touch! My email address is at the top of this document.

Tiny disclaimer

This script is in BETA at the moment. Stuff might not work or might be removed in the future. Other functions might be added. Always make sure you backup your data before using the script. Any data loss or damage to your files is your responsibility.

If you have suggestions or bug reports, feel free to send them to mail@klaasnienhuis.nl.

Also, please don’t replicate anything in this documentation without my written consent.

Main functions

There are two main functions: import a kml or kmz file and export scene objects to a kmz file. Besides that, you can set the units for the file you’re importing. For instance, if you’re importing a shape which is 1 kilometer by 1 kilometer and set the import units in the script to “m” (meters), your shape will be 1000 meters by 1000 meters in 3ds Max.

NOTE: please keep in mind that 3ds Max doesn’t handle very large numbers very well. So if you’re importing the border of China in millimeters, the results might not be very accurate in 3ds Max.

The main functions are pretty basic

Units

Keep in mind there’s a difference in 3ds Max between display units and system units. All unit conversion in this script and in many other importers is done based on the system units. If you’re looking for predictable results (and aren’t we all?) make sure your system units match up with the import units in the script. The script helps you setup this correctly. Firstly it shows you the system units used in 3ds Max, secondly you can press a button to change the import units to match the system units in the scene.

Alternatively you can change the system units. You’d have to do this if you’re importing very large shapes, such as outlines of countries. Set your system units to kilometers or miles in that case.

the import settings help you determine the best unit setup in the script. It’s advised to match the import units to the system units.

These are the display units in 3dsMax. To access the system units, press the “System units setup” button at the top.

Here you can alter the system units. These are the units used for the import process.

Importing shapes

You can import a kmz or kml file. Set the units you’d like to use and get the file. Once imported the shapes will be projected in the the x/y/z space in 3ds Max. Besides that, a helper object is created which is the parent of all imported shapes and contains some data in it. Don’t delete this object if you’re planning to export stuff related to these shapes later on.

I’ve drawn this shape in google earth and saved it as a kmz file

I’ve located the file on my disk and set the import units to “m”. This is the same as my system units in this case, but it isn’t strictly necessary.

This is the imported shape. The KML helper is located at the origin.

The KML helper contains some data. You can’t edit this, it’s just for show

Exporting shapes

Exporting shapes is just as simple. You just have to remember to parent everything you want to export to this KML helper. Please note that the KML format doesn’t use bezier shapes, just straight line segments. If you want to export curved shapes like the example below, subdivide your shapes or use a normalize spline modifier to do that for you.

You can select the KML helper and press export. In that case all children of the KML helper are exported. You can also select one or more of its children. In that case only the selected items are exported. Just keep in mind to parent everything you want to export to that KML helper.

I’ve drawn a nice design on top of the Netherlands.

Specify an output location, select the KML helper or some objects and press the “Export” button.

This is the design loaded in google earth. Notice how GE interprets closed shapes as polygons and fills them automatically.

3D models

With the script you can also import and export 3D models. 3D model exchange is still pretty limited at the moment but it will be extended in the future. 3D models in KMZ files are actually ordinary collada files. The script uses the default collada im/exporter that ships with 3ds Max. When importing also textures are read in. Textures and materials aren’t exported very nicely. This is an area I’m working on.

Import and export settings aren’t automated yet. Please take a look at the settings displayed here and adopt them. Especially the units: in the collada import and export settings the units have to be set to “Meters”

Import a 3D model

Importing a 3D model works the same as importing shapes, just pick a kmz file, set the units and press the “import” button. Many google earth 3D models have been made in sketchup. These models might have double faces which causes z-fighting.

I’ve downloaded this model. It’s a KMZ file with a 3D model in it.

Use these import settings

Here’s the textured model. Notice the heavy z-fighting, not a pretty sight

Export 3D model

Exporting a 3D model follows the same pattern as exporting shapes. Parent your geometry to a KML helper and export it. You’ve got to import a kml/kmz file first to get this done. Otherwise there’s no KML helper to work with.

I’ve made yet another nice design, now in 3D. I’ve parented these objects to the KML helper at the origin.

After pressing “Export” I get the export settings dialog. Use these

Open the file in google earth: voila, balls!

Installation

Install the script by either dragging the .mzp file into a viewport or by using the menu: Maxscript > Run script...

After that a dialog appears. Press the “Install Clara_IO [version number]” button. A dialog appears to ask you if you’re sure. If the installation has been successful, another dialog appears which tells you how to add the script to a toolbar, quad, shortcut or menu. Close the installation dialog.

The installation dialog

This dialog asks if it’s ok to clear the destination folder before installing the script in it.

The success message with an instruction on how to add the script to the gui

Add a button on a toolbar

To add the script to a toolbar, use the menu: Customize > Customize User Interface... Go to the “Toolbar” tab and in the “Category” list pick the “Klaas tools” item. A list of scripts in that category appears. Pick the “KML parser [version number]” item and drag that to an existing toolbar or make a new toolbar for it. Save the ui layout if you want to keep it.

You can also put the script in a menu, quad, under a keyboard shortcut or a combination of these.

The customize user interface dialog

Add the script to a toolbar

Updating

The script checks for an update every time it starts up. If there’s an update available, the script will notify you with a message in a button. Press it to download the update and start the installer. Follow the instructions under the “Installation” chapter. However, you don’t need to customize the gui again. Just close the installer and script and reopen the script. It’s been updated now.

An update is available, go get it