Placemarks

Contents

Introduction

A placemark is useful to mark special locations in the scene, such as:

Here is the static class diagram of the Placemark class.

Placemark class diagram


This article introduces point placemarks (also known as pushpins). Read the Lines & Polygons article to learn how to use line and polygon placemarks.

A point placemark has the following properties:

You can also attach a placemark to a building, a block, or a level (this feature requires API version 1.3).

Creating a point placemark

Here is how you can create a point placemark and set its position to a specific coordinates (x, y, z).

Source: placemarks example, function CreatePlacemark()

// Create a placemark
myPlacemark = germ.CreatePlacemark();	// myPlacemark is a global variable
 
// Set placemark position
var point = germ.CreatePointGeometry();
point.SetPosition(10, 0, 2);
myPlacemark.SetGeometry(point);
 
// Add placemark to the scene
germ.AddPlacemark(myPlacemark);
Tip: Refer to Coordinate System article to learn how GermaniumWeb represents position.

Setting properties of point placemark

Setting name, content, and more info URL

The placemark name is shown as the placemark label in the 3D scene. The name, content, and more info URL are shown in a callout balloon when you click a placemark. Note that the content can contain HTML.

Placemark label Callout balloon showing name, content, and more info URL

Source: placemarks example, function SetNameContentURL()

if (!myPlacemark) {
	myPlacemark = germ.CreatePlacemark();
	germ.AddPlacemark(myPlacemark);
}
myPlacemark.SetName("Staircase");myPlacemark.SetContent("In case of fire, use this instead of the lift.");myPlacemark.SetMoreInfoUrl("http://en.wikipedia.org/wiki/Stairway");

Changing visual appearance

An icon placemark

By default, a point placemark appears as a 3D diamond. You can change the appearance by following these steps:

  1. Create an Image object, specifying the URL of the image you want to use as the icon.
  2. Create an IconStyle object; then apply the Image object created in previous step using IconStyle.SetImage().
  3. Get the placemark's StyleSet object; then apply the IconStyle object created in previous step using StyleSet.SetGeometryStyle().

Refer to the API documentation on placemark appearance for further details.

Source: placemarks example, function ChangeVisualAppearance()

// Create a placemark if necessary.
if (!myPlacemark) {
	myPlacemark = germ.CreatePlacemark();
	germ.AddPlacemark(myPlacemark);
}
 
// Define a custom icon stylevar sourceUrl = "http://www.germanium3d.com/res/icons/stairs.png";var image = germ.CreateImage(sourceUrl);	// create an Image objectvar iconStyle = germ.CreateIconStyle();		// create an IconStyle objecticonStyle.SetImage(image);			// apply the ImageiconStyle.SetHotspot("50%", "100%");var styleSet = myPlacemark.GetStyleSet();	// get the placemark's StyleSetstyleSet.SetGeometryStyle(iconStyle);		// apply the IconStyle
Tip:
  • Refer to the icon gallery for icons GermaniumWeb provides. Alternatively, you can create your own icons, upload them to your web server, and use them in your application by changing the Image sourceUrl to the URL of your icons.
  • The order of setting objects in your code does not matter because JavaScript passes objects by reference.

Changing label style

Custom label style

You can change the color of placemark label:

  1. Create a LabelStyle object; then set the label color using LabelStyle.SetTextColor().
  2. Get the placemark's StyleSet object; then apply the LabelStyle object created in previous step using StyleSet.SetLabelStyle().


Source: placemarks example, function ChangeLabelStyle()

// Create a placemark if necessary
if (!myPlacemark) {
	myPlacemark = germ.CreatePlacemark();
	germ.AddPlacemark(myPlacemark);
}
 
// Define a custom label stylevar labelStyle = germ.CreateLabelStyle();	// create a LabelStyle objectlabelStyle.SetTextColor("ffff00");var styleSet = myPlacemark.GetStyleSet();	// get the placemark's StyleSetstyleSet.SetLabelStyle(labelStyle);		// apply the LabelStyle
Tip: The order of setting objects in your code does not matter because JavaScript passes objects by reference.

Changing balloon style

Custom balloon style

You can change the appearance of the callout balloon:

  1. Create a BalloonStyle object; then set its properties.
  2. Get the placemark's StyleSet object; then apply the BalloonStyle object using StyleSet.SetBalloonStyle().


Source: placemarks example, function ChangeBalloonStyle()

// Create a placemark if necessary
if (!myPlacemark) {
	myPlacemark = germ.CreatePlacemark();
	germ.AddPlacemark(myPlacemark);
}
 
