Way Finder

The SISfm Way Finder reads requests from the Find Way function of Map Enquiry, and for a specified site or floor plan returns:

place names for each travel type.
routes, as coordinates plus route segment descriptions, travel type, From and To coordinates or place names, and To floor plan offset and loc_code.

For each site or floor plan, each travel type (e.g. Pedestrian, Vehicle) has a route network with place and route names. Different travel types can use the same network, with different formulae to prioritise network use: for example, the same network might be used by both Pedestrian and Wheelchair travel types.

Each route network is accessed in a Cadcorp BDS file at the following physical location:

DataFolderSis\site_code\site-route-network.BDS

DataFolderSis\site_code\floor_loc_code-route-network.BDS

where:

DataFolderSis is the value of that setting for this application (see below)
site_code is each site subfolder

floor_loc_code is each floor loc_code

travel_type is the travel type

Way Finder uses either Cadcorp GeognoSIS or Cadcorp SIS ActiveX Modeller, has no user interface, and is intended to be run in production as a Windows service. It reads settings from a configuration file, and writes activity to a log file.

Configuration

The Way Finder reads the following settings from the file WayFinder.exe.config in the same folder as WayFinder.exe. The order of parameters is not significant unless one is repeated, when the last occurrence is used. Setting a parameter to an empty value is the same as omitting the parameter. Use a plain text editor such as Notepad to change settings to suit your environment.

Key		Value
`CadcorpGeognoSIS`		URL to access a Cadcorp GeognoSIS web service, specifying the server on which the service is running, and the port number to access the service (e.g. 4326). Optional, if omitted Cadcorp SIS ActiveX Modeller will be used.
`CadcorpLicenceServer`		The name or IP address of the Cadcorp licence server, or `no-net` to specify a local licence. Optional, if omitted a local licence will be used if present, otherwise the server specified in Windows environment variable `CADCORP_LICENCE_SERVER_LIST`, otherwise a server obtained by network broadcast. This setting is ignored unless Cadcorp SIS ActiveX Modeller is being used.
`DataFolderWeb`		The physical path of the SISfm web folder.
`DataFolderSis`		The physical path of the folder containing the Cadcorp BDS files. This may be the same as the Map Compiler `DataFolderSis` setting for Cadcorp SWD files, or a different location. Note that whereas the SISfm web application does not access SWD files, SISfm Way Finder requires access to these BDS files. If SWD and BDS files are in different locations, it is desirable that these have a common file system root, so that SWD files can reference BDS files using relative paths.
`BdsRefreshSeconds`		If specified, and a positive number, at this interval (in seconds) modified route topology BDS files are reloaded. A small refresh interval will reduce way finding performance.
`RouteTravelTypeN`		List where `N=1,2,3...` of travel types. Case-sensitive.
`RouteNetworkN`		List where `N=1,2,3...` of route networks, used to match the travel type part of BDS file names. Case-sensitive. Optional, if omitted the route network name is the same as the travel type name.
`RouteItemLengthFormulaN`		List where `N=1,2,3...` for the corresponding `RouteTravelType` of route item expressions. These are used to obtain "weighted lengths" for each item when calculating a route. Any expression may be used, although if a string expression is used it must be a string represention of a numeric value. Optional, the default expression is the actual item length (expression "_length#") which allows both topological and non-topological lines to be processed. For other values, only topological Links and Nodes are processed.
`RouteSpeedN`		List where `N=1,2,3...` for the corresponding `RouteTravelType` of travel speeds, in Km/hour. These are applied to the "weighted lengths" to obtain travel times.
`RouteDescOmitCompass`		If set to `TRUE`, compass directions are omitted from route segment descriptions.
`DbConnection`		As for the web configuration, except that a Microsoft Access database path must be physical. Required if `DbRouteAccessTable` or `DbFloorsInRoutes` are defined.
`DbRouteAccessTable`		The name of a database table used to store route access restrictions.
`FloorsInRoutes`		List where `N=1,2,3...` specifying that floor offsets and floor location codes are included in routes (used by Find Way to display floor layers on site plans, see setting `FloorsOnSite`), each having the following comma separated values: Facility type code (see the `FacilityType` setting). The name of the links overlay in site SWD files.
`BuildingLocCodeAttribute`		The name of the item attribute in building links overlays which contains the floor plan location code. Must be the same as the `BuildingLocCodeAttribute` setting used by Map Compiler.
`LocCodeFormat`		The format of location code values (`loc_code`). Must be the same as the `LocCodeFormat` setting used by Map Compiler and the web application. Required if `FloorsInRoutes` is defined.

