# CityEngine 实时对比连接器 - 完整使用手册

## 目录
1. [插件功能介绍](#1-插件功能介绍)
2. [系统要求](#2-系统要求)
3. [下载与安装](#3-下载与安装)
4. [配置说明](#4-配置说明)
5. [启动与使用](#5-启动与使用)
6. [实时对比功能](#6-实时对比功能)
7. [常见问题与故障排除](#7-常见问题与故障排除)
8. [高级配置](#8-高级配置)
9. [技术支持](#9-技术支持)

---

## 1. 插件功能介绍

CityEngine 实时对比连接器是一个连接 ce.cityvistion.com 与本地 CityEngine 的插件，实现 CGA 代码的实时对比测试。

### 核心功能
- **实时同步**：ce.cityvistion.com 的 CGA 编辑器代码实时推送到本地 CityEngine
- **双引擎对比**：同时显示 cgajs 解析结果和 CityEngine 解析结果
- **差异分析**：自动分析两个引擎的几何、拓扑、属性差异
- **黄金测试**：以 CityEngine 为黄金标准，验证 cgajs 解析能力

### 工作原理
```
ce.cityvistion.com CGA 编辑器
    ↓ WebSocket 推送 CGA 代码
本地 CityEngine 连接器
    ↓ 调用 CityEngine.exe -application com.esri.cgac.application
生成 RPK / JSON 几何数据
    ↓ WebSocket 返回结果
ce.cityvistion.com 对比面板并排显示
```

---

## 2. 系统要求

### 硬件要求
- **CPU**：2 核及以上
- **内存**：4GB 及以上
- **磁盘**：至少 500MB 空闲空间

### 软件要求
- **操作系统**：Windows 10/11 或 Windows Server 2016+
- **CityEngine**：2023.0 及以上版本（推荐 2025.1）
- **Python**：3.9 及以上版本
- **网络**：能访问 `https://api.cityvistion.com` 和 `https://ce.cityvistion.com`

### 依赖库
- `websocket-client>=1.6.0`
- `requests>=2.31.0`

---

## 3. 下载与安装

### 方式一：一键安装（推荐）

```powershell
powershell -ExecutionPolicy Bypass -Command "Invoke-WebRequest -Uri 'https://pyprt.cityvistion.com/downloads/install-cityengine-connector.ps1' -OutFile $env:TEMP\install-cityengine-connector.ps1; & $env:TEMP\install-cityengine-connector.ps1"
```

**安装内容**：
- 下载并解压 `cityengine-connector.zip` 到 `C:\CityEngine\Plugins\cityengine-connector\`
- 安装 Python 依赖库
- 生成配置文件 `config.json`
- 注册到 CityEngine `scripts` 目录

### 方式二：手动安装

1. **下载插件**
   ```
   https://pyprt.cityvistion.com/downloads/cityengine-connector.zip
   ```

2. **解压插件**
   ```powershell
   Expand-Archive -Path cityengine-connector.zip -DestinationPath C:\CityEngine\Plugins\cityengine-connector\
   ```

3. **安装依赖**
   ```powershell
   python -m pip install -r C:\CityEngine\Plugins\cityengine-connector\requirements.txt
   ```

4. **配置插件**
   编辑 `C:\CityEngine\Plugins\cityengine-connector\config.json`

5. **注册到 CityEngine**
   复制 `connector.py` 到 `C:\Program Files\ArcGIS\CityEngine2025.1\scripts\`

---

## 4. 配置说明

### 配置文件位置
```
C:\CityEngine\Plugins\cityengine-connector\config.json
```

### 配置参数说明

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `server_url` | string | 是 | WebSocket 服务器地址，默认 `wss://api.cityvistion.com:8443/ws/cga-live` |
| `token` | string | 是 | 工作站标识，如 `cityengine-workstation-hk` |
| `log_level` | string | 否 | 日志级别，默认 `INFO`（可选：DEBUG/INFO/WARNING/ERROR） |

### 配置示例
```json
{
  "server_url": "wss://api.cityvistion.com:8443/ws/cga-live",
  "token": "cityengine-workstation-hk",
  "log_level": "INFO"
}
```

### 获取 token
- **香港服务器**：`cityengine-workstation-hk`
- **台式机 1**：`cityengine-workstation-01`
- **台式机 2**：`cityengine-workstation-02`
- **新机器**：安装时自动注册分配

---

## 5. 启动与使用

### 方式一：命令行启动（推荐用于调试）

```powershell
python "C:\CityEngine\Plugins\cityengine-connector\connector.py" --token cityengine-workstation-hk
```

**启动成功标志**：
```
2026-07-19 02:30:00,000 [INFO] Connected to wss://api.cityvistion.com:8443/ws/cga-live
2026-07-19 02:30:00,000 [INFO] Connector started
```

### 方式二：Windows 服务启动（推荐用于生产环境）

1. **安装服务**
   ```powershell
   sc.exe create CityVistionConnector binPath= "\"C:\Program Files\python\python.exe\" \"C:\CityEngine\Plugins\cityengine-connector\connector.py\" --token cityengine-workstation-hk" start= auto DisplayName= "CityVistion CityEngine Connector"
   sc.exe description CityVistionConnector "Real-time CGA comparison between ce.cityvistion.com and CityEngine"
   sc.exe failure CityVistionConnector reset= 86400 actions= restart/60000/restart/60000/restart/60000
   ```

2. **启动服务**
   ```powershell
   Start-Service CityVistionConnector
   ```

3. **查看状态**
   ```powershell
   Get-Service CityVistionConnector
   ```

### 方式三：CityEngine 内启动（推荐用于可视化操作）

1. 打开 CityEngine
2. 进入 `Window → Show View → Scripting`
3. 点击 `Add Script`，选择 `cityvistion_connector.py`
4. 点击 `Run` 启动连接器

---

## 6. 实时对比功能

### 使用步骤

1. **启动连接器**：确保连接器已启动并显示 `Connected`
2. **打开 ce.cityvistion.com**：登录并进入 CGA 编辑器
3. **点击"实时对比"标签**：在编辑器右侧打开对比面板
4. **编写 CGA 代码**：在编辑器中编写 CGA 代码
5. **查看对比结果**：
   - 左侧：cgajs 解析的模型
   - 右侧：CityEngine 解析的模型
   - 下方：差异分析报告

### 对比指标

| 指标 | 说明 |
|---|---|
| 顶点数 | 模型的顶点数量 |
| 面数 | 模型的面数量 |
| 体积 | 模型的体积（立方米） |
| 面积 | 模型的表面积（平方米） |
| Bounding Box | 模型的边界框 |
| 法线方向 | 面的法线方向是否一致 |
| 材质 | 材质和贴图是否一致 |

### 差异等级

| 等级 | 说明 |
|---|---|
| ✅ 基本一致 | 体积差异 < 0.1%，顶点/面数一致 |
| ⚠️ 轻微差异 | 体积差异 0.1%-1%，顶点/面数少量差异 |
| ❌ 显著差异 | 体积差异 > 1%，顶点/面数大量差异 |

---

## 7. 常见问题与故障排除

### 问题 1：WebSocket 连接 403 Forbidden

**症状**：
```
Connection failed: Handshake status 403 Forbidden
```

**原因**：缺少必需的 `role` 参数

**解决**：
1. 检查 `connector.py` 中的 WebSocket URL 是否包含 `role=workstation`
2. 正确的 URL 格式：
   ```python
   url = f"{self.server_url}?role=workstation&token={token}"
   ```

### 问题 2：找不到 CityEngine 可执行文件

**症状**：
```
RuntimeError: CityEngine not found
```

**原因**：CityEngine 2025.1 没有独立的 `cgac.exe`

**解决**：
1. 确保 `find_cgac()` 函数查找的是 `CityEngine.exe` 而不是 `cgac.exe`
2. 正确的调用方式：
   ```python
   cmd = [
       str(ce_path),
       "-application", "com.esri.cgac.application",
       "-input", str(cga_file),
       "-output", str(output_dir),
   ]
   ```

### 问题 3：TLS 证书错误

**症状**：
```
SSL: certificate has expired
```

**原因**：Windows 系统证书存储中有过期根证书

**解决**：
1. 使用 certifi CA bundle：
   ```python
   import certifi
   import ssl
   ssl_context = ssl.create_default_context(cafile=certifi.where())
   self.ws = websocket.create_connection(url, timeout=30, sslopt={"ca_certs": certifi.where()})
   ```

### 问题 4：cgac 编译超时

**症状**：
```
cgac timed out
```

**原因**：CGA 代码复杂或 CityEngine 启动慢

**解决**：
1. 增加超时时间到 120 秒或更长
2. 简化 CGA 代码，避免复杂几何操作
3. 确保 CityEngine 有足够的内存和 CPU 资源

### 问题 5：对比面板不显示

**症状**：ce.cityvistion.com 的对比面板不显示或显示 "Three.js 未加载"

**原因**：Three.js 未正确加载

**解决**：
1. 确保 `window.__cv_three` 或 `window.THREE` 包含 Three.js 组件
2. 检查 `getTHREE()` 函数是否正确识别 Three.js
3. 如果缺少 `Scene` 函数，从 CDN 加载完整 Three.js

---

## 8. 高级配置

### 多工作站配置

如果你有多台 CityEngine 工作站，可以配置不同的 `token`：

| 工作站 | token | 用途 |
|---|---|---|
| 香港服务器 | `cityengine-workstation-hk` | 主对比节点 |
| 台式机 1 | `cityengine-workstation-01` | 备用节点 1 |
| 台式机 2 | `cityengine-workstation-02` | 备用节点 2 |

### 自动重启配置

使用 Windows 服务的恢复选项，实现崩溃后自动重启：

```powershell
sc.exe failure CityVistionConnector reset= 86400 actions= restart/60000/restart/60000/restart/60000
```

**参数说明**：
- `reset= 86400`：24 小时后重置失败计数
- `actions= restart/60000/restart/60000/restart/60000`：失败后 60 秒重启，最多重启 3 次

### 日志配置

修改 `config.json` 中的 `log_level`：

| 级别 | 说明 |
|---|---|
| `DEBUG` | 详细调试信息，包括 WebSocket 消息内容 |
| `INFO` | 一般信息，包括连接状态和任务执行 |
| `WARNING` | 警告信息，包括连接失败和任务超时 |
| `ERROR` | 错误信息，包括异常和崩溃 |

### 自定义 cgac 参数

如果需要自定义 cgac 编译参数，可以修改 `parse_cga_with_cgac()` 函数：

```python
cmd = [
    str(ce_path),
    "-application", "com.esri.cgac.application",
    "-input", str(cga_file),
    "-output", str(output_dir),
    # 自定义参数
    "-verbose",
    "-log", str(log_dir / "cgac.log"),
]
```

---

## 9. 技术支持

### 日志文件位置

| 日志 | 位置 |
|---|---|
| 连接器日志 | `C:\CityEngine\Plugins\cityengine-connector\logs\connector.log` |
| cgac 日志 | `C:\CityEngine\Plugins\cityengine-connector\logs\cgac.log` |
| Windows 服务日志 | Windows 事件查看器 → Windows 日志 → 应用程序 |

### 常见问题解答

**Q1: 连接器启动后立即断开？**
A: 检查 `config.json` 中的 `token` 是否正确，以及服务器是否在线。

**Q2: CityEngine 解析结果与 cgajs 差异很大？**
A: 这是正常现象，说明 cgajs 的解析能力需要提升。差异数据会自动上报到自动修复引擎。

**Q3: 如何更新连接器？**
A: 重新下载最新版本的 `cityengine-connector.zip` 并覆盖安装。

**Q4: 如何卸载连接器？**
A: 删除 `C:\CityEngine\Plugins\cityengine-connector\` 目录，并从 CityEngine `scripts` 目录删除 `cityvistion_connector.py`。

### 联系支持

- **管理后台**：`https://pyprt.cityvistion.com/cv-admin.html`
- **插件市场**：`https://marketplace.cityvistion.com/` → 🔌 插件市场
- **问题反馈**：通过管理后台的"问题反馈"功能提交

---

## 附录

### A. 快速参考卡

| 操作 | 命令 |
|---|---|
| 一键安装 | `powershell -ExecutionPolicy Bypass -Command "Invoke-WebRequest -Uri 'https://pyprt.cityvistion.com/downloads/install-cityengine-connector.ps1' -OutFile $env:TEMP\install-cityengine-connector.ps1; & $env:TEMP\install-cityengine-connector.ps1"` |
| 命令行启动 | `python "C:\CityEngine\Plugins\cityengine-connector\connector.py" --token your-token` |
| 服务安装 | `sc.exe create CityVistionConnector binPath= ...` |
| 服务启动 | `Start-Service CityVistionConnector` |
| 服务状态 | `Get-Service CityVistionConnector` |
| 服务停止 | `Stop-Service CityVistionConnector` |
| 服务删除 | `sc.exe delete CityVistionConnector` |

### B. 文件结构

```
C:\CityEngine\Plugins\cityengine-connector\
├── connector.py              # 主程序
├── config.json               # 配置文件
├── config.json.example       # 配置模板
├── requirements.txt          # Python 依赖
├── README.md                 # 说明文档
├── install-cityengine-connector.ps1  # 安装脚本
└── logs/
    ├── connector.log         # 连接器日志
    └── cgac.log              # cgac 日志
```

### C. 版本历史

| 版本 | 日期 | 更新内容 |
|---|---|---|
| 1.0.0 | 2026-07-19 | 初始版本，支持实时对比、cgac 无头编译、WebSocket 连接 |
| 1.0.1 | 2026-07-19 | 修复 WebSocket 403 问题（添加 role=workstation 参数） |
| 1.0.2 | 2026-07-19 | 修复 cgac 调用方式（使用 CityEngine.exe -application） |

---

**文档版本**：1.0.2  
**更新日期**：2026-07-19  
**适用插件版本**：CityEngine 实时对比连接器 v1.0.2