// Define a custom label stylevar balloonStyle = germ.CreateBalloonStyle();	// create a BalloonStyle objectballoonStyle.SetCloseButtonVisibility(false);balloonStyle.SetBackgroundColor("EAFF88");balloonStyle.SetOutlineColor("728B00");var styleSet = myPlacemark.GetStyleSet();	// get the placemark's StyleSetstyleSet.SetBalloonStyle(balloonStyle);		// apply the BalloonStyle 
germ.SetActivePlacemark(myPlacemark);		// open the placemark balloon

Attaching a placemark to a BBL object

When marking a part of a building, you may want the placemark to be hidden when the building part is hidden and shown when the building part is shown. You can do this by attaching the placemark to a BBL object.

A placemark can be attached to only 1 BBL object. Thus, if a placemark is already attached to a BBL object, the placemark will be detached first and then attached to the specified BBL object.

Source: placemarks example, function AttachPlacemarkToLevelL02()

// Load a building if necessary.
if (germ.GetNumberOfBuildings() == 0) {
	germ.Load("http://www.germanium3d.com/static/sample/generic_building/generic_building.xlcl",
		null, LoadOk, LoadFail);
}
 
// Will be called if loading finishes successfully
function LoadOk() {
	// Create a placemark
	var placemark = germ.CreatePlacemark();
	placemark.SetName("Window");
	placemark.SetContent("It is near a white and blue screen.");
	placemark.SetMoreInfoUrl("http://en.wikipedia.org/wiki/Window");
 
	// Set placemark position
	var point = germ.CreatePointGeometry();
	point.SetPosition(17.2, 5.6, -50.7);
	placemark.SetGeometry(point);
 
	// Define a custom icon style
	var sourceUrl = "http://www.germanium3d.com/res/icons/blank_blue.png";
	var image = germ.CreateImage(sourceUrl);	// create an Image object
	var iconStyle = germ.CreateIconStyle();		// create an IconStyle object
	iconStyle.SetImage(image);			// apply the Image
	iconStyle.SetHotspot("50%", "100%");
	var styleSet = germ.CreateStyleSet();		// create a StyleSet object
	styleSet.SetGeometryStyle(iconStyle);		// apply the IconStyle
	placemark.SetStyleSet(styleSet);		// apply the StyleSet to the placemark
 
	// Add placemark to the scene
	germ.AddPlacemark(placemark);
 
	// Get level L02
	var building = germ.GetBuildingByIndex(0);
	var block = building.GetBlockByBBLId("OFFICE");
	var levelL02 = block.GetLevelByBBLId("L02");
 
	// Attach placemark to level L02	placemark.AttachToBBLObject(levelL02);}
 
// Will be called if loading fails
function LoadFail(errMsg, errCode) {
	alert('Loading failed. Error code: ' + errCode + '; message: ' + errMsg);
}

Now when you hide/show level L02, the placemark is also hidden/shown.

Source: placemarks example, function HideShowLevelL02()

// Get level L02
var building = germ.GetBuildingByIndex(0);
var block = building.GetBlockByBBLId("OFFICE");
var levelL02 = block.GetLevelByBBLId("L02");
 
// Toggle level visibility
levelL02.SetVisibility(!levelL02.GetVisibility());

Removing a placemark

You can remove a placemark from the 3D scene using RemovePlacemark().

Source: placemarks example, function RemoveFirstPlacemark()

if (germ.GetNumberOfPlacemarks() > 0) {
	var placemark = germ.GetPlacemarkByIndex(0);
	germ.RemovePlacemark(placemark);
} else {
	alert("There no placemark in the 3D scene.");
}

For convenience, you can remove all placemarks using RemoveAllPlacemarks().

Source: placemarks example, function RemoveAllPlacemarks()

germ.RemoveAllPlacemarks();

References

Retrieved from "http://www.germanium3d.com/code/PlacemarkConcepts"

This page has been accessed 383,486 times. This page was last modified on 6 June 2011, at 01:45.


Developers


Main

API Key Registration

Developer Guide
- Introduction
- Buildings
- Point Placemarks
- Line & Polygon      PlacemarksUpdated
- Model Placemarks New
- HTMLBoxes New
- Eye Control
- Clip Planes
- Events
- Coordinate System
- Navigation Modes
- Options

API Documentation

Examples
- Applications Gallery
- Hello Germanium
- Interactive samples

More Resources
- API Release Notes
- Developer FAQ
- "A Beginner's Guide" slides
- Training Materials
- Icon Gallery
- Sample Buildings
- BBL Tree

Report Bugs