OSGB WebGL 工具

功能介绍

OSGB WebGL 工具是一个 Windows 桌面应用，用于处理倾斜摄影三维模型（OSGB 格式）的转换、标注和导出。主要功能包括：

• OSGB 模型加载与转换：将 OSGB 格式的倾斜摄影数据转换为 3D Tiles 格式
• 3D 查看与交互：在 CesiumJS 引擎中实时预览模型，支持相机操控和导航
• 标注与测量：
  • 放置标记点并添加文本标签
  • 距离、面积、高度测量
  • 视角书签保存与恢复
• 项目持久化：保存和加载项目文件（JSON 格式），保留所有标注、测量和参数
• 截图导出：支持多倍率截图（1x/2x/4x）
• 部署包生成：导出包含 3D Tiles 和云端查看器的完整部署包
• 模型统计：显示加载的瓦片块信息和模型统计数据

开发环境

系统要求

Linux (Arch)

pacman -S nodejs npm yarn
# 或使用 nvm 管理 Node 版本

Windows

• Node.js 16+ (LTS 版本推荐)
• npm 8+ 或 yarn 1.22+
• Visual Studio Build Tools (用于 native 模块编译)

环境配置

1. 克隆项目并安装依赖：

git clone <repository-url>
cd osgb-webgl-tool
npm install

2. 验证安装：

npm run typecheck  # TypeScript 类型检查
npm test           # 运行单元测试
npm run e2e        # 运行 E2E 测试（可选）

构建步骤

开发环境启动

npm install                # 首次安装依赖
npm run dev               # 启动开发服务器（Vite + Electron）

开发模式下，应用会自动重载代码改动。

Windows 打包

npm run build             # 构建渲染进程和主进程
npm run dist:win          # 打包 Windows 安装包（.exe + .msi）

构建产物位置：

• 渲染进程：dist/ 目录
• 主进程：out/ 目录
• Windows 安装包：release/ 目录

引擎获取

OSGB 转换引擎

该工具依赖外部的 OSGB→3D Tiles 转换引擎。引擎获取流程（详见 Task 20）：

方案 1：使用预编译二进制

1. 获取引擎二进制

   • 下载预编译的转换引擎（osgb-converter.exe 或等效版本）
   • 推荐从官方渠道获取测试过的稳定版本

2. 配置引擎路径

   • 应用启动时，会通过 resolveEnginePath() 自动查找引擎
   • 默认查找位置：
     • vendor/engine/osgb-converter.exe (项目内)
     • 系统 PATH 中的引擎
     • 用户指定的路径（环境变量 OSGB_ENGINE_PATH）

3. 验证引擎

   npm run dev  # 首次启动时应用会验证引擎可用性
   

方案 2：从源码编译（用户 Fork）

若需自行编译引擎，可使用开源项目 fanvanzh/3dtiles 作为基础：

1. Fork 项目

   # 在 GitHub 上 Fork fanvanzh/3dtiles 到你的账户
   # 然后 clone 你的 fork
   git clone https://github.com/your-username/3dtiles.git
   cd 3dtiles
   

2. 触发 GitHub Actions 构建

   • 进入项目的 GitHub 页面
   • 导航到 Actions 标签页
   • 选择 windows.yml 工作流
   • 点击 Run workflow 手动触发 Windows 构建
   • 等待构建完成（通常 10-30 分钟）

3. 下载构建产物

   • 进入完成的 workflow run
   • 在 Artifacts 部分下载 Windows 二进制
   • 解压到 vendor/engine/win/ 目录

4. 或使用脚本自动获取

   # 项目中可能包含的获取脚本
   scripts/fetch-engine.sh
   

样例 OSGB 数据

项目包含测试用样例数据，位置：test-data/osgb/

部署说明

云端查看器部署

项目包含一个完全独立的静态 Web 查看器（viewer-web/），用于在浏览器中查看已转换的 3D Tiles。

