| 項目 | 內容 |
|---|---|
| 專案名稱 | TRA_time_space_diagram |
| Author | 呂卓勳 Cho-Hsun Lu |
| billy1125@gmail.com | |
| 版本 | 1.3.9 |
鐵道愛好者通常都會使用鐵路運行圖(Railway Time-Space Diagram)，幫助研究鐵道相關事務，雖然有人會出版紙本台鐵鐵路運行圖，但是當台鐵改點，紙本的資訊參考價值就會變低。所以當我知道台鐵已經將時刻資訊以 JSON 公開於網路上之後，便試圖以 Python 開發一個繪製台灣鐵路運行圖的程式。
本程式鐵路運行圖均來自於台鐵 open data 進行分析整理與繪製。然而公開資料不等於實際台鐵的運行計畫，僅是旅客所需的列車到站與離站時間資料，列車的待避或會車狀況無法在運行圖中展示，貨運、迴送等非客運車次也因台鐵並未在公開資料集提供。因此會出現運行圖與實際運行有所差異，以及無法提供非客運車次的運行線。因此實際鐵路運行情況，請以台鐵所公布資訊或鐵路運行實況為準。
本程式用於將台鐵公開之時刻表 JSON 格式檔案 (以下稱台鐵 JSON)，轉換為鐵路運行圖，運行圖格式為可縮放向量圖形（Scalable Vector Graphics, SVG）。並且提供一個批次下載台鐵 JSON 之簡易程式。
目前本程式基於 Python 3.12.4 開發，除此之外本程式需要以下套件，包括：
- Pandas：用於列車推算通過車站時間，本程式開發使用版本為 2.2.2
- beautifulsoup4：用於擷取台鐵 JSON，本程式開發使用版本為 4.12.3
進度條程式碼則採用 Vladimir Ignatev 所設計的程式。svg 繪圖部分程式感謝 nedwu的啟發，並且參考其專案部分程式碼。
以上套件為主要開發環境，若您採用非相同版本之 Python 與套件，執行上有任何錯誤歡迎交流。
請將所有程式解壓縮到同一檔案夾，包括 CSV、JSON、OUTPUT 等檔案夾均需於同一檔案夾，再將所需要轉檔的台鐵 JSON 檔案，置放於 JSON 檔案夾之中，台鐵 JSON 檔案可至台鐵公開資料網站中下載。
程式以作業系統的命令行 (command-line) 模式執行，執行方式包括一般模式與參數模式，分述如下：
命令行執行語法
$ python batch.py
************************************
台鐵JSON轉檔運行圖程式 - 版本：1.3.9
************************************
之後會顯示本程式的標題，並且顯示版本。
請選擇轉檔方式，直接轉檔請直接按Enter鍵，需要轉檔特定車次請輸入「Y」再進行選擇，離開請按「N」：Y
詢問您是否需要轉換特定車次，若您需要轉換特定車次，請按「Y」，若不需，請直接按下「ENTER」即可。
請注意！已轉檔的 JSON 檔案將移動到 JSON_BACKUP 檔案夾。 若按下
「ENTER」，程式將直接就 JSON 檔案夾中所有以「JSON」附檔名之資料進行轉檔，直到所有 JSON 檔案轉換完成為止。
請問特定車次號碼？
請輸入車次號後再按Enter鍵。如果有多個車次，請依序輸入各車次，中間以半形空白鍵隔開(例如: 408 426 111)，再按Enter鍵：3671
若按下「Y」，將繼續顯示以上問題。
請輸入車次號後再按Enter鍵，例如第 3671 車次普快車，請輸入「3671」再按Enter鍵，程式將尋找是否有該車次，並且直接繪製運行圖。
如果有多個車次需要繪製，請依序輸入各車次，中間以半形空白鍵隔開(例如: 408 426 111)，輸入結束則直接按下「Enter」即可。
共有 60 個JSON 檔案需要轉檔。
目前進行日期「20230623」轉檔。
[==========================================------------------] 70.7% ...目前正在轉換: 車次3671
繪製運行圖的過程中，程式將顯示進度條與正在處理的車次。
檔案轉換完成！轉換時間共 15.6 秒
如果繪製完成，將顯示以上訊息，訊息包括轉換所耗費的時間。
附註：轉換時間需視 CPU 效能，保守時間約 1 分鐘內可完成。
無法執行！沒有 JSON 檔案，請在 JSON 資料夾中置入台鐵的時刻表 JSON。
如果您在置放 JSON 的檔案夾中沒有台鐵 JSON 檔案，則會顯示以上錯誤訊息。 程式繪製完成的運行圖，將依照不同台鐵營運路線，分別置放於 OUTPUT 檔案夾之中，檔名則與轉換的 JSON 檔名相同。
本程式能以批次模式執行，程式可將 JSON 所在的資料夾逐一批次轉檔，再儲存到輸出資料夾。參數為「-b」，可見以下語法：
$ python batch.py -b
請注意，若您要改動台鐵 JSON 檔案、運行圖輸出與轉檔後 JSON 檔案資料夾位置，請修改檔案「config.ini」，檔案內容如下，可依照您的需要修改：
[DEFAULT]
JsonFolder = JSON # 台鐵 JSON 檔案預設資料夾
OutputFolder = OUTPUT # 運行圖輸出預設資料夾
BackupFolder = JSON_BACKUP # 轉檔後 JSON 檔案預設資料夾
以批次模式執行後，程式將自動將所有置放於您指定的 JSON 檔案夾中的台鐵 JSON 進行轉檔，並且依照不同台鐵營運路線，置放於您指定的 OUTPUT 檔案夾之中，最後將轉檔後的 JSON 資料夾移動至轉檔後 JSON 檔案預設資料夾。
檔案夾位置可指定完整的硬碟路徑，請注意：
請勿有中文字元，可能會出現未預期的錯誤。
若您需要批次下載當日之台鐵所有 JSON 程式，請以命令行模式，執行 JSON 檔案夾中之 download_json.py 程式，執行語法為：
$ python download_json.py
該程式將直接下載台鐵公開資料網站網站中所有 JSON 檔案，並且置放於 JSON 檔案夾中。
附註：台鐵每日均提供當日至 60 天內每日之時刻表資料，以 JSON 格式提供。如果想要看相關資料定義的說明，可至政府資料開放平台參考。
本程式所轉換之運行圖，檔案副檔名為 .svg，請使用瀏覽器直接開啟檔案即可，本程式所轉換之運行圖於 Google Chrome、Mozilla Firefox、Opera、Apple Safari 均能正常顯示，至於其他瀏覽器尚未實地測試，若有問題也歡迎回報。
- nedwu(https://github.com/nedwu) 的程式碼
- 黃祈恩(https://www.facebook.com/profile.php?id=100051647619113&sk=about) 幫忙將台鐵車站代碼基本資料的 CSV 檔案更正
- 施佩佶(https://www.facebook.com/profile.php?id=100009938435817) 於 2020.10.16 通報 6655、6657 車次錯誤問題
- 張柏皓(https://www.facebook.com/profile.php?id=100066832751160) 於 2023.04.19 通報 6105、6702 車次錯誤問題
- 王羿 (https://www.facebook.com/profile.php?id=100033320060400) 於 2023.06.03 通報 2023.06.22 5374 車次錯誤問題
感謝以上網友對於本程式的建議與錯誤回報，您的協助能讓本程式更臻完整，感謝！