Download Report

Reference Manual
Version 1.0.3.7193
Date: 25.04.2014
Legal Notice
This documentation and the software it describes are protected by copyright. 3DIS grants
the non-exclusive right to use the software, which is supplied exclusively in object code
format.
3DIS reserves all rights that are not expressly granted to the licensee. Without previous
approval in writing, and except for in cases permitted by law, it is particularly prohibited
to
copy, propagate or in any other manner make this documentation or this software
publicly accessible, or
process, disassemble, reverse engineer, translate, decompile or in any other manner
open the software and subsequently copy, propagate or make the software publicly
accessible in any other manner.
This documentation and software have been produced with all due care and checked for
correctness in accordance with the best available technology. 3DIS disclaims all liability
and warranties, whether express or implied, relating to the product’s quality, performance
or suitability for any given purpose which deviates from the performance specifications
contained in the product description. The licensee bears all risk in regard to hazards and
impairments of quality which may arise in connection with the use of this product.
3DIS will not be liable for damages arising directly or indirectly from the use of the manual
or the software, nor incidental or consequential damages, except in case of intent or gross
negligence. 3DIS expressly disclaims all liability for the loss of or damage to hardware or
software or data as a result of direct or indirect errors or destruction and for any costs
(including connection charges) related to the documentation and the software and due to
incorrect installations not performed by 3DIS itself.
The information in ths manual and the software are subject to change without notice for
the purpose of technical improvement.
© 3DIS GmbH 2013. All rights reserved.
3DIS GmbH
Konrad-Zuse-Straße 6
D - 46397 Bocholt
Visit 3DIS on the internet at www.3dis.de
Microsoft, Windows, Windows XP, Windows Vista, Windows 7, DirectX und ActiveX are
trademarks owned by Microsoft Coporation in the USA and/or other countries.
All other products and company names are trademarks of their respective owners.
Symbols und Highlighting
This symbol denotes useful tips, simplifying and/or speeding up
the application handling.
This symbol denotes important information or instructions that
must be followed in order to avoid malfunctioning.
This symbol marks file attachments, which can be extracted
from this document to the hard disk.
Italic
is used for identifiers of user interface elements.
Sans-serif
is used for names of objects and software modules.
Typewriter is used in code listings and excerpts of code listings in running
text, i.e. function names, as well as for paths and file names.
Underlined
are important terms upon their first occurrence, which are explained in greater detail in the glossary.
Foreword
This documentation is subdivided into the following main parts:
User’s Manual This part contains information useful to users of the WebViewer, such as
system requirements, installation instructions and configuration options.
Integration Manual In this part examples of integrating the WebViewer into existing web
applications are given. This part should be read by web developers intending to enrich an
existing application with visualization capabilities for 3D city models through integrating
the WebViewer plugin.
Technical Reference/Information This part covers technicals details not directly concerning the WebViewer but regarding the infrastructure required to set up a streaming
architecture for the WebViewer in a production environment. This part may be of interest
to system and network administrators.
Contents
I. User’s Manual
1
1. Introduction
1.1. About WebViewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2. Distinction between CityViewer and WebViewer . . . . . . . . . . . . . . .
1.3. System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2
2
3
3
2. Installation & Updates
2.1. WebViewer software modules . . . . . . . . . . . . . .
2.2. Software Installation . . . . . . . . . . . . . . . . . . .
2.2.1. Software distribution / Silent mode installation
2.2.2. WebViewer Updates . . . . . . . . . . . . . . .
2.3. Basic web integration . . . . . . . . . . . . . . . . . . .
2.3.1. ActiveX control . . . . . . . . . . . . . . . . . .
2.3.2. Firefox / Chrome extension . . . . . . . . . . .
.
.
.
.
.
.
.
5
5
6
6
6
7
7
8
.
.
.
.
9
9
10
11
11
3. Configuration
3.1. Proxy settings . . . . .
3.2. Cache . . . . . . . . .
3.3. Main menu & settings
3.4. Context menu . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4. Operational states
12
II. Integration Manual
13
5. Application integration
14
5.1. WebViewer.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.2. Embedding the WebViewer in a website . . . . . . . . . . . . . . . . . . . 14
5.3. Host page reloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6. Programming interface
19
6.1.
6.2.
6.3.
6.4.
Remarks . . . . . . . . . . . . . . . .
Events . . . . . . . . . . . . . . . . .
Loading models . . . . . . . . . . . .
Camera . . . . . . . . . . . . . . . .
6.4.1. Get current view . . . . . . .
6.4.2. Modify current view . . . . .
6.5. Settings . . . . . . . . . . . . . . . .
6.5.1. Display options . . . . . . . .
6.5.1.1. General options . . .
6.5.1.2. Compass & legend .
6.5.1.3. Environment . . . .
6.5.2. Movement & collision options
6.5.3. Model information . . . . . .
6.6. User interface . . . . . . . . . . . . .
6.6.1. Forms . . . . . . . . . . . . .
6.6.2. Tools . . . . . . . . . . . . . .
6.6.3. Menu & status . . . . . . . .
6.6.4. Toolbars . . . . . . . . . . . .
6.7. Miscellaneous . . . . . . . . . . . . .
6.7.1. Walls . . . . . . . . . . . . . .
6.7.2. Measuring control . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
19
19
20
23
23
24
26
27
27
28
30
30
31
32
32
33
33
34
34
35
35
7. Integration example
38
III. Technical Reference/Information
40
8. Hosting CCF models
41
8.1. Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.2. Streaming architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.3. MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Further information
43
Glossary
44
Part I.
User’s Manual
1. Introduction
1
Chapter 1
Introduction
1.1. About WebViewer
The WebViewer is a viewer for 3D city models, which have been compiled into a CompactCityFormat
(CCF) model.
The WebViewer is available as an ActiveX control, Firefox extension
and Chrome extension and thus can be used in Microsoft Internet
Explorer as well as Mozilla Firefox and Google Chrome.The WebViewer
exposes it’s capabilities through a programming interface accessible
from Javascript which allows the integration in any web application.
The WebViewer loads CCF models from a local disk or streams model
data on-demand from a web server. Based on this architecture, a model can be used
simultaneously on multiple workstations without the need of having the entire data stored
on a local disc on every workstation. A web server from which model data is streamed can
be located either in a private local area network or even in the public internet.
The WebViewer comes with the following basic features:
Free navigation through virtual 3D city models
Real-time streaming of model data from a web server over HTTP
Set walls to highlight parts of the model
Screenshots from the current 3D view
Shadow simulation
Stereo rendering
Measurement tool
– Measure distances, heights, reference points and areas in geo coordinates
2
1. Introduction
– Add additional attributes to measurements (e.g. description, comments)
– Export measurements as Shape files
Additional feature packages with domain specific tools required for specialist applications
may be added in the future.
1.2. Distinction between CityViewer and WebViewer
The CityViewer is a desktop application by 3DIS which also visualizes 3D city models
in CCF format. While sharing the same core streaming and visualization technology,
CityViewer and WebViewer are two separate software modules which can be installed
and used independently of each other. It is even possible to install both, CityViewer
and WebViewer, simulataneously. One can say, that the WebViewer is the smaller, but
web-enabled version of the CityViewer.
The following list shows commonalities and differences between both viewers:
The WebViewer has a Javascript API that allows it to be integrated into any web-
based application while the CityViewer is a standalone desktop application.
WebViewer and CityViewer share the same rendering- and streaming engine. Both
have similar user interfaces with only slight differences.
The CityViewer contains a lot more tools (e. g. a recorder tool or an object seach
tool), which aren’t availabe in the WebViewer. This is why the WebViewer is smaller
than the CityViewer.
1.3. System requirements
The following requirements must be met in order to ensure that the WebViewer is running
properly on a system.
Operating system Microsoft Windows XP (Service Pack 3 or higher), Microsoft Windows
Vista, Microsoft Windows 7
Framework
.NET Framework 2.0
Browser Microsoft Internet Explorer 9.0 (or higher) 32-bit version, Mozilla Firefox 10.0
(or higher), Google Chrome 20.0 (or higher)
3
1. Introduction
Processor
Memory
Minimum 2 GHz (multicore processor recommended)
Minimum 1 GB (2GB recommended)
Graphics adapter 3D graphics adapter (Direct3D9 support), minimum 128 MB dedicated
memory, Pixelshader ≥ 2.0 and Vertexshader ≥ 1.1
4
2. Installation & Updates
2
Chapter 2
Installation & Updates
2.1. WebViewer software modules
The WebViewer consists of a number of software modules, which, banded together, provide
the functionality required for streaming and displaying 3d city models as well as installation
routines and interfaces for various web browsers. The most essential modules are listed
and described below.
The WebViewerApplication is a .NET application containing the base functionality,
such as the rendering engine, the streaming engine as well as basic UI elements.
After the WebViewer has been installed on a system, the WebViewerApplication can
typically be found in C:\Program files\WebViewer as well as in the Windows
Software Control Panel.
The Internet Explorer Add-On is the WebViewerApplication registered as an ActiveX
Object.
The Firefox plugin provides an interface between the Firefox browser and the Web-
ViewerApplication.
The Chrome extension provides an interface between the Chrome browser and the
WebViewerApplication.
The Uninstaller removes all modules and uninstalls WebViewer from a system.
It is strictly recommended that users do not manually uninstall or remove
any of these modules. Should single WebViewer modules be missing or
running with different versions the WebViewer may not run properly. To
uninstall the WebViewer, use unistall.exe in the installation folder or
remove the application in Windows Software Control Panel.
5
2. Installation & Updates
2.2. Software Installation
All WebViewer software modules are installed with an Installer (WebViewerInstaller.exe).
This latest Installer can be downloaded from the 3DIS webpages. When a user visites
a webpage with WebViewer, he is usually asked to download that file and install it.
The Installer needs Administrator privileges and installs all software modules mentioned
above.
2.2.1. Software distribution / Silent mode installation
WebViewercan be installed on client machines with Software deployment services. For this
purpose WebViewerInstaller can install WebViewer in Silent mode. To turn on Silent mode
installation, use the /S switch as argument to the Installer.
WebViewerInstaller.exe /S
When using /S Silent mode installation, make sure to run the installer
with administrator privileges.
A return value of 0 indicates a successful installation.
2.2.2. WebViewer Updates
How WebViewer deals with new versions can be handled in different ways. With default
settings, WebViewer will not search for updates by itself. It’s up to the integrating Webpage to ask WebViewer to search for updates on a 3DIS server. This is done by calling
CheckForWebViewerUpdate(). If a new WebViewer version is available, a window
with a download link to the new Installer will be shown. The default settings can be
changed by a user in the “Help → Updates”-menu.
To avoid any WebViewer Updates, follow these two steps:
Make sure a user can not search manually for updates by setting the /disableupdates
switch during installation. This will disable WebViewers “Help → Updates”-menu
item.
Integrate WebViewer in a Webpage which never calls CheckForWebViewerUpdate()
6
2. Installation & Updates
2.3. Basic web integration
The following chapter outlines the embedment of the installation package in a simple
website.
It is recommended to use browser sniffing in order to provide both
installation packages in a single website. At this point, however, no
example of a browser sniffing technique is given.
Implementors of custom WebViewer integrations are free to take a deeper
look into the full integration example referred to in a later chapter of
this documentation to get an idea of how a browser sniffing technique
may be applied.
2.3.1. ActiveX control
The listing below illustrates how to embed the WebViewer ActiveX control in a website.
The example assumes that the cabinet file is located in the same directory as the website.
1
2
3
4
5
6
7
8
9
10
11
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/
xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>WebViewer</title>
</head>
<body>
<OBJECT ID="WebViewerControl" style="width:640px;height:360px;" CLASSID="CLSID:0803
DD33-04F2-41F4-8795-6FAF8AC6252D" CODEBASE="WebViewerInstaller.exe#version=X,X,X,
XXXX"> 
</OBJECT>
If WebViewer is not installed, download <a href="WebViewerInstaller.exe">WebViewer
</a> and install it.
</body>
</html>
Listing 2.1: Embedment of the WebViewer ActiveX control in a website
The WebViewer is only available as a 32-bit version. It is recommended
to use a browser sniffing approach to determine if a user is able to use
the WebViewer in his version of the Internet Explorer instance.
When an update of the ActiveX control is released, the version number in the codebase
attribute of the object tag has to be updated and the WebViewerControl_x86.cab
7
2. Installation & Updates
file needs to be replaced with the new version. Each time a user navigates to the website,
the version number is compared to the version number of the installed ActiveX control.
If the version number denoted in the website is higher than the version number of the
installed ActiveX control, the installation process is relaunched to update the control.
In case the automatic installation of the WebViewer fails for whatever reason, an installer
allowing for a manual (though guided) installation is available. How this alternative
installation mechanism can best be integrated as a fallback solution is outlined in a later
chapter.
2.3.2. Firefox / Chrome extension
The listing below gives an example of how to integrate the WebViewer extension into a
website.
1
2
3
4
5
6
7
8
9
10
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/
xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>WebViewer</title>
</head>
<body>
<embed id=’WebViewerControl’ type=’application/webviewer-plugin’ width=’640’ height
=’360’ />
If WebViewer is not installed, download <a href="WebViewerInstaller.exe">WebViewer</
a> and install it.
</body>
</html>
Listing 2.2: Embedment of the WebViewer Firefox / Chrome extension in a website
8
3. Configuration
3
Chapter 3
Configuration
3.1. Proxy settings
From within corporate local area networks internet
access quite often is only possible through a proxy
server. To handle such network constellations, the
WebViewer offers a number of configuration options
reflecting the configuration options that can also be
found in the most commonly used browsers.
Choosing the Use system proxy option causes the WebViewer to use the proxy settings configured through
the Windows control panel and Internet Explorer. Alternatively, custom proxy settings can be provided
by the user.
Proxy servers in corporate networks usually require
a client authentication in order to process requests.
Figure 3.1.: Proxy configuration di- The user can specify a username and password to
alog
be used for authentication or, by enabling the Use
Windows credentials option, instruct the WebViewer
to use the username and password of the current user’s Windows login for authentication.
9
3. Configuration
Using Windows login information for the proxy authentication is only
possible, if the authentication process between a client running a WebViewer instance and the proxy server is secured by an encryption scheme.
If an unencrypted authentication process is used (because the proxy
server only offers an unecrypted authentication scheme), the Windows
operating system denies any authentication attempt based on a general
security policy prohibiting the transmission of user credentials over an
unsecure channel.
The proxy configuration can be tested by entering the address of a website located on
a server in the target network into the Address text field in Test configuration. After
activating the Test button, the WebViewer tries to connect to the website. The result of
the connection test is printed to the read-only protocol text field.
3.2. Cache
Model data streamed on-demand from a web server is
stored in a cache on the hard disk before it is displayed
by the WebViewer. Thus, the loading speed is significantly
increased the next time the same model data needs to be
loaded, since it does not have to be downloaded over a
potentially slow network connection again. Furthermore,
the network traffic is reduced because each model part
only has to be downloaded once. The WebViewer for
Internet Explorer uses a different cache than the version Figure 3.2.: Cache configurafor Firefox.
tion dialog
The cache configuration dialog displays the current size
of the cache and the directory on the hard disk it is stored in. The user can choose a
different directory for storing the cached data in or empty the current cache directory if it
has grown to large.
If a model is currently loaded, emptying the cache and relocating the
cache directory are not possible.
10
3. Configuration
3.3. Main menu & settings
Figure 3.3.: Main menu
The WebViewer main menu can either be shown or in
hidden state. The menu gives configuration options
on several forms and tabs and can also be queried as
well as set through the WebViewer’s Javascript API
(see chapter 6).
To toggle the main menu, open the context menu
through right clicking in the display area while holding down the Ctrl key or set the visibility of the main menu programmatically.
3.4. Context menu
The context menu gives the user easy access to the WebViewer’s configuration dialogs. The context menu can be
opened through right clicking in the display area while holding
down the Ctrl key. The Show menu entry can be programmatically disabled to avoid that users can change any options
concerning the models appearance.
Figure 3.4.: Context menu
11
4. Operational states
4
Chapter 4
Operational states
After the WebViewer has been initialized, it can be in one of a number of operational states.
The current state is indicated by the image displayed in the center of the WebViewer’s
display area. Table 4.1 lists all possible states with their respective images.
State
Description
Image
Ready
The WebViewer has been successfully initialized and is ready to load a model.
The model loading process has been triggered and the WebViewer is currently fetching and preprocessing model metadata information.
If model loading fails, the WebViewer returns
to the Ready state. Otherwise the model is
rendered in the display area.
CacheRecovery If the WebViewer was (for whatever reason)
closed in an unexpected way, the integrity
of the model cache will ensured on the next
startup. If a model should be loaded during
this state, it will be shown after the recovery
has finished.
Locked
When multiple instances of the WebViewer
are running simultaneously (e. g. in multiple
browser windows) all but the first instance
that has been started are in the Locked
state.
In this state all function calls to the WebViewer through it’s Javascript API will have
no effect.
Incomplete
In Firefox or Chrome the WebViewer is in
Incomplete state if the plugin is installed,
but does not have access to the underlaying
WebViewerApplication. Usually this happens,
because the installation failed.
Loading
Loaded /
Streaming
As soon as you see an horizon, the model
was opened successful and data streaming
started. The 3D model should be appear in a
few seconds and mouse/keyboard input was
enabled to start exploring the model.
Table 4.1.: The WebViewer’s operational states
12
Part II.
Integration Manual
Application integration
14
5.1. WebViewer.js
Based on the embedment of the WebViewer in a website, which has been already described in chapter 2, this chapter further details the
integration of the WebViewer into an existing web application by illustrating the use browser sniffing and of event handlers, which is
critical for an integration to be successful. The WebViewer and BrowserDetect classes can be found in WebViewer.js
file, which also
contains all constant definitions as Javascript values to use them in your application.
5.2. Embedding the WebViewer in a website
The listing below revisits the embedment of the WebViewer in a website using a simple browser sniffing approach. A few lines of Javascript
code are utilized to detect
whether a user is using Internet Explorer, Firefox, or Chrome.
5. Application integration
5
Chapter 5
whether the browser, in case Internet Explorer is used, is running in 64-bit mode.
whether the browser, in case Firefox or Chrome are used, is equipped with the required plugin.
Should the automatic installation of the WebViewer fail in Internet Explorer, a link to an installer allowing for a manual (though guided)
installation is displayed as a fallback.
If the page loads, the WebViewer is initialized and events are attached.
19
20
21
22
23
24
25
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>WebViewer</title>
</head>
<body>
<div style="width:640px;height:360px;">
<script src="WebViewer.js" type="text/javascript"></script>
<script type="text/javascript">
try {
var WebViewerExePath = "WebViewerInstaller.exe";
if(BrowserDetect.OS == "Windows") {
if (BrowserDetect.browser == "Firefox" || BrowserDetect.browser == "Chrome") {
if (BrowserDetect.WebViewerPresent == true)
document.write("<embed id=’WebViewerControl’ type=’application/webviewer-plugin’ width=’100%’ height=’100%’ style=’border: thin
solid #408080;’ />");
else {
document.write("Diese Seite benötigt ein Plugin.");
document.write("Um das 3D-Modell betrachten zu können, laden Sie das WebViewer Plugin herunter und installieren Sie
dieses.");
document.write("");
document.write("<a href=\"WebViewerExePath\" >Laden Sie die WebViewer Installationsdatei hier herunter.</a>".
replace("WebViewerExePath", WebViewerExePath));
document.write("");
}
5. Application integration
15
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
26
27
28
29
30
31
32
33
34
function onInitializationComplete() {
// Do not call any WebViewer functions until this event was fired.
// This is the place to set some default values
}
function onInitializationFailed() {
alert(’Initialization failed’);
}
function onModelLoaded() {
5. Application integration
16
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
} else if (supportIE && (BrowserDetect.browser == "IE" || BrowserDetect.SupportsActiveX)) {
var cabVersionWithComma = WEBVIEWER_VERSION.replace(/\./g, ",");
if (BrowserDetect.CPU == "x86"){
document.write("<object id=’WebViewerControl’ style=’width:100%;height:100%;border:thin solid #408080;’ classid=’CLSID:0803DD33
-04F2-41F4-8795-6FAF8AC6252D’ codebase=’WebViewerExePath’#version=X,X,X,XXXX’>".replace("WebViewerExePath", WebViewerExePath)
.replace("X,X,X,XXXX", cabVersionWithComma));
document.write("Diese Seite benötigt ein Plugin.");
document.write("Diese Seite benötigt ein Plugin.");
document.write("Um das 3D-Modell betrachten zu können, laden Sie das WebViewer Plugin herunter und installieren Sie
dieses.");
document.write("");
document.write("<a href=\"WebViewerExePath\" >Laden Sie die WebViewer Installationsdatei hier herunter.</a>".
replace("WebViewerExePath", WebViewerExePath));
document.write("");
document.write("</object>");
} else {
document.write("Bitte verwenden Sie für diese Seite die 32 Bit Version des Internet Explorers.");
}
} else {
document.write("WebViewer ist für Ihren Browser leider derzeit nicht verfügbar.");
}
} else {
document.write("WebViewer ist für Ihr Betriebssystem leider derzeit nicht verfügbar.");
}
} catch (err) {
alert(err);
}
// do something else here. E.g. enable UI elements
}
//Initialize WebViewer and regeister events
window.onload = function () {
try {
//Initialize with the id we used above
if (!WebViewer.Initialize(’WebViewerControl’, true)) {
//When reaching here, WebViewer was not embedded/installed correctly.
return;
}
// Register events
WebViewer.RegisterEvent(’ModelLoadedEvent’, onModelLoaded);
//Add Initialization events as last
WebViewer.RegisterEvent(’InitializationCompleteEvent’, onInitializationComplete);
WebViewer.RegisterEvent(’InitializationFailedEvent’, onInitializationFailed);
} catch(err) {
alert(err);
}
};
</script>
</div>
</body>
</html>
Listing 5.1: Embedment of the WebViewer in a website using browser sniffing
A complete list of events published by the WebViewer is given in section 6.2.
5. Application integration
17
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
5.3. Host page reloading
Upon reloading the web page the WebViewer is hosted in, an instance of the WebViewer will lose all application state information. After the
reload the WebViewer will be in the Ready state (see chapter 4). Therefore it is recommended that partial page updates mechanisms be
used to update a host page.
5. Application integration
18
Programming interface
19
6.1. Remarks
The WebViewer exposes it’s functionality through a Javascript API. This chapter lists and describes all functions of this API. All functions
are to be called directly on the WebViewer scripting object.
6.2. Events
A website can register a number event handlers with the hosted the WebViewer instance, thereby receiving notifications of certain events
that can either originate from one of the internal tools or signal general state changes of the WebViewer. The way in which event handlers
are registered is different for Internet Explorer and Firefox.
Event
Paramater [type]
Description
6. Programming interface
6
Chapter 6
InitializationCompleteEvent()
Indicates that a the hosted the WebViewer instance has successfully been initialized and is ready to be
used. Until this event has fired, no function besides the event handler registration should be called on the
WebViewer instance.
InitializationFailedEvent()
Indicates that the WebViewer could not be initialized. Additional information on the reason for the intialization failure may be communicated through the log file.
ModelLoadedEvent()
Indicates that a CCF model has been loaded successfully.
ModelLoadingFailedEvent()
Additional information on the reason for the failure that occured during loading may be communicated
through the log file.
Indicates that a model has been closed. Once this event has fired, a new model can be opened.
ModelClosedEvent()
dX [double]
dY [double]
dZ [double]
fAngle [float]
Indicates that the camera’s position and/or orientation has been modified. The parameters passed to this
event represent the X, Y and Z component of the camera’s position and the geographic direction of the
camera angle rotated clockwise from north (N
0, E
90, S
180, W
270).
ObjectSelectedEvent(...)
strId [string]
This event is fired when the user selects a 3D object using the mouse. The parameters passed to this event
are the unique identifier of the feature.
LegalNoticeEvent(...)
strLegalNotice
[string]
This event is fired after a model has been loaded which contains a legal notice which should be shown to
the user. If the page does not register this event and a model contains a legal notice text, WebViewer will
open an internal window. strLegalNotice may be plain text, HTML formatted text or a HTML page.
MeasurementStarted(...)
iIndex [int]
This event is fired when the user started a measurement.
MeasurementFinished(...)
iIndex [int]
This event is fired when the user finishes a measurement.
MeasurementDeleted(...)
iIndex [int]
This event is fired when a measurement is removed.
CameraModifiedEvent(...)
This event is fired continuously while the user is measuring.
The following functions can be used to load and close a CCF model.
Paramater [type]
Description
6. Programming interface
20
iIndex [int]
6.3. Loading models
Function
This event is fired when the user cancels a running measurement.
MeasurementCanceled()
MeasurementUpdated(...)
Loads a model pointed to by the passed strUrl parameter. The parameter can contain a HTTPURL pointing to a model on any web server. Likewise the parameter can be a path to a model on
a local disk.
If a model is already loaded, the previously loaded model will be automatically closed.
Loading a password protected model using this function will open a window and ask the user for
credentials.
LoadModelWithStart(...)
strUrl [string]
dPosX [double]
dPosY [double]
dPosZ [double]
Loads a model pointed to by the passed strUrl parameter. The parameter can contain a HTTPURL pointing to a model on any web server. Likewise the parameter can be a path to a model on
a local disk.
dPosX, dPosY and dPosZ represent the X, Y and Z components of the intial camera position. If
the Z component is negative the WebViewer will use it as a relative ground height and attempts to
compute an absolute Z value for the given start coordinate.
If a model is already loaded, the previously loaded model will be automatically closed.
Loading a password protected model using this function will open a window and ask the user for
credentials.
LoadModelWithStartTarget(...)
strUrl [string]
dPosX [double]
dPosY [double]
dPosZ [double]
dTargetX [double]
dTargetY [double]
dTargetZ [double]
Loads a model pointed to by the passed strUrl parameter. The parameter can contain a HTTPURL pointing to a model on any web server. Likewise the parameter can be a path to a model on
a local disk.
dPosX, dPosY and dPosZ represent the X, Y and Z components of the intial camera position. If
the Z component is negative the WebViewer will use it as a relative ground height and attempts to
compute an absolute Z value for the given start coordinate.
dTargetX, dTargetY and dTargetZ represent the X, Y and Z components of the intial camera
target. If the Z component is negative the WebViewer will use it as a relative ground height and
attempts to compute an absolute Z value for the given target coordinate.
If a model is already loaded, the previously loaded model will be automatically closed.
Loading a password protected model using this function will open a window and ask the user for
credentials.
LoadModelWithFocusBox(...)
strUrl [string]
dBoxCenterX [double]
dBoxCenterY [double]
dBoxCenterY [double]
dBoxWidth [double]
dBoxDepth [double]
dBoxHeight [double]
Loads a model pointed to by the passed strUrl parameter. The parameter can contain a HTTPURL pointing to a model on any web server. Likewise the parameter can be a path to a model on
a local disk.
dBoxCenterX, dBoxCenterY,dBoxCenterZ and dBoxWidth, dBoxDepth, dBoxHeight describe a 3D axis-aligned boundingbox at which the camera initialy will look at.
If a model is already loaded, the previously loaded model will be automatically closed.
Loading a password protected model using this function will open a window and ask the user for
credentials.
6. Programming interface
strUrl [string]
21
LoadModel(...)
strUrl [string]
strWallPoints
[string]
fWallHeight [float]
fWallWidth [float]
iRed [int]
iGreen [int]
iBlue [int]
Loads a model pointed to by the passed strUrl parameter. The parameter can contain a HTTPURL pointing to a model on any web server. Likewise the parameter can be a path to a model on
a local disk.
strWallPoints defines a wall through 2D coordinate pairs (X Y). Wall coordinates need to match
the pattern “c1_x c1_y c2_x c2_y ...“ (double values with decimal point separated by whitespaces). strWallHeight and strWallWidth define the height and thickness of each wall element.
Values iRed iGreen and iBlue define the wall color.
The camera will be positioned southwards from the wall and focuses it in north direction.
If a model is already loaded, the previously loaded model will be automatically closed.
Loading a password protected model using this function will open a window and ask the user for
credentials.
LoadModelWithWallStart(...)
strUrl [string]
strWallPoints
[string]
fWallHeight [float]
fWallWidth [float]
iRed [int]
iGreen [int]
iBlue [int]
dPosX [double]
dPosY [double]
dPosZ [double]
Loads a model pointed to by the passed strUrl parameter. The parameter can contain a HTTPURL pointing to a model on any web server. Likewise the parameter can be a path to a model on
a local disk.
strWallPoints defines a wall through 2D coordinate pairs (X Y). Wall coordinates need to match
the pattern “c1_x c1_y c2_x c2_y ...“ (double values with decimal point separated by whitespaces). strWallHeight and strWallWidth define the height and thickness of each wall element.
Values iRed iGreen and iBlue define the wall color.
dPosX, dPosY and dPosZ represent the X, Y and Z components of the intial camera position. If
the Z component is negative the WebViewer will use it as a relative ground height and attempts to
compute an absolute Z value for the given start coordinate.
If a model is already loaded, the previously loaded model will be automatically closed.
Loading a password protected model using this function will open a window and ask the user for
credentials.
6. Programming interface
22
LoadModelWithWall(...)
23
strUrl [string]
strWallPoints
[string]
fWallHeight [float]
fWallWidth [float]
iRed [int]
iGreen [int]
iBlue [int]
dPosX [double]
dPosY [double]
dPosZ [double]
dTargetX [double]
dTargetY [double]
dTargetZ [double]
Function
Return type
Description
CloseModel()
int
Attempts to close a currently loaded model. A return value of 1 indicades, that the model is closed. A return
value of 0 indicates, that the user canceled the closing procedure.
IsModelLoaded()
int
A return value of 1 indicates, that a model is loaded in the WebViewer. If the return value is 0, no model is
currently loaded.
6.4. Camera
6.4.1. Get current view
Function
Return type
Description
GetCameraPositionX()
double
Returns cameras current X position (easting) coordinate.
GetCameraPositionY()
double
Returns cameras current Y position (northing) coordinate.
GetCameraPositionZ()
double
Returns cameras current Z position (height) coordinate.
6. Programming interface
Loads a model pointed to by the passed strUrl parameter. The parameter can contain a HTTPURL pointing to a model on any web server. Likewise the parameter can be a path to a model on
a local disk.
strWallPoints defines a wall through 2D coordinate pairs (X Y). Wall coordinates need to match
the pattern “c1_x c1_y c2_x c2_y ...“ (double values with decimal point separated by whitespaces). strWallHeight and strWallWidth define the height and thickness of each wall element.
Values iRed iGreen and iBlue define the wall color.
dPosX, dPosY and dPosZ represent the X, Y and Z components of the intial camera position. If
the Z component is negative the WebViewer will use it as a relative ground height and attempts to
compute an absolute Z value for the given start coordinate.
dTargetX, dTargetY and dTargetZ represent the X, Y and Z components of the intial camera
target. If the Z component is negative the WebViewer will use it as a relative ground height and
attempts to compute an absolute Z value for the given target coordinate.
If a model is already loaded, the previously loaded model will be automatically closed.
Loading a password protected model using this function will open a window and ask the user for
credentials.
LoadModelWithWallStartTarget(...)
float
Returns cameras current X direction (from normalized direction vector (X, Y, Z)).
GetCameraDirectionY()
float
Returns cameras current Y direction (from normalized direction vector (X, Y, Z)).
GetCameraDirectionZ()
float
Returns cameras current Z direction (from normalized direction vector (X, Y, Z)).
GetCameraTargetX()
double
Returns cameras current X (easting) target coordinate (CameraTargetX = CameraPositionX + 10 *
CameraDirectionX).
GetCameraTargetY()
double
Returns cameras current Y (northing) target coordinate (CameraTargetY = CameraPositionY + 10 *
CameraDirectionY).
GetCameraTargetZ()
double
Returns cameras current Z (height) target coordinate (CameraTargetZ = CameraPositionZ + 10 *
CameraDirectionZ).
IsCameraMoving()
int
Returns if camera is currently moving. This return 1 if the user moves the camera via mouse/keyboard
manually or if camera moves during an automated flight.
GetCameraHeightAboveGround()
double
Returns cameras height above ground level (terrain). Return value can be negative if camera is below
ground. Return 0 if ground level is unknown, e.g. because there is no terrain loaded at the moment.
6.4.2. Modify current view
24
Function
Paramater [type]
Description
SetCameraDirection(...)
fDirectionX [float]
fDirectionY [float]
fDirectionZ [float]
Sets the camera direction vector.
SetCameraDirectionFromNorth(...)
fYaw [float]
fPitch [float]
Sets the cameras direction vector relative to north.
positive yaw angle: clockwise rotation
positive pitch angle: upwards rotation
Angles are in degree (0-360 ).
SetCameraPosition(...)
dPositionX [double]
dPositionY [double]
dPositionZ [double]
Sets the camera position to the given geo coordinates. If the dPositionZ component is negative,
the WebViewer will interpret it as a relative ground height and attempts to compute an absolute
Z value for the given coordinate.
SetCameraPositionString(...)
sPositionX [string]
sPositionY [string]
sPositionZ [string]
(same as SetCameraPosition)
NavigateToCameraTarget(...)
dTargetX [double]
dTargetY [double]
dTargetZ [double]
Animated camera flight to a position focussing the target coordinate. If the dTargetZ component is negative the WebViewer will interpret it as a relative ground height and attempts to
compute an absolute Z value for the given coordinate. If there is a building at that coordinate,
the building will be focused.
°
6. Programming interface
GetCameraDirectionX()
dPositionX [string]
dPositionY [string]
dPositionZ [string]
(same as NavigateToCameraTarget)
NavigateToCameraPosition(...)
dPositionX [double]
dPositionY [double]
dPositionZ [double]
Animated camera flight to the given geocoordinates. If the dPositionZ component is negative
the WebViewer will interpret it as a relative ground height and attempts to compute an absolute
Z value for the given coordinate.
NavigateToCameraPositionString(...)
dPositionX [string]
dPositionY [string]
dPositionZ [string]
(same as NavigateToCameraPosition)
NavigateToCameraPositionTarget(...)
dPositionX [double]
dPositionY [double]
dPositionZ [double]
dTargetX [double]
dTargetY [double]
dTargetZ [double]
Animated camera flight to the position focussing the target coordinate. If the dTargetZ component is negative the WebViewer will interpret it as a relative ground height and attempts to
compute an absolute Z value for the given coordinate. If there is a building at that coordinate,
the building will be focused. The position values will be ignored in that case.
25
NavigateToCameraPositionTargetString(...)
sPositionX [double]
sPositionY [double]
sPositionZ [double]
sTargetX [double]
sTargetY [double]
sTargetZ [double]
(same as NavigateToCameraPositionTarget)
SetCameraHeightAboveGround(...)
fHeight [float]
Sets the cameras position Z value relative to the ground height.
SetCameraTarget(...)
dTargetX [double]
dTargetY [double]
dTargetZ [double]
Sets the cameras direction vector to focus the given coordinate. If the dTargetZ component is
negative, the WebViewer will interpret it as a relative ground height and attempts to compute
an absolute Z value for the given coordinate.
SetCameraTargetString(...)
dTargetX [string]
dTargetY [string]
dTargetZ [string]
(same as SetCameraTarget)
RotateLeftRight(...)
fAngle [float]
Rotates the cameras direction vector to left / right (yaw).
RotateUpDown(...)
fAngle [float]
Rotates the cameras direction vector upwards / downwards (pitch).
MoveForwardBackward(...)
fDistance [float]
Moves the cameras position forward / backwards (walk in current camera direction; keep current
camera height).
MoveLeftRight(...)
fDistance [float]
Moves the cameras position to left / right (strafe with current camera direction; keep current
camera height).
MoveUpDown(...)
fDistance [float]
Modifys the camera positions Z value (keeps current position and direction. Only modifys the
cameras height).
6. Programming interface
NavigateToCameraTargetString(...)
ZoomInOut(...)
fDistance [float]
Fly forward / backward (moves camera and keep cameras direction; modifying the cameras
position to zoom in current look direction).
Sets the camera position and direction to the sessions initial start position
ResetCamera()
6.5. Settings
The WebViewer exposes a number of configuration options through the functions listed in the below table. Each configuration option is
accessed through a unique identifier which corresponds to one of the following types:
a boolean value
a floating point value
26
a color represented by a red, green, blue and alpha component ranging from 0 - 255
Mutator/accessor function
Paramater [type]
SetInteger(...)
iId [int]
value [int]
GetInteger(...)
iId [int]
SetBool(...)
iId [bool]
value [bool]
GetBool(...)
iId [int]
SetFloat(...)
iId [int]
value [float]
GetFloat(...)
iId [int]
SetColor(...)
iId [int]
iR [int]
iG [int]
iB [int]
iAlpha [int]
Return type
Description
Sets a integer value for the configuration option identified by iId.
This function can also used for boolean configuration options where 0 is false and 1 (and
all other values != 0) is true
int
Returns the integer value of the configuration option identified by iId.
This function can also be used for boolean configuration options and returns 0 as false
and 1 as true.
Sets a boolean value for the configuration option identified by iId.
bool
Returns the boolean value of the configuration option identified by iId.
Sets a floating point value for the configuration option identified by iId.
float
Returns the floating point value of the configuration option identified by iId.
Sets a RGB color values between 0-255 for the configuration option identified by iId.
iAlpha is the alpha value where 0 is fully transparent and 255 is fully opaque.
6. Programming interface
an integer value
GetColorRed(...)
iId [int]
int
Returns the red component (0-255) of the color associated with the configuration option
identified by iId.
GetColorGreen(...)
iId [int]
int
Returns the green component (0-255) of the color associated with the configuration
option identified by iId.
GetColorBlue(...)
iId [int]
int
Returns the blue component (0-255) of the color associated with the configuration option
identified by iId.
GetColorAlpha(...)
iId [int]
int
Returns the alpha component (0-255) of the color associated with the configuration
option identified by iId. A value of 0 is fully transparent and 255 is fully opaque.
27
1
2
3
4
5
// set configuration variable value
WebViewer.SetFloat(CS_OPTIONS_CAMERA_ANGLE, 45);
// query configuration variable value
var angle = WebViewer.GetFloat(CS_OPTIONS_CAMERA_ANGLE);
A Javascript file containing all configuration options and their respective integral values as Javascript constants is attached
documentation.
to this
6.5.1. Display options
The following identifier constants allow to programmatically set or query different display option values. They are grouped in different
types of settings which correspond to the different tabs in the display option configuration dialog.
6.5.1.1. General options
Option ID (iId)
mutator/accessor
Description (value)
6. Programming interface
The available options and their identifier constants are listed and explained in the following chapters. The default usage to set/query
settings is similar to:
CS_OPTIONS_CAMERA_ANGLE
SetFloat/GetFloat
Use this ID to set/query the currently used camera angle (1-120 degree). The default
value is 45.
CS_OPTIONS_CAMERA_RANGE
SetFloat/GetFloat
Use this ID to set/query the currently used camera range of sight (1 - 3500 meter).
CS_OPTIONS_MULTISAMPLE
SetInteger/GetInteger
Use this ID to set/query the currently used multisample / antialiasing level
(0,1,2,4,8,... maximum supported level on device graphics adapter). If the value exceeds the maximum supported level, the maximum level will be used. If a level is
not supported on device graphics adapter, the next less supported level will be used.
CS_OPTIONS_UNTEXTURED_SURFACE_COLOR
SetColor/GetColor
Use this ID to set/query the currently used default color which is used for surfaces
with no material and no texture.
CS_OPTIONS_CAMERA_LIGHT_ENABLE
SetBool/GetBool
Use this ID to set/query if the camera light is currently enabled.
CS_CAMERA_MODE
SetInteger/GetInteger
Use this ID to set/query the currently used camera mode.
28
CS_SURFACE_ORIENTATION
SetInteger/GetInteger
SetInteger/GetInteger
3 = Pedestrian view
1 = show front- and back faces (default)
2 = show only front faces
3 = show only back faces
Use this ID to set/query the currently used fill mode.

6.5.1.2. Compass & legend
2 = 3D view
Use this ID to set/query the currently used orientation mode.

CS_SURFACE_FILLMODE
1 = 2D view
1 = point rendering
2 = wireframe rendering
3 = solid rendering (default)
6. Programming interface

Option ID (iId)
mutator/accessor
Description (value)
CS_UI_COMPASS_SCALEMODE
SetInteger/GetInteger
Use this ID to set/query the currently used compass scale mode. The
CS_UI_COMPASS_SCALEMODE describes how the value, which has to be set via
CS_UI_COMPASS_SCALEFACTOR, will be interpreted. The allowed values are:

0 = No scale (default)
1 = Use SCALEFACTOR as factor
2 = Use SCALEFACTOR as percent window width
3 = Use SCALEFACTOR as percent window height
SetFloat/GetFloat
Use this ID to set/query the currently used compass SCALEFACTOR. The factor has different effects corresponding to the current mode, which is set via
CS_UI_COMPASS_SCALEMODE.
CS_UI_COMPASS_PRIORITY
SetInteger/GetInteger
Use this ID to set/query the currently used compass priority. The allowed values
are:
29

CS_UI_LEGEND_SCALEMODE
SetInteger/GetInteger
1 = Use the models integrated compass, if available (default)
2 = Use the user defined compass
3 = Use WebViewer default compass
Use this ID to set/query the currently used legend scale mode. The
CS_UI_LEGEND_SCALEMODE describes how the value, which has to be set via
CS_UI_LEGEND_SCALEFACTOR, will be interpreted. These values are allowed:

0 = No scale (default)
1 = Use SCALEFACTOR as factor
2 = Use SCALEFACTOR as percent window width
3 = Use SCALEFACTOR as percent window height
6. Programming interface
CS_UI_COMPASS_SCALEFACTOR
CS_UI_LEGEND_SCALEFACTOR
SetFloat/GetFloat
Use this ID to set/query the currently used legend SCALEFACTOR. The factor has different effects corresponding to the current mode, which is set via
CS_UI_LEGEND_SCALEMODE.
CS_UI_SHOW_COMPASS
SetBool/GetBool
Use this ID to set/query if a compass is currently shown.
CS_UI_SHOW_LEGEND
SetBool/GetBool
Use this ID to set/query if a legend is currently shown.
Option ID (iId)
mutator/accessor
Description (value)
CS_ENVIRONMENT_TYPE
SetInteger/GetInteger
Use this ID to set/query the currently used background environment.
6.5.1.3. Environment
0 = Atmosphere (default)
1 = Clouds
30
CS_ENVIRONMENT_FOGENABLE
SetBool/GetBool
Use this ID to set/query if fog is currently used.
CS_ENVIRONMENT_CLOUDCOVER
SetFloat/GetFloat
Use this ID to set/query the currently used cloud cover value. Use values between
-1 (no clouds) and 1 (full clouds).
CS_ENVIRONMENT_BRIGHTNESS
SetInteger/GetInteger
Use this ID to set/query the currently used environment brightness. Use values
between 0-255.
CS_ENVIRONMENT_SUN_ENABLED
SetBool/GetBool
Use this ID to set/query if sun light is currently enabled.
CS_ENVIRONMENT_SUN_BYSYSTEMTIMEENABLED
SetBool/GetBool
Use this ID to set/query the currently used date/time to affect the sunlight.

CS_ENVIRONMENT_SUN_TIMESTAMP
SetInteger/GetInteger
true = Use date and time from client machine
false = Use value from CS_ENVIRONMENT_SUN_TIMESTAMP
Use this ID to set/query the currently used date / time for sunlight. Value is a UNIX
timestamp (01.01.1970 00:00:00 = 0 seconds).
6.5.2. Movement & collision options
The following identifier constants allow to programmatically set or query different display option values. They correspond to the values in
the camera control and collision detection configuration dialog.
6. Programming interface

mutator/accessor
Description (value)
CS_MOVEMENT_LOOK_SENSITIVITY
SetInteger/GetInteger
Use this ID to set/query the currently used mouse input sensitivity for looking. Use
values between 1-100.
CS_MOVEMENT_MOVE_SENSITIVITY
SetInteger/GetInteger
Use this ID to set/query the currently used mouse / keyboard input sensitivity for
moving. Use values between 1-100.
CS_MOVEMENT_DOUBLECLICK_FOCUS_BUILDING
SetBool/GetBool
Use this ID to set/query if on doubleclick the view will automatically focus the
clicked building.
CS_MOVEMENT_DOUBLECLICK_GOTO_POINT
SetBool/GetBool
Use this ID to set/query if on doubleclick the view will automatically move to the
clicked location.
CS_MOVEMENT_ANIMATION_TIME
SetInteger/GetInteger
Use this ID to set/query the currently used time to use for animated camera travelling. Time is in milliseconds (default = 1000ms).
CS_MOVEMENT_ORIENTATE_NORTH
SetBool/GetBool
Use this ID to set/query if currently the view will be orientated to north after an
animated camera travelling ends.
CS_MOVEMENT_PEDESTRIAN_HEIGHT
SetFloat/GetFloat
Use this ID to set/query the currently used height for pedestrian view mode. Height
is in meter (default = 1.80m).
CS_COLLISION_ENABLED
SetBool/GetBool
Use this ID to set/query if currently the camera can move through walls or other
geometry.
CS_COLLISION_DISTANCE
SetFloat/GetFloat
Use this ID to set/query the currently used value for maximal distance of clickable
objects (0-3500m). If no object should be clickable, set this value to 0 and gain more
performance through using less memory.
6.5.3. Model information
The following identifier constants allow to programmatically query information about the current loaded model.
Option ID (iId)
accessor
Description (value)
CS_MODEL_ISLOADED
GetBool
Use this ID to query if a model is currently loaded
CS_MODEL_SRID or CS_MODEL_EPSG
GetInteger
Use this ID to query the currently SRID / EPSG code. Both constants return the
same value.
CS_MODEL_NAME
GetString
Use this ID to query the current model name (name in status bar)
CS_MODEL_DESCRIPTION
GetString
Use this ID to query the current model desciption (description in status bar)
6. Programming interface
31
Option ID (iId)
6.6. User interface
The WebViewer exposes a number of user interface elements such as common forms, tools, menus and toolbars. These elements can be
opened/shown by calling these functions.
Function
Paramater [type]
Description
Open(...)
iOpenId [int]
Opens the form / tool identified by iOpenId. The WebViewer will only open one form at a time.
ShowToolbar(...)
iToolbarId [int]
bShow [int]
Sets the visibility (1 = visible, 0=invisible) of the menu / toolbar identified by iToolbarId.
Paramater [type]
Return type
Description
IsOpen(...)
iOpenId [int]
int
Returns is the form / tool identified by iOpenId is currently
opened.
IsToolbarShown(...)
iToolbarId [int]
int
Returns the visibility of the menu / toolbar identified by
iToolbarId.
32
The available user interface elements and their identifier constants are listed and explained in the following chapters.
A Javascript file containing all user interface identifier and their respective integral values as Javascript constants is attached
documentation.
to this
6.6.1. Forms
Common forms can be opened by calling Open(...)with one of the following identifier. All forms are also available through the menu, if
the menu is set visible.
Form ID (iOpenId)
Opened menu entry
FORM_OPENMODEL
File => Open model by URL
FORM_DIRECTORYBROWSER
File => Model directory
FORM_SCREENSHOT
File => Screenshot
6. Programming interface
Function
FORM_MODELINFORMATION
Model => Information
FORM_COLLISION
Camera => Collision detection
FORM_CONTROLS
Camera => Camera controls
FORM_DISPLAYOPTIONS
Display => Options
FORM_PROXY
Settings => Proxy
FORM_CACHE
Settings => Cache
FORM_ABOUT
Help => Info
FORM_FEEDBACK
Help => Feedback
FORM_CHANGELOG
Help => Changelog
FORM_HELP
Help => Help
33
Tools can be opened by calling Open(...)with one of the following identifier. All tools are also available through the menu, if the menu
is set visible.
Form ID (iOpenId)
Tool description
FORM_TOOL_MEASURING
Enables measurement capabilities (points, line of sight, distance, height, path, area, wall)
FORM_TOOL_SIMPLEMEASURING
Enables simple measurement capabilities (distance)
FORM_TOOL_LAYERSELECTOR
Enables capabilities to change the visibility of different data layers
6.6.3. Menu & status
The WebViewer has a main menu and a status bar which both are disabled by default. A user can open the main menu by simultaneously
pressing Ctrl key and right mouse button. The main menu offers access to all options and parameters. The integrating web
application can prohibit to open this menu by calling AllowShowMenu(0)
Function
Paramater [type]
Description
AllowShowMenu(...)
bAllow [int]
Allows the user to choose Open menu in the context menu when pressing Ctrl Key and right mouse button.
6. Programming interface
6.6.2. Tools
The main menu and status bar can programmatically be enabled/disabled by calling ShowToolbar(...)with the following toolbar
identifier
Toolbar ID (iToolbarId)
Description
MAIN_MENU
Enables / disables the main menu.
STATUS_BAR
Enables / disables the status bar.
6.6.4. Toolbars
34
Toolbar ID (iToolbarId)
Description
TOOLBAR_DISPLAY
Enable/Disable display toolbar
TOOLBAR_CAMERA
Enable/Disable camera toolbar
TOOLBAR_LOCATION
Enable/Disable location toolbar
TOOLBAR_TOOLS
Enable/Disable tools toolbar
TOOLBAR_MODEL
Enable/Disable model toolbar
TOOLBAR_LASTLOCATION
Enable/Disable last location toolbar
6.7. Miscellaneous
Mutator/accessor function
Return type
Description
GetVersion()
string
Returns a version string of the currently installed WebViewer version.
CheckForWebViewerUpdate()
Checks the 3DIS update Server if an update is available. The function checks for updates even if a user has turned
off automatic updates. If an update is available, a dialog will pop up with a download link to the latest version.
This dialog will pop up only once a day. “Once a day” is the default value, which can be editet by the user in the
update dialog.
6. Programming interface
Toolbars are grouped buttons. These shortcuts allow the user to quickly switch different options. The visibility of a toolbar can be set by
calling ShowToolbar(...)with one of the following identifier. All toolbars are also available through the menu (Tools => Toolbars), if
the menu is set visible.
6.7.1. Walls
Walls can either be initialized upon loading a model using the respective Load(...) functions or can be modified with these function
while a model is already loaded.
Description
SetWall(...)
strWallPoints
[string]
gHeight [float]
fWidth [float]
iRed [int]
iGreen [int]
iBlue [int]
Sets a wall on the models ground. strWallPoints defines a wall through 2D coordinate pairs (X Y). Wall
coordinates need to match the pattern “c1_x c1_y c2_x c2_y ...“ (double values with decimal point separated
by whitespaces). strWallHeight and strWallWidth define the height and thickness of each wall element. Values
iRed iGreen and iBlue define the wall color.
SetWallHeight(...)
fHeight [float]
Changes the walls height.
SetWallWidth(...)
fWidth [float]
Changes the walls width.
SetWallColor(...)
iRed [int]
iGreen [int]
iBlue [int]
Changes the walls color.
ShowWall(...)
fHeight [float]
Changes the visibiliy of the wall.
ToggleWall()
Toggles the visibility of the wall.
RemoveWall()
Removes a defined wall.
6.7.2. Measuring control
The functions described in this section can be used to initiate new measurements. WebViewer supports seven basic measurement modes.
Upon initiating a new measurement, a user has to specify which mode the new measurement shall have. Valid measurement mode values
are
MT_MODE_DISTANCE, measures the distance between two measurement points
MT_MODE_HEIGHT, measures the elevevation difference between two measurement points
6. Programming interface
Paramater [type]
35
Function
MT_MODE_POLYGON, measures the length of a closed path (the last point is automatically connected to the first point) defined by
multiple measurement points
MT_MODE_POINT , marks georeferenced points
MT_MODE_POLYLINE, measures the length of a path defined by multiple measurement points
MT_MODE_LINEOFSIGHT, measures the distance between the current camera position to another measurement point
MT_MODE_WALL, measures a closed path (the last point is automatically connected to the first point) and sets up a wall defined by
multiple measurement points
Return type
Description
iMode [int]
fWidth [float]
iRed [int]
iGreen [int]
iBlue [int]
bAlwaysOntop
[int]
int
Initiates a new measurement of the specified mode. The return value is an identifier for
the created measurement object required to access the measurement later on.
StopMeasurement()
int
Stops a currently active measurement, returning the identifier of the stopped measurement. If no measurement is active the return value is -1.
IsMeasuring()
int
Returns 1 if the measuring process is currently active, otherwise 0.
GetMeasurementCount()
int
Returns the number of currently registered measurements.
int
Removes the measurement identified by iIndex. If the measurement has been successfully removed the return value is 1, otherwise 0.
RemoveMeasurement(...)
iIndex [int]
RemoveLastMeasurement()
Removes the last created measurement.
RemoveAllMeasurements()
Removes all measurements.
Removes all measurements that are currently in the selected state.
RemoveSelectedMeasurements()
SelectMeasurement(...)
iIndex [int]
bSelect [int]
Selects (bSelect = 1) or unselects (bSelect = 0) the measurement identified by
iIndex.
JumpToMeasurement(...)
iIndex [int]
Navigates the camera to the measurement identified by iIndex.
To receive measurement results, use the following accessor functions with the corresponding constants, which are listened below.
Function
Paramater [type]
Return type
Description
6. Programming interface
Paramater [type]
StartMeasurement(...)
36
Function
GetMeasurementString(...)
iIndex [int]
iMeasurementType
[int]
string
Returns measurement details for measurement iIndex as a string. Use MT_STRING_*
values as iMeasurementType to access values.
GetMeasurementValue(...)
iIndex [int]
iMeasurementType
[int]
double
Returns measurement details for measurement iIndex as a double. Use MT_DOUBLE_*
values as iMeasurementType to access values.
Description
MT_STRING_MEASUREMENT
Returns a detailed string with all information about the measurement
MT_STRING_START
Returns the first coordinate
MT_STRING_END
Returns the last coordinate
MT_STRING_NODES
Returns a list with all coordinates
MT_STRING_NAME
Returns the measurements name
MT_DOUBLE_MODE
Returns the measurements mode (iMode parameter from StartMeasurement(...))
MT_DOUBLE_HEIGHT
Returns the measurements height
MT_DOUBLE_HIGHLIGHTED
Returns if a measurement is highlighted (if it was selected via SelectMeasurement(...))
MT_DOUBLE_LENGTH
Returns the measurements total length in meter
MT_DOUBLE_PITCH
Returns the measurements angle in degree
MT_DOUBLE_ALWAYSONTOP
Returns if the measurement is set as bAlwaysOntop in StartMeasurement(...)
MT_DOUBLE_AREA
Returns the measurements area in square meter
MT_DOUBLE_POINTS
Returns the number of coordinates (number of nodes) from a measurement
6. Programming interface
37
Toolbar ID (iMeasurementType)
7. Integration example
7
Chapter 7
Integration example
An integration example based on the Javascript API detailed in the previous chapter can
be downloaded from the 3DIS website under the following URL:
http://www.3dis.de/tl_files/themes/3dis/Downloads/WebViewer/webviewer_
example.zip
The source code of this example is well documented and may give additional guidance on
how the WebViewer can be integrated into existing web applications.
Figure 7.1.: WebViewer integration example
Customers may use this example as a starting point for their own GIS integration. In a
common integration scenario, the example page can be opened from Javascript in a new
browser window by clicking on a map using the following URL parameters:
modelUrl: The URL pointing to a CCF model. The model will be loaded automat-
ically after the web page has loaded.
position: The initial camera position in world coordinates.
38
7. Integration example
target: The camera’s initial target in world coordinates.
Example:
1
2
3
...
window.open(’WebViewer.html?modelUrl=http://path/to/model.ccf&position
=474134.03,5608442.50,278.71&target=474119.78,5608438.50,278.71’, ’WebViewer’);
...
Listing 7.1: Opening the WebViewer window from Javascript
The above example is not supposed to represent a full implementation
of the WebViewer utilizing all it’s features. This example is available in a
free download package and can be used by anyone as a starting point
for their own implementation or be passed on to any third party for
the purpose of creating a customized implementation. For an additional
service fee 3DIS can provide a customized implementation tailored to a
customers specifications. Such customizations are explicity NOT part of
the standard product package.
The link above always uses the latest WebViewer version. The modules
contained in this public version search for updates on a 3DIS server.
Registered customers can order a customized plugin version with a
different update path to have full control over the update process and
the WebViewer version inside the boundaries of their institution.
39
Part III.
Technical Reference/Information
8. Hosting CCF models
8
Chapter 8
Hosting CCF models
8.1. Remarks
This chapter covers technical details on setting up the WebViewer in a production environment. In such an environment, in which the WebViewer is typically installed on
multiple systems, it is recommended that CCF models intended to be visualized using the
WebViewer be placed on a central server all client systems have access to.
While in the development or integration stage, a CCF model can also
be placed on a local disc and loaded from that location supplying the
correct path to the Load() function of WebViewer’s Javascript interface.
8.2. Streaming architecture
Making CCF models available on a central server can either be achieved
by placing them in a shared directory on a file server or by putting them
on a web server. Both approaches require the directory structure 3DIS
delivers CCF models in to be remain unchanged.
8.3. MIME types
When streaming CCF models from a web server, it is recommended to configure the web
server with the MIME types listed in table 8.1, as some proxy servers and firewalls tend
to block the transfer of files whose file type can be discerned through a header inspection
but that are not transferred with a corresponding MIME type
41
8. Hosting CCF models
File extension
MIME type
.zcf
.zcm
.zcg
.zcb
.zct
.zpc
.zmetadata
.ccq
.cco
.xpi
.crx
application/zip
application/zip
application/zip
application/zip
application/zip
application/zip
application/zip
application/octet-stream
application/octet-stream
application/x-xpinstall
application/x-chrome-extension
Table 8.1.: MIME types of CCF model files
42
Further information
Further information
Further information about the WebViewer is avaiable on our website at www.3dis.de.
In case of concrete questions please contact us by e-mail through
info@3dis.de
or by phone under
+49 (0)2861 891980.
43
Glossary
Glossary
ActiveX is a framework for defining reusable software components in a programming
language-independent way. Software applications can then be composed from one
or more of these components in order to provide their functionality.
It was introduced in 1996 by Microsoft as a development of its Component Object
Model (COM) and Object Linking and Embedding (OLE) technologies and is
commonly used in its Windows operating system, although the technology itself is
not tied to it.
Browser sniffing is a technique used in websites and web applications in order to
determine the web browser a visitor is using, and to serve browser-appropriate
content to the visitor.
Chrome extension adds new functionality to the Chrome browser. It can add anything
from a toolbar button to a completely new feature. They allow the application to
be customized to fit the personal needs of each user if they need additional features,
while keeping the applications small to download.
Culling is a technique used in computer graphics, that determines whether a polygon of
a graphical object is visible. It is a step in the graphical pipeline that tests whether
the points in the polygon appear in clockwise or counter-clockwise order when
projected onto the screen.
Firefox extension adds new functionality to Mozilla Firefox. It can add anything from
a toolbar button to a completely new feature. They allow the application to be
customized to fit the personal needs of each user if they need additional features,
while keeping the applications small to download.
HTTP (Hypertext Transfer Protocol) is an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data
communication for the World Wide Web.
Internet Explorer protected mode Internet Explorer’s protected mode is a feature
that makes it more difficult for malicious software to be installed on your computer.
Protected mode is turned on by default in the Internet, intranet, and Restricted
sites zones.
Javascript is a programming language originally engineered at Sun Microsystems with
the intention of creating a method of manipulating webpages on a user’s computer,
without the need for refreshing the page.
44
Glossary
MIME type is a two-part identifier for file formats on the Internet. Examples are
application/zip, image/jpeg and text/html.
Multisample anti-aliasing is a technique used in computer graphics to improve image
quality by smoothing edges, thus reducing the “stair steps” effect (jaggies) often
occuring on edges of objects rendered as part of a 3D scene.
Silent mode is an installation mode, where software is installed without any user interaction. In fact, no Windows or any other output will be visible to the user. Silemt
mode installations are useful to install software on client machines with Software
deployment services
45