Introduction

Model placemarks enables you to create placemarks with an arbitrary 3D model.

This article shows you how to use model placemarks. It assumes that you are familiar with the concept of placemarks introduced in the Placemarks article.

Creating a Model placemark

A model placemark represents a 3D object in the scene. It can be used to represent small objects such as furniture and vehicles. Here is how you can create a model placemark:

1. Create a placemark.
2. Assign ModelGeometry to the placemark.
3. Set the url of the ModelGeometry to a COLLADA model file.
4. Set the ModelGeometry's position, orientation and/or scale.
5. Set the origin of the ModelGeometry (optional)
6. Choose whether to display the loading icon, using a ModelStyle (optional)

Source: ModelGeometry example, function CreateModelPlacemark()

// Creating a ModelGeometry
// Create a placemark & set its name
var placemark = germ.CreatePlacemark("Discussion Corner");
germ.AddPlacemark(placemark);
 
// Assign ModelGeometry to the placemark
var modelGeom = germ.CreateModelGeometry();	// create a ModelGeometry object
placemark.SetGeometry(modelGeom);		// assign it to the placemark
 
// Set the url of the model
modelGeom.SetSourceUrl("customModels/table.DAE"); 
 
// Set ModelGeometry's position
var modelPosition = germ.CreateCoordinates(11.1, 4.2, -40.11);
modelGeom.SetPosition(modelPosition);

Loading

Loading icon

When a model placemark is added to the scene, GermaniumWeb will load the model file if the source URL of the ModelGeometry has not been loaded previously. The length of the loading process depends on the model's file size and the speed of your internet connection. While the file is being loaded, the loading icon is displayed in place of the model. You can choose to disable the loading icon: Create a ModelStyle object and SetUseLoadingIcon to false. Get the Placemark's StyleSet object and apply the ModelStyle object using StyleSet.SetGeometryStyle(). Source: ModelGeometry example, function CreateModelPlacemark_NoLoadingIcon() // Hide the loading icon with ModelStyle var style = germ.CreateModelStyle(); style.SetUseLoadingIcon(false); pm.GetStyleSet().SetGeometryStyle(style); Tip: The loading icon always appears at the position of the ModelGeometry. See the Origin section on how the actual geometry is related to this position.

OnModelLoadEnds Event

It is sometimes useful to know when the loading of the model is complete. You can do so by registering to the OnModelLoadEnds event.

The OnModelLoadEnds event is raised whenever a model file from a new url has completed loading for the first time. If the first load was successful, subsequent loading completion of model placemarks using the same model file will not raise the event again.

Source: ModelGeometry example, function RegisterToOnModelLoadEnds()

// OnLoadEnds, glide to the placemark 
function GlideToPlacemark(event)
{		
   if (event.loadOk)
   {
      var currGeom,
          currPM,
	  totalPM = germ.GetNumberOfPlacemarks();
 
      // Loop through all placemarks			
      for (var i = 0; i < totalPM; i++)
      {
         currPM = germ.GetPlacemarkByIndex(i);
 
         // Obtain the geometry of the Placemark
         currGeom = currPM.GetGeometry();
 
	 // If it is a model geometry, compare url with event's url
	 if (currGeom.GetType() == Germanium.Types.ModelGeometry &&
	     currGeom.GetSourceUrl() == event.url)
	 {
	    germ.GetEye().GlideEyeToVisualObjectOrt(currPM, -0.486, 10.44, 0);
	 }
      }					
   }
}
 
germ.AddEventHandler(Germanium.Event.OnModelLoadEnds, GlideToPlacemark);

In the event that a model placemark fails to load successfully, an error icon is displayed instead and the OnModelLoadEnds event will be raised with the corresponding load event errors.

Supported model formats

Currently, model placemarks only support loading of geometry exported in the COLLADA format. Check our COLLADA guide for more information about COLLADA files.

Origin

Similar to an icon placemark's hotspot a model has an origin which is placed on the ModelGeometry's position. You can choose from 2 different origins, File or First Node. The default setting is File, which sets the origin to the COLLADA file's origin. First Node sets the origin to be the location of the first COLLADA node encountered in the file.

You may encounter the scenario below where, using the File origin, a model placemark's 3D geometry appears at a different place from its position. Also, since the loading icon and callout balloon tail point to the placemark's position when it is activated, they appear to be pointing to empty space. This often happens when the 3D model was not placed at the world origin in the 3D modeling software when exported to COLLADA. Setting the origin to First Node fixes this problem.

Using File origin

Using First Node origin

To set the origin to First Node, you call:

Source: ModelGeometry example, function SetOriginFirstNode()

  modelGeom.SetOrigin(Germanium.ModelGeometry.Origin.FirstNode);

Let's go through an example to see how the 2 origin modes differ and how they are useful. Suppose we have the office scene on the right in our 3D modeling package, and we want to export a desk (highlighted in blue) into a separate COLLADA file for use as a model placemark. The world origin of the office is indicated by the green and red arrows. Tip: Typically, models exported from a complete 3D scene will not be at the world origin of the 3D modeling package. Tip: You should only export each unique furniture model once and reuse the same model for similar placemarks for significantly better performance.

In this example, we want to recreate this office scene in GermaniumWeb by exporting the building to Building Composer, and exporting the desks as model placemarks. If we export the desk highlighted in blue and add it to GermaniumWeb as a model placemark positioned at (0,0), the 3D model will appear in the correct place at (2,2), but its loading icon and placemark callout tail will be placed at (0,0) instead.

To fix this, we set the origin to FirstNode and set the placemark's position to (2,2). GermaniumWeb will place the origin of the first COLLADA node (in this case, the desk's) at (2,2). Note: The position of the origin is dependent on the modeling application. It is possible that both the file and first node origin is at the same point, in which case changing the origin won't matter.

Transforms

Positioning, orienting, and scaling of a model placemark is applied around the location selected origin.

Using the example geometry from our previous discussion, the figures below illustrate the difference between using File and First Node when the model geometry is manipulated.

SetPosition(3,3,0):
SetOrientation(0,0,45):
SetScale(2,2,1):

Developers