KML Building Importer - Tutorial

Building generated from KML in GermaniumWeb

The KML Building Importer takes in .KML files and generates a simple building using the floorplan images within the KML files. The generated levels have a 3D volume, giving it a stronger presence in the 3D space.

The following sections goes through the steps to create a .KML file for GermaniumWeb using Google Earth¹, and from which you can either load the resulting KML file in a sample GermaniumWeb application or proceed to the Developers tutorials to design your own GermaniumWeb application to load your KML file.

Preparation

Before you create your building, you should have its floorplan images ready, or you can download the ones we used here. The floorplan images can be in PNG (32-bit), TGA (32-bit) or BMP (32-bit) formats but we especially recommend using PNG format. You can learn how to make your floorplan images into PNG format with transparency using Photoshop here.

• Create a new folder. Name it whatever you want, but since we are boring we shall call ours "KMLTutorial".
• Place all your floorplan images in that folder.
• If you are using our floorplan images, extract all the contents from the zipped file to that folder too. Check that your folder now contains 5 floorplan image files (B1.png, L1.png, L2.png, L3.png, Roof.png) and Location.kml.

Floorplan images unzipped from KMLTutorial.zip

Locating the Building

Inside Google Earth, uncheck Terrain

Next we locate our building in Google Earth.

• Start Google Earth.
• Navigate on the globe to the site of your building.
• Or if you are using our building, you can find it by opening the Location.kml file in Google Earth and you will be automatically flown there.
• If somehow that doesn't work, try searching 1°18'6.36"N, 103°49'22.59"E in the top left Search panel, under the Fly To tab.

• Make sure that under the bottom left Layers panel, the Terrain box right at the bottom is unchecked, or your building might not be visible later even after you add it.

Creating a New Building

Now it’s time to create our building. We will do this by creating folders in Google Earth. Each folder represents a Building in the resulting model. You can read more about the BBL to directory structure conversion in the User Guide.

Right click on Temporary Places and add a new folder for our building

To create a new folder: In the Places panel, right click on the folder you want to create your new folder in, under Add, click Folder. You can just use Google Earth's default Temporary Places folder for this tutorial. Tip: Use the shortcut key Ctrl+Shift+N to quickly create a new folder . New folder window A New Folder window should pop up and you have to: Enter a name for your building in the Name field Make sure that the Allow this folder to be expanded box is checked Describe your building in the Description tab if you want to And click OK Your Building folder is created!

Creating a New Block

Right click on the Building folder and add a new folder

We represent a Block as a folder as well, placing it inside the Building folder. Just as a building can have many blocks, you can have multiple Block folders in a Building folder.

Repeat the steps to create a new folder as described in Creating a New Building, except this time you to create the folder in the Building folder you just created. This will become a Block in the Building.

You can create more Blocks if your Building requires it but in this tutorial we will only create one since our Building only has one Block.

Creating a new Level

In each Block there are usually several Levels and they are the smallest unit structure in your Building. Hence, we will not represent a Level as a folder but as an Image Overlay created in the Block folder it belongs to.

Right click on the Block folder and add an Image Overlay

To create an Image Overlay: Tip: Double click Location.kml under the Places panel to focus on your building first. Explanation below is for inquisitive lambs only, for those who just want to get this over and done with – proceed. Warning: When you add an Image Overlay, it will take up most of the screen. If your building appears tiny on screen or is out of sight, when it’s time to align them, you will have a fun time frantically scaling down your floorplan image or shifting it back to where your building is. To save yourself some trouble, make sure your building fills most of the screen first. In the Places panel, right click on the Block folder you want to add the Level in, click Add and select Image Overlay.

Image Overlay Dialog: Set Altitude to be Absolute

• A New Image Overlay window will pop up in which you should:
  • Enter the name of this Level in the Name field. If you are using our building, we recommend you to start with Level 1.
  • For the Link field, click on the Browse button and locate the floorplan image of that Level in the folder we asked you to create in Preparation. Your floorplan image should now appear in the background. It follows that you should add L1.png, the Level 1 floorplan of the building here.
    Tip: You can reduce the opacity of your floorplan image now to help you align the Level to the building in Google Earth using the Transparency bar, or you can always change it later if you need to.
  • Select the Description Tab and enter the description of that Level.
  • Select the Altitude Tab. Change Clamped to ground to Absolute and enter the altitude for that Level. The altitudes of the various levels B1, L1, L2, L3 and Roof, in our building have altitudes -5m, 0m, 4m, 8m and 12m respectively.
    Note: Negative altitudes can only be entered in Google Earth version 5.0 onwards. You can manually edit the KML file if you are using earlier versions of Google Earth.
  • Before you click OK, you need to align your floorplan image to your building in Google Earth. Shift the New Image Overlay window to a corner and use the green transform markers to move (centre cross-hair), scale (corner and side cross-hairs), and rotate (diamond shape) your floorplan image. Try to match the screenshot below. You may want to refer to Google Earth’s user guide for more help.

Align the floorplan image over the Building's satellite image

• When you are done, click OK to add the Level to the Block.

Your new Level is created!

Adding more Levels to the Block

Copy the Image Overlay

Now that you have added one Level, if you are studious you can slowly repeat the above for all the other Levels. However, we are lazy so we will simply duplicate the Level we have already created and edit its properties for all the other Levels so that we do not have to re-align them.

• Right click on the Level you have just created under the Places panel and select Copy.

Paste the copied Image Overlay back into the Block folder

Final arrangement of the Image overlays in Google Earth

• Lastly, ensure that your Levels in the Places panel are arranged in order, lowest level first (see screenshot on the right). Do this by dragging them around within the Places panel.

Exporting

Save the newly created Building folder

Congratulations! You have generated a KML file for the KML Building Importer (built into GermaniumWeb), you can now proceed on to develop your own GermaniumWeb application for your building or view your building using our sample application below.

Viewing your KML file in a sample GermaniumWeb application

To view the KML file you just saved, you can edit the webapp.html found in our KMLTutorial_completed.zip above and use it for yourself:

• Open webapp.html in a text editor like Notepad or WordPad.
• Press Ctrl + F and the Find window will appear. For the Find what field, enter var strSceneFilePath = 'http://www.germanium3d.com/static/sample/KMLTutorial/Generic Office Building.kml' and click Find Next. You should find it in the first few lines of the file.
• Change http://www.germanium3d.com/static/sample/KMLTutorial/Generic Office Building.kml to the filepath (on your computer) for your KML file.

Replace the filepath in the html file with your own.

• Press Ctrl + S to save the changes in webapp.html.
• Open webapp.html in your web browser. You should see the sample application with your KML file loaded.

Finished KML Building loaded in GermaniumWeb

You can also view the sample application with our completed tutorial KML file loaded here.

Going further

• Developing the web application for your Building
  • Learn how to load and manipulate the Building in your web application by using the GermaniumWeb API.
• Set the position of your Building in GermaniumWeb
  • Find out how to set the position of a Building relative to other Buildings when they are loaded into GermaniumWeb.

¹ Google™ and Google Earth™ are registered trademarks of Google Inc. in the United States and/or other countries.