====== Multiviewer API ======

===== General information =====

Hexagon Multiviewer is the general technology platform and a basis to serve Hexagon specific solutions such as Panoramic Viewer (PV), Oblique Viewer (OV), Virtual Inspection (VI), Thermal Inspection (TI) and Site Inspection (SI)

Hexagon Multiviewer (MV) supports several ways of interaction and stage initialization:
  * URL parameters
  * MV Message hub which is available by a [[https://mv.services.hxgncontent.com/Messageshab/PutMessage/|HTTPS end-point]]

The main idea is – that you can open MV with URL parameters for stage initializing and configuration:

<code>
https://mv.services.hxgncontent.com?u=***&p=***&project=***
</code>

and continue using the app. If you want to interact with instances of MV, that is already running in your web browser, you can open MV with parameter **msid**:

<code>
https://mv.services.hxgncontent.com?msid=GUID&u=***&p=***&project=***
</code>

and use the GUID as a token for interaction with running instances of MV through the “message hub”.
 
===== URL parameters  =====

^Name ^Description ^
|msid         | GUID for interaction with the instance of MV. If the parameter is provided - MV will check messages on the server, otherwise - pulling messages will not be activated. **Be careful**, every running instance must have its own unique id so a UUID in the form of a GUID is recommended. |
|u            | User name (provided by Hexagon) |
|p            | User password (provided by Hexagon) |
|origin       | You can specify from where the message came. For example: “desktop”, “web”, … For pulling of the messages from the server, you also must provide parameter “origin” as a result you will get all messages excluding the messages with same “origin” value |
|cmd          | “state” (full control over application state), "gotlocation"(pan screen to the defined location & activate a spatial search for this location) and "moveto" (pan screen to the defined location). |
|project      | Project name%%*%% |
|x            | X coordinate for spatial search & centering of a map window |
|y            | Y coordinate for spatial search & centering of a map window |
|srid         | Spatial reference identifiers of x & y coordinates (projection and datum reference number)%%**%% |
|vLayers      | Names of layers%%*%% (divided by ";") that should be visible  |
|hLayers      | Names of layers%%*%% (divided by ";") that should be hidden  |
|assLayers    | Names of layers%%*%% (divided by ";") for which you want to activate the "spatial search" |
|dssLayers    | Names of layers%%*%% (divided by ";") for which you want to deactivate the "spatial search" |
|ssTrigger    | There is an action for “spatial search” activation, available values: “SINGLE_CLICK” and “ALT_S” |
|maximize     | Layer name%%*%% which view must be maximized after "spatial search" |
|openImages   | List of pairs: layer name, image id to open, and view mode: N - new view, C - current view, format "layer_name%%|%%image_id%%|%%N;layer_name%%|%%image_id%%|%%C..." |
|frl          | Force restore the layout. Allows application applied layout, which was set up for the project, during the previous session. \\ The layout is saved every time you change a project or use shortcut ctrl + alt + s. To reset layout you can use shortcut ctrl + alt + r.\\  If you want to force layout restore, the key should be present in parameters with any value, for exa frl=1.\\ **Exceptions:**\\ 'frl' is not effective if 'vLayers', 'hLayers', 'assLayers' or 'dssLayers' parameters are included in request.\\ For oblique images 'frl' is only effective when all viewports are docked.\\ {{ :api:workspace_docked.jpg?600 |}}\\ If individual users by clients should be able to control the workspace when MV is controlled by API the API request should only define 'u', 'p', 'project' and eventually 'maximize'.|
|lp           | Lock position. Center panoramic image on spatial search location and locks subsequent images on this position until released by left click on the focus point. If you want to lock position the key should be present in parameters with any value, f exa lp=1|

//%%*%% - You must handle spaces in name (white space, '+' or '%20') – see example 1.//

//%%**%% - For the moment following SRDI are supported: 4326, 3857, 25832, 3009//

**Examples:**

Example 1: Open the project 'MVDEMO DDG Multiple years', [[https://mv.services.hxgncontent.com?u=cmvdemo&p=cmvdemo&origin=desktop&project=CMVDEMO DDG Multiple years|enter URL]]:


<code>https://mv.services.hxgncontent.com?u=cmvdemo&p=cmvdemo&origin=desktop&project=CMVDEMO DDG Multiple years</code>
or
<code>https://mv.services.hxgncontent.com?u=cmvdemo&p=cmvdemo&origin=desktop&project=CMVDEMO+DDG+Multiple+years</code>
or
<code>https://mv.services.hxgncontent.com?u=cmvdemo&p=cmvdemo&origin=desktop&project=CMVDEMO%20DDG%20Multiple%20years</code>


Example 2: The project 'CMVDEMO DDG Multiple years' includes four different covermaps and DDG 2015 and DDG 2016 for Ballerup Kommune. To open nearest image to x=711050,y=6181170 and centered in the position with covermap DDO 2014 overlayed by image point for DDG 2016, [[https://mv.services.hxgncontent.com?u=cmvdemo&p=cmvdemo&origin=desktop&project=CMVDEMO+DDG+Multiple+years&vLayers=DDG2016+Ballerup+Kommune;DDO2014&hLayers=DDG2015+Ballerup&x=711050&y=6181170&srid=25832&assLayers=DDG2016+Ballerup+Kommune&dssLayers=DDG2015+Ballerup&maximize=DDG2016+Ballerup+Kommune|enter URL]]:


<code>
https://mv.services.hxgncontent.com?u=cmvdemo&p=cmvdemo&origin=desktop&project=CMVDEMO+DDG+Multiple+years&vLayers=DDG2016+Ballerup+Kommune;DDO2014&hLayers=DDG2015+Ballerup&x=711050&y=6181170&srid=25832&assLayers=DDG2016+Ballerup+Kommune&dssLayers=DDG2015+Ballerup&maximize=DDG2016+Ballerup+Kommune
</code>
===== Integration with CAD/GIS  =====

For integration with CAD/GIS system, you can use a combination of the URL parameters + “message hub”

**Step #1** - unique ID generation

C#:

<code csharp>
string msid = Guid.NewGuid().ToString();
</code>

**Step #2** - put **msid** into url-parameters and run new instance of MV in browser

C#:

<code csharp>
string msid = Guid.NewGuid().ToString();
string initUrlDemo = String.Format(
   @"https://mv.services.hxgncontent.com/?msid={0}&u={1}&p={2}&origin=desktop&cmd=state&project={3}&vlayers={4}
   &x={5}&y={6}&srid={7}&maximize={8}&hlayers={9}&dssLayers={10}&assLayers={11}&ssTrigger={12}",
   msid, UserName, Password, Project, vLayers, X, Y, Srid, Maximize, hLayers, dssLayers, assLayers, ssTrigger
);
System.Diagnostics.Process.Start("chrome", initUrlDemo);
</code>

**Step #3** - push message to the "message hub"

C#:

<code csharp>
JavaScriptSerializer jsSerializer = new JavaScriptSerializer();
string messageStr = jsSerializer.Serialize(
   new 
   { 
      Cmd = "state", Project, vLayers, hLayers, Maximize, X, Y, Srid, dssLayers, assLayers, ssTrigger 
   }
);

string data = String.Format(@"token={0}&origin=desktop&isjson=true&messageText={1}", msid, messageStr);
string uri = String.Format(@"https://mv.services.hxgncontent.com/Messageshab/PutMessage", cmvUrl);

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
request.KeepAlive = false;
request.ProtocolVersion = HttpVersion.Version10;
request.Method = "POST";
byte[] postBytes = Encoding.ASCII.GetBytes(data);
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = postBytes.Length;

Stream requestStream = request.GetRequestStream();
requestStream.Write(postBytes, 0, postBytes.Length);

HttpWebResponse response = (HttpWebResponse)request.GetResponse();
// inform somehow user
</code>

**Step #4** - in 1-2 seconds, MV instance, that was started with **msid**, pulled messages out of the hub and updated the viewer's stage \\ \\  

====== How to integrate MV in third-party web-site ======


===== IFRAME =====

Using <IFRAME> tags is one of the possible ways to integrate the MV into a third-party web-site. There are two ways how allow third-party web-site to show the MV through <IFRAME>:
  - Add rights for a specific account by using rule **%%Services:MV.IFRAME.ALLOW.https://thirdparty.com%%** (requires agreement with Hexagon)
  - Add third-party web-site to MV web.config file in variable **IframeAllowedHosts** (use ';' as delimiter between ones) 


There are two pages which can be specify in attribute "srs" of the <IFRAME> tag:
  - https://mv.services.hxgncontent.com?u=USERNAME&p=PASSWORD... (user management rule or web.config )
  - https://mv.services.hxgncontent.com/Login (only web.config)

To integrate MV into third-party web-site you should put this:

<code xml>
<iframe width="500" height="500" src="https://mv.services.hxgncontent.com/?u=cmvdemo&p=cmvdemo&origin=desktop&project=CMVDEMO+DDG+Multiple+years"></iframe>
</code> 

or this:

<code xml>
<iframe width="500" height="500" src="https://mv.services.hxgncontent.com/Login></iframe>
</code>