Developers Knowledge Base

[#1]

What is OpenLS (Route) Web Service

The OpenLS (Route) service allows you to determine a route based on specification, start point, and end point. The supported interfaces of the service are SOAP/WSDL-based WSIRoute and the OGC OpenLS (OLS) 1.1 Route Service.

This service provides an interface to compute a shortest path between a given set of stops. The web service can optionally reorder the given set of stops to find a best path. The route result consists of estimated time to travel, total distance covered, the bounding box, geometry, turn-by-turn instructions, and the language used for the instructions.

OpenLS (Route) Service Interface

Operations

• DetermineRoute : Determines the turn-by-turn instructions and geometry of the route based on the input specification and start and end points.
• FindClosest : Returns the cost of the shortest path from every start point to every end point.
• GetAllDatasetInfo : Returns a DatasetInfo array for all datasets supported by the Web Service.
• GetServiceInfo : Returns informations of the service.

Refer GeoMedia WebMap Administrator Guide here for more details on supported operations.

Data Structures

Refer GeoMedia WebMap Administrator Guide here.

Setup OpenLS (Route) Service with Sample Data

• Go to Administration Console and create a new instance type OpenLS (Route) Service.
• Configure this instance by selecting the 'Include demo data' check box to set up a new OpenLS (Route) Service with demo data (or in the Configuration File dialog, specify a location for the web service configuration files).

After the OpenLS (Route) service is created and configured, browse the URL http://localhost/DemoRouteService/Route.asmx. If the web service is accessible, a list of simple operations are displayed.

Setup OpenLS (Route) Service with Custom Data

• Creating Route Web Service Instance

Go to Administration Console and create a new instance type OpenLS (Route) Service without demo data configuration.

• Publishing Route Data Files

To publish the data files required by the Route Web Service, the Route Data Publisher Utility (RouteDataPub.exe) is used. The utility supports several operations to publish data files from linear feature data stored in GDO format or to migrate existing network data from a variety of formats.

Refer GeoMedia WebMap Administrator Guide here for details.

The RouteDataPub.exe is located at "C:\Program Files (x86)\Hexagon\GeoMedia WebMap\program" and it is run from Windows CMD prompt using the syntax "RouteDataPub /<CreateNewNetworkOperation> <Options>"

For details on Route Data Publisher Utility refer GeoMedia WebMap Administrator Guide here.

Example 1: How to create .network and .ID file

Compile a network from the Interstates feature class in the USSampleData.mdb dataset:

RouteDataPub /CreateNetwork /Connection c:\warehouses\USSampleData.mdb /Edge interstates /ID id /Geometry geometry /Tolerance 0.01 /Output c:\warehouses\ussampledata.network /OutputID c:\warehouses\ussampledata.ID /Overwrite

Example 2: How to create .rangetree

Compile a rangetree from the Interstates feature class in the USSampleData.mdb dataset:

RouteDataPub /CreateRangeTree /Geometry c:\warehouses\ussampledata.geometry /Output c:\warehouses\ussampledata.rangetree /Overwrite

For complete list of operations required to create a new network refer GeoMedia WebMap Administrator Guide here.

• Publishing Route Data Files from Commercial Network Datasets

If we are migrating data from either Navteq or TeleAtlas data, then we need to create a Route Data Publisher Utility Configuration File. For other datasets, the configuration file is not used. The configuration file can be used to create the files described in the Route Data Publisher Appendix by default or to republish a Graph, RangeTree, or EdgeProperty file without publishing the rest of the files.

To publish Route Data Files from Commercial Network Datasets refer GeoMedia WebMap Administrator Guide here for details.

• Configuring Route Web Service

Next step is create an XML file that matches the particular Route data set. This XML file acts as a configuration file by pointing to the data files created in the previous step. The configuration file should be created and populated before the new Route Service is created through the WebMap Publisher Server Configuration Utility. When a new Route Service is created, we are prompted to enter the name and location of the configuration file.

The config.xml file of demo data from Route Web Service is located at: "C:\Program Files\Common Files\Hexagon\Services\Instances\[instanceName]\Data"

Note: It is better to get a config.xml file from other Route Web Service with demo data than create a new .xml file.

After creating the config.xml, configure the OpenLS (Route) instance in Adminstration Console by refering to this xml file as, "C:\Program Files\Common Files\Hexagon\Services\Instances\[instanceName]\Data\config.xml"

• Creating Route Directions Configuration File

The Route Web Service returns the route result in two structures. The first one is a summary of the entire route, while the second is one per route segment. We can optionally request driving directions based on the route segments returned by the web service. The Route Directions Configuration file is an XSLT file designed to configure the output of the directions for each route segment.

Two sample XSLT files (English - en-US.xslt, Chinese - zh-CN.xslt) are delivered with the Route Web Service demo data, which are located default at "C:\Program Files\Common Files\Hexagon\Services\Instances\[instanceName]\Data"

These lines must be added in config.xml file:

<SupportedLanguages>
     <Language>en-US</Language>
     <Language>zh-CN</Language>
</SupportedLanguages>

Testing the OpenLS (Route) web service with SOAP UI

Since the supported interfaces of the service are SOAP/WSDL-based, the operations supported by OpenLS (Route) web service can be tested using the SOAP UI. Download SOAP UI.

Create a new SOAP project and provide initial WSDL as http://localhost/DemoRouteService/Route.asmx?wsdl (Note: DemoRouteService is an OpenLS(Route) instance configured with demo data) The supported interfaces/operations are listed under WSIRoute and individual interface’s request can be modified to get desired result.

For example if the “GetAllDatasetInfo” operation request is fired it will provide the details of the dataset configured in the Route Service. See snapshot.

Similarly, the “DetermineRoute” operation request (refer attached xml) is also modified to get the basic routing output using start point and end point.

Thus by using the SOAP UI tool the interfaces/operations supported by the OpenLS Route web service can be tested with different input requests. The output response thus provides necessary idea that would be needed to develop a fully customized Routing solution.

Integration with Portal SDK

Advanced web services of GeoMedia WebMap provides a web service for OpenLS Routing. Its implementation is not out of the box. Custom development is required around this web service and also at portal client like user interface, map visualization and interaction in order to achieve Routing workflow on Geospatial Portal.
In this integration basic start point to end point routing with quickest route is discussed. Computing route via a point between start and end points is also discussed here. Routing Instructions and Route Summary can be displayed in tabular format. The Route geometry information provided by the web service has to be parsed so that a route layer can be created using PSS and displayed on Map along with the start, end and via points.

Step 1: Add Route webservice as web reference in Portal SDK project

In the PortalSDK Application project, add a web reference to http://[server_name]/DemoRouteService/Route.asmx and name it (say) RoutingService.

Step 2: Create a generic handler (*.ashx) to add Route webservice server side code

Add a Generic Handler to the Application project, say Routing.ashx. Replace the contents of the ashx with the following code.

Source Code - GWM_Routing_Integration_with_Portal_SDK.cs

Add missing references (if any). The above handler code is taken from the WebMap documentation. But it has been modified to respond to ajax calls which sends input parameters (Start Point, End Point, ViaPoints). The above code after computing the routing, the output is serialized to JSON and sent as response to the ajax call.

Step 3: User Interface to perform and visualize Routing on Portal SDK Client Application

These are the design requirements:

1. Button to fetch start and end points from user click on mapviewer and display the coordinates in a textbox.
2. Checkbox to enable/disable use of viaPoints in route calculation.
3. If viaPoint is enabled, button to add via points from user click on mapviewer.
4. List via Points coordinates clicked by the user.
5. Provision to delete a particular via Point from the above list.
6. Button to compute/generate route with the input parameters. Validations on input parameters before computing route.
7. Clear button to reset the input parameters and clear the route layer.
8. Tab Panel to incorporate the above designs 1-7.
9. Another Tab Panel which has a table to show the route instruction and route summary.

Sample User Interface:

Step 4: Some useful Javascript snippets

User input point and placing pins
Fetching a point from user click on map, and place a pin at that point. Using this code snippet, start, end point and via points coordinates can be fetched and displayed on map using a pin.

The specific pin can be cleared using the following snippet:

$GP.map.pin.clear({
     featureClassId: "startPointPin" //use featureClassId to remove a specific pin
});

Execute Route button click event
Button click event to generate route using the input parameters (start and end points, viaPoints if selected). It fires an ajax to the Routing handler.  Code

Write a custom function to parse route result JSON object to display route layer, route instructions etc…

Sample JSON structure for route result object. Parse this object to visualize routing output information on Geospatial Portal.

If objRoute is output route object, then

SRS Name: objRoute.Geometry.Item.geometryMembers[0].srsName
Route Layer geometry bounding box: objRoute.Summary.BBox
Total Route Distance: objRoute.Summary.Distance.Value
Total Route Duration: objRoute.Summary.Duration
Route instructions array: objRoute.RouteInstructions (contains route instructions geometry information (coordinates) for each instruction.)

Fetch Route Instruction and Geometry data
Consider an array routeInstructionsObj = objRoute.RouteInstructions to store route instructions information. It will be used to get geometry and instruction information.
In the route instruction array, actual start - end points and via points coordinates can be fetched by

if (routeInstructionsObj[i].Geometry.Item.hasOwnProperty("coordinates")) { // Stops
     coordinateObj = routeInstructionsObj[i].Geometry.Item.coordinates.Value.split(',');
     geojsonStops.features.push({ type: "Feature", geometry: { type: "Point", coordinates: coordinateObj } });
}

Loop through the instruction array routeInstructionsObj for Item.coordinates and store the coordinates in geojson variable geojsonStops. This will be used to draw points using PSS. Meanwhile, routeInstructionsObj[i].Geometry.Item.curveMembers contains the route coordinates for each instruction.

geojsonRoute.features.push({ type: "Feature", geometry: { type: "LineString", coordinates: coordinateArray } });

Loop through the instruction array routeInstructionsObj for Item.curveMembers[].segments and store the coordinates in geojson variable geojsonRoute. This will be used to draw route layer (linestring) using PSS.

Each Instruction has the following information. Parse this instructions accordingly into tabular format.

routeInstructionsObj[i].Instruction
routeInstructionsObj[i].Duration
routeInstructionsObj[i].Distance
routeInstructionsObj[i].BBox

Draw route map using PSS
Draw PSS using the stop point coordinates and route layer (linestring) coordinates stored in geojson. Code

pssStyleObj is the style geojson object. It is used to style the route layer (line) and stop (points). Refer Portal SDK documentation for $GP.map.draw api for the sample geojson object structure.  Code

Step 5: Code Build and Deployment setup

Build the PortalSDK solution, once the all the required source code (for ashx handler, UI design and javascript functions to process route result at client-side) is in place.
Create a WMS service for the same data source which was used to process route data earlier. This will be helpful for the user to place accurate start and end points on the map.

Movie: Routing on Geospatial Portal

Details about the movie:

• US Sample Data (States and Interstate) is used as WMS backdrop layer, and Route Service dataset used is the demo data.
• User selects Start and End Point and computes Route.
• Route layer is drawn using PSS and is added to layerlist control.
• Route Instructions and Route Summary available.
• Option to generate Route through a via point(selected by user).

Note:View in fullscreen and 720p resolution for better visualization

[#2]

Hi neumann,

I am integrating GMW routing with PortalSDK EP02 2016.

I am using US sample data for routing service.

In debug mode, i am able to compile SDK code after adding Web Reference and everything is working fine for me.

But in release mode, i am not able to complile Portal SDK code and getting following error...

An attempt was made to load an assembly with an incorrect format: C:\Windows\Microsoft.Net\assembly\GAC_64\Intergraph.Licensing.Net.Utilities\v4.0_11.11.1.47__73552223d025f77f\Intergraph.Licensing.Net.Utilities.dll. 

Please suggest something on this.