Following is a typical configuration file, for the test data supplied with the SISfm web application at its default web site location:

<?xml version="1.0"?>
<configuration>
  <appSettings>
    <add key="CadcorpGeognoSIS"         value="http://localhost:4326/GeognoSIS/GeognoSIS.wsdl" />
    <add key="CadcorpLicenceServer"     value="" />

    <add key="DataFolderWeb"            value="C:\inetpub\wwwroot\SISfm\" />
    <add key="DataFolderSis"            value="C:\inetpub\wwwroot\SISfm\test\sisdata\" />

    <add key="BdsRefreshSeconds"        value="300" />

    <add key="RouteTravelType1"         value="Vehicle" />
    <add key="RouteItemLengthFormula1"  value="_length#*Category&^3" />
    <add key="RouteSpeed1"              value="160" />

    <add key="RouteTravelType2"         value="Pedestrian" />
    <add key="RouteItemLengthFormula2"  value="" />
    <add key="RouteSpeed2"              value="5" />

    <add key="RouteTravelType3"         value="Wheelchair" />
    <add key="RouteNetwork3"            value="Pedestrian" />
    <add key="RouteItemLengthFormula3"  value='Iif(Exists("NoWheelchair$"),1e6,_length#)' />
    <add key="RouteSpeed3"              value="3" />

    <add key="RouteDescOmitCompass"     value="FALSE" />

    <add key="DbConnection"             value="C:\inetpub\wwwroot\SISfm\test\databaseIFM.mdb" />
    <add key="DbRouteAccessTable"       value="route_access" />

    <add key="FloorsInRoutes1"          value="Building,Buildings" />
    <add key="FloorsInRoutes2"          value="CP,Car Parks" />

    <add key="BuildingLocCodeAttribute" value="" />
    <add key="LocCodeFormat"            value="SSBBBbFFR" />
  </appSettings>
</configuration>

Cadcorp Data

Way Finder requires a Cadcorp BDS file for each site/floor plan and travel network with place and route names, prepared using Cadcorp SIS Desktop.

Route BDS files can be referenced from their corresponding site.swd/floor_loc_code.swd file, which is recommended to assist in data alignment. If these references are retained, these overlays should be excluded for the Map Compiler using its OverlayExclude setting.

Cadcorp topology should normally be used to represent route networks as Node and Link items, each of which can be named using the Name$ attribute, which:

for Node items identifies places on the site/floor plan. Their names are shown in the From and To selectors of the Find Way dialog of Map Enquiry. The length of these names should fit within these selector fields. In many cases Node items will not be named.
for Link items provides names for use in route descriptions (e.g. "Alpha Street", "gravel path", "pedestrian crossing"). These are optional.

Place names should identify notable features along routes, and building entrances. For vehicular travel types, place names should also include car parks, and car park nodes should be linked to neighbouring building entrance nodes (using links named "walkway" for example).

Network restrictions can be specified using the following commands in the Cadcorp SIS Topology / Networks command group:

Direction Restrictions - on Link items, e.g. one-way street.
Turn Restrictions - on Node items, e.g. no right turn.

Link items may include other attributes, from which an expression specified by a RouteItemLengthFormula setting can obtain "weighted lengths" when calculating a route. For example, in the above configuration:

the Vehicle travel type weights Link item length by the cube of a Category& attribute with values such as 1 to 5 for major to minor roads; with this expression, routes will prefer major roads, because minor roads are weighted to appear longer.
the Wheelchair travel type weights Link item length as 1e6 (1000 Km) when a NoWheelchair$ attribute exists; this effectively makes the link (e.g. a staircase) inaccessible when an alternative route exists (e.g. including a lift), and 'No route found' is returned if the weighted route length is 1e6 or more.

