This pages givens an introduction on how to build your own integrated solution using the Orbit Web Client SDK for Mobile Mapping or Oblique Imagery.
This document will help you to understand the steps to be taken to engage the SDK, and the user interface options that you can provide. Develop your solution according to the standards for user interaction that are used in your host software.

The Orbit Web Client gives access to 3 components, which may or may not be available according to server settings and license of the plugin at hand :

• Map component
• Mobile Mapping component
• Oblique component

You will most likely use either the Mobile Mapping or the Oblique component.

First make the Orbit Web Client available in your host. If your host provides a Map component, you most probably wish to hide that part from the Orbit Web Client. There is an API method to do so. This document assumes that you need to integrate your host's map component with the Orbit Web Client Mobile Mapping or Oblique viewing capabilities, instead of using the Orbit Web Client map component.

Any integration, plugin or extension (hereafter named as Product) using the Orbit Web Client must be registered. A Product is identified by its Developer ID and Product ID.

As registered Developer company you received your Developer ID to be used for any Product you will develop. Each new Product you create must have its own Product ID. Request a new Product ID by providing the product name and purposes to the Orbit Sales team.

The Orbit WebClient requires an Activation Key to operate.
The manually entered Activation Key will be verified automatically by the Orbit WebClient. The WebClient requires connection to the Orbit Online License Service to validate the Activation Key, read more Orbit Online License Lease and Activation.

Using the API, it is possible to set the Orbit Publisher as License Server to overcome manual input of the Activation Key. The Web Client will request the Activation Key from the Orbit Publisher and proceed online validation via the Online License Service.
This technique requires a license configuration update of the Orbit Publisher and limits connection of the Plugin to the given Publisher only.

To update the license configuration of your Orbit Publisher, see Orbit Publisher Installation.

The Orbit Web Client needs to connect to an Orbit Publisher Server, either Mobile Mapping or Oblique.
The Publisher administrator has the necessary tools to configure data setups, access permissions, startup parameters and more. Such a setup is called a “Publication”. A user may have access to multiple Publications.

To allow the user to login to the Publisher of his choice, a Login Screen is provided within the SDK.
In the Login Screen, the user must enter :

• Publisher server URL
• User Name
• Password
  > user must make connection, which will load the Publications
• Publication
  > user makes a choice and clicks “Start”.

You may also provide these 4 parameters directly to the Web Client in order to shortcut user entry.

As implementation developer, you are required to implement the storage of the related Configuration data :

• get & save the Configuration data
• recall and set the Configuration data

At startup, providing the Configuration data to the Orbit Web Client will restore the user history and user preferences (such as auto-login). You can call the Login Screen with a dedicated API method if required.

If the user wishes to switch between Publications or login to an other Publisher, he should return to the Login Screen, make a different choice, and click again “Open Publication”. To do so, the developer must implement a button that opens the Login Screen in the Orbit Web Client.

Showing imagery at startup, or not :

By default a Publication is opened with a startup location and image. The startup location is specified by the administrator on the server. This is typically done for web-based implementations where no pre-defined map location is available at launch.

You may choose to keep the Mobile Mapping component blank and await user action. This is typically done for host-extensions where a map viewing is already present. Set the ApplyStartupParametersOnLoad setting to false to disable opening a startup location and image.

Implementation of the Mobile Mapping component.

You should provide a toolbar offering the required functions to operate the panorama viewer, some examples :

An image needs to be opened to allow visualization. In order to do so, the GUI needs to provide a way to allow the user to select a panorama image to open.

First thing to implement is to visualize the individual “Photo Recording Positions” on the map.
Use an API method to request these positions : this request is limited by a bounding box as it is not feasible to request all. Most commonly, request the photo positions with a bounding box covering the current map display, but only from a reasonable scale on, e.g. 1/1500. When zooming out to a smaller scale than the threshold scale, do not request or display these positions anymore as it most probably will cause sluggish performance and cluttered viewing.

Secondly, when zooming out, you should display the “Coverage” instead of the individual photo recording positions. This represents a simplified representation of the locations where images are available. Here too, limit the viewing to a scale of e.g. 1/50000.

Display a Coverage/ as a wide, transparent line.

• Render from scale 1/1500 to scale 1/50000.
• Default style : Width 8 px, Transparency 50%

Finally, show these photo recording positions and coverages in the correct color associated with the images. Color is a property of the Category to which an image belongs.

Auto refresh
Make the visualization of the photo recording positions fully automated. There is no need for the user to select an area : automatically refresh the photo positions after every pan or zoom action so that all relevant information is always present.

