Papervision3D External Models: Part 2

Jeff Winder

September 2009

Creating and loading models using SketchUp

SketchUp is a free 3D modeling program, which was acquired by Google in 2006. It has been designed as a 3D modeling program that's easier to use than other 3D modeling programs. A key to its success is its easy learning curve compared to other 3D tools.

Mac OS X, Windows XP, and Windows Vista operating systems are supported by this program that can be downloaded from Although there is a commercial SketchUp Pro version available, the free version works fine in conjunction with Papervision3D.

An interesting feature for non-3D modelers is the integration with Google's 3D Warehouse. This makes it possible to search for models that have been contributed by other SketchUp users. These models are free of any rights and can be used in commercial (Papervision3D) projects.

Exporting a model from Google's 3D Warehouse for Papervision3D

There are several ways to load a model, coming from Google 3D Warehouse, into Papervision3D. One of them is by downloading a SketchUp file and exporting it to a format Papervision3D works with. This approach will be explained.

The strength of Google 3D Warehouse is also its weakness. Anybody with a Google account can add models to the warehouse. This results in a variety of quality of the models. Some are very optimized and work fluently, whereas others reveal problems when you try to make them work in Papervision3D. Or they may not work at all, as they're made of too many polygons to run in Papervision3D. Take this into account while searching for a model in the 3D warehouse.

