This document describes how to embed a Diorama in your web-page and how to populate the diorama using the Diorama API based on javascript. In order to appreciate this manual you need to know what a diorama and a scene is. In the context of this system a diorama is a location where a story is told. You can dress up this location with various resources such as sounds, image overlays (To do) and 3D models. The diorama can contain scenes where each scene has it’s own location and adds it’s own resources to the diorama while open. Scenes can display the same resources as a diorama but in addition also time dependent things such as image slideshows and video’s.

It makes sense to break up a story in scenes because it allows the viewer to explore the scenes and resources are only loaded when required.


Since the application runs in a IFrame it is difficult to reliably communicate with the program from a different window. However, the new Post and message events in modern browsers make it possible to transmit messages to and from the Diorama application. The added advantage is that to javascrip objects are exposed to external javascript. This means that only commands supported by the Diorama API can be used.

A diorama has a strict hierarchy. At the root there is Google Earth. The API can add one or many “Dioramas”. Each Diorama can contain various resources and any number of “Scenes”. Scenes can contain contain their own resources such as text, sound, 3D models and images.

The API does not use variables which means that the diorama needs to be constructed with the hierarchy in mind. One branch at a time. So after you create a diorama, you need to issue the subsequent commands to add resources to the diorama. These resources are active while the diorama is open. Once you issue a createScene command subsequent commands will apply to the Scene only.

Sound system

The diorama system has a 3D sound renderer that handles a range of sounds and sound types that enable you to paint a sound landscape appropriate to your scene.

There are different types of sounds in a diorama. Each of the sounds behave differently and it is helpful to understand the sound types for the best possible sound experience. When a sound scape is properly defined the various sound sources will fade in and fade out correctly without causing a cacophony of competing noise.

All sounds must be in mp3 format.

Background music

Background music can be applied to a diorama or a single scene. The music automatically repeats itself and keeps playing for the duration the diorama or scene is open. Backgrond music is played in stereo at a steady volume but is faded back when a voice plays or when a geolocated music source is approached.


The voice sound is typically of a tour guide that might tell the viewer about the scenery in front of them. The voice is played in stereo or mono (depending on sound file) and balanced on both speakers. The volume is constant. When the voice starts the background music and environment sound automatically fades back so the voice can be heard clearly.


The Environment sound is either associated with a specific 3D point or with an altitude layer. Environment sounds can be used to describe the landscape in sounds. Seagulls in port. Traffic sounds down-town or the yelling of children at a school. Environment sounds are faded back when a voice starts playing.

There are two types of environment sounds. The “environmentPointSound” is a sounce with it’s origin specified as an exact 3D point. The proximity of the camera to the point controls the volume of the sound where closer means louder. The orientation of the camera determines the balance of the sound between left and right speaker.

The “altitudeSound” is a sound that occurs between a minimum and maximum altitude. It can be used to create a traffic sound layer that fades to zero as the camera altitude increases but the volume will not be affected my latitude or longitude camera position changes.


The music sound is a variation on the environmentPointSound. It behaves the same in every way but as the camera approaches the music, the background music will be faded back. this is done to avoid two music sources clashing with each other.

System requirements

The diorama makes use of the Google Earth plugin and depending on the browser may require Flash to be in stalled as well for the sound. An installation link will automatically show if you don’t have the Google Earth plugin installed installed.

Embedding a diorama in your web-page

Embedding a diorama in your web page can be done is various ways.

Step one

Insert the following HTML code in the head section of your web-page:

<script type="text/javascript" src=""/></script>

This will load the diorama interface library that allows you to create a diorama and communicate with it.

Step two

Create a div in the body section of your web-page that will contain your diorama. You can decorate your div anyway you see fit as long as it contains an ID attribute. This is followed by some javascript that will dynamically create the HTML required for the diorama.

<div id="mycontainer"/> //with your own styling and size definition applied.
    PIA_Diorama.createInstance('mycontainer', true, loadscript);

    function loadscript(){
        PIA_Diorama.createDiorama('San Sebastian','',43.32354,-1.9883,0,20,70,600);

In this example the diorama is created in a div called “mycontainer” after which loadScript is called. In the load Script function you can place one of the may API calls that define the diorama, scenes and additional resources. You MUST call run only at the very end of the script. The meaning of the calls inside loadScript will be discussed elsewhere in this document.

Note that we did not use a loadProgress callback in this example because we are using the default interface which will already display load progress.


©2009 All Rights Reserved  •  by