Transportoid

Dodanie własnego rozkładu do aplikacji

UWAGA! Dodawanie rozkładów własnego miasta do Transportoida nie jest już możliwe, nowe rozkłady są tworzone wyłącznie przez autorów.

Aby dodać rozkład jazdy swojego miasta do aplikacji Transportoid, należy przygotować plik w formacie ZIP zawierający dane według poniższej specyfikacji. Następnie proszę skontaktować się z autorem. Dostarczony rozkład po weryfikacji poprawności zostanie umieszczony na serwerze i stanie się dostępny na wszystkich telefonach z zainstalowaną aplikacją Transportoid.

UWAGA! Jeśli planujesz ręcznie przepisywać rozkłady, nie rób tego! Stracisz na to mnóstwo czasu a cała praca i tak pójdzie na marne po najbliższej aktualizacji rozkładów. Jedyny sensowny sposób to napisanie konwertera, który raz przygotowany przetworzy nowe rozkłady jazdy w kilka(naście) sekund.

Przykładowe konwertery rozkładów

Konwerter plików XML w formacie BUSMAN, język C# – ParserWro (za pomocą tego programu przygotowano bazy dla Wrocławia)

Konwerter plików HTML, język C#, dla ZTM Warszawa – ParserWaw

Konwerter plików HTML, język C#, dla KZK GOP – ParserKZK

Konwerter plików HTML, język PHP, dla Rybnika - rybnik (autorem jest Patryk Połomski – cykuss[małpa]gmail.com)

Konwerter plików HTML, język Python, dla Krakowa - mpkkrakow (autorem jest Piotr Owcarz – powcarz+transportoid[małpa]gmail.com)

Wskazówka: ponieważ praktycznie każdy parser opiera się na wyrażeniach regularnych, potrzebne jest dobre narzędzie do ich testowania – polecam wszystkim damowy program The Regex Coach

Tworzenie nowego konwertera

Przy tworzeniu własnego konwertera warto postępować wg poniższego schematu:

1. napisać funkcję, która przetworzy odjazdy jednej linii z jednego przystanku na trzy linijki odjazdów (roboczy/sobota/niedziela)
2. napisać funkcję, która wywołując sekwencyjnie funkcję nr 1 dla kolejnych przystanków utworzy rozkład jazdy całej linii
3. napisać funkcję, która wywołując funkcję nr 2 dla wszystkich linii utworzy komplet plików składających się na rozkłady jazdy
4. uzupełnić powyższe funkcje o tworzenie listy rozkładów, przystanków i adnotacji

Weryfikacja poprawności rozkładów

Poprawność pliku ZIP z rozkładami jazdy należy sprawdzić za pomocą Weryfikatora poprawności baz:

Weryfikator napisany jest w języku C#, dostępna jest wersja EXE (weryfikator) oraz źródła (strona projektu). Pomyślna weryfikacja oznacza, że rozkłady spełniają specyfikację formatu danych. Nie oznacza to jeszcze pełnej poprawności rozkładów – np. nie da się automatycznie sprawdzić, czy linie komunikacyjne w pliku linie.txt posortowane są w intuicyjny sposób.

Weryfikator może być także używany z linii komend pod Windows i Linuksem (przy użyciu Mono):

weryfikatorrozkladow.exe -file sciezkadotestowanegopliku.zip
weryfikatorrozkladow.exe -dir sciezkadokataloguzrozpakowanymzipem

Kod wyjścia równy zero oznacza poprawną weryfikację, kod różny od zera oznacza błąd weryfikacji (znaczenie różnych wartości można znaleźć w źródłach)

Testowanie własnego rozkładu

Aby przetestować przygotowany samodzielnie rozkład jazdy, należy utworzyć na karcie SD katalog transportoid.data (jeśli jeszcze nie istnieje) i umieścić w nim plik o nazwie test.zip zawierający rozkłady do przetestowania.

W trybie testowym menu aplikacji zmienia się i zawiera dwie pozycje:

Pierwszą opcję należy wybrać zawsze, gdy nowo testowany plik rozkładu zawiera zmodyfikowaną listę linii bądź przystanków.

UWAGA! Jeśli podczas parsowania rozkładów program zawiesza się, oznacza to błędnie sformatowany plik danych. Podłącz kabel USB i uruchom debugger (ADB), przy ponownym uruchomieniu w logach znajdziesz listę kolejno przetwarzanych plików. Podejrzany jest ostatni wczytywany przed wystąpieniem wyjątku (błędu).

