back to the OSM tools main page
spatialite_osm_net
Syntax:
usage: spatialite_osm_net ARGLIST
==============================================================
-h or --help print this help message
-o or --osm-path pathname the OSM-XML file path
both OSM-XML (*.osm) and OSM-ProtoBuf
(*.osm.pbf) are indifferenctly supported.
-d or --db-path pathname the SpatiaLite DB path
-T or --table table_name the db table to be feeded
you can specify the following options as well
-cs or --cache-size num DB cache size (how many pages)
-m or --in-memory using IN-MEMORY database
-2 or --undirectional double arcs
--roads extract roads (default)
--railways extract railways
(mutually exclusive)
template-file specific options:
-ot or --out-template path creates a default template-file
-tf or --template-file path using a template-file
|
Example:
$ spatialite_osm_net -o my_country.osm.pbf -d my_country.sqlite -T roads
SQLite version: 3.7.11
SpatiaLite version: 3.1.0
Parsing input: Pass 1 (Nodes and Ways) ...
Parsing input: Pass 2 (Arcs of the Graph) ...
Creating helper table 'roads_nodes' ... wait please ...
Helper table 'roads_nodes' succesfully created
Dropping temporary table 'osm_tmp_nodes' ... wait please ...
Dropped table 'osm_tmp_nodes'
Dropping temporary table 'graph_nodes' ... wait please ...
Dropped table 'graph_nodes'
VACUUMing the DB ... wait please ...
All done: OSM graph was succesfully loaded
$
|
the above shown command must be invoked from the shell:
- -o my_country.osm.pbf selects the OSM input file (in this case, of the OSM-protobuf format).
- -d my_country.sqlite selects the SpatiaLite's DB-file to be created and populated.
- -T roads specifies the table prefix to be used for the Graph/Network to be created.
- you can eventually add any other DB-related optimization switch, if you think it will be useful.
Want to learn more ? read the DB optimization short note
Please note: sometimes you can notice many Unresolved-Node or Unresolved-Way warning messages: dont be too much worried.
This simply means that your OSM input file does actually contains several broken cross-references (i.e. invalid complex Map objects).
This one is a quite common situation, but it's rather innocuous (invalid objects will be simply ignored, fully preserving any other valid object).
Another example:
$ spatialite_osm_net -o my_country.osm.pbf -d my_country.sqlite -T rails --railways
SQLite version: 3.7.11
SpatiaLite version: 3.1.0
Parsing input: Pass 1 (Nodes and Ways) ...
Parsing input: Pass 2 (Arcs of the Graph) ...
Creating helper table 'rails_nodes' ... wait please ...
Helper table 'rails_nodes' succesfully created
Dropping temporary table 'osm_tmp_nodes' ... wait please ...
Dropped table 'osm_tmp_nodes'
Dropping temporary table 'graph_nodes' ... wait please ...
Dropped table 'graph_nodes'
VACUUMing the DB ... wait please ...
All done: OSM graph was succesfully loaded
$
|
- in the previous example we've created from scratch a new DB-file containing a Road Network
This time we'll create into the same DB-file yet another different Graph representing a Railway Network - -T rails specifies the table prefix to be used for the Graph/Network to be created.
- --railways specifies that a Railway Network (and not a Road Network) is intended to be created.
- any other argument exactly has the same meaning as before.
Once the command succesfully completes its execution, you'll find a brand new DB-file just created ...
... you can explore this DB-file e.g. using spatialite_gui. As you can notice, there are four tables in this DB-file:
- the roads table contains the arcs representing the Road Network.
- the roads_nodes table contains the nodes representing the Road Netword.
- the rails and rails_nodes tables play exactly the same roles in representig the Railway Network.
- All arcs of the Graph still preseve the original OSM-Way ID (stored into the osm_id column).
This one is a useful information for debugging purposes and is intended to make easier to eventually correct issues found in the upstream OSM dataset.
Please note: you can directly use the Build Network feature available on the GUI tool in order to create a VirtualNetwork supporting Routing queries.
Alternatively you can use the same feature available on spatialite_gis, or you can use the spatialite_network CLI tool; both them performs the same identical task.
This is an example illustrating how-to build a full-qualified VirtualNetwork corresponding to Roads.
You can then directly query this VirtualNetwork in order to get Routing solutions.
The roads_nodes and rails_nodes may appear to be needless redundant: they are not strictly required in order to correctly represent the Graph, because all Nodes are implicitly defined by Arcs. Anyway there are really good reasons suggesting to create an explicit representation for Nodes:
- this allows to still preserve the original OSM-Node ID (stored into the osm_id column).
As we have already seen about Arcs, this one is a useful information for debugging purposes and in order to correct issues found in the upstream OSM dataset. - a separate layer explicitly representing Nodes is really useful when connecting the DB-file to some GIS application (e.g. QGIS).
- and finally, the cardinality column contains an information highly valuable for debugging purposes.
What is node cardinality ?It simply is the total count of incoming / outcoming Arcs connected to the same Node.Obviously when a node presents a cardinality = 1 there is an exceptional (and may be unexpected) condition. i.e. this denotes a dead end or blind alley: there is no way allowing to go further away, because there is simply a single Arc connected to this Node. Commonly used Networks surely can have many dead ends and blind alleys, it's a normal and fully legitimate condition. But sometimes this condition may reveal an unexpected topology discontinuity (one major issue actually poisoning / killing the Graph for Routing purposes). A wise interpretation of node cardinality is a powerful conceptual instrument allowing to quickly identify obscure reasons causing crazy and puzzling Routing solutions. You can read from this Wiki page futher details about how-to use Node Cardinality in order to easily identify obscure topology discontinuities affecting (and plaguing) OSM networks. |
 |
