# Trajectory_Prediction

**Repository Path**: ShiruiTian/Trajectory_Prediction

## Basic Information

- **Project Name**: Trajectory_Prediction
- **Description**: 开源安全目标软件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 184
- **Forks**: 135
- **Created**: 2026-02-04
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 复杂移动场景中的多尺度时空轨迹预测网络

本项目面向二维空间中的多尺度时空轨迹预测网络（Multi-Scale Spatio-Temporal Trajectory Former，MSTFormer），将每条轨迹建模为移动智能体在连续时间内的观测序列，并基于历史运动状态预测其未来位置变化。项目以轨迹预测模型为核心，集成训练、测试、可视化、不确定性估计、在线滚动预测、异常检测、逐步误差分析及国产化迁移预览等功能，可用于复杂动态环境下的运动趋势分析与风险评估。

## 项目特点

- 支持基于历史轨迹的未来二维坐标预测。
- 支持长历史窗口与长预测窗口建模。
- 集成多尺度时空轨迹预测网络。
- 提供 ADE、FDE、TPEM、DPEM 等多维度评价指标。
- 支持预测结果可视化与逐步误差分析。
- 支持 MC Dropout 不确定性估计、在线滚动预测和异常轨迹检测。
- 提供 `sptensor` 工具链接口，用于面向 HIP/DCU 环境的国产化迁移预览。

## 模型概览

主模型位于 `MSTFormer.py`。整体结构包括以下模块：

- `TCN`：提取历史轨迹中的局部时序模式，增强模型对短时运动变化和局部趋势的表征能力。
- `Cross Attention`：实现 TCN 时序特征与 Informer 编码特征之间的信息桥接，提升多尺度时序信息融合效果。
- `Informer`：建模长时间跨度内的全局依赖关系，适用于长序列轨迹输入和较长未来窗口预测。
- `BiLSTM + Linear`：进一步整合双向时序上下文，并将时序特征映射为未来二维坐标。
- 自回归注意力解码头：在增强模型中用于逐步生成未来位移，提升长期预测阶段的轨迹连续性。

模型输入为 `history_len` 步历史轨迹，输出为 `future_steps` 步未来坐标。当前增强配置下，每个时间步的输入特征包括：

- `x, y`：目标二维位置坐标。
- `vx, vy`：目标在两个坐标方向上的速度分量。
- `ax, ay`：目标在两个坐标方向上的加速度分量。

## 训练配置与测试指标

以下为当前增强模型的主要训练配置和最近一次本地运行得到的测试指标。

### 训练配置

| 项目 | `MSTFormer`  |
| --- | --- |
| 输入特征维度 | 6 |
| 特征内容 | `x, y, vx, vy, ax, ay` |
| `history_len` | 300 |
| `future_steps` | 90 |
| `trajectory_length` | 390 |
| `hidden_dim` | 256 |
| `batch_size` | 32 |
| 学习率 | `3e-4` |
| 权重衰减 | `1e-4` |
| 训练轮数 | `180` |
| 优化器 | `AdamW` |
| 归一化方式 | `StandardScaler` |
| 解码头 | 自回归注意力解码头 + `GRUCell` + 位移累积 |
| checkpoint 配置文件 | `best_model_enhanced.pth.config.json` |

### 测试指标

| 模型 | ADE | FDE | TPEM | DPEM | 说明 |
| --- | ---: | ---: | ---: | ---: | --- |
| `MSTFormer`  | 32.6065 | 63.1733 | 3.8815% | 7.5202% | 使用自回归注意力解码头后的测试结果 |

其中，`ADE` 表示平均位移误差，用于衡量预测轨迹与真实轨迹在整个预测窗口内的平均偏差；`FDE` 表示终点位移误差，用于衡量预测终点与真实终点之间的偏差；`TPEM` 和 `DPEM` 分别表示轨迹预测误差百分比和目的地预测误差百分比，是经过轨迹尺度归一化后的相对误差指标。

### 增强训练过程记录


README 仅展示具有代表性的训练轮次结果，避免把 180 轮完整日志全部展开到文档中；完整训练记录会在本地自动保存为：

