Layer files
The Way-Fi Library utilizes the GeoJSON format to define the routing graph.
Multiple files can be loaded, each representing a separate layer. These layers can be interconnected by links across them.
There are essentially two types of files:
- Wall definition files: these do not contain arcs and are primarily used to define non-walkable areas.
- Graph definition files: these explicitly define a routing graph by specifying nodes and arcs.
When loading the first type (walls), the routing graph is automatically generated using a visibility graph. In the second case, the graph is directly constructed from the data defined in the file.
Note: If a file contains at least one arc, it is automatically treated as a graph definition file (i.e. of the second type).
Choosing the right file type
The choice between the two depends on your needs:
- Use the first type if your goal is simply to define non-walkable areas.
- Use the second type if you want fine-grained control over user movement, such as customizing arc costs or modifying them dynamically at runtime.
Features
A GeoJSON file contains a collection of features, each consisting of a geometry and a set of properties. The Way-Fi Library leverages these properties to distinguish between different elements of the graph.
Walls
Walls define areas that cannot be walked through, and are represented as polygons.
Nodes
Nodes represent junction points where one or more arcs of the graph meet.
Links
Links are special properties that connect the current node to another node in a different layer. They must specify the name of the layer containing the target node, as well as the target node’s ID. For this reason, it is essential to load each layer using the exact name referenced by other layers that link to it.
Universal Node Linking (UNL)
Universal Node Link (UNL) is a mechanism that allows connecting two or more nodes without knowing their IDs in advance.
To define a UNL, set the unl property on the corresponding node using the following format:
<prefix>#<name>/<target>;<cost>[;<mask>[;<type>[;<oneWay>]]]
where:
<prefix>A common prefix applied to all nodes participating in the same UNL group.<name>The name of the current node. The prefix is prepended to this value to form the full node identifier.<target>The name of the target node. The prefix is also prepended to this value. It can be * to indicate a connection to all nodes sharing the same prefix.<cost>The cost associated with the arc.<mask>(optional) The mask of the arc. Defaults to 0 if not specified.<type>(optional) The type of the arc. Defaults to 0 if not specified.<oneWay>(optional) Defines the direction of the connection. Defaults to 1 if not specified:- 1: one-way arc from current node to target
- 2: bidirectional arc (an additional arc is created from target to name with the same cost, mask, and type)
Arcs
An arc connects two nodes and can optionally include a cost a type (class in the GeoJSON), and a mask.
If no cost is specified, the Euclidean distance between the nodes is used by default.
The mask is a bitfield that allows arcs to be enabled or disabled at runtime.
The two nodes are specified by the fields nodeFrom and nodeTo, respectively.
The connection is intended to be bidirectional, unless the oneway property is explicitly set to false.
Suggeste values for mask
The following values are recommended for the mask field.
Consistent use across all buildings guarantees interoperability between different applications.
- 0x00: Any arc
- 0x01: Normal walking
- 0x02: Accessible for visually impaired
- 0x04: Accessible with wheels (wheelchairs or luggage)
- 0x08: Accessible with bulky luggage
- 0x10: Accessible with stretchers and carts
- 0x20: Accessible with forklifts and other vehicles
- 0x40: Accessible with bicycles and scooters
- 0x80: Accessible with leashed animals
- 0x0100: Escape (in case of fire or evacuation)
- 0x0200: Security (police, security staff, etc.)
- 0x0400: Restricted (operators, maintenance staff, etc.)
Suggeste values for type
The following values are recommended for the type field.
Consistent use across all buildings guarantees interoperability between different applications.
- 0: generic (unknown)
- 1: stairs
- 2: escalator
- 3: spiral stairs
- 4: emergency stairs
- 5: service stairs
- 6: ladder
- 7: retractable ladder
- 8: stairlift
- 9: ramp
- 10: moving walkway (travelator)
- 11: vehicle ramp
- 12: elevator
- 13: stretcher elevator
- 14: paternoster elevator
- 15: freight elevator
- 16: footbridge
- 17: tunnel
- 18: balcony walkway
- 19: turnstile (controlled access gate)
- 20: security checkpoint
- 21: security vestibule (bank-type mantrap)
- 22: tactile path
- 23: shuttle
- 24: pole (fireman’s pole)
- 25: hatch
- 26: slide
- 27: rope
- 28: suspension bridge
- 29: climbing wall
- 30: teleport
Point Of Interests
Points of Interest (POIs) are defined as points with an additional categories property, containing a semicolon-separated list of category names. These POIs can serve as destination targets. By passing a category to WayFinder.addDestinations, all POIs matching that category will be collectively set as destination points.
Example
The following file is a simple yet complete GeoJSON that can be used as a layer for the Way-Fi Library. It includes a predefined graph, but if you remove the nodes starting from ID 1 (inclusive) and all arcs, it will function as a wall definition file. In this case, the graph will be automatically generated when the file is loaded.
Note the presence of a link node that connects to another layer named "street".
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Node",
"id": 0,
"link": {
"layer": "street",
"nodeTo": 0,
"cost": 0.10
}
},
"geometry": {
"type": "Point",
"coordinates": [ 35.0, 0.0 ]
}
},
{
"type": "Feature",
"properties": {
"type": "Node",
"id": 1
},
"geometry": {
"type": "Point",
"coordinates": [ 35.0, 57.0 ]
}
},
{
"type": "Feature",
"properties": {
"type": "Node",
"id": 2
},
"geometry": {
"type": "Point",
"coordinates": [ 5.0, 23.5 ]
}
},
{
"type": "Feature",
"properties": {
"type": "Node",
"id": 3
},
"geometry": {
"type": "Point",
"coordinates": [ 35.0, 23.5 ]
}
},
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[ 35.0, 0.0 ],
[ 35.0, 23.5 ]
]
},
"properties": {
"type": "Arc",
"nodeFrom": 0,
"nodeTo": 3,
"mask": 0
}
},
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[ 35.0, 23.5 ],
[ 35.0, 57.0 ]
]
},
"properties": {
"type": "Arc",
"nodeFrom": 3,
"nodeTo": 1,
"mask": 0
}
},
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[ 5.0, 23.5 ],
[ 35.0, 23.5 ]
]
},
"properties": {
"type": "Arc",
"nodeFrom": 2,
"nodeTo": 3,
"mask": 0
}
},
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [ [
[ 10.0, 27.0 ],
[ 30.0, 27.0 ],
[ 30.0, 57.0 ],
[ 10.0, 57.0 ],
[ 10.0, 27.0 ]
] ]
},
"properties": {
"type": "Wall"
}
},
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [ [
[ 0.0, 20.0 ],
[ 0.0, 0.0 ],
[ 30.0, 0.0 ],
[ 30.0, 20.0 ],
[ 0.0, 20.0 ]
] ]
},
"properties": {
"type": "Wall"
}
},
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [ [
[ 40.0, 0.0 ],
[ 60.0, 0.0 ],
[ 60.0, 57.0 ],
[ 40.0, 57.0 ],
[ 40.0, 0.0 ]
] ]
},
"properties": {
"type": "Wall"
}
}
]
}