| 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 |