|
|
1 |
=== About === |
|
|
2 |
|
|
|
3 |
libroutez is a library written to help plan trips. Currently, its focus is |
|
|
4 |
on providing directions for using public transit, but it could be easily |
|
|
5 |
extended to cover other things (e.g. cycle-path planning). Specifically, |
|
|
6 |
it provides an interface to solving the following problems: |
|
|
7 |
|
|
|
8 |
- Finding the closest point in a road/transportation network to a specific |
|
|
9 |
latitude-longitude pair. |
|
|
10 |
- Finding the shortest path between two points in a road/transportation |
|
|
11 |
network. |
|
|
12 |
|
|
|
13 |
The design of libroutez is based on the following principles: |
|
|
14 |
|
|
|
15 |
- Focus on solving user and developer problems, not data structures or |
|
|
16 |
algorithms. For example, though libroutez uses the astar algorithm internally, |
|
|
17 |
we try to expose the interface to that through a simple method called |
|
|
18 |
"find_path". |
|
|
19 |
- Be extensible, but only in response to demonstrative developer need. |
|
|
20 |
- Be fast. libroutez uses an internal graph representation that, after being |
|
|
21 |
generated, can be loaded very quickly on program startup. Trips on a modest |
|
|
22 |
sized transit network can be generated in a fraction of a second on modern |
|
|
23 |
hardware (and there are plans to speed things up further). |
|
|
24 |
- Minimize memory use. Obviously the scale of public transit systems will |
|
|
25 |
incur some overhead here, but we want to be maximally useful on embedded |
|
|
26 |
systems and virtual servers where such resources may be scarce. |
|
|
27 |
- Minimize dependancies. For example, we don't assume the user wants to use a |
|
|
28 |
PostGRES database to store trip planning data (though they can if the want to). |
|
|
29 |
libroutez itself has no run-time dependancies beyond the C++ standard library. |
|
|
30 |
|
|
|
31 |
The libroutez has utility functions for converting Google Transit Feed |
|
|
32 |
(http://code.google.com/p/googletransitdatafeed) and OpenStreetMap |
|
|
33 |
(http://openstreetmap.org) data into its own format. It should be very easy |
|
|
34 |
to add a simple converter for your preferred data type. |
|
|
35 |
|
|
|
36 |
=== Setup and use === |
|
|
37 |
|
|
|
38 |
These instructions assume you are on a UNIX-based system (e.g. Linux or |
|
|
39 |
MacOS X). |
|
|
40 |
|
|
|
41 |
1. Download and install the following packages: |
|
|
42 |
- Boost |
|
|
43 |
- Probably any recent version should do. We need shared_ptr, unordered_set, |
|
|
44 |
and unordered_map (unordered_map.hpp is included in debian/ubuntu packages |
|
|
45 |
libboost1.37-dev & libboost1.38-dev) |
|
|
46 |
- Google Transit Data Feed (http://code.google.com/p/googletransitdatafeed/) |
|
|
47 |
- As of this writing you need what's in SVN, as it has a fix that I made |
|
|
48 |
to actually handle interpolated stops correctly. The next version after |
|
|
49 |
1.1.9 should have my fix. |
|
|
50 |
- SWIG |
|
|
51 |
- A recentish version is desirable. I used 1.3.36. |
|
|
52 |
|
|
|
53 |
Helpful hint: To install a python package in a local prefix, do: |
|
|
54 |
|
|
|
55 |
"python setup.py install --home=$HOME --prefix=" when inside the package |
|
|
56 |
|
|
|
57 |
You may need to set PYTHONPATH to $HOME/lib/python first. |
|
|
58 |
|
|
|
59 |
2. Build the C++ graph module and the bindings. |
|
|
60 |
|
|
|
61 |
The usual... |
|
|
62 |
|
|
|
63 |
- ./autogen.sh && ./configure && make |
|
|
64 |
|
|
|
65 |
For an install into your home directory, try running ./configure like so: |
|
|
66 |
|
|
|
67 |
- ./configure --prefix=$HOME --libdir=$HOME/lib |
|
|
68 |
|
|
|
69 |
or maybe: |
|
|
70 |
|
|
|
71 |
- ./configure --prefix=$HOME --libdir=$HOME/lib64 # (for many 64-bit systems) |
|
|
72 |
|
|
|
73 |
3. Set up your language environment. |
|
|
74 |
|
|
|
75 |
You can either 'make install' to install the binding source to the library |
|
|
76 |
directory you chose with './configure', or set your library and ruby/python |
|
|
77 |
path to the libroutez source directory of your choice. e.g.: |
|
|
78 |
|
|
|
79 |
export LD_LIBRARY_PATH=/path/to/libroutez and |
|
|
80 |
export PYTHONPATH=/path/to/libroutez/python |
|
|
81 |
export RUBYLIB=/path/to/libroutez/ruby |
|
|
82 |
|
|
|
83 |
(setting RUBYLIB is only necessary if you want to use ruby, python is used |
|
|
84 |
by the graph creation utility, so you almost certainly do want that in your |
|
|
85 |
path) |
|
|
86 |
|
|
|
87 |
4. Build a graph. |
|
|
88 |
|
|
|
89 |
To reduce application start up time, libroutez uses a custom graph format |
|
|
90 |
which is created from GTFS and OpenStreetMap data. The creategraph utility |
|
|
91 |
is used to create this. |
|
|
92 |
|
|
|
93 |
The invocation is pretty simple. If you want to create a graph file called |
|
|
94 |
'mygraph.routez', simply invoke creategraph.py as follows: |
|
|
95 |
|
|
|
96 |
./creategraph.py /path/to/gtfsfeed.zip --osm="/path/to/osmfile.osm" \ |
|
|
97 |
mygraph.routez mygraph-gtfsmapping.yml |
|
|
98 |
|
|
|
99 |
Want some sample data to play with? You can download the combination of |
|
|
100 |
William Lachance's Halifax GTFS and Geobase data: |
|
|
101 |
|
|
|
102 |
- http://wlach.masalalabs.ca/hfxfeed.zip |
|
|
103 |
- http://wlach.masalalabs.ca/greater-hrm-geobase.osm.gz |
|
|
104 |
|
|
|
105 |
The Halifax GTFS feed is produced by me, based on information provided |
|
|
106 |
by the city of Halifax. For more information, please see: |
|
|
107 |
http://github.com/wlach/halifax-transit-feed. |
|
|
108 |
|
|
|
109 |
The OSM data is derived from the GeoBase dataset provided by the |
|
|
110 |
government of Canada, and is distributed under the following terms: |
|
|
111 |
http://geobase.ca/geobase/en/licence.jsp |
|
|
112 |
|
|
|
113 |
5. Starting playing with the library. |
|
|
114 |
|
|
|
115 |
Now that you've built a graph, you can start planning trips. Try the |
|
|
116 |
'testgraph' mini program in examples. The following corresponds to |
|
|
117 |
a trip from Cogswell and Maynard to Glengarry Gardens at 9am on Monday, |
|
|
118 |
September 14th 2009 in Halifax, Nova Scotia, Canada: |
|
|
119 |
|
|
|
120 |
"testgraph mygraph.routez 44.649942 -63.583457 44.6605 -63.7467 1252933200" |
|
|
121 |
|
|
|
122 |
You should get a bunch of directions in "routezspeak" in response. :) Note that |
|
|
123 |
no attempt is currently made to prettify the output, but hopefully this will at |
|
|
124 |
least give you a starting point (perhaps that would be a fun little first |
|
|
125 |
project for someone who wants to contribute?). Correlating the descriptive |
|
|
126 |
information contained within a Google Transit feed with libroutez's internal |
|
|
127 |
data structures will necessitate using the gtfs mapping yaml file generated |
|
|
128 |
by the creategraph utility. |
|
|
129 |
|
|
|
130 |
For those who like programming in ruby and python, there are examples of both |
|
|
131 |
in the same directory as 'testgraph'. |
|
|
132 |
|
|
|
133 |
=== Contributing === |
|
|
134 |
|
|
|
135 |
Contributions to libroutez are gratefully accepted. The easiest thing to do |
|
|
136 |
is fork my repository on github (http://github.com/wlach/libroutez), apply |
|
|
137 |
your change (make sure to add your name and nature of contribution to |
|
|
138 |
AUTHORS), then either email me (at wrlach@gmail.com) or the libroutez mailing |
|
|
139 |
list (http://groups.google.com/group/libroutez) to let us know about what you |
|
|
140 |
did. Patch files sent directly to wrlach@gmail.com are also welcome. |
|
|
141 |
|
|
|
142 |
In order for changes to be committed, they will need to be licensed under the |
|
|
143 |
same terms as the rest of libroutez (the MIT license). Please note that you |
|
|
144 |
consent to this in your git commit message or mail the libroutez mailing list |
|
|
145 |
saying that this (or all) your contributions are released under the MIT |
|
|
146 |
license. |
|
|
147 |
|