Unweaver
Visit https://unweaver.org for the official documentation.
Unweaver is a routing engine focused on flexibility. It can read many data formats (including OpenStreetMap), find shortest-path routes via a web API, and allows completely customizable combinations of cost functions and directions specifications, summarized in "profiles". Unweaver's costing strategy includes dynamics (as opposed to precalculated) edge costs for when profiles need to be heavily parameterized on a per-user basis.
If you want to use unweaver
as a command line application or library, see
the installation section. If you want to contribute to the
development of unweaver
itself, see CONTRIBUTING.md.
Installation
unweaver
can be used as a command line application or a library that can be
used to develop new applications or analyze geospatial networks in a Jupyter
notebook.
Regardless of the way you install and use unweaver
, it has a set of
non-Python dependencies that will need to be installed on your system first.
-
Go here to get instructions on installing the non-Python dependencies required by
unweaver
. -
Go here to get instructions on installing
unweaver
as a command line application. -
Go here to get instructions on installing
unweaver
as a library.
Install and configure non-python dependencies
Unweaver depends on the following software packages in order to run:
- SQLite: A file-based SQL database and the format of the routable GeoPackage
created by
unweaver
. - SpatiaLite: An extension for SQLite that adds geospatial support.
- GDAL: A common geospatial library for reading/writing geodata formats.
- proj4: A common geospatial library for managing map (re)projections.
Platform-specific installation instructions
On a Mac using Homebrew:
brew install sqlite libspatialite gdal proj
(See this troubleshooting on Mac section if
you still can't load SQLite extensions with unweaver
)
On a debian-based distribution:
apt install libsqlite3 libspatialite libgdal libproj
Enable SQLite extension support in Python
Python may be distributed with or without SQLite and extensions support. For example, if you are using pyenv to manage your Python installation, you will need to ensure it is built with flags enable SQLite support.
unweaver
as a command line application
Install Unweaver is build with the poetry
toolkit. When Unweaver is properly released on
PyPI, installing the module will be as simple as running poetry add unweaver
. For
now, it must be installed from this repository. This can be done using either with
poetry
(ideal) or pip
(for backwards compatibility).
pip
:
With This can be done with a one-liner:
pip install git+https://github.com/nbolten/unweaver.git@f9f4bed#egg=unweaver
Where the @
entry is the commit. This can also be set to a branch name.
unweaver
as a library
Install poetry
:
With Edit your pyproject.toml
to include a line like this under
[tool.poetry.dependencies]:
unweaver = {git = "https://github.com/nbolten/unweaver.git", rev = "f9f4bed"}
You can choose rev
to be whatever git commit hash you want to use.
pip
:
With This can be done with a one-liner:
pip install git+https://github.com/nbolten/unweaver.git@f9f4bed#egg=unweaver
Where the @
entry is the commit. This can also be set to a branch name.
Data format flexibility
Unweaver can ingest any linear (LineString) format processable by GDAL, including GeoJSON and Shapefiles. The primary graph data structure created from these data is a portable, routable GeoPackage.
This GeoPackage stores network information in an edge list format using two
feature tables: nodes
and edges
.
nodes
has a primary key (fid
), a unique node id (_n
), and a Point
geometry column (geom
by default). The nodes
table can be extended to
include any number of other columns, but unweaver
does not automatically do
so during the build step at this time.
edges
has a primary key (fid
) a unique pair of node ids that describe the
edge (_u
and _v
), and a LineString geometry column. The edges
table is
automatically extended during the build process, transforming input linear data
properties into column names and values. For example, a "length" numeric
property in the input data will result in the creation of a numeric "length"
column populated with the associated values. The use of _u
and _v
to
uniquely identify an edge means that unweaver
describes a digraph and not
a multidigraph. Multidigraph support is planned for the near future, as
real-world networks frequently have multiple paths starting and ending at the
same location.
Running the example
Get the data
The example expects there to be a GeoJSON file representing a sidewalk network
in the example/layers
directory. You may need to create the layers
directory. Unfortunately, we don't have a consistent place to put this example
data yet, so to get it please request it from someone at the Taskar Center or
from the repo author.
Build the graph
Run unweaver build ./example
in the main repo. If you are running Unweaver
as a developer using poetry
, run poetry run python -m unweaver build ./example
.
This will create example/graph.gpkg
, a GeoPackage that Unweaver can use for
network queries, including routing.
Weight the graph
Run unweaver weight ./example
in the main repo. If you are running Unweaver
as a developer using poetry
, run poetry run python -m unweaver weight ./example
.
This will update example/graph.gpkg
with a precalculated weight value for a
(necessarily non-representative) stereotyped manual wheelchair user.
Run the web server
Run unweaver serve ./example
in the main repo. If you are running Unweaver
as a developer using poetry
, run poetry run python -m unweaver server ./example
.
This will run a Flask web server to which requests to the
/shortest_path/<profile>.json
, /shortest_path_tree/<profile>.json
, and
/reachable_tree/<profile>.json
endpoints may be sent.
Troubleshooting
Can't load extensions on a Mac
Unweaver needs to load the SpatiaLite extension for SQLite3, but the version of SQLite3 that comes with Macs cannot load extensions by default. You will need to:
- Install sqlite3 from a third party, such as homebrew:
brew install sqlite3
- After installing (or after running
brew link sqlite3
), follow the instructions to set up your PATH and library flag locations to be the homebrew ones. This will involve editing your shell's config, usually.bashrc
or.zshrc
. - Ensure that your environment is set up correctly by opening a new terminal
and running
which sqlite3
. If the path is/usr/bin/sqlite3
and not a path with the wordCellar
in it, your environment is not correct and you need to (1) runsource .bashrc
(or.zshrc
) to enable it in your current environment, then test again, and (2) troubleshoot your environment until it automatically loads your shell config automatically (sometimes a restart is required). - Install Python such that it links to this sqlite3 or builds its own with
extension support.
pyenv
can be configured to do so with some flags. Example here. - Use this version of Python to set up your
poetry
environment below usingpoetry env <path/to/your/pyenv/bin/python
or<path/to/your/pyenv/bin/python> -m venv venv
to create a non-poetry custom virtual environment.