-
Notifications
You must be signed in to change notification settings - Fork 1
GettingStartedSystemMap
The system map is an experimental module. The API and implementation are in flux. Use at your own risk.
That being said, these instructions will help you get up and running with the system map. There are a number of moving parts, and there may be other ways to set up particular steps. This page lists one way to get everything set up.
First, you'll need to have OpenTripPlanner itself up and running. You can find information on how to get up and running on the GettingStartedEclipse pag. (If you prefer not to use Eclipse, you follow the instructions on the GettingStartedMaven page instead.)
The system map also requires GeoServer to be set up. (Technically it just requires a WMS server that returns custom responses, however it has only been tested with GeoServer.)
You can install GeoServer a number of different ways. You can download the latest release as a .war file and stick it in Tomcat and run it manually. Alternatively, or you can install from source.
The URL to serve the WMS tiles and respond to WMS getfeatureinfo requests will need to be exposed to the client. Other URLs, like the URL to the admin interface, do not need to be exposed.
Once GeoServer is installed, the GTFS data must be made available to GeoServer. One way is to use gtfsdb to store the data in PostGIS.
When it's in the database, add a PostGIS store under a new workspace. Then add layers for the routes and stops. You should name the route and stop layers "routes" and "stops". Currently the api extended is hardcoded to expect its responses to contain those strings. You'll need the names of the layers and the geoserver url at a later step, when the config.js in webapp is configured. If you want to take advantage of highlighting stops and routes the user interacted with, you should create two more layers which also point to the routes and stops data. These can be named anything, but I've used "routes_highlighted" and "stops_highlighted".
Before getting into what these data modifications are, a little background as to the reason for them. Since the shape data will be served as WMS, when the user interacts with the map, a WMS getfeatureinfo request is sent to the server to find out if there are any features there. In a straight GeoServer environment, geoserver will respond back with some html if the user interacted with a feature. In our environment, the request will first go to the api extended. The api extended will then pass the request over to geoserver, which will respond back with the ids of the features, if any, that were requested. The extended api will then look up the appropriate gtfs information for the response, and pass that back to the client. There are other strategies for this as well. For example, a custom geoserver extension could have geoserver look up this information, and return the appropriate response directly. But currently the api extended handles assembling the information from different sources back into a response to the client.
So what needs to be customized is geoserver's response back to the extended api. Geoserver uses freemarker templates to customize the response. Here are the steps required for these customizations:
-
In your data dir, find your workspace, and the layers in this workspace
-
For each layer, you'll need to add three freemarker template files:
-
header.ftl - empty file
-
footer.ftl - empty file
-
content.ftl - <#list features as feature> ${feature.fid} </#list>
Instead of passing back html, geoserver should now pass back a whitespace separated list of ids. The responses should look like: "stops.R01" or "routes.N". An easy way to verify if it's working is to look at the openlayers layer preview for the routes and stops and click on a particular feature. The responses here are what geoserver will respond with for the extended api. If you see an html table, that means the freemarker template customizations aren't being applied.
Find the configuration file for the extended api: opentripplanner-api-extended/src/main/resources/org/opentripplanner/api/extended/application-context.xml . Edit the path to the gtfs file, and specify the base wms url for geoserver. This is the url that the extended api will use when forwarding the wms requests to geoserver, so it should represent how the machine running the api-extended will access the machine running geoserver (it can be an internal ip address).
Find the configuration file for the webapp: opentripplanner-webapp/src/main/webapp/js/otp/config.js . There are a few changes that will need to be made here:
-
In the system map section:
-
enabled: true
-
layerUrlRoutes/layerUrlStops/layerUrlRoutesHighlighted/layerUrlStopsHighlighted: these should be set to the public externally facing urls to the wms server. Openlayers will use these urls to fetch the tiles for the system map routes and stops. Note that they can all point to the same url. There are different options set to support having each layer be served from a separate location. Perhaps this was premature optimization.
-
layerNamesRoute/layerNamesStop/layerNamesRouteHighlighted/layerNamesStopHighlighted: these need to match the layer names in geoserver. They can be prefixed with the workspace. So if your route layer is called "routes" and your workspace in geoserver is called "gtfsdb", your layerNamesRoute would be set to "gtfsdb:routes".
-
controlStopsUrl: This should be set to the url that the api extended will respond to. If no url paths are changed (either in web.xml or in a webserver) the default "/opentripplanner-api-extended/wms" should work just fine.
-
In the map section, you can modify the defaultExtent that gets loaded. This should be an openlayers bounds object. I suspect that you'd want to change this if using the system map to start zoomed in on a popular area. If you leave the default of "automatic" an ajax request is made to the opentripplanner-api-webapp module which will return the extent of your graph's data.
If you've made it this far, the system should be working. If it is, congratulations! If not, try checking the logs for what looks like is wrong. Here are some typical errors and usually what's causing them:
-
Nothing loads in the map - Your base layers are probably wrong in the config.js file.
-
No system map is loaded - make sure enabled is set to true in the config.js file. If that doesn't help, check for javascript errors.
-
The base layer is loaded but there are broken tiles on top - Is geoserver running? If so, check the geoserver wms urls in config.js. If they look fine, try accessing geoserver's layer preview directly through the geoserver interface. If that works, does that url (minus the params) match the urls in the config.js file? If none of these help, have a look at geoserver's log file for any clues.
-
Hovering/Clicking on stops doesn't generate a popup - Is the opentripplanner-api-extended module running? Is geoserver running? Is the controlStopsUrl set correctly in config.js? Check firebug to see what the response is to the ajax request, which might have a clue. You can try that url manually in a browser to see what happens. If nothing, try checking geoserver manually. In the layer preview, clicking on a stop should return a string like "stops.R01" where R01 is the gtfs stop id. If you get an html response, the freemarkertemplate customizations haven't been applied.
Everything should be working at this point, but there are a number of things that can be changed to make things look nicer.
-
Line/stop styling. Since geoserver is serving the geometry data, the styles can be customized to a very large degree. You'll want to look at sld
-
Logo - In config.js, set the logo parameter to the url for a custom logo
-
Custom route icons - set the useCustomIconsForAgencies parameter in the config.js file. This should be set to a list of gtfs agency ids, and are customizable at the agency level. The filesystem structure needs to look like: custom///(-|-).png . These need to be case sensitive. If things aren't working, check to see what url the client is trying to fetch for the image, and name the image appropriately.
Beyond that, there are many more features that could be added. Accessibility information, real time locations, and service alerts could all be valuable for a system map.
Further development of system map would be helped by some kind of in-browser vector graphic rendering: DisplayingVectorGraphics