Set visibility
You may provide a tool to switch the viewing of these photo recording positions on and off.

Selectability is not required
The photo recording position objects in your map view do not need to be selectable by the standard tools from your host system. They only need to be selectable by a specific 'select panorama' method as described below. Depending on the standards for user interaction in your host system, set this accordingly.

Cache data
Be smart in your requests : cache the photo recording positions to avoid unnecessary overhead and compromised performance.

Provide a function that targets image selection (see toolbar). The user clicks on a photo recording position representation on the map view. Select that object. You now know the co-ordinates (X, Y) and an ID (attribute). Using this, use the appropriate method to load and view the image. The Orbit Web Client will open the image and the user can now pan, zoom and navigate.

This method of selection will open (or replace) the first image. Extra selections can be launched using the “+” icon in the first image view, which will open a supplementary viewer window (maximum 4 windows).

Users may click just next to a recording position : you can ask the Orbit Web Client to load the nearest image by providing the clicked co-ordinate. You may also ask the Orbit Web Client to load the 2 or 3 nearest images (this number is most likely set by the user in the Orbit Web Client 'Settings' HUD, when available). Alternatively, you may integrate an address search tool which at its turn results in a co-ordinate, replacing the manual point-and-click.

You can help the user a lot when you represent the current panorama viewing direction and viewing angle on the 2D map. You can do so by listening to the State events that the Orbit Web Client sends, and draw a pie chart slice on the map, representing the direction (center direction of the slice) and field of view angle (width of the slice).

If multiple images are opened, do this for every image. Remember to also display the viewer number in the according slice, and use the appropriate color. Here are some examples :

You can download fov-rendering.zip some example code to render this type of pie slices.

• drawFOVSymbol.as : Actionscript example of rendering a field-of-view symbol to a graphics.
• createSVGPath.js : Javascript example of creating a field-of-view SVG path.

Do render these pie slices in the according color.

The Orbit Web Client can open up to 4 images simultaneously. In the Orbit Web Client, the user can close a viewer (hoover the image number to see the “x”-button in the top left corner of each image view) or select an extra one (click the “+”-button next to the number). In your code, you will thus need to manage an array of panoramaviewers and keep track of each of them. Note that, when selecting a second image, the first image remains unchanged.

There are 2 ways to overlay vector data on panoramas :

• include vector layers in the Publication (requires declaration of the data on Publisher, by the server administrator)
• send data over from your host application to the image viewers to display on the fly (using the API).

Layers that are declared in the Publication can be controlled by the tools within the Orbit Web Client. You can also use the API to switch visibility on/off for each of them. Note that in such case, you may need to have a GUI for that in your host application and that would probably be overhead as this on/off switching is available in the Orbit Web Client.

You can create a vector layer in the Orbit Web Client, propagate it with objects and set appearance parameters. To do so, you'll need to cover the following steps :

1. Determine the layer from your host that you wish to overlay
2. Select the objects in that layer around the recording positions of the visible images
3. push that data over to the Orbit web Client using the API
4. Set the graphic appearance such as color of symbol
5. Control its visibility in the Orbit Web Client, either via the built in HUD or using the API (see above).

Depending on the standards of user interaction in your host system, allow the user to select a portion of the vector data that he would wish to see overlaid in the image view, or simply select a layer and do the rest automatically (Preferred option). There are different ways to do that :

• select (a range of) specific objects
• select a query result
• automate the selection by using a distance-from-viewpoint within a selected layer or all visible layers. (Preferred option)

The latter option skips the physical selection of objects, so the user only needs to choose a layer. The objects are determined by their distance from the photo position (maximum 50m). Posting more objects to the Orbit Web Client will not result in improved visibility, but rather in reduced performance and clutter along the horizon in the image.

Advised procedure :

1. Select the objects within 50m from the recording position for each image viewed, and pass them to the Orbit Web Client.
2. Update this selection every time a different image is selected or a viewer is closed or opened.
3. Pass objects with attributes and graphic specs as allowed by the API.

GUI : provide a panel or other UI widget with a list of layers that can be overlaid in your host. If possible, provide a toggle button or menu item in the Table Of Contents or Dataset List to switch its visibility in the Orbit Web Client on and off.
For Example, this is the standard HUD available within the Orbit web client to switch layers on/off; It only lists the layers known by the Orbit web client, and not all layers known by your host system :