- `trajectory_prediction_<history>_<future>_train/training_info/training_history.json`
- `trajectory_prediction_<history>_<future>_train/training_info/training_history.csv`
- `trajectory_prediction_<history>_<future>_train/training_info/training_history.md`

当前 `300/90` 增强模型在本地可确认的代表性轮次记录如下：

| 轮数 | Train Loss | Val Loss | Train ADE | Train FDE | Val ADE | Val FDE | Train TPEM | Train DPEM | Val TPEM | Val DPEM | 学习率 |
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 / 180 | 2.129137 | 1.074003 | 120.8905 | 234.9433 | 77.6653 | 151.8211 | 14.3910% | 27.9680% | 9.2454% | 18.0730% | 3.00e-04 |
| 2 / 180 | 0.461677 | 0.197736 | 46.4445 | 89.6097 | 32.3542 | 62.5449 | 5.5288% | 10.6673% | 3.8515% | 7.4454% | 3.00e-04 |

这两轮展示了增强模型在训练初期的快速收敛过程；当完整跑满 180 轮时，全部轮次都会按上述三种格式保存在本地训练目录中。


### 最近一次运行耗时

| 运行类型 | 耗时 |
| --- | ---: |
| `MSTFormer` 模型测试 | 160.92 秒 |
| `MSTFormer` 模型上一次测试 | 181.25 秒 |
| `MSTFormer` 模型另一次测试 | 183.12 秒 |
| `MSTFormer` 模型另一次测试 | 189.08 秒 |

## 预测可视化

项目支持对模型预测结果进行轨迹可视化展示。可视化结果通常包括：

- 蓝色实线：历史观测轨迹。
- 绿色实线：预测区间内的真实未来轨迹。
- 红色虚线：模型生成的预测轨迹。
- 图例：用于区分不同轨迹类型。

动态可视化结果会随时间逐步展开，先展示历史轨迹，再同步展示真实未来轨迹与预测未来轨迹，便于直观观察预测偏差、运动趋势和轨迹连续性。

![Trajectory Prediction GIF](test_predictions/best_prediction_animation.gif)

## 目录说明

- `MSTFormer.py`：训练、测试、可视化和功能集成入口。
- `data/file_processor.py`：轨迹文件解析、数据读取与可复现打乱。
- `feature1_uncertainty.py`：基于 MC Dropout 的预测不确定性估计。
- `feature2_online_prediction.py`：在线滚动预测功能。
- `feature3_anomaly_detection.py`：轨迹异常检测功能。
- `feature4_stepwise_analysis.py`：逐步误差分析与质量报告生成。
- `tools/sptensor_bridge.py`：`sptensor` 桥接脚本，用于 HIP/DCU 迁移预览。
- `best_model_enhanced.pth`：当前增强版模型权重文件。
- `best_model_enhanced.pth.config.json`：增强版模型对应的数据配置与结构配置文件。
- `best_model.pth`：历史兼容模型权重文件。
- `best_model.pth.config.json`：历史模型对应的数据配置文件。

## 环境依赖

建议使用 Python 3.9 及以上版本，并安装以下依赖：

```bash
pip install torch pytorch-tcn numpy pandas scikit-learn matplotlib pillow
```

## 数据文件

项目中常用数据文件包括：

- `data/data.txt`：原始文本格式轨迹数据。
- `data/data_11000_resampled.json`：包含 11000 条重采样轨迹的数据文件，适合复现实验。
- `data/data_1000_resampled.json`：小规模样例数据，适合快速测试和功能验证。

建议保持：

```text
trajectory_length = history_len + future_steps
```

如果轨迹长度与模型配置不一致，程序会在 `TrajectoryDataset` 中进行截断或补零处理，并给出相应提示。

## 使用命令

### 1. 测试当前模型

该命令会读取 `best_model_enhanced.pth.config.json`，并按保存的配置进行模型测试。

```bash
py -3 .\MSTFormer.py --mode test
```

### 2. 测试模型并运行全部分析功能