For our example we're going to export a picnic table that was found on Google 3D Warehouse.

  1. Start Sketch Up.
  2. Choose a template when prompted. This example uses Simple Template – Meters, although there shouldn't be a problem with using one of the other templates.
  3. Go to File | 3D Warehouse | Get models to open 3D Warehouse inside SketchUp.
  4. Papervision3D External Models: Part 2

  5. Enter a keyword to search for. In this example that will be picnic table.
  6. Select a model of your choice. Keep in mind that it has to be low poly, which is something you usually find out by trial and error.
  7. Click on Download Model, to import the model into SketchUp and click OK when asked if you want to load the model directly into your Google SketchUp model.
  8. Place the model at the origin of the scene. To follow these steps, it doesn't have to be the exact origin, approximately is good enough.
  9. By default, a 2D character called Sang appears in the scene, which you do not necessarily have to remove; it will be ignored during export.
  10. Because the search returned a lot of picnic tables varying in quality, there is a SketchUp file (can be downloaded from This file has a picnic table already placed on the origin. Of course, you could also choose another picnic table, or any other object of your choice.
  11. Papervision3D External Models: Part 2

  12. Leave the model as it is and export it. Go to File | Export | 3D Model. Export it using the Google Earth (*.kmz) format and save it in your assets folder.

T he file format we're exporting to originally was meant to display 3D objects in Google Earth. The file ends with .kmz as its extension, and is actually a ZIP archive that contains a COLLADA file and the textures. In the early days of Papervision3D, it was a common trick to create a model using SketchUp and then get the COLLADA file out of the exported Google Earth file, as the Google Earth KMZ file format wasn't still supported then.

Importing a Google Earth model into Papervision3D

Now that we have successfully exported a model from SketchUp, we will import it into Papervision3D. This doesn't really differ from loading a COLLADA or 3D Studio file.

The class we use for parsing the created PicnicTable.kmz file is called KMZ and can be found in the parsers package. Add the following line to the import section of your document class:

import org.papervision3d.objects.parsers.KMZ;

Replace or comment the code that loads the animated COLLADA model and defines the animations from the previous example. In the init() method we can then instantiate the KMZ class, assign it to the model class property, and load the KMZ file. Make sure you have saved PicnicTable.kmz file into the assets folder of your project.

model = new KMZ();


That looks familiar, right? Now let's publish the project and your model should appear on the screen.

Papervision3D External Models: Part 2

Notice that in many cases, the downloaded and exported model from Google 3D Warehouse might appear very small on your screen in Papervision3D. This is because they are modeled with other metric units than we use in Papervision3D. Our example application places the camera at a 1000 units away from the origin of the scene. Many 3D Warehouse models are made using units that define meters or feet, which makes sense if you were to translate them to real-world units. When a model is, for example, 1 meter wide in SketchUp, this equals to 1 unit in Papervision3D. As you can imagine, a 1 unit wide object in Papervision3D will barely be visible when placing the camera at a distance of 1000. To solve this you could use one of the following options:

  • Use other units in Papervision3D and place your camera at a distance of 5 instead of 1000. Usually you can do this at the beginning of your project, but not while the project is already in progress, as this might involve a lot of changes in your code due to other objects, animations, and calculations that are made with a different scale.
  • Scale your model inside SketchUp to a value that matches the units as you use them in Papervision3D. When the first option can't be realized, this option is recommended.
  • Scale the loaded model in Papervision3D by changing the scale property of your model.
      model.scale = 20;
  • Although this is an option that works, it's not recommended. Papervision3D has some issues with scaled 3D objects at the time of writing. It is a good convention to use the same units in Papervision3D and your 3D modeling tool.

If you want to learn more about modeling with SketchUp, visit the support page on the SketchUp web site You'll find help resources such as video tutorials and a help forum.

Creating and loading models using Blender

Blender is an open source, platform-independent 3D modeling tool, which was first released in 1998 as a shareware program. It went open source in 2002. Its features are similar to those in commercial tools such as 3ds Max, Maya, and Cinema4D. However, it has a reputation of having a difficult learning curve compared to other 3D modeling programs. Blender is strongly based on usage of keyboard shortcuts and not menus, which makes it hard for new users to find the options they're looking for. In the last few years, more menu-driven interfaces have been added.

It's not in the scope of this article to teach you everything about the modeling tools that can be used with Papervision3D. This also counts for Blender. There are many resources such as online tutorials and books that cover how to work with Blender.

A link to the Blender installer download can be found on its web site:

Exporting a textured cube from Blender into Papervision3D

In this example, we're going to create a textured and UV mapped cube to show how we can export a model from Blender to Papervision3D. The most recent versions of Blender have an integrated COLLADA exporter. Where the integrated exporter in 3ds Max has issues with Papervision3D, this exporter works fluently.

Let's see how we have to model and texture a cube in Blender:

  1. Start Blender. By default it opens a minimal scene, made up of a camera, a 3D object, and a light source.
  2. Go to Add | Mesh | Cube in the top menu. This will add a new cube to the scene.
  3. Place the cube on the origin of the scene. You can do this by dragging the gizmo or by changing the transform properties. These can be opened by using the Object menu (located at the bottom of the viewports) and by going to Transform Properties (shortcut n). Set LocX, LocY, and LocZ to 0, which will set the cube's position to zero on all axes. Double-clicking the current values makes them editable.
  4. Papervision3D External Models: Part 2

    Selecting objects
    In case you lose the selection of an object in a Blender scene, you can re-select it by right-clicking it.

  5. Scale the object, so it will match the units that we'll use in Papervision3D. This can be achieved in the Transform Properties panel. A dimension of 500 on all axes is a good value. You can set either the Scale values to 250 or the Dim values to 500. When you select the Link Scale button, you have to change these values only for one axis, as it will constrain its proportions.
  6. Scroll your mouse wheel to zoom out and see the whole cube again.
  7. Change from Object Mode to Edit Mode.
  8. Papervision3D External Models: Part 2

  9. The Object menu will be replaced with Mesh menu. Collapse it and select UV Unwrap (shortcut U when in edit mode). Click the bottom option called Unwrap (smart projections) and click OK when a new window shows up. This will create a UV map for us.
  10. The unwrapped map of the surface can be found in the UV/Image Editor. You can change your view from 3D View to UV/Image Editor by clicking the window icon at the bottom left corner of the 3D view of the scene.
  11. Papervision3D External Models: Part 2

  12. The UV/image editor will replace the 3D view and some new menu items show up. Go to the Image menu and select Open (shortcut Alt + O) to open up the image you want to use as texture. In order to use relative paths in the exported model, we will save the model once it is finished to the same folder as the texture, which we have selected in this step. You might want to take this into account when selecting the image.
  13. The selected image should appear on your screen.
  14. Exit the UV/image editor by selecting the 3D View window type.
  15. Change the Draw type from Solid to Textured, using the button next to the Mode selection, which we've previously set to Edit Mode.
  16. Papervision3D External Models: Part 2

  17. In the Buttons Window, which is the bottom window by default, select the Shading and Material button.
  18. Papervision3D External Models: Part 2

  19. You will see the Links and Pipeline panel, as shown in the previous image, press Add New to link the material to the cube.
  20. After linking the object, a new panel called Material will show up. Select the TexFace button.
  21. Save your file in the Blender format into the same directory as you have saved the used texture. This enables us to export using relative paths.
  22. Make sure you have the cube still selected and go to File | Export | COLLADA 1.4 (.dae). This will open the COLLADA exporter.
  23. Enter location to save the file and make sure you have selected:
    • Triangles
    • Only Export Selection because we do not want to export any other objects in the scene
    • Use Relative Paths, so we do not have to change the path to the material manually in the COLLADA file
    • Use UV Image Mats, so the model will make use of the UV map
    • Papervision3D External Models: Part 2

  24. Press Export and Close or just Export, to save the COLLADA.

Once these steps are completed successfully, the cube is ready for loading in Papervision3D. Loading this model works exactly the same as loading COLLADA, which is created by 3ds Max.

Copy the created model and texture to the assets folder of your project before loading the model. Loading requires you to have the DAE parser imported.

Change the init() method so that it will load the COLLADA model instead of the model from our previous example.

model = new DAE();


Publish your project and you should see the cube we created in Blender.

Papervision3D External Models: Part 2

Keeping control over your materials

It is very convenient that the materials defined inside a 3D modeling tool can be used in Papervision3D. On the other hand, there are situations where you want to have control over materials. To name a few:

  • When you want to use another material type such as a movie clip or streaming video
  • When you want to change a material property such as interactive, precise, and smooth
  • When you want to apply a shader

The moment you call the load() method using any of the 3D model parsers, you can pass a material list, specifying the materials you want to use. This works in a similar way to specifying a material list at instantiation of a cube and looks as follows:

var materials:MaterialsList = new MaterialsList();
materials.addMaterial(new ColorMaterial(0x0000FF), "materialDefinition");
var model:DAE = new DAE();

The materialDefinition string in the materials list refers to the unique ID of a material that was automatically set during export of a model. As you do not have any control over setting the ID yourself, you have to find it either by opening the COLLADA file in a text editor or trace it once the model has been loaded. The latter approach will be explained in a while.

The final example in this article shows how to change properties of a material once the object and materials are loaded. We're going to make the material interactive and rotate the object on each click. The previous example with the Blender-created cube will be used as a starting point.

Create a new project out of the previous example. For this new project we will use Tweener, so add the Tweener library to your Build Path (Flex Builder), Classpath (Flash CS3) or Source Path (Flash CS4).

In the init() method we can set viewport interactivity to true and add an event listener to the model, waiting for FileLoadEvent.LOAD_COMPLETE to be dispatched.

viewport.interactive = true;
model.addEventListener(FileLoadEvent.LOAD_COMPLETE, modelLoaded);

Next, we define the modelLoaded() method. Once this method is triggered, we will have full access to the loaded model and its child objects.

private function modelLoaded(e:FileLoadEvent):void

As we're going to change the materials applied to the model, it might be helpful to trace model.materials, to find out their name(s). Some exporters automatically define a material name or add a suffix to the name, which was defined in the modeling program.

trace("Used materials by this model: " + model.materials);

In our case this would trace BlenderCube_jpg. This string can be used to get an object's material, allowing you to set its properties.

model.getMaterialByName("BlenderCube_jpg").interactive = true;

Note that if you want to set BitmapMaterial-specific properties such as smooth, you first need to cast the material to BitmapMaterial.

Next, we define a listener waiting for clicks on an object nested inside the model. This needs to be set for every child object you want to be clickable. Therefore, we use model.getChildByName and search for a nested object. You can set the second parameter recursive to true, in order to search for a nested object inside a nested object. In fact, the model is a child object of the DAE class that was used to load it.

model.getChildByName("Cube_001", true).addEventListener
(InteractiveScene3DEvent.OBJECT_CLICK, click);

The name Cube_001 was automatically defined inside the modeling tool. You can also see this name when Papervision3D parses the object and traces its name in the output window.

INFO: DisplayObject3D: Cube_001

To see this you can publish the previous project that also loads the cube created in Blender.

In the final part of this example, we set up the click() method that will be triggered each time the cube is clicked. Tweener will be used to animate the cube.

private var targetRotationX:Number = 0;

private function click(e:InteractiveScene3DEvent):void
Tweener.addTween(model, {localRotationX:targetRotationX, time:1.5,


Publish this code and you will see the same cube as in the Blender example. However, clicking on it will rotate the cube over its local x-axis, with an elastic transition.

As this example shows, we can change material properties at run time. If you like, you can even change the material at run time, just like you would replace a material on primitive cube.


Modeling is a very broad topic as there are many 3D programs, each with numerous features. When you want to display custom objects besides the built-in primitives, you can load models created by 3D programs.

This two-part article showed how to create basic models in 3ds Max, SketchUp, and Blender, and how to export them for Papervision3D. To do this we've used three different file formats:

  • COLLADA (.dae): An open source 3D model file type, which has been supported since the early releases of Papervision3D. This is the most developed file type, which also supports animation and animation clips.
  • 3D Studio (.3ds): An established 3D file format that is supported by most 3D modeling programs.
  • SketchUp (.kmz): A format that is used by Google Earth, which can be created by a free program called SketchUp.

Creating models for use in Papervision3D has some requirements and conventions to take into account:

  • Keep a low polygon count
  • Add polygons to problematic parts of your model to prevent z-sorting artifacts or texture distortion
  • Keep your texture small
  • Use textures Flash can read
  • Use UV maps
  • Bake textures
  • Use recognizable names for objects and materials
  • Use the same metrics as in Papervision3D
  • Find balance in optimization

Models that are loaded in Papervision3D automatically load images that are defined as materials in the 3D modeling program. At the end of this article we've seen how we can have access to these materials. The way we can access a model's material doesn't differ from accessing a material on a primitive cube.

You've been reading an excerpt of:

Papervision3D Essentials

Explore Title