# 码头路径调度与路径规划

**Repository Path**: jajimeidou/wharf_dispatching_path_planning

## Basic Information

- **Project Name**: 码头路径调度与路径规划
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 4
- **Created**: 2020-07-18
- **Last Updated**: 2024-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 外四码头调度服务

本项目为外四码头改造提供以下服务

+ 各类车辆的调度
+ 车辆运行路径的规划
+ 码头内交通的控制

同时配备了控制界面

+ 将本服务的各项输出进行可视化呈现
+ 对本服务的运行状况进行监控
+ 允许操作员手动控制执行相关功能，人为介入服务运行


此文档包含以下部分

+ [系统边界](#系统边界)
+ [系统架构](#系统架构)
+ [下载安装](#下载安装)
  + [前端](#前端)
  + [后端](#后端)
+ [开发运行](#开发运行)
+ [接口及数据格式](#接口及数据格式)

## 系统边界

本系统实际运行环境中依赖于码头内部的上位机，本系统的输入输出均是与上位机交互。以下是本系统的运行环境（图中<span style="color: green">绿色部分</span>即为本系统）

<div align=center><img src="https://s1.ax1x.com/2020/10/03/03SS3Q.png"/></div>


> 注：开发过程中并未直接接入实际码头的系统，所以该项目代码中包含了一个虚拟上位机，详见[后台说明文档](./backend/readme.md)

## 系统架构

本系统内部采用传统的客户端/服务端架构，相关代码和说明文档分别在：客户端（[前端](./application)）、服务端（[后台](./backend)）

<div align=center><img src="https://s1.ax1x.com/2020/10/03/039Tc4.png"/></div>

## 下载安装

项目源码直接在页本面右上方点击<span style="color:white;background-color:#f38d30;padding:5px 10px;margin:0 10px">克隆/下载</span>按钮下载压缩包至本地，解压即可。

在运行之前需要安装相关的依赖

### 前端

开发之前需要配置好 node 环境，安装 npm 工具

若使用 vscode 打开本项目，在终端进入开发目录

```shell
> cd .\application\wharf_map\
```

安装项目依赖

```shell
> npm install
```

安装完毕后发现当前目录下多出一个 `node_modules\` 目录，里面就是安装好的依赖

### 后端

开发之前配置好 python3 运行环境（建议使用 python 3.8），

进入开发目录 `backend`

```shell
> cd .\backend\
```

执行以下指令安装所需的包

```shell
> pip install -r requirements.txt
```

## 开发运行

技术栈说明

+ 前端：js, html, css
  + [Vue](https://github.com/vuejs/vue)
  + [tweenjs](https://github.com/tweenjs/tween.js/)
  + websocket

+ 后端：python3
  + [asyncio](https://docs.python.org/zh-cn/3/library/asyncio.html) 异步编程
  + [aiohttp](https://docs.aiohttp.org/en/stable/) web 后台基础

开发手册：

+ 前端：[开发运行指南](./application/readme.md)
+ 后端：[开发运行指南](./backend/readme.md#运行)

## 接口及数据格式

本系统的输入数据均来自码头的上位机，下面对所需数据进行详细说明，接口列表如下：

+ [车辆实时状况](#车辆实时状况)
+ [当前任务列表](#当前任务列表)
+ [事件](#事件)

### 车辆实时状况

对于码头场地内运行的所有集卡，本系统需要知道它们的实时信息，用于调度和交通控制。

车辆信息的数据格式如下

```json
{
  "time": "<string> 当前时间",
  "vehicles": [
    {
      "id": "<string> 集卡的编号（独一无二）",
      "auto": "<boolen> 是否为无人车",
      "task_id": "<string | null> 当前车辆正在执行的任务编号，没有的话就 null",
      "status": "<string> 车辆的状态",
      "coordinate": {
        "x": "<int> 在场地内的横坐标",
        "y": "<int> 在场地内的纵坐标"
      },
      "position": "<int> 所属的位置点（地图打点的序号）",
      "capacity": "<int> 车辆的容量（能装的集装箱数量）",
      "energy": "<int>[1, 100] 剩余能量百分比（能量包括油量或电量）",
      "velocity": "<float> 车速",
      "acceleration":"<float> 当前的加速度",
      "direction": {
        "x": "<float> cosθ（θ为方向角）",
        "y": "<float> sinθ（θ为方向角）"
      },
      "path": "[<int>] 当前在走的路径的点集（地图打点的序号集合），没有就是空数组" 
    },
    ...
  ]
}
      
```

|参数名|类型|说明|
|-----|----|:---|
|time|字符串| 当前时间点 |
|vehicles|数组| 车辆信息的数组 |

车辆信息内部参数说明如下

| 参数名       | 类型        | 说明                                                         |
| ------------ | ----------- | ------------------------------------------------------------ |
| id           | 字符串      | 集卡的编号（独一无二）                                       |
| auto         | 布尔        | True：是无人车；False：有司机驾驶                            |
| task_id      | 字符串/null | 被分配的任务编号，没有任务就为空                             |
| status       | 枚举        | 车辆当前的状态，包含：Free可分配任务，Moving正在驾驶，Busy正在充电/加油 |
| coordinate.x | 整型        | 车辆此时在场地内的横坐标                                     |
| coordinate.y | 整型        | 车辆此时在场地内的纵坐标                                     |
| position     | 整型        | 车辆此时所在的位置属于地图上事先打好的第几号点               |
| capacity     | 整型        | 车辆能装载的集装箱数量                                       |
| energy       | 整型        | 车辆剩余的能量占总能量的百分比（20代表20%），最小 1，最大 100 |
| velocity     | 浮点数      | 车当前的速度，单位：米/秒                                    |
| acceleration | 浮点数      | 车辆当前的加速度，加速为正数，减速为负数                     |
| direction.x  | 浮点数      | cosθ（θ为方向角）                                            |
| direction.y  | 浮点数      | sinθ（θ为方向角）                                            |
| path         | 数组        | 车辆当前正在行驶的路径，以点的数组表示，点是地图上打好的点（的序号） |



### 当前任务列表

对于码头当前排上的任务，调度系统需要知道它们的内容，以便为他们分配最合适的车辆。

任务列表信息数据格式如下

```json
{
    "time": "<string> 当前时间",
    "tasks": [
        {
            "id": "<string> 任务的编号（独一无二）",
            "shipment": "<boolen> 任务类型，是装船还是卸船",
            "time": "<string> 此任务中要求车辆到达目的地的时间",
            "direction": "<int> 船只靠岸时船头方向",
            "yard_id": "<string> 堆场编号",
            "yard_pos": "<int> 堆场所在的位置点序号",
            "crane_id": "<string> 桥吊编号",
            "crane_pos": "<int> 桥吊所在的位置点序号",
            "lock_id": "<string> 需要经过的锁钮机编号",
            "lock_pos": "<string> 需要经过的锁钮机所在的位置点序号",
            "containers": "<int> 要运输的集装箱数量",
        },
        ...
    ]
}
```

| 参数名 | 类型   | 说明           |
| ------ | ------ | -------------- |
| time   | 字符串 | 当前时间点     |
| tasks  | 数组   | 任务信息的数组 |

任务信息的内部结构说明如下：

| 参数名     | 类型   | 说明                                       |
| ---------- | ------ | ------------------------------------------ |
| id         | 字符串 | 任务的编号（与任务本身一一对应，独一无二） |
| shipment   | 布尔   | True：装船任务；False：卸船任务            |
| time       | 字符串 | 此任务中要求车辆到达目的地的时间           |
| direction  | 整型   | 船只靠岸时船头方向，0：向西，1：向东       |
| yard_id    | 字符串 | 要去往的堆场编号                           |
| yard_pos   | 整型   | 该堆场在地图上的几号点位                   |
| crane_id   | 字符串 | 要去往的桥吊编号                           |
| crane_pos  | 整型   | 该桥吊在地图上的几号点位                   |
| lock_id    | 字符串 | 该任务要求车辆经过的锁钮机编号             |
| lock_pos   | 整型   | 该锁钮机在地图上的几号点位                 |
| containers | 整型   | 该任务要运输的集装箱数量                   |



### 事件

用于触发单车调度，这个码头场地中的事件包括：车辆到达任务终点后发出的信号，车辆的能源不足发出的信号，司机午休时间去食堂通过终端发送一个信号，等等诸如此类的事件均通过上位机发送给调度系统。

发送的具体数据格式如下

```json
{
    "time": "<string> 当前时间",
    "signal": "<string> 事件的类型名",
    "id": "<string> 发生该事件的车辆编号",
    "position": "<int> 事件发生的地点，即此时车辆在地图上的点位"
}
```

参数说明如下：

| 参数名   | 类型   | 说明                                               |
| -------- | ------ | -------------------------------------------------- |
| time     | 字符串 | 当前时间点                                      |
| signal   | 字符串 | 事件的类型名，有充电，加油，任务完成，食堂用餐     |
| id       | 字符串 | 发生该事件的车辆编号                             |
| position | 整型   | 事件发生的地点，即此时车辆在地图上的点位           |