3DMaps SDK Overview


The 3DMaps SDK consists of the following parts:

  • 3DMaps WebGL Runtime
  • Desktop Converter
  • Server Converter
  • Offline License Manager
  • License Manager

They can all be downloaded from the downloads page if your account has the Premium Developer privileges. Information about developer privileges and different account types can be found here.

3DMaps WebGL Runtime is a JavaScript library that is required in order to run 3DMaps. It resides on the server-side (hosted runtime is supported) and is completely transparent to the users/client machines. No web browser plugins are necessary. By including the runtime with the HTML <script> tag, just as you would with an other JavaScript library, you can start to write code for 3DMaps and take full advantage of the 3DMaps WebGL API.

To embed 3DMaps in a web page, you create a HTML <div> tag with an id and via JavaScript tell 3DMaps to replace the contents of that <div> tag during runtime. It is really as simple as that!

<body><div id="mapcontainer"></div></body>
maps = new Agency9.Maps("mapcontainer", "http://url/to/settings-file.json");


The Desktop Converter is a tool for converting and merging aerial imagery and terrain elevation data to the formats supported by 3DMaps. It can also be used to combine many 3D-models into a single dataset. With a graphical user interface, the Desktop Converter is easy to use. It includes the basic funcionality required to create datasets for 3DMaps.


Desktop Converter

The Server Converter is a command line-tool used to convert data to formats supported by 3DMaps. It is more powerful than the Desktop Converter in that it supports many more options. Because it is a command line-tool, it can be a little bit tricky to get used to. Please read the documentation carefully first.

Server Converter

The Offline License Manager (OLM) manages a single license for 3DMaps in an environment without an internet connection. Every server providing 3DMaps content to your users needs one license. The OLM can also be used if there are delays when your server is trying to connect to the online license manager hosted by Agency9. Note that an internet connection is required during the setup procedure for the OLM.

Offline License Manager

Offline License Manager

The License Manager (LM) can be configured to remedy delays (if any) to the online license manager hosted by Agency9, much like the Offline License Manager does. Multiple licenses are supported by the LM. An internet connection is needed with the LM because, upon startup, it verifies the licenses against the online manager hosted by Agency9. The LM continues to do so on scheduled intervals. Because of this, your servers will not experience any licensing verification delays provided they have a good connection to the LM running on your local network or on a network close to the physical location of your servers.

License Manager

License Manager

Note that it is optional to use the license managers. Only when you need to run 3DMaps offline or when there are connectivity problems to the manager hosted by Agency9 should you need to use a license manager.

How it works

When the 3DMaps WebGL Runtime has been included in your HTML document, the <div> to hold the 3DMaps content has been specified and the terrain data is available (generated in the A3X format by one of the converter tools*), it is time to load the data in 3DMaps.

var terrain = new Agency9.Layer.A3XTerrainLayer("terrain", "http://url/to/my/terrain/dataset");

Most datasets in 3DMaps are arranged in layers placed on top of eachother or side by side. Layers are invisible until data is added to them. For terrain data, it is called an A3XTerrainLayer.

The dataset that is loaded first is often the terrain. In the A3X format, it is made up of one or more levels of detail (LoD), sometimes 10-20 levels or more. The total number of levels for one dataset depends on the original source data and the options passed to the converter tool. An A3XTerrainLayer (in fact all layers in 3DMaps) is built on the quadtree data structure.

Level 0 (zero) is the level with the least amount of detail. It is the first level that is visible to the user. Think of this level as what you see when you are far up above the ground looking down onto it. When you are zooming in, the next level with a little more detail is loaded and then the next and so forth. Close to the ground, the level with the most amount of detail is visible. This is the level with the highest number in the dataset.

It works in the same way for the CachedFeatureLayer which is the name of a layer used to hold an aggregate of 3D-models. When creating a CachedFeatureLayer with the converter tools, it is possible to specify exactly how many levels to generate. For textured models this is important from a performance view point since there might be a lot of models visible if the camera is zoomed out to show, for example, a city overview.

For more information about the features of 3DMaps WebGL, see the showcases on our main site or have a look at the tutorials section.

* Note that it is also possible to create a flat terrain layer in 3DMaps and project data fetched from a WMS server onto it without first generating a static dataset with the converter tools.