Aby opuścić tryb testowy, należy usunąć z karty SD plik \transportoid.data\test.zip

Budowa bazy rozkładów

Baza danych rozkładów jest archiwum ZIP składającym się z

1. plików rozkładów jazdy dla pojedynczych linii
2. pliku zawierającego listę linii komunikacyjnych
3. pliku zawierającego listę przystanków
4. pliku zawierającego informacje o bazie danych
5. pliku zawierającego informacje o geograficznej lokalizacji przystanków (opcjonalnie)
6. pliku zawierającego listę adnotacji do odjazdów (opcjonalnie)

Plik z rozkładem jazdy

Format pliku z rozkładem pojedynczej linii jest następujący:

wiersz 1: krótka nazwa linii (np. 1)
wiersz 2: przystanek początkowy (otwarty tekst, nie indeks)
wiersz 3: przystanek końcowy (otwarty tekst, nie indeks)
BLOK_ODJAZDÓW razy n

gdzie BLOK_ODJAZDÓW jest powtórzonym n razy czteroliniowym zestawem określającym godziny odjazdów z kolejnych przystanków:

wiersz 1: numer przystanku (z pliku przystanki.txt)
wiersz 2: ODJAZDY w dni robocze
wiersz 3: ODJAZDY w soboty
wiersz 4: ODJAZDY w niedziele

Wyjątek: ostatni blok (przystanek końcowy) może opcjonalnie składać się tylko z wiersza 1, bo niektórzy przewoźnicy nie publikują godzin dojazdu na pętlę. W przypadku pętli końcowej podane godziny oznaczają PRZYJAZD na pętlę. Odjazdy podaje się w pierwszym przystanku linii.

Wiersz nr 1 bloku odjazdów (wiersz z numerem przystanku) może być zakończony literami NZ (bez spacji między numerem a literami), co oznacza przystanek na żądanie.

Blok ODJAZDY ma zawsze jeden wiersz i może przyjmować jedną z trzech postaci:

1. kolejne odjazdy uporządkowane od najwcześniejszego, oddzielone przecinkami, postaci hmm lub hhmm (904 = 9:04, 1223 = 12:23), Nowość opcjonalnie z przypisami (patrz rozdział Przypisy) lub dwiema gwiazdkami (opis tamże)
2. napis JAKWYZEJ (może wystąpić tylko w rozkładach z soboty lub niedzieli) – kopiuje odjazdy z wiersza wyżej
3. napis BRAK – informuje, że dana linia nie odjeżdża w danym dniu ze wskazanego przystanku

Przykładowy wiersz odjazdów dla autobusu szczytowego:

507,606,702,802,1206,1306,1406,1806,2006,2106,2159,2259

UWAGA! Częstą pomyłką jest brak sortowania rozkładów linii nocnych rosnąco, oto prawidłowa postać dla rozkładu zawierającego odjazdy przed północą:

005,105,205,305,405,2305

Plik z listą linii

Plik definicji linii komunikacyjnych nosi nazwę linie.txt i zawiera listę nazw plików z definicjami rozkładów – w takiej kolejności, w jakiej linie mają być prezentowane w aplikacji

Przykładowy fragment pliku linie.txt:

0001-0.txt
0001-1.txt
0002-0.txt
0002-1.txt
0003-0.txt
0003-1.txt

Uwaga! W niektórych sytuacjach skrypt przetwarzający rozkłady alfabetycznie może obrać kolejność linii 1, 10, 100, 2, 20, 200 – tymczasem zazwyczaj pożądana jest kolejność 1, 2, 10, 20, 100, 200.

Plik z listą przystanków

Plik definicji przystanków nosi nazwę przystanki.txt i zawiera listę wszystkich przystanków występujących w rozkładach, po jednej nazwie na wiersz. Każdy przystanek poprzedzony jest kolejną liczbą całkowitą (pierwszy wiersz startuje od zera) po którym następuje spacja i nazwa przystanku. UWAGA ZMIANA! Przystanki nie muszą być posortowane, kolejność może być dowolna. Numeracja obowiązkowo od zera wzwyż kolejnymi liczbami całkowitymi, bez dziur.

Przykładowy fragment pliku przystanki.txt:

71 Podwale
72 most Grunwaldzki
73 Renoma
74 Opera
75 Oławska
76 Uniwersytecka
77 Dubois
78 pl. Bema