```bash
py -3 .\MSTFormer.py --mode test --run_all_features
```

### 3. 训练 300/90 配置主实验

```bash
py -3 .\MSTFormer.py --mode train --data_file data/data_11000_resampled.json --file_type json --num_trajectories 11000 --history_len 300 --future_steps 90 --trajectory_length 390 --epochs 50 --batch_size 32 --model_path best_model_enhanced.pth
```

### 4. 测试指定模型

```bash
py -3 .\MSTFormer.py --mode test --model_path .\best_model_enhanced.pth
```

### 5. 运行 `sptensor` 国产化迁移预览

```bash
py -3 .\MSTFormer.py --mode sptensor --sptensor_tool cuda2hip
```

## 单项功能命令

### 不确定性估计

```bash
py -3 .\MSTFormer.py --mode test --run_uncertainty
```

### 在线滚动预测

```bash
py -3 .\MSTFormer.py --mode test --run_online_prediction
```

### 异常检测

```bash
py -3 .\MSTFormer.py --mode test --run_anomaly_detection
```

### 逐步误差分析

```bash
py -3 .\MSTFormer.py --mode test --run_stepwise_analysis
```

## `sptensor` 国产化迁移预览

`sptensor` 是本项目中的可选外部工具链，用于支撑面向 HIP/DCU 环境的国产化部署探索。本项目负责轨迹预测模型的训练、评估与分析，`sptensor` 负责底层 `C/CUDA -> HIP` 的离线代码迁移预览。

在使用该功能前，需要先将 `sptensor` 克隆到本地。推荐路径为 `.external_repos/sptensor`：

```bash
git clone https://gitee.com/liu_muzhou/sptensor.git .external_repos/sptensor
```

如果使用其他路径，可通过 `--sptensor_root` 显式指定。

当前已接入功能包括：

- `cuda2hip`：对内联 CUDA 片段进行 API 级 HIP 预览重写。
- `riscv2hip`：将 RISC-V 样例转换为 HIP kernel 风格预览结果。
- `c2hip`：为后续 `C -> HIP` 导出和国产异构部署实验保留接口，使用前需先在 `sptensor` 中完成 `c2hip` 构建。

常用命令如下：

```bash
py -3 .\MSTFormer.py --mode sptensor --sptensor_tool cuda2hip
py -3 .\MSTFormer.py --mode sptensor --sptensor_tool riscv2hip
py -3 .\MSTFormer.py --mode sptensor --sptensor_tool c2hip --sptensor_input_file path\to\kernel.c
```

参数说明：

- `--sptensor_root`：指定本地 `sptensor` 仓库路径，默认值为 `.external_repos/sptensor`。
- `--sptensor_output_dir`：指定迁移预览结果归档目录。
- `--sptensor_inline_code`：为 `cuda2hip` 传入自定义 CUDA 代码片段。
- `--sptensor_no_build`：关闭轻量工具的自动构建流程。

## 常用可调参数

- `--history_len`：历史轨迹长度。
- `--future_steps`：未来预测步数。
- `--trajectory_length`：单条轨迹总长度。
- `--num_trajectories`：读取轨迹数量。
- `--batch_size`：批大小。
- `--epochs`：训练轮数。
- `--seed`：数据打乱与数据集切分随机种子。
- `--feature_output_dir`：功能模块输出目录。

## 输出结果

程序通常在以下目录保存结果：

- `trajectory_prediction_<history>_<future>_train/`：训练模式实验目录，包含完整训练日志、图表、模型与训练历史。
- `trajectory_prediction_<history>_<future>_test/`：测试模式实验目录，包含测试日志、可视化与功能模块输出。
- `predictions/` 或 `test_predictions/`：最佳轨迹图、动态 GIF 和功能模块输出。
- `sptensor_export_<tool>/`：运行 `--mode sptensor` 时生成的实验日志与归档信息。
- `sptensor_bridge_runs/`：迁移预览输出目录，通常包含输入源码、预览结果、stderr 和 metadata。
- `training_history.json/.csv/.md`：按 epoch 保存的完整训练过程记录，分别适合程序读取、表格分析和 Markdown 展示。