构建查看器

cd viewer-web
npm install
npm run build   # 输出到 viewer-web/dist/

部署到 Nginx

1. 复制查看器到服务器：

scp -r viewer-web/dist/ user@server:/var/www/viewer/

2. Nginx 配置示例：

server {
    listen 80;
    server_name viewer.example.com;
    
    location / {
        root /var/www/viewer;
        try_files $uri $uri/ /index.html;
    }
    
    # 3D Tiles 数据（CORS 支持）
    location /tiles/ {
        proxy_pass http://tiles-server:8080/;
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, OPTIONS';
    }
}

3. 启动服务：

systemctl restart nginx

访问查看器

• 桌面：http://viewer.example.com/
• 移动端：支持触摸交互（双指旋转/缩放）

测试

单元测试

npm test                 # 运行所有单元测试（27 个）
npm test -- --coverage  # 生成覆盖率报告（目标 80%+）

测试覆盖：

• 项目存取（src/main/project-store.test.ts）
• OSGB 检查器（src/main/osgb-inspector.test.ts）
• 瓦片扫描（src/main/tiles-scanner.test.ts）
• 瓦片服务（src/main/tiles-server.test.ts）
• 转换流程（src/main/conversion-runner.test.ts）
• 部署包导出（src/main/deploy-export.test.ts）

E2E 测试

npm run e2e             # 启动 Playwright 测试（需要启动开发服务）
npm run e2e -- --debug  # 调试模式（打开 inspector）

E2E 测试覆盖关键用户流程：

• 项目创建与初始化
• OSGB 验证
• 转换执行与进度跟踪
• 标注与测量交互
• 项目保存/加载
• 视角书签管理

类型检查

npm run typecheck       # 运行 TypeScript 类型检查（无编译）

真实模型验证清单

在 Windows 机器上安装和测试完整的应用流程（需要真实 OSGB 数据）：

前置条件

• Windows 10/11 系统
• 真实 OSGB 模型数据（500MB+ 规模）
• 最少 4GB 可用内存
• 网络连接（用于部署访问）

安装与启动

• 安装 Windows 应用包（npm run dist:win 生成的 .msi）
• 启动应用，验证无崩溃
• 验证窗口标题为"OSGB WebGL 工具"

模型加载与转换

• 打开项目：选择真实 OSGB 目录
• 校验：应用正确识别模型结构和块数
• 选择转换参数（使用默认值测试）
• 执行转换：
  • 验证进度条正确更新
  • 检查转换日志无错误
  • 转换完成后自动进入查看器

查看与测量

• 模型加载在 Cesium 中正确渲染
• 相机操控流畅（鼠标旋转、缩放、平移）
• 距离测量：
  • 在模型上测量已知尺寸的物体
  • 对比测量结果与实际尺寸（误差应 <1%）
• 面积测量：
  • 测量已知面积的区域（如建筑群）
  • 验证测量精度
• 高度测量：
  • 测量已知高度的建筑或地形
  • 验证测量精度

标注与交互

• 添加标记点：放置 5+ 个标记，验证显示和文本标签
• 删除标记：选择标记并删除，验证实时更新
• 视角书签：
  • 保存当前视角为书签
  • 改变视角
  • 恢复书签，验证视角正确恢复
• 截图导出：
  • 1x 倍率：验证清晰度
  • 4x 倍率：验证高分辨率导出

项目持久化

• 保存项目：
  • 设置标注和测量后，点击"保存项目"
  • 选择文件位置并保存
  • 验证 JSON 文件创建
• 加载项目：
  • 点击"打开项目"，选择之前保存的文件
  • 验证所有标注、测量和参数恢复
  • 验证标注实体在模型上正确绘制

部署与云端访问

• 导出部署包：
  • 选择"导出部署包"
  • 输入项目名称
  • 验证生成完整的部署文件夹
