CITS2002 Systems Programming

Lecture & Workshop
recordings on LMS

Schedule

FAQ

C textbooks

OS textbooks

Information resources

Look after yourself!

Project 1 2015 - which bus should I catch?

Perth's Public Transport Authority (PTA) provides public access to its scheduled times, stop locations, and route information from its webpage www.transperth.wa.gov.au/About/Spatial-Data-Access. The data is released as a collection of inter-related textfiles following the Google Transit Feed Specification (GTFS), which is also used by many other public transport companies, worldwide.

The goal of this project is to assess your understanding of introductory C99 programming language features, including its control-structures, simple data-structures, and it standard library support for string handling and text files. The project can be successfully completed using the information presented in CITS2002's lectures, laboratories, and tutorials, to the end of week-5.

You will need to download your own copy of the data (about 90MB) by clicking on the first link "By downloading the data you are agreeing to the terms of the License..."
The currently available data is valid until November 25th (after the project's due date).

The primary task

The project requires you to develop a C99 program, named whichbus, which uses GTFS-format data to find the shortest travel time between two provided locations. Your program should check for and accept 5 command-line arguments:

the name of a directory containing a set of GTFS files, and
a starting and an ending location (as pairs of latitude and longitude coordinates, typically home and work),

and produce plain-text output describing the "best" single-segment public transport route that should be taken to travel between the two locations. The starting time of the journey should be taken from the environment variable named LEAVEHOME. This enables you to develop and test your program by holding the day and time constant. We will assume that all services run every day. However, ensure that a 3-character 'day' still appears at the beginning of the LEAVEHOME environment variable. The example, below, shows how you can set this environment variable to the current day, hour and minute, and then export it to your program.

The definition of the "best" route is the one requiring the minimum total journey time, consisting of single-segment:

walking from the starting point to the single bus, train, or ferry stop;
travel time on the bus, train, or ferry;
time walking from the final stop to the required destination.

Representative executions and outputs of your program, requesting single-segment journeys - one by bus and another by rail - are:

prompt>  export  LEAVEHOME="`date '+%a %H:%M'`"

prompt>  echo $LEAVEHOME
Wed 10:56

prompt>  ./whichbus  transperth  -32.014402  115.758259 -31.981039  115.819120
10:56  walk  316m  to  stop  10349  "Stirling Hwy After Wellington St"
11:04  catch  bus 98  to  stop  10380  "Stirling Hwy After Clifton St"
11:23  walk  750m  to  destination
11:36  arrive

prompt>  export  LEAVEHOME="Mon 14:00"

prompt>  ./whichbus  transperth  -31.747750  115.766545  -31.952804  115.854921
14:00  walk  332m  to  stop  99871  "Joondalup Stn Platform 1"
14:07  catch  rail  "Joondalup Line"  to  stop  99602  "Perth Underground Stn Platform 2"
14:33  walk  336m  to  destination
14:39  arrive

Your program should allow the traveller sufficient time to walk from their starting location (typically their home) to, say, a nearby bus-stop. Amazingly, people can walk in straight lines at a constant speed of one metre-per-second, between any two points (through buildings!), and buses are always on time! No walking segment should be longer than 1000m.

In addition, in order to reduce the number of potential journeys that need searching, the actual segment on a bus, train, or ferry, must commence within one hour of leaving the starting location (home).

An extended task

You can achieve full marks, 20/20, for the project by successfully implementing the primary task, above. In addition, you may wish to attempt an extended task to recover any lost marks. you may wish to attempt an extended task to recover any lost marks The extended task permits a journey to consist of two-segments, on any combination of bus, train, or ferry. A two-segment journey would involve additional steps:

getting off the first bus, train, or ferry;
walking to transfer to another bus, train, or ferry;
waiting for the connection to arrive;
traveling on a second bus, train, or ferry towards the destination; and
(as before) walking from the final stop to the required destination.

The representative execution and output of your program, requesting a journey involving a train segment and then a bus segment, is:

prompt>  ./whichbus  transperth  -32.029674  115.755018  -31.981039  115.819120
11:08  walk  305m  to  stop  99341  "North Fremantle Stn Platform 1"
11:15  catch  rail  "Fremantle Line"  to  stop  99281  "Claremont Stn Platform 1"
11:25  walk  165m  to  stop  19604  "Gugeri St Before Bay View Tce"
11:30  catch  bus  102  to  stop  26723  "Mounts Bay Rd After Hampden Road"
11:41  walk  620m  to  destination
11:51  arrive

If you successfully achieve the extended task, you can recover up to 5 marks that may have been lost while attempting the primary task. The maximum mark for your project submission will still be 20/20.

Program requirements

Projects will be marked using an automatic marking program (for correctness) and by visual inspection (for good programming practices). It is thus important that your program produces its output in the correct format. Only lines commencing with digits (for times) will be considered valid output during the testing - thus, you can leave your "last minute" debugging output there if you wish.

Each line of output consists of a number of fields, which may be separated by one-or-more space or tab characters. The names of bus, train, and ferry stops should be enclosed within double-quotation characters, as the names include spaces. Times should be specified as HH:MM using a 24-hour clock, and no journey (in testing) will span midnight. Distances should be reported as an integer number of metres (truncated, no decimal component), such as 340m.

A program will be provided to enable you to test the correctness of the output format of your program.

Suggested steps for the primary task

Consider how you would travel between the two locations if you were a dumb robot with unlimited time, patience, and energy.
Download the GTFS dataset, and skim its documentation webpage. See what is in each textfile, determine which files will be required, and which files not required.
Discuss the problem with a colleague (your project partner?) as to how you'd each attack the problem. Merge. Iterate.
Too soon for coding? Probably. Code your main() function, checking for and validating the 5 command-line arguments.
Find the bus, train, or ferry stops that are within 1000m (walk) of the starting location.
Determine which bus, train, or ferry routes use each of those stops, today, after the journey's starting time.
Do any of those bus, train, or ferry routes pass within 1000m (walk) of the destination? Which journey has the shortest total time?
No? Hmmm, looks like we'll need to transfer to another bus, train, or ferry....

Good luck!

Chris McDonald.