Preferable, implement a class that keeps track of each panorama and the layers that are overlaid. Post just the necessary amount of data (as explained above - a radius form the photo position) on the Orbit Web Client. When the choice of image changes, you will need to refresh the overlay data as well. You can do so by replacing the objects that were posted to the Orbit Web Client to a new set of objects that are visible around the new panorama photo position. Remember to clear or remove the layer before re-posting data.

Many vector data is 2D. A 360 degree image view is in 3D. The absence of a Z co-ordinate forces an as-good-as-possible assumption. The Orbit Web Client panorama viewer will calculate a Z-value equal to the approximate ground level. That ground level is calculated down from the distance of the camera above ground. The overlaid data is thus projected on a fixed height, which may not always be effective. To adjust the height of a 2D layer, use the panorama Vector Overlay HUD.

Be aware that you are using the appropriate CRS definition when exchanging data from and to the Orbit Web Client : your host system may express data in a different CRS than the Orbit Web Client's Publication.
If conversion is required, you should do so before sending data over to the Orbit Web Client.

The Orbit Web Client provides a HUD panel with many measurement functions. The user can simply open this panel and execute any measurement without any development from your side. The measurement results are displayed in the same HUD and result values can be copied to the clipboard.

When a measurement function is started, the Orbit Web Client launches an event that can be monitored. Equally, when a measurement function is stopped, an event is launched. You can use these events to follow the progress of the measurement, and when stopped request all the results. Depending on the type of measurements, the list of result values differs.

Alternatively, you can launch any of the measurement functions from within your host software. In combination with the events, you can skip the HUD completely and display the results in your host.

It is advised to give user feedback on the measurements. According to common standards in your host system, you can display the measurement result as an overlay or other indication on the map.

Measurement results can be used to create new objects : a point, line or area measurement includes the list of co-ordinates as part of the result set. You can implement a function in your host system that allows the user to add a measurement as a new object in a chosen layer. The API provides the geometry type (point, line area) so you can present only those layers that qualify for accepting the measurement as new object. You may also implement to add measurement results data as attribute values.

As for overlays, be aware of possible difference in CRS definitions. A conversion may be required.

To create a snapshot of the current view, the user can click the “snapshot” button. The snapshot generates a JPG extraction made available to the API.

If the host component wishes to do something with these snapshots, the host component can listen to snapshot update events, retrieve the snapshot image and do something with it. A snapshot update event is triggered every time the user clicks the snapshot button.

If the host component does nothing snapshot-related, the snapshot button should be removed from the Orbit Web Client toolbar using the according API method.

When visualizing oblique imagery, a focus position is used to focus all viewers on a single image detail. When the focus co-ordinate changes, the best overlapping obliques are loaded automatically by the client.

Based on the integration context, the best viewer layout should be selected : horizontal, vertical or tiled.

Make sure that every time the map is re-centered, the focus coordinate is also updated to the new map center, so the oblique imagery is updated.

You may choose to display the focus co-ordinate using a small cross icon in the center of the map :

Only update the focus coordinate when it makes sense to do so. When the user is zoomed too far out, it makes no sense to keep the oblique viewers centered on a detail that is not discernible anymore. By default the web client use 1/5.000 as a threshold scale.

To analyze an oblique photo more closely, the user can enable the follow-focus mode. When follow-focus is enabled, the user changes the focus coordinate by tracking mouse clicks & drags. Whenever the user clicks or drags, the focus coordinate is updated to that coordinate. As a result, all other oblique viewers are recentered.

The host component should behave in a similar fashion and update the focus coordinate when the user clicks or drags. When updating the focus coordinate multiple times in quick succession (like during a mouse drag) the host component should use the “approximate” flag when updating the focus coordinate. This flag tells the component that a full coordinate transformation (including a round-trip to the server) is not wanted. Instead an approximate conversion is attempted. After the drag don't forget to update the focus coordinate without approximation to get an accurate, final result.

To apply zoom changes in all viewers at once, the user can enable the follow-zoom mode. Whenever the zoom factor changes, all other oblique viewers zoom with an equal measure.

The host component should update the zoom factors for all oblique viewers, when updating scale.

To create a snapshot of the current panorama, the user can click the “snapshot” button. The snapshot generates a JPG extraction made available to the API.

If the host component wishes to do something with these snapshots, the host component can listen to snapshot update events, retrieve the snapshot image and do something with it. A snapshot update event is triggered every time the user clicks the snapshot button.

If the host component does nothing snapshot-related, the snapshot button should be removed from the Orbit Web Client toolbar using the according API method.