## 适用类型与应用场景

本项目属于通用二维时空轨迹预测框架，可学习目标历史运动轨迹中的时序规律、速度变化、加速度变化和运动模式，从而预测目标未来运动状态。其应用对象不限于行人，也可扩展至车辆、移动机器人、无人机、船舶、无人平台等具有连续运动特征的目标。

### 行人轨迹预测

行人轨迹预测是本项目的典型应用方向。模型可根据行人在一段时间内的历史位置、速度和加速度信息，预测其未来运动趋势，为风险识别、路径规划和行为分析提供支持。

#### ETH

ETH 数据集来源于真实校园道路场景，具有开放空间、人群交互和多方向运动等特点，适用于验证模型在开放场景中的轨迹预测能力。

![alt text](10665.0.png)

#### Hotel

Hotel 数据集来源于酒店广场区域，场景结构相对开放，行人运动方向自由，交互行为较为频繁，适用于评估模型在弱结构化公共空间中的预测性能。

![alt text](12771.png)

#### SSD

SSD 场景包含城市街道和公共区域中的复杂运动目标，具有多目标、高动态和环境干扰等特点，可用于验证模型在复杂动态场景中的鲁棒性。

![alt text](<reference (4).jpg>) ![alt text](<reference (6).jpg>) ![alt text](<reference (1).jpg>) ![alt text](<reference (2).jpg>) ![alt text](<reference (3).jpg>)

#### ZARA

ZARA 数据集包含购物街区中的密集人流场景，存在交叉通行、避让、跟随和短时停顿等行为，适用于验证模型在复杂社会交互环境中的泛化能力。

![alt text](1271.png)

### 典型应用场景

在自动驾驶环境中，模型可根据行人的历史运动轨迹预测其未来位置和移动趋势，辅助车辆提前进行风险评估、路径规划和主动避让，提高复杂道路场景下的行车安全性。在智能交通系统中，模型可用于分析大规模人群流动规律，支撑客流分布预测、交通组织优化、拥堵识别和资源调度。在智慧园区场景中，模型可持续分析人员移动轨迹，识别人员聚集、长时间停留和异常流动等行为，为园区运营管理、服务优化和应急疏散提供依据。在安防监控场景中，模型可结合异常检测功能识别逆行、徘徊、快速聚集、异常闯入等运动模式，实现风险事件的提前预警。在商业综合体中，模型可用于挖掘顾客移动路径、热点区域、停留规律和客流变化趋势，为空间布局优化、广告投放、运营管理和精准营销提供数据支撑。

除复杂环境感知场景外，本项目还可应用于移动机器人导航、仓储 AGV 调度、无人机航迹预测、低空物流安全管控、船舶航迹预测、港口交通分析、军事目标态势推演、体育运动跑位分析和多智能体仿真系统等任务。上述场景均具有连续运动目标和未来状态预测需求，可通过适配输入特征、轨迹长度和场景约束，将本项目扩展为面向不同运动目标的轨迹预测与行为分析工具。

## 贡献与开源依赖

本项目引用以下开源基础库，用于构建面向轨迹预测与异构计算迁移的技术支撑能力。

### `sptensor`

项目地址：https://gitee.com/liu_muzhou/sptensor

`sptensor` 作为稀疏张量加速与代码迁移工具链，本项目通过子模块或外部依赖方式接入其 `cuda2hip` 等迁移功能，用于支撑轨迹预测模型在 HIP/DCU 等国产异构计算环境中的部署预览与适配验证。

### `implement-algorithm-library`

项目地址：https://gitee.com/zzh551/implement-algorithm-library

`implement-algorithm-library` 作为算法参考实现集，本项目参考其中的路径规划、状态估计等相关模块，结合轨迹预测任务进行适配性重构和功能扩展，用于增强复杂动态环境下的运动分析能力。

本项目在引用相关开源依赖时遵循对应仓库许可证要求，并保留必要的版权与来源说明。相关集成以可复现、可审计和可维护为原则，确保外部依赖使用过程清晰、可靠。