Format danych
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:
- napisać funkcję, która przetworzy odjazdy jednej linii z jednego przystanku na trzy linijki odjazdów (roboczy/sobota/niedziela)
- napisać funkcję, która wywołując sekwencyjnie funkcję nr 1 dla kolejnych przystanków utworzy rozkład jazdy całej linii
- 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
- 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
- plików rozkładów jazdy dla pojedynczych linii
- pliku zawierającego listę linii komunikacyjnych
- pliku zawierającego listę przystanków
- pliku zawierającego informacje o bazie danych
- pliku zawierającego informacje o geograficznej lokalizacji przystanków (opcjonalnie)
- 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:
- 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)
- napis JAKWYZEJ (może wystąpić tylko w rozkładach z soboty lub niedzieli) – kopiuje odjazdy z wiersza wyżej
- 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).