UWAGA! Należy unikać umieszczania w tym pliku przystanków przy których nie staje żadna linia, jest to marnowanie miejsca na ekranie (obecność takich pozycji niczego nie psuje).

Plik informacyjny

Plik informacyjny nosi nazwę info.txt składa się z 6 wierszy:

nazwa miasta
data początku ważności rozkładów
data przygotowania bazy danych
imię i nazwisko przygotowującego bazę
e-mail przygotowującego bazę
informacje dodatkowe

Przykładowy plik info.txt:

Wrocław
18.02.2010
20.02.2010
Tomasz Zieliński
tomasz.zielinski@gmail.com
Rozkład jazdy po feriach

Plik z informacjami geograficznymi – opcjonalny

Plik z informacjami o geograficznej lokalizacji przystanków jest opcjonalny, nosi nazwę przystankiwsp.txt

Plik ten składa się z wierszy postaci

<nr> x0;y0;[x1;y1;x2;y2;...]

Gdzie nr jest numerem przystanku jak określono w pliku przystanki.txt. Numer jest oddzielony od współrzędnych jedną spacją. Numery mogą być podane w dowolnej kolejności, nie mogą się dublować, nie wszystkie indeksy muszą zostać użyte.

Współrzędne x0 oraz y0 są obowiązkowe i określają położenie przystanku na mapie. Jeśli dostępne są dane o lokalizacji słupków wchodzących w skład przystanku, należy umieścić je jako następne w kolejności, podając zawsze najpierw długość a potem szerokość geograficzną. W przypadku, gdy mamy do dyspozycji wyłącznie lokalizacje słupków, brakujące współrzędne całego przystanku najlepiej obliczyć jako średnią arytmetyczną lub środek ciężkości słupków składających się na ten przystanek.

Współrzędne geograficzne podawane są jako stopnie geograficzne pomnożone przez milion, jest to zawsze liczba całkowita. Przykład obliczeń:

12°34’56” = 12.582222° = 12582222

Fragment przykładowego pliku przystankiwsp.txt

83 17035512;51111942;
85 17042445;51117354;17041372;51117235;17044190;51117302;

UWAGA! Ten plik musi być kodowany w standardzie ASCII

Plik z przypisami – opcjonalny

Plik z przypisami nosi nazwę adnotacje.txt, pozwala zawrzeć w programie informacje, które w rozkładach mają zazwyczaj postać przypisów z oznaczeniami literowymi (np. „autobus niskopodłogowy” lub „zjazd do zajezdni”). Plik zawiera po jednym przypisie w jednym wierszu. Format jest następujący:

XX YY NAPIS

gdzie:

XX to oznaczenie, które będzie umieszczane w plikach z rozkładami jazdy – zawsze dwie litery z zakresu [a-zA-Z] każda, przy czym wielkość (case) drugiej litery ma dodatkowe znaczenie, patrz poniżej
YY to oznaczenie, które pojawi się na ekranie przy godzinie odjazdu – powinien to być znak lub łańcuch znaków odpowiadający oznaczeniu z odjazdów papierowych
NAPIS to tekst, który będzie wyświetlany jako legenda objaśniająca znaczenie przypisów

UWAGA! Wielkość drugiej litery w ciągu XX ma dodatkowe znaczenie, mała litera oznacza kurs pojazdem niskopodłogowym

UWAGA! Istnieje możliwość dodawania oznaczenia o pojeździe niskopodłogowym także bez przypisu, należy wówczas zamiast XX użyć dwóch gwiazdek (czyli **). Sposób ten dostępny jest także wtedy, gdy rozkłady nie mają pliku adnotacje.txt

Konwerter rozkładów powinien umieszczać identyczne przypisy pod jednym symbolem (gdy zgodność dotyczy zarówno oznaczenia jak i napisu).

Fragment przykładowego pliku adnotacje.txt

EX R kurs do Rędzina
Fy BN kurs do Blizanowic; autobus NISKOPODŁOGOWY
NK C kurs skrócony do Centrostalu

Fragment przykładowego pliku z odjazdami, z dodanymi odnośnikami do przypisów:

507EX,606EX,702,802,1206Fy,1306,1406NK,1806,2006,2106NK,2159**,2259

Kodowanie znaków w plikach tekstowych

Wszystkie pliki, o ile nie określono inaczej, muszą być kodowane w formacie UTF-8 i mogą zawierać nagłówek BOM (jest to zalecane).