• 部署到服务器：
  • 上传 3D Tiles 到 Web 服务器
  • 配置 Nginx 或类似 Web 服务
  • 部署查看器
• 访问验证：
  • 桌面浏览器：Chrome/Firefox/Safari 访问云端查看器
  • 移动设备：手机浏览器访问
  • 验证模型加载与交互流畅
  • 验证缩放和旋转响应快速

性能测试

• 模型加载时间：< 30 秒（取决于大小）
• 帧率：桌面环境 >30 FPS，移动环境 >15 FPS
• 内存使用：< 4GB
• 无内存泄漏：运行 30 分钟后重复上述操作

问题记录与修复

• 记录所有发现的问题（崩溃、功能缺陷、性能问题）
• 分类：
  • 关键（影响核心功能）
  • 高（影响用户体验）
  • 低（可在后续版本修复）
• 创建 issue 并追踪修复进度
• 修复后重新验证受影响功能

最终签核

• 全部测试项通过或问题已记录
• 无遗留崩溃或数据丢失
• 可交付生产环境

项目结构

osgb-webgl-tool/
├── src/
│   ├── main/                      # Electron 主进程
│   │   ├── index.ts              # 应用入口 & IPC 注册
│   │   ├── project-store.ts       # 项目读写
│   │   ├── osgb-inspector.ts      # OSGB 目录检查
│   │   ├── tiles-scanner.ts       # 3D Tiles 扫描
│   │   ├── tiles-server.ts        # 本地 HTTP 服务
│   │   ├── conversion-runner.ts   # 转换子进程
│   │   ├── deploy-export.ts       # 部署包导出
│   │   └── resolve-engine.ts      # 引擎路径解析
│   ├── renderer/                  # 渲染进程（React + CesiumJS）
│   │   ├── App.tsx                # 主应用组件
│   │   ├── components/            # UI 组件
│   │   │   ├── ProjectSetup.tsx
│   │   │   ├── ConversionPanel.tsx
│   │   │   ├── ToolBar.tsx
│   │   │   ├── AnnotationPanel.tsx
│   │   │   └── ...
│   │   └── viewer/                # CesiumJS 工具
│   │       ├── cesium-viewer.tsx
│   │       ├── tilesets.ts
│   │       ├── marker-tool.ts
│   │       ├── measurement-tool.ts
│   │       └── viewpoint-tool.ts
│   ├── preload/
│   │   └── index.ts               # 进程间通信桥接
│   └── shared/
│       ├── ipc.ts                 # IPC 通道定义
│       └── types.ts               # 共享类型定义
├── viewer-web/                    # 云端查看器（独立应用）
│   ├── src/
│   └── dist/                      # 构建输出
├── test-data/
│   ├── osgb/                      # 样例 OSGB 数据
│   └── tiles*/                    # 转换输出
├── vendor/
│   └── engine/                    # 转换引擎（可选）
├── package.json
├── tsconfig.json
├── vite.config.ts                 # Vite 构建配置
└── electron-builder.yml           # Electron 打包配置

常见问题

Q: 转换引擎未找到

A: 检查以下路径：

• vendor/engine/osgb-converter.exe
• 环境变量 OSGB_ENGINE_PATH
• 系统 PATH 中是否有引擎

Q: 模型加载缓慢

A: 根据模型大小调整参数：

• 降低 maxLvl（最大细节等级）
• 启用 simplify（简化几何）
• 启用 draco（Draco 压缩）

Q: 标注在加载项目后不显示

A: 确保：

• 项目 JSON 文件格式正确
• 瓦片目录 (tilesDir) 可访问
• 查看器已完全加载瓦片（检查进度条）

Q: 部署到云端后无法访问

A: 检查：

• Nginx CORS 配置是否启用
• 3D Tiles 文件路径是否正确
• 浏览器控制台是否有 CORS 错误

许可证

[项目许可证信息]

贡献

欢迎提交 Issue 和 Pull Request。

联系方式

[项目联系方式]