# `pyETRC`列车运行图系统
## 概述
本项目是基于Python语言和PyQt5的非官方性质、简易的中国铁路列车运行图系统。本代码的发布遵循`GPLv3`协议。在协议允许范围内,作者保留一切权利和最终解释权。
作者联系方式:mxy0268@qq.com
本项目在Windows 10 操作系统下开发和测试。
### 与`ETRC`的联系
#### 渊源
`pyETRC`项目的最初灵感来源和很多功能设置都来自由LGuo等前辈基于java语言开发的`ETRC`列车运行图系统。为致敬开发`ETRC`项目的前辈,本项目定名为**`pyETRC`列车运行图系统**,简称为`pyETRC`。
#### 交互支持
本系统支持读取和导出`ETRC`列车运行图系统的运行图文件(`*.trc`)。但由于两软件支持的功能有差异,读取和导出过程可能造成一定的信息损失。
本系统与`ETRC`列车运行图系统的实现各有侧重。相比本系统,`ETRC`列车运行图系统有如下的特色比较突出:
* **动态运行图**。本系统不支持此功能。
* 对于精确到客运时刻的需求,**自带较完善的线路数据库和车次时刻数据库**。而本系统的线路和车次数据库依赖外部文件,且目前很不完整。
* 较完善的车次切片功能。
* 更简洁的操作和数据,或者说需要用户提供的数据更少。
相比`ETRC`列车运行图系统,本系统主要有如下的特色:
* 更准确、完整的数据支持,包括精确到秒的时刻和精确到三位小数的里程,允许上下行分设不同站点,标尺,天窗,交路等。
* 做了一定的效率优化,对较大运行图的执行效果相对更好。
* 提供了一些运行图快速微调工具和分析工具,例如调整某一站名(同时修改所有列车数据中引用的改站名),对比两运行图等。
* 在`3.0.0`版本以后,提供了路网级的数据库管理模块,可以在更高层面上管理,更方便地查看、导出区段运行图。
两系统各有长短。因此我们建议,如果有需求,可以两套系统结合使用。
## 环境与运行
使用**源代码**方式运行本项目,需要具有以下环境。
1. `Python` 3.7及以上的版本。开发所用的版本是3.7.4.
> 注:本项目使用了大量的`f-string`语法,该语法在`Python ` 3.6以后的版本才被支持。一些较新的代码中利用了`Python` 3.7中`dict`键值对顺序与添加顺序一致的特性。如果使用3.6.*版本,这部分代码可能出现一些问题。如果使用3.6以下版本,则会报错。
2. 下列的`Python`第三方库,都可以用`pip`安装。
* `PyQt5`。必须。推荐使用`5.10.1`版本。
* `xlwt`。可选。在涉及输出`.xls`的操作中需要用到。
* `xlrd`。可选。在涉及读取.`xls`的操作中需要用到。
* `xpinyin`。可选。在本系统`2.3.0`版本之前的线路数据库排序中用到。
* `NetworkX`。可选。在`3.0.0`版本引入的路网数据管理中,用于以图论算法计算经由给出的路径。
3. 作者开发的另一支持库`Timetable_new`。该库需要使用github上的源代码安装。
### 第三方库安装
在安装第三方库之前,需要配置好`python`环境,并将安装目录添加到`PATH`环境变量中,安装好`pip`库。相关教程可借助搜索引擎找到。
在shell中依次执行以下命令,无报错即可。
```powershell
pip install PyQt5==5.10.1
pip install xlwt
pip install xlrd
pip install xpinyin
pip install networkx
```
### `Timetable_new`的安装
依次执行:
```powershell
git clone https://github.com/CDK6182CHR/Timetable_new
cd Timetable_new
.\install.bat
```
如果不用`git`,也可以在[链接](https://github.com/CDK6182CHR/Timetable_new)中下载并解压源代码,双击执行`install.bat`。
> 注:`install.bat`文件适合windows操作系统。如果是其他操作系统,请自行更改相关代码。
`install.bat`的代码如下。
```powershell
python setup.py build
python setup.py sdist
python setup.py install
pause
```
### 运行
运行`main.py`文件即可。
```powershell
python main.py
```
## 项目结构
这部分作为简单的扩展开发指南。
### 可执行文件
本项目目前有3个可执行文件。
1. `main.py` 是主程序运行入口。
2. `LineDB.py` 在`2.3.0`版本之后添加,是线路数据库维护系统的运行入口。
3. `RailNetManager.py` 在`3.0.0`版本之后添加,相对独立的路网级运行图数据库管理系统。
### 包结构
本项目主要依赖的是`train_graph`包。下面简要说明包结构。
#### 运行图基础数据域
以下类主要用于存储数据,一般不包含与`PyQt`交互的过程,一般涉及文件读写。如果要基于本项目进行扩展开发,**推荐直接调用这些类**。自`2.3.1`版本开始,这部分被封装为`data`包(package)。
* `line.py` 铁路线路数据对象。
* `trainstation.py` `2.3.2`版本开始新增的列车时刻表中车站类。继承`dict`实现,并可以按需要新增功能。
* `linestation.py` 与`trainstation.py`类似,是对应`Line`中的车站数据。
* `train.py` 列车对象。
* `ruler.py` 标尺(时分标准)对象。
* `forbid.py` 天窗数据对象。
* `graph.py` 运行图对象,主要包括一条线路`Line`和一组车次`Train`。
* `circuit.py` 车底交路对象。每个交路包含若干车次`Train`的序列,每个车次可以属于至多一个交路。
* `route.py` 尚未开发完成的列车运行径路对象。
#### 公共工具域
从大约`2.4.0`版本开始新增`utility`包,主要是通用的工具,以及对Qt既有组件的改进。目的在于,通过引进面向对象设计模式,提高代码复用能力。模块名、类名的前缀`pe`是`pyETRC`的简写,以区分于`Q`开头的Qt原生组件类。
- `peCellWidget.py` 是对`QTableWidget`中的(通过`setCellWidget`方法设置的)单元格组件的改进。原生的`CellWidget`从没有包含所处的单元格位置信息,不能在其获得焦点时,同步修改`tableWidget.currentItem()`等属性。此模块用于解决这个问题。
其中,`PECellWidget`类仅对RTTI有用,暂无其他意义。**请不要直接实例化这个类**。请使用`CellWidgetFactory.new()`工厂方法创建实例控件。
- `peCelledTable.py`与`PECellWidget`配套使用的支持单元格组件定位的表格。主要是重写了`setCellWidget`方法。
- `peControlledTable.py` 是对需要支持增删、上下移动行的表格的封装。引进Adapter设计模式。本身继承的是`QWidget`,但将有关方法调用转发给内置的`QTableWidget`实例对象。
实例化时,也可以通过参数`meta`指定创建`QTableWidget`的某个子类实例,本项目中目前用到的是`PECelledTable`。
#### 绘图域
在调用了`PyQt`的模块中,有一部分与底层的绘图(绘制运行线)直接相关,它们是本项目的核心,这里单独列出来。
* `GraphicWidget.py` 核心绘图窗口。继承`QGraphicsWidget`实现,运行图的铺画在本类中完成。
* `trainItem.py` 列车运行线对象。包含了主要的运行线铺画逻辑。是`GraphicWidget`类中的图元。在`2.0.0`版本之后,每一趟列车(一个`Train`对象)允许拥有多个`TrainItem`对象。
#### 停靠面板域
与运行图数据操作相关的类主要有两种形式,一是以**停靠面板**方式,长期显示和有效的面板;二是以对话框为主的操作交互界面。前者包含了本系统的核心操作功能,下面简要说明停靠面板类及其相关类。
* `circuitWidget.py` 交路编辑停靠面板,快捷键为`ctrl+4`。
* `colorWidget.py` 默认颜色设置面板。在`1.4.0`之后的版本中,被集成到`运行图设置`面板中。
* `configWidget.py` 运行图设置面板。包含关于运行图铺画比例、运行图备注等设置。快捷键为`ctrl+