For a network requiring no length expression, and where named places and network restrictions are not required, non-topological LineString items can be used instead of Link items.

Site plan networks can include their floor plan networks, when the nodes of the floor plan specified by the site link attribute (e.g. ccLinkList$) must be at Z=0, the next floor above must be at Z=4, etc.

It is recommended that each route network is thoroughly verified using one of the Cadcorp SIS commands:

Home / Measurement / Measure Distance in Find route measurement mode.
Analysis / Routing / Point-to-Point (when .User-defined 'cost' expression can be used to test RouteItemLengthFormula settings.

Route Access Restrictions

Route access restrictions can be maintained in a database and table specified by the DbConnection and DbRouteAccessTable settings. The table must include the following fields:

`map_name`		The name of a site map or floor plan (the name of the folder under `DataFolderMap` containing it).
`travel_type`		A travel type (one specified by `RouteTravelType`).
`item_name`		The value of the `Name$` attribute of a Node or Link item in this route BDS file to be restricted.
`unavailable`		The hours within which the restriction applies, as a comma separated list of "-" separated start and end times to the nearest quarter hour, e.g. `08:30-13:00,14:30-18:30`. Use `24:00` to specify an end time of midnight.

Way Finder checks for changes to this table once per minute.

Request and Response Files

Map Enquiry requests a route (or a place name list) by creating a file named WayRequest-session.xml in the temp folder of the SISfm web folder, where session identifies the user session.

Way Finder checks for WayRequest-*.xml files once per second and replaces them by corresponding WayResponse-*.xml files containing route data.

Map Enquiry, having made the request, checks for its WayResponse-*.xml file once per second, and when found displays the route (or stores the place name list) and deletes the file. If the response is not found after five checks, Map Enquiry displays a "no route found" message (or disables way finding for that site or floor plan).

Way Finder deletes any existing WayRequest-*.xml and WayResponse-*.xml files when it is started. Each SISfm web session deletes any files from its temp folder that are more than one day old.

Example place name request:

<way map="MLsite" type="" x1="" y1="" x2="" y2="" from="" to="" />

Example place name response:

<way>
  <travelType name="Pedestrian">
    <place name="Archer's Corner" />
    <place name="Pavilion Café" />
    <place name="Social Club - Main Entrance" />
    <place name="Social Club - North Entrance" />
  </travelType>
  <travelType name="Vehicle">
    <place name="Archer's Corner" />
    <place name="Social Club - Main Entrance" />
    <place name="Social Club - North Entrance" />
  </travelType>
</way>

Example route request:

<way map="MLsite" type="Pedestrian" x1="" y1="" x2="" y2="" from="Archer's Corner" to="Pavilion Café" />

Example route response:

<way metres="93" seconds="67" path="324149.608645592,6256539.03785451,0,0,324180.523691866,6256539.03785451,0,0,324211.43873814,6256539.03785451,0,0,324236.543124774,6256557.13099432,0,0">
  <step from="0" to="1" desc="From Archer's Corner start on South Street, go E for 31m to Social Club - Main Entrance,"/>
  <step from="1" to="2" desc="continue straight onto South Street, go E for 31m,"/>
  <step from="2" to="3" desc="bear left onto footpath, go NE for 31m to Pavilion Café."/>
</way>

Log File

Way Finder appends its activity to WayFinder.log in the current working directory. This file is flushed to disk at each update, therefore current activity can be viewed using a suitable plain text editor (such as Textpad). This file should be deleted or archived periodically to avoid it getting too large.

Following is a brief log example:

12-21-2016 13:57:30
12-21-2016 13:57:30 IFM SISfm WayFinder, Version 7.8.1
12-21-2016 13:57:34
12-21-2016 13:57:34 Using Cadcorp GeognoSIS
12-21-2016 13:57:34
12-21-2016 13:57:34 CadcorpGeognoSIS        = http://localhost:4326/GeognoSIS/GeognoSIS.wsdl
12-21-2016 13:57:34 DataFolderWeb           = C:\inetpub\wwwroot\SISfm\
12-21-2016 13:57:34 DataFolderSis           = C:\inetpub\wwwroot\SISfm\test\sisdata\
12-21-2016 13:57:34
12-21-2016 13:57:34 BdsRefreshSeconds       = 300
12-21-2016 13:57:34
12-21-2016 13:57:34 RouteTravelType1        = Vehicle
12-21-2016 13:57:34 RouteItemLengthFormula1 = _length#*Category&^3
12-21-2016 13:57:34 RouteSpeed              = 160
12-21-2016 13:57:34
12-21-2016 13:57:34 RouteTravelType2        = Pedestrian
12-21-2016 13:57:34 RouteItemLengthFormula2 =
12-21-2016 13:57:34 RouteSpeed              = 5
12-21-2016 13:57:34
12-21-2016 13:57:34 RouteDescOmitCompass    = FALSE
12-21-2016 13:57:34
12-21-2016 13:57:34 DbConnection            = (defined)
12-21-2016 13:57:34 DbRouteAccessTable      = route_access
12-21-2016 13:57:34
12-21-2016 13:57:34 Loaded C:\inetpub\wwwroot\SISfm\test\sisdata\ML\20015A01-route-Pedestrian.bds
12-21-2016 13:57:34 Loaded C:\inetpub\wwwroot\SISfm\test\sisdata\ML\site-route-Pedestrian.bds
12-21-2016 13:57:34 Loaded C:\inetpub\wwwroot\SISfm\test\sisdata\ML\site-route-Vehicle.bds
12-21-2016 13:57:54
12-21-2016 14:05:41 Route request for MLsite by Pedestrian from (324149.608645592,6256539.03785451) to (324236.543124774,6256557.13099432) ["Archer's Corner" to "Pavilion"]
12-21-2016 14:05:42 Route metres 93 seconds 67 path 324149.608645592,6256539.03785451,0,0,324180.523691866,6256539.03785451,0,0,324211.43873814,6256539.03785451,0,0,324236.543124774,6256557.13099432,0,0
12-21-2016 14:07:19 Route request for MLsite by Pedestrian from (324148.383678545,6256539.106207906) to (324236.543124774,6256557.13099432) ["Current Location" to "Pavilion"]
12-21-2016 14:07:20 Route metres 45 seconds 33 path 324149.608645592,6256539.10620791,0,0,324149.608645592,6256539.03785451,0,0,324180.523691866,6256539.03785451,0,0,324211.43873814,6256539.03785451,0,0,324236.543124774,6256557.13099432,0,0
12-21-2016 14:07:29 Route request for MLsite by Pedestrian from (324187.8760602,6256559.413798515) to (324236.543124774,6256557.13099432) ["Current Building" to "Pavilion"]
12-21-2016 14:07:29 Route metres 31 seconds 22 path 324187.8760602,6256574.82093277,0,0,324211.43873814,6256574.82093277,0,0,324236.543124774,6256557.13099432,0,0
12-21-2016 15:18:25 Route restrictions:
12-21-2016 15:18:25 No access on MLsite by Vehicle to Archer's Corner
12-21-2016 15:18:25 No access on MLsite by Vehicle to East Crescent
12-21-2016 15:19:44 Route request for MLsite by Vehicle from (324180.523691866,6256539.03785451) to (324180.523691866,6256574.82093277) ["Social Club - Main Entrance" to "Social Club - North Entrance"]
12-21-2016 15:19:44 Route not found

Note that place list requests, which occur whenever Map Enquiry displays a plan, are not logged.

Way Finder execution is terminated if the following are logged:

GeognoSIS connection failed
A connection to the Cadcorp GeognoSIS service specified by the CadcorpGeognoSIS setting cannot be established, or the connection has been broken.

No Cadcorp SIS ActiveX Modeller licence available
The CadcorpGeognoSIS setting is not specified, and a Cadcorp SIS ActiveX Modeller licence is not available.

Unexpected error: details
Please contact IFM Support if this message is logged. During initialisation, Way Finder terminates, otherwise it attempts to continue.

`DataFolderSis`	is the value of that setting for this application (see below)
`site_code`	is each site subfolder
`floor_loc_code`	is each floor loc_code
`travel_type`	is the travel type