Advanced configuration settings
OSM dataset are not always regularly self-consistent as expected: a wide variability exists from zone to zone, accordingly to local mapper's tastes and preferences.Remember, OSM is community-driven project: a standard tags definition exists, but this simply being based on a a loose (and freely variable) dictionary.
So it's not at all surprising to eventually discover that many inconsistencies exist, and that variable criteria may have been adopted in different zones by different mapping communities.
In the previous examples we have simply used the standard default configuration assumed by spatialite_osm_net to be the one best fit for average cases.
Anyway a much more sophisticated and more flexible configuration is now supported by spatialite_osm_net, one based on external template-files.
############################################################### # # the '#' char represents a comment marker: # any text until the next new-line (NL) char will # be ignored at all. # ############################################################### # # NodingStrategy section # # - NodingStrategy:way-ends # any Way end-point (both extremities) is assumed to represent # a Node into the Graph [network] to be built. # - NodingStrategy:none # any Way is assumed to directly represent an Arc into the Graph # [network] to be built. No attempt to split and renode the # Graph's Arcs will be performed. # - NodingStrategy:all # any Way point is assumed to represent a Node into the Graph # [network] to be built, if it's shared by two or more Ways. # NodingStrategy:way-ends # default value # NodingStrategy:none # NodingStrategy:all ############################################################### # # OnewayStrategy section # # - OnewayStrategy:full # the following OSM tags will be assumed to identify oneways: # * oneway:1, oneway:true or oneway:yes [oneway, normal direction] # * oneway:-1 or oneway:reverse [oneway, reverse direction] # * junction:roundabout, highway:motorway or highway:motorway_link # * [implicit oneway, normal direction] # - OnewayStrategy:none # all Arcs will be assumed to be bidirectional (no oneway at all). # - OnewayStrategy:ignore-roundabout # any junction:roundabout tag will not be assumed to mark an oneway. # - OnewayStrategy:ignore-motorway # any highway:motorway or highway:motorway_link tag will not be # assumed to mark an oneway. # - OnewayStrategy:ignore-both-roundabout-and-motorway # any junction:roundabout, highway:motorway or highway:motorway_link # tag will not be assumed to mark an oneway. # OnewayStrategy:full # default value # OnewayStrategy:none # OnewayStrategy:ignore-roundabout # OnewayStrategy:ignore-motorway # OnewayStrategy:ignore-both-roundabout-and-motorway ############################################################### # # ClassInclude section # # - tokens are delimited by colons ':' # - the second and third tokens represents a Class-name tag # identifying the Arcs of the Graph: i.e. any Way exposing # this tag will be processed. # - special case: suppressing the third token selects any # generic main-class tag to be processed # ClassInclude:highway: # default value (all kind of highway) ############################################################### # # ClassIgnore section # # - tokens are delimited by colons ':' # - the second and third tokens represents a Class-name tag # identifying Ways to be completely ignored. # ClassIgnore:highway:pedestrian ClassIgnore:highway:track ClassIgnore:highway:services ClassIgnore:highway:bus_guideway ClassIgnore:highway:path ClassIgnore:highway:cycleway ClassIgnore:highway:footway ClassIgnore:highway:byway ClassIgnore:highway:steps ############################################################### # # SpeedClass section # # - tokens are delimited by colons ':' # - the second token represents the Road Class-name # [no name, i.e. '::' identifies the defaul value # to be applied when no specific class match is found] # - the third token represents the corresponding speed # [expressed in Km/h] # SpeedClass::30.0 # default value SpeedClass:motorway:110.0 SpeedClass:trunk:110.0 SpeedClass:primary:90.0 SpeedClass:secondary:70.0 SpeedClass:tertiary:50.0 # SpeedClass:yet_anotherclass_1:1.0 # SpeedClass:yet_anotherclass_2:2.0 # SpeedClass:yet_anotherclass_3:3.0 |
The above one is a full example of such template-file:
- you can freely choose the best fit noding stragegy:
- by specifying NodingStrategy:none you intend that each OSM-Way will be always assumed to represent an arc in the graph.
In other words, OSM-Ways can never be split / rearranged. - by setting NodingStrategy:way-ends an OSM-Way will be split in two distinct arcs each time that one of its OSM-Nodes coicides with an extreme Node of some different OSM-Way.
- by setting NodingStrategy:all an OSM-Way will be split in two distinct arcs each time that one of its OSM-Nodes appear to be referenced at the same time by some other different OSM-Way.
- Please note: the none strategy is a very conservative one, no heuristic assumption is assumed at all; anyway it's very difficult that this strategy will work succesfully when applied to real-world OSM datasets.
The all strategy is a very aggressive one: it could be really succesful in extracting a valid graph from an average OSM dataset, but you can expect that several false-intersections could be eventually introduced into the graph (too much optimistic aspectations about heuristic assumptions).
The way-ends strategy falls somewhere in the middle, minimizing the risk to introduce false connections; but at the same time there is a high probability that many genuine connections will not be identified at all.
- by specifying NodingStrategy:none you intend that each OSM-Way will be always assumed to represent an arc in the graph.
- you can freely choose the best fist oneway strategy:
- by setting OnewayStrategy:full all implicit and explicit oneway settings defined into the OSM dataset will be honored.
- by setting OnewayStrategy:none all oneway settings defined into the OSM dataset will be completely ignored.
i.e. all Arcs inserted into the graph will always be assumed to be unconditionally birectional. - by setting OnewayStrategy:ignore-roundabout all OSM-Ways exposing the highway:roundabout tag will no longer be assumed to implicitly represent an oneway.
- by setting OnewayStrategy:ignore-motorway all OSM-Ways exposing the highway:motorway or highway:motorway_link tag will no longer be assumed to implicitly represent an oneway.
- the OnewayStrategy:ignore-both-roundabout-and-motorway setting will enforce the two above criteria at the same time.
- you can freely define which kind of OSM-Ways are to be inserted in the output network:
- by setting a ClassInclude:key:value directive you'll select a class to be included (e.g. ClassInclude:railway:rail or ClassInclude:highway:motorway).
You can eventually include a full class (including all possible subclasses) omitting to specify the subclass value, e.g. by declaring a single ClassInclude:railway: directive you'll include all railways (any kind). - by setting a ClassIgnore:key:value directive you'll select a class to be ignored (e.g. ClassIgnore:railway:tram or ClassIgnore:highway:bridleway).
- Please note: this works as a two-stage filter; first will be evaluated all the included classes, then excluding each class declared to be ignored.
- by setting a ClassInclude:key:value directive you'll select a class to be included (e.g. ClassInclude:railway:rail or ClassInclude:highway:motorway).
- you can freely assign the average speed for each category of Arcs by setting a specific SpeedClass:category:speed directive. e.g. SpeedClass:motorway:110.0 or SpeedClass:tertiary:50.0 Please note: speeds are expected to be expressed in Km/h.
$ spatialite_osm_net -ot road_template template-file "road_template" succesfully created $ spatialite_osm_net -ot rail_template --railways template-file "rail_template" succesfully created $ |
$ spatialite_osm_net -o my_country.osm.pbf -d my_country.sqlite -T roads -tf road_template $ spatialite_osm_net -o my_country.osm.pbf -d my_country.sqlite -T rails -tf rail_template $ |
back to the OSM tools main page