@szjy/traffic-simulation

v0.1.4

Published

11 days ago

vue3 pdf component

0High
0Medium
0Low

boycgit

jscon

yangsansan

Traffic Simulation System (交通仿真系统)

📖 项目简介 (Project Introduction)

Traffic Simulation System 是一套基于 Vue 3 和 Cesium 的高性能三维交通仿真解决方案。本项目旨在为智慧交通、BIM 中心及城市规划场景提供强大的可视化编辑与仿真能力。

核心组件 SzSimulationEditor 允许用户在三维地理空间中进行交通流线的绘制、模型（车辆、建筑）的布局、以及基于时间轴的复杂动画编排。通过直观的交互界面，用户可以快速构建逼真的交通运行场景，并支持数据的云端保存与回放。

典型应用场景：

交通拥堵模拟：复现路口、隧道的车流情况。
施工方案推演：模拟道路施工期间后的交通流变化。
应急预案演练：可视化呈现突发事故下的疏散流程。

📂 目录结构 (Directory Structure)

项目采用 Monorepo 结构（尽管目前主要集中在 packages），结构清晰，模块分工明确。

e:\coding\bimcenter\traffic-simulation
├── dist/                   # 构建产物目录
├── examples/               # 示例工程（用于开发调试核心组件）
│   ├── main.ts             # 示例入口文件
│   └── components/         # 示例独有的测试组件
├── packages/               # 核心库源码目录
│   ├── api/                # 后端 API 接口定义
│   ├── common/             # 通用工具与模块
│   │   ├── MapTools/       # 核心地图工具 (Cesium 封装, 绘图, 动画核心等)
│   │   └── SequenceTimelinePlayer/ # 时间轴播放器组件
│   ├── components/         # 业务组件库
│   │   └── SimulationEditor/ # 核心仿真编辑器组件
│   ├── hooks/              # Vue Composition API 钩子
│   └── utils/              # 通用辅助函数
├── public/                 # 静态资源 (Cesium 库文件, 图标等)
├── .npmrc                  # npm 配置
├── index.html              # Vite 页面入口
├── package.json            # 项目依赖与脚本配置
├── vite.config.mts         # Vite 构建配置
└── README.md               # 项目说明文档

关键模块说明

packages/common/MapTools: 包含 Cesium 的核心封装逻辑，如 trafficFlowSimulator.js (车流模拟)、modelTransformUtils.js (模型变换)、Plotting (标绘工具)。
packages/components/SimulationEditor: 整个仿真编辑器的入口组件，集成了工具栏、属性面板和时间轴。

🛠 环境与依赖配置 (Environment & Dependencies)

开发环境要求

Node.js: >= 18.0.0
包管理器: 推荐使用 pnpm (若无请先安装: npm install -g pnpm)
操作系统: Windows / macOS / Linux

核心技术栈

| 技术 | 版本 | 说明 | | :--- | :--- | :--- | | Vue | ^3.4.21 | 核心前端框架 | | Cesium | ^1.137.0 | 三维地球引擎 | | Element Plus | 2.7.1 | UI 组件库 | | Vite | ^5.1.6 |构建工具 | | TypeScript | ^5.2.2 | 静态类型检查 | | ECharts | ^5.5.0 | 图表可视化 | | @turf/turf | ^7.3.2 | 地理空间计算库 |

🚀 项目运行指南 (Run Guide)

1. 安装依赖

在项目根目录下执行以下命令安装所有依赖：

npm install
# 或者
pnpm install
# 或者
yarn

2. 启动开发服务器

启动本地开发环境，包含热更新功能：

npm run dev

启动后，访问控制台输出的本地地址（通常为 http://localhost:5173）即可看到 examples 目录下的演示页面。

3. 构建生产版本

构建库文件输出到 dist 目录：

npm run build

4. 类型检查

在构建前进行 TypeScript 类型检查：

npm run build:dev

🧩 功能模块与使用示例 (Features & Usage)

项目核心并未对外暴露零散 API，而是提供了一个高内聚的组件 <SzSimulationEditor />。

核心功能列表

车流绘制 (Flow Tool): 支持在地图上绘制贝塞尔曲线路径，设置车道宽度、车流速度及车辆密度。
模型布局 (Model Tool): 可从库中拖拽车辆、建筑模型至场景中，支持平移、旋转、缩放操作。
时间轴编排 (Timeline Player):
- 关键帧动画: 为模型设置位置、姿态的关键帧，自动生成平滑插值动画。
- 阶段管理: 将仿真过程划分为不同阶段（如：施工前、施工中、施工后）。
环境模拟: 内置雨、雪、雾等天气效果切换。
API 集成: 支持通过 solutionId 自动加载远程仿真方案配置。

使用示例 Code

在你的 Vue 组件中引入并使用编辑器：

<template>
  <div style="width: 100vw; height: 100vh;">
    <SzSimulationEditor
      ref="editorRef"
      :solution-id="currentSolutionId"
      :base-url="apiBaseUrl"
      :token="userToken"
      :layer-tree="projectLayerData"
    >
      <!-- 可选：自定义 Cesium 容器插槽，通常不需要手动填充，组件内部处理 -->
    </SzSimulationEditor>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { SzSimulationEditor } from '@szjy/traffic-simulation';
import '@szjy/traffic-simulation/dist/style.css'; // 引入样式

const currentSolutionId = ref('PLAN_123456');
const apiBaseUrl = 'https://api.example.com';
const userToken = 'eyJh...'; 
const projectLayerData = [...]; // 图层树数据
</script>

🔌 API 接口文档 (Component API)

`<SzSimulationEditor />` Props

Methods (通过 ref 调用)

| 方法名 | 参数 | 说明 | | :--- | :--- | :--- | | setViewer(viewer) | Cesium.Viewer | 手动设置 Cesium Viewer 实例（通常组件内部会自动初始化，但在某些集成场景下可能需要外部传入）。 |

🛡 项目维护规范 (Maintenance)

代码风格

Vue: 使用 Composition API (<script setup>) 风格。
Linting: 项目集成了 ESLint 和 Prettier，提交代码前请确保无 Lint 错误。
命名:
- 组件文件名使用 PascalCase (如 SimulationEditor.vue).
- JS/TS 变量与函数使用 camelCase.
- 常量使用 UPPER_CASE.

提交规范

请遵循 Git Commit Message 规范：

feat: 新功能
fix: 修复 Bug
docs: 文档修改
style: 代码格式修改（不影响运行逻辑）
refactor: 代码重构
perf: 性能优化

❓ 常见问题 (FAQ)

Q1: 启动项目后地图一片黑，或者报错 Cesium 资源 404？

A: Cesium 需要加载大量的静态资源（纹理、WebAssembly 等）。确保 public/node_modules/cesium 目录存在且包含完整的 Build 产物。在 main.ts 中我们配置了 window.CESIUM_BASE_URL，请检查该路径是否与你本地的静态资源服务器路径匹配。

Q2: 如何添加新的车辆模型？

A: 需要修改 packages/components/SimulationEditor/src/tools/constants.ts 中的 VechicleTypeOptions 配置，并确保相应的 GLTF/GLB 模型文件已上传至静态资源服务器或通过 URL 可访问。

Q3: 为什么构建报错 "Vue types error"？

A: 请检查 packages 下的组件是否正确导出了类型。运行 npm run build:dev 可以看到详细的 TSC 报错信息。通常是因为 props 定义缺少类型声明或使用了隐式 any。