I componenti rilasciati sono i seguenti:
- GTFS2NeTEx-converter : software per la conversione di feed GTFS in NeTEx Italian Profile Level 1 (EPIP) secondo lo Schema NeTEx Italian Profile e le corrispondenti Linee Guida di Compilazione
GTFS2NeTEx-converter e' un applicativo a linea di comando, organizzato in moduli che contengono varie classi e metodi.
Il software richiede l'installazione di:
- Python 3.10 o superiore
Devono inoltre essere installate (pip install o pip3 install) le librerie:
- pandas
- haversine
GTFS2NeTEx-converter utilizza SQLite3 in fase di elaborazione; l'ambiente SQLite3 e' generato in fase di runtime dalla corrispondente libreria base Python 3: non e' pertanto necessaria alcuna forma di installazione di un RDBMS.
Si consiglia l'utilizzo con macchine dotate di almeno 16GB RAM.
Clonare il progetto git in una apposita directory <DEV_HOME>
cd <DEV_HOME>
git clone https://github.com/Liguria-Digitale/GTFS2NeTEx-converter.git
GTFS e' una specifica, uno standard de facto e non uno standard de iure come NeTEx.
Non avendo uno schema di controllo puo' essere soggetto a molteplici implementazioni, pur mantenendo una struttura base aderente alla specifica ufficiale.
Per questa ragione GTFS2NeTEx-converter e' implementato aderendo strettamente alla specifica General Transit Feed Specification, traguardando lo schema NeTEx Italian Profile.
Pertanto non vengono elaborati:
- files .txt non contemplati dalla specifica
- campi non previsti dalla specifica all'interno dei files .txt contemplati dalla specifica
Laddove si rendesse necessaria l'elaborazione di tali informazioni il codice dovra' essere personalizzato.
Una descrizione esaustiva dei File Requirements e' fornita nel GTFS Schedule Reference
Il programma nella versione attuale controlla l'esistenza dei files:
- agency.txt
- calendar_dates.txt (*)
- calendar.txt (*)
- feed_info.txt
- routes.txt
- stops.txt
- trips.txt
- stop_times.txt
- shapes.txt
(*) calendar_dates.txt e calendar.txt possono essere presenti in alternativa o in combinazione.
Si avverte inoltre che per ottenere una conversione ottimale:
- vengono trattati solamente feed GTFS monoziendali (ovvero feed in cui il file
agency.txtcontiene un solo record) - deve essere presente il file
feed_info.txt, correttamente compilato - nel file
stop_times.txtdeve essere presente e correttamente valorizzato il camposhape_dist_traveled: qualora la condizione non sia verificata il programma termina - deve essere presente il file
shapes.txt:- se
shapes.txtnon e' disponibile il programma termina: si consiglia l'utilizzo preliminare del tool Pfaedle (vedi 4.2.1) - se
shapes.txte' disponibile ma il camposhape_dist_travelednon e' valorizzato, GTFS2NeTEx-converter effettua il calcolo delle distanze in fase di conversione utilizzando la formula degli haversines
- se
Si consiglia di effettuare un pre-processing del feed GTFS, allo scopo di verificarne la correttezza e la rispondenza alla specifica.
Esempi di tools specifici di validazione:
-
Transitfeed e' una collezione di applicazioni Python 2.7 che permettono di effettuare operazioni di validazione formale e controllo del GTFS in input (sulla stessa macchina possono coesistere molteplici versioni di Python 2 e Python 3). I vari applicativi sono descritti anche in Transitfeed Wiki
-
GTFS Validator e' disponibile come:
- servizio web
- come applicazione desktop
Entrambi i tools descritti segnalano anche warnings relativi ai seguenti problemi:
-
Too Fast Travel imputabili alle seguenti cause:
- Fermate consecutive posizionate troppo distanti tra loro (tipicamente e' un errore di posizionamento delle fermate stesse)
- Intertempi errati (troppo brevi) rispetto alla distanza tra fermate consecutive
-
Too Many Consecutive Stop Times With Same Time probabilmente imputabili ad errori di interpolazione temporale delle fermate consecutive da parte del sistema che genera il GTFS
Questi problemi non inficiano il processo di conversione in NeTEx (e la successiva validazione formale) ma possono generare errori in fase di import del NeTEx prodotto in ambienti di travel planning quali OpenTripPlanner, pertanto la loro correzione e' fortemente consigliata.
Per ovviare alla mancanza del file shapes.txt si consiglia l'utilizzo di:
-
Pfaedle e' una applicazione C++ sviluppata e mantenuta dal Algorithms and Data Structures Group dell'Universita' di Friburgo.
Pfaedle permette di effettuare un map-matching accurato di un feed GTFS in input utilizzando un file
.osm(OpenStreetMap) relativo all'area geografica interessata: la rete di trasporto corretta e' scelta automaticamente da Pfaedle in base al valoreroute_typediroutes.txt.I files .osm per l'Italia sono scaricabili dal Geofabrik Download Server .
Il feed GTFS generato contiene:
- il file
stop_times.txtcon il camposhape_dist_traveledvalorizzato, consentendo di dedurre i JourneyPatterns dal GTFS. - il file
shapes.txtcon il camposhape_dist_traveledvalorizzato, consentendo di calcolare le estensioni delle distanze in NeTEx.
Pfaedle e' anche utilizzabile in modalita' containerizzata (Dockerfile), altamente consigliabile.
- il file
In ambienti Windows aprire una Command Window come Amministratore (in ambienti Linux/MacOS aprire una Terminal Window con privilegi di root):
cd <DEV_HOME>
Il convertitore e' lanciato con il comando:
python GTFS2NeTEx-converter.py --folder <GTFS_FEED_FOLDER> --NUTS <NUTS2_CODE> --db <AGENCY_ACRONYM> --az <AGENCY_ACRONYM> --vat <AGENCY_VAT_NUMBER> --version <VERSION_NAME>
Il significato degli argomenti (tutti obbligatori) e' il seguente:
--folder <GTFS_FEED_FOLDER>: puntamento alla path assoluta della directory ove il feed GTFS e' stato precedentemente decompresso--NUTS <NUTS2_CODE>: codice NUTS2 del territorio in cui e' compreso il bacino di esercizio dell'azienda di trasporto (l'elenco completo dei codici NUTS2 per l'Italia e' consultabile in Elenco NUTS2 italiani)--db <AGENCY_ACRONYM>: nome del database SQLite3 intermedio utilizzato dal convertitore (evitare blank e caratteri speciali)--az <AGENCY_ACRONYM>: acronimo dell'azienda TPL (evitare blank e caratteri speciali) che verra' utilizzato per strutturare i dati in NeTEx--vat <AGENCY_VAT_NUMBER>: numero di Partita IVA dell'azienda TPL (11 caratteri numerici)--version <VERSION_NAME>: nome della versione del NeTEx prodotto (evitare blank e caratteri speciali)
Esempio di utilizzo:
python GTFS2NeTEx-converter.py --folder D:\APPO-OPENTRIPPLANNER\DATI\GTFS-feeds-RL\BASE-TPLLINEA\GTFS-IT-ITC3-TPLLINEA-20240701-20240908-pf-fares --NUTS IT:ITC3 --db TPLLINEA --az TPLLINEA --vat 01556040093 --version 240202
Se il processo termina correttamente all'interno della directory <GTFS_FEED_FOLDER> saranno presenti i seguenti files:
<NUTS2_CODE>-<AGENCY_ACRONYM>-NeTEx_L1.xml: file NeTEx Italian Profile Level 1 (non compresso)<NUTS2_CODE>-<AGENCY_ACRONYM>-NeTEx_L1.xml.gz: stesso file NeTEx Italian Profile Level 1 (in formato gz compresso)<AGENCY_ACRONYM>.db: database SQLite3 intermedio utilizzato dal convertitore durante l'elaborazione; puo' essere usato sia per scopi di debugging che elaborato successivamente per altre finalita' (es. calcolo KPI relativi all'offerta di trasporto descritta nei dati); un efficace editor multipiattaforma open source per SQLite è' DB Browser for SQLite
L'applicazione è anche disponibile in formato docker (vedi sezione packages)
La cartella gtfs deve essere mountata come volume, e passata come <GTFS_FEED_FOLDER>:
docker run --rm --volume ./gtfs:/gtfs ghcr.io/liguria-digitale/gtfs2netex-converter:latest --folder /gtfs --NUTS <NUTS2_CODE> --db <AGENCY_ACRONYM> --az <AGENCY_ACRONYM> --vat <AGENCY_VAT_NUMBER> --version <VERSION_NAME>