WeldVision

WeldVision 是一个面向焊缝检测、三维可视化、路径规划演示、结果导出和 Python 视频生成的 Windows 桌面应用。当前版本采用 WPF + .NET 10 + C++ Native + Python 的分层集成方案，重点是把点云/模型数据处理、焊缝检测、界面展示和打包发布串成一条可运行链路。

当前仓库已经具备这些能力：

  • WPF 桌面界面，包含总览、3D 视图、焊缝列表、规划列表、历史导出、推理绑定、视频管线和设置页。
  • Native C++ 焊缝检测链路，通过 P/Invoke 从 .NET 调用。
  • 基于检测结果的集成式路径规划骨架。
  • JSON 导出和历史记录持久化。
  • Python 视频生成脚本调用和产物回收。
  • 中文/英文切换与浅色/深色主题切换。
  • deploy.ps1 一键打包 WPF 应用、Native DLL、数据集和 Python 运行时。

需要明确的是，当前项目仍然是“工程化集成骨架 + 可运行演示链路”，不是完整工业机器人焊接控制系统。真实机器人逆运动学、精确碰撞检测、在线 SLAM、深度学习推理执行、工艺参数优化和闭环质量监测，目前仍处于接口预留或适配器阶段。

项目地址：

WeldVision/WeldVision/src · yantuguiguziPGJ/WeldVision - AtomGit

1. 项目结构

WeldVision/
├─ src/
│  ├─ WeldVision.App/             WPF 表现层
│  ├─ WeldVision.Application/     应用编排层
│  ├─ WeldVision.Domain/          领域模型层
│  └─ WeldVision.Infrastructure/  基础设施层
├─ native/
│  ├─ WeldVision.Algorithms.Native/  Native C++ 焊缝检测工程
│  └─ build/                         CMake/VS 构建输出
├─ 焊接测试/                        默认数据集和 weld_pipeline.py
├─ artifacts/                       .NET 构建输出
├─ deploy/                          打包输出目录
├─ history/                         运行历史记录
├─ deploy.ps1                       一键打包脚本
└─ README.md

2. 总体架构设计

2.1 四层分层

仓库主体采用四层结构：

  • src/WeldVision.App WPF 表现层，负责窗口、Tab 页、3D 交互、语言/主题切换、命令绑定和视图状态展示。
  • src/WeldVision.Application 应用编排层，负责组织一条完整工作流：数据集发现、焊缝检测、路径规划、感知适配、场景构建、历史记录、导出和视频生成。
  • src/WeldVision.Domain 领域模型层，定义稳定的数据结构和扩展边界，例如 WorkpieceDataSet、SeamDetectionResult、PathPlanningResult、VisualizationScene、WorkbenchSessionRecord。
  • src/WeldVision.Infrastructure 基础设施层，负责文件系统访问、Native DLL 调用、Python 进程调用、路径规划实现、导出实现、历史记录实现和感知适配器实现。

这套分层的核心目标是：界面不直接依赖 Native/Python 细节，编排层不依赖 WPF 控件，领域层不依赖外部实现，基础设施层可以按模块替换。

2.2 启动与依赖注入

应用入口在 App.xaml.cs。启动流程如下：

  1. 创建 ServiceCollection。
  2. 解析默认工作目录 MainWindow.ResolveWorkingDirectory()。
  3. 注册语言服务、主题服务、数据服务、Native 检测服务、路径规划服务、感知服务、导出服务、历史记录服务和视频生成服务。
  4. 构造 MainWindowViewModel。
  5. 设置默认语言为中文、默认主题为浅色。
  6. 解析并显示 MainWindow。

当前主要注册关系：

  • ILocalizationService -> LocalizationService
  • IThemeService -> ThemeService
  • IWorkpieceDataService -> WorkpieceDataService
  • ISeamDetectionEngine -> NativeSeamDetectionEngine
  • IVisualizationSceneBuilder -> VisualizationSceneBuilder
  • IPathPlanningService -> IntegratedRobotPathPlanningService
  • IPerceptionIntegrationService -> PerceptionIntegrationService
  • IWorkbenchHistoryStore -> JsonWorkbenchHistoryStore
  • IWorkbenchExporter -> JsonWorkbenchExporter
  • IVideoGenerationService -> PythonVideoGenerationService
  • IWorkbenchOrchestrator -> WorkbenchOrchestrator

这意味着 MainWindow 和 MainWindowViewModel 不再手工 new 后端服务，后续替换底层模块时只需要替换 DI 注册。

2.3 关键工作流

核心编排在 WorkbenchOrchestrator.cs。

AnalyzeAsync() 调用链：

  1. IWorkpieceDataService.DiscoverDefaultDataSet
  2. ISeamDetectionEngine.DetectAsync
  3. IPathPlanningService.PlanAsync
  4. IPerceptionIntegrationService.RunAsync
  5. IVisualizationSceneBuilder.BuildScene
  6. 生成默认导出路径
  7. 写入 history/workbench-history.json
  8. 汇总为 WorkbenchSnapshot

界面上的三个主命令分别对应：

  • Analyze
  • Export JSON
  • Generate Video

其中：

  • ExportLatestAsync() 会把最近一次 WorkbenchSnapshot 序列化到 exports/workbench-*.json
  • GenerateVideoAsync() 会调用 Python 管线，并把结果回填到当前快照

3. 详细模块设计

3.1 WPF 表现层

主界面位于：

界面层职责包括：

  • 展示工作目录、数据集摘要、检测摘要、规划摘要、视频摘要和错误信息。
  • 展示焊缝列表、规划列表、模型绑定、感知结果和历史记录。
  • 维护 Viewport3D 场景内容 Model3DGroup。
  • 在 3D 视图中处理旋转、平移、缩放、重置视角和选中对象聚焦。
  • 在 3D 视图中叠加起点/终点标签。
  • 响应语言切换和主题切换。

3.2 3D 视图交互设计

MainWindow 中的 3D 交互不是占位实现，而是完整的窗口内交互逻辑：

  • 左键拖动：绕场景旋转相机。
  • 右键拖动：平移相机。
  • 滚轮：缩放。
  • 中键：重置视角。
  • 选中焊缝或规划段后：自动聚焦到选中对象。

此外还包含：

  • 右上角独立方向轴视图。
  • 起点/终点标签投影到 2D Overlay。
  • 焊缝与规划段的选中高亮。
  • “3D Validation Guide”和图例面板。

相机预设逻辑在 ApplyCameraPreset()，会根据选中对象和场景半径自动设定观察距离和视场角。

3.3 语言与主题设计

语言和主题服务位于：

当前支持：

  • 中文 / English
  • Light / Dark

语言切换后不仅会刷新普通标签文本，还会刷新：

  • 3D 标签文案
  • 列表列头
  • 选中对象说明
  • 状态文本
  • 检测/规划/视频摘要
  • 历史记录、能力状态等 ViewModel 的本地化字段

主题切换通过 Application.Resources 内的动态资源实现，常见控件如 Button、Border、TabItem、ComboBox、DataGrid 均已接入统一资源。

3.4 数据集发现策略

数据发现有两层逻辑：

  • MainWindow.ResolveWorkingDirectory() 负责在应用启动时寻找“默认工作目录”。
  • WorkpieceDataService.DiscoverDefaultDataSet() 负责在工作目录下找到首个合法数据集目录。

合法数据集目录要求同一目录下至少存在：

  • *.ply
  • *.obj
  • *.png

默认工作目录搜索顺序：

  1. AppContext.BaseDirectory
  2. AppContext.BaseDirectory\data
  3. 解决方案根目录下递归搜索

因此，开发环境和打包后的目录结构都能被同一套逻辑识别。

3.5 Native 焊缝检测链路

Native 检测服务位于 NativeSeamDetectionEngine.cs。

调用链是：

  1. 通过 NativeLibraryResolver 确保 Native DLL 可解析。
  2. 调用 NativeMethods.RunSeamDetection(pointCloud, obj, png)。
  3. Native 侧返回 UTF-8 JSON 字符串指针。
  4. .NET 侧反序列化为 DTO。
  5. DTO 再映射为领域模型 SeamDetectionResult。

Native 返回结果包含：

  • 点云/模型/参考图路径
  • 点云点数和模型顶点数
  • 检测中心与局部基坐标
  • 前后平面和内外边界元数据
  • 局部焊缝段与世界坐标焊缝段

这条链路是当前系统里最接近“生产逻辑”的部分。

3.6 路径规划骨架

路径规划服务位于 IntegratedRobotPathPlanningService.cs。

它不是简单复制焊缝段，而是对每条焊缝做了这些处理：

  • 从焊缝起点和终点计算切向量。
  • 使用焊缝的 Approach 生成工具接近方向。
  • 构造工具法向。
  • 根据场景中心估算“远离场景中心”的粗粒度避碰抬升方向。
  • 叠加粗粒度可达性偏置，形成最终 Approach。

当前已实现的是：

  • 姿态对齐
  • 粗粒度避碰方向估计
  • 粗粒度可达性偏置

当前尚未实现的是：

  • 机器人品牌/型号级逆运动学求解
  • 真实关节约束
  • 离散碰撞检测
  • 轨迹平滑和速度规划

3.7 感知集成适配器

感知服务位于 PerceptionIntegrationService.cs。

当前内置两个模块：

  • Scene SLAM Mapper
  • Seam DL Inference

这两个模块当前做的是“环境探测 + 接口描述 + 结果回传”，不是直接执行完整感知任务：

  • SLAM 模块会检查 ROS_DOMAIN_ID 和 ros2(.exe)。
  • Deep Learning 模块会检查 TENSORRT_ROOT、CUDA_PATH、onnxruntime_perf_test.exe、trtexec.exe。

返回结果会体现在界面的：

  • Model Bindings
  • Inference Results
  • Capability Roadmap

这使项目具备后续接入真实 ROS2、ONNX Runtime 或 TensorRT 的结构位置。

3.8 历史记录与导出

历史记录实现位于 JsonWorkbenchHistoryStore.cs。

特点：

  • 文件固定写到 <rootDirectory>/history/workbench-history.json
  • 每次分析成功后写入一条 WorkbenchSessionRecord
  • 读取时按 CreatedAt 倒序返回

导出实现位于 JsonWorkbenchExporter.cs。

特点：

  • 导出目录固定为 <workingDirectory>/exports
  • 文件命名为 workbench-yyyyMMdd-HHmmss-sessionId.json
  • 导出内容包含最近一次会话的关键工作台记录

3.9 Python 视频生成链路

视频生成服务位于 PythonVideoGenerationService.cs。

执行流程：

  1. 查找 weld_pipeline.py
  2. 创建输出目录 <workingDirectory>/exports/video
  3. 解析 Python 启动器
  4. 启动 Python 进程执行脚本
  5. 读取 video-manifest.json
  6. 反序列化为 VideoGenerationResult

Python 解析顺序：

  1. AppContext.BaseDirectory/python/python.exe
  2. AppContext.BaseDirectory/../python/python.exe
  3. py -3
  4. python

脚本必须生成 video-manifest.json，否则 .NET 会认为视频生成失败。

4. 构建与输出设计

4.1 .NET 输出目录

仓库通过 Directory.Build.props 统一指定输出路径：

  • 中间输出：artifacts/obj/<ProjectName>/
  • 最终输出：artifacts/bin/<ProjectName>/<Configuration>/

这避免了默认 bin/obj 散落在各项目目录中，便于统一收集产物和清理。

4.2 目标框架

当前 C# 项目目标框架为：

  • net10.0-windows

其中：

5. 环境要求

推荐开发环境：

  • Windows 10/11
  • .NET SDK 10
  • Visual Studio 2022 或 Visual Studio 2022 Build Tools
  • CMake 3.20+
  • 可选 Python 3.12 / 3.13 / 3.14

如需执行视频生成，Python 环境建议包含：

  • numpy
  • Pillow
  • imageio
  • imageio_ffmpeg

6. 开发构建方法

6.1 构建 Native DLL

在仓库根目录执行：

cmake -S native/WeldVision.Algorithms.Native -B native/build -G "Visual Studio 17 2022" -A x64
cmake --build native/build --config Release

产物位置：

native/build/Release/WeldVision.Algorithms.Native.dll

6.2 构建 WPF 应用

推荐使用项目级构建命令：

$env:DOTNET_CLI_HOME="$PWD/.dotnet"
$env:DOTNET_SKIP_FIRST_TIME_EXPERIENCE="1"
$env:DOTNET_CLI_TELEMETRY_OPTOUT="1"
dotnet build .\src\WeldVision.App\WeldVision.App.csproj -c Release --nologo --disable-build-servers -p:UseSharedCompilation=false

产物通常位于：

artifacts/bin/WeldVision.App/Release/

说明：

  • 当前仓库更适合使用项目级构建，而不是优先使用整个 sln。
  • DOTNET_CLI_HOME 被显式设置到仓库内，是为了避免全局环境污染和首启写入问题。
  • --disable-build-servers 和 UseSharedCompilation=false 有助于减少构建环境不稳定时的缓存干扰。

7. 运行方法

7.1 开发环境直接运行

确保已经满足：

  1. Native DLL 已成功构建。
  2. 仓库内存在包含 *.ply、*.obj、*.png 的数据集目录。

然后任选其一：

  • 在 Visual Studio 启动 WeldVision.App
  • 直接运行 artifacts/bin/WeldVision.App/Release/WeldVision.App.exe

程序启动后会自动：

  1. 搜索默认工作目录
  2. 自动触发一次分析
  3. 加载 3D 视图、焊缝列表、规划列表和历史记录

7.2 打包后运行

打包完成后直接运行：

.\deploy\app\WeldVision.App.exe

打包版优先使用：

  1. deploy/python/python.exe
  2. deploy/app/<数据集目录>

这保证打包后的应用尽量不依赖目标机器上的系统 Python 和额外数据目录。

8. 界面使用说明

8.1 Overview

总览页用于快速判断当前工作流是否正常，主要展示：

  • 工作目录
  • 数据集摘要
  • 检测摘要
  • 路径规划摘要
  • 视频摘要
  • 当前错误信息
  • 能力路线图

8.2 3D View

3D 页用于校验焊缝和规划结果是否与工件几何一致，包含：

  • 点云显示
  • 焊枪网格显示
  • 焊缝段显示
  • 规划段显示
  • 选中对象信息面板
  • 起点/终点标签
  • 方向轴
  • 图例和验证说明

鼠标操作：

  • 左键拖动：旋转
  • 右键拖动：平移
  • 滚轮：缩放
  • 中键：重置相机
  • “Reset View” 按钮：恢复默认视角

8.3 Seams

显示检测到的焊缝段列表。选中某条焊缝后：

  • 3D 视图中的对应焊缝会高亮
  • 视角自动聚焦到该焊缝附近
  • 右侧信息面板同步刷新

8.4 Planning

显示路径规划结果。选中某条规划段后：

  • 3D 视图中的对应规划段会高亮
  • 相机会聚焦到该段
  • 面板中显示该规划段的起止点、接近方向和长度信息

8.5 History / Export

该页分为两部分：

  • 当前导出路径和数据集目录
  • 历史记录表格

点击 Export JSON 后，会在数据集目录下的 exports 目录生成 JSON 文件。

8.6 Inference

展示感知模块绑定说明与运行结果，主要用于：

  • 检查未来接入 SLAM / DL 的结构位置是否已经准备好
  • 检查当前机器环境是否能探测到 ROS2、CUDA、TensorRT、ONNX Runtime 等运行时

8.7 Video

点击 Generate Video 后会调用 weld_pipeline.py。成功后通常会在：

<workingDirectory>\exports\video\

生成这些文件：

  • weld_preview.png
  • weld_comparison.png
  • weld_path.json
  • weld_result.mp4
  • video-manifest.json

8.8 Settings

设置页支持：

  • Language: 中文 / English
  • Theme: Light / Dark

切换后会立即作用于当前窗口和当前数据展示。

9. deploy.ps1 详细解释

打包脚本位于 deploy.ps1。

它的目标不是单纯执行 dotnet publish，而是把运行 WeldVision 所需的几类资源一起整理到 deploy/ 目录中：

  • WPF 自包含应用
  • Native 焊缝检测 DLL
  • 数据集
  • weld_pipeline.py
  • Python 运行时
  • 启动说明文件

9.1 标准执行方式

推荐执行命令：

powershell -ExecutionPolicy Bypass -File .\deploy.ps1 -Configuration Release -Runtime win-x64

带显式 Python 路径的形式：

powershell -ExecutionPolicy Bypass -File .\deploy.ps1 -Configuration Release -Runtime win-x64 -PythonHome C:\Python314

9.2 支持参数

脚本参数：

.\deploy.ps1 [-Configuration Release] [-Runtime win-x64] [-PythonHome <path>]

参数说明：

  • Configuration 发布配置，默认 Release
  • Runtime 目标运行时，默认 win-x64
  • PythonHome 显式指定 Python 根目录，目录下应包含 python.exe

9.3 Python 解析顺序

脚本中的 Resolve-PythonHome 会按顺序尝试：

  1. -PythonHome
  2. 环境变量 WELDVISION_PYTHON_HOME
  3. 环境变量 PYTHONHOME
  4. 常见安装路径
    • C:\Python314
    • C:\Python313
    • C:\Python312
    • C:\Program Files\Python314
    • C:\Program Files\Python313
    • C:\Program Files\Python312
  5. py.exe
    • 先试 py -3.14
    • 再退回 py -3

如果这些位置都找不到，会直接抛错并停止打包。

9.4 数据集与脚本发现逻辑

脚本会先递归搜索 weld_pipeline.py，然后把该脚本所在目录视为数据集目录，并从该目录查找：

  • 第一个 *.ply
  • 第一个 *.obj
  • 第一个 *.png

如果任一文件缺失，脚本会中止，因为打包版必须带一套可直接运行的数据和 Python 脚本。

9.5 脚本逐步执行流程

deploy.ps1 实际做的事如下：

  1. 计算仓库根目录、deploy/、deploy/app/、deploy/python/ 路径。
  2. 搜索 weld_pipeline.py。
  3. 解析 Python 根目录。
  4. 推导数据集目录名称。
  5. 校验数据集中 *.ply、*.obj、*.png 是否存在。
  6. 清理旧的 deploy/app、deploy/python 和旧数据集目录。
  7. 设置 DOTNET_CLI_HOME、DOTNET_SKIP_FIRST_TIME_EXPERIENCE、DOTNET_CLI_TELEMETRY_OPTOUT。
  8. 执行 dotnet publish 输出自包含 WPF 应用。
  9. 把 Native DLL 复制到 deploy/app/。
  10. 把 weld_pipeline.py 和数据集文件复制到 deploy/app/<数据集目录名>/。
  11. 把整个 Python 运行时复制到 deploy/python/。
  12. 检查 Lib/site-packages 中若干关键包目录是否存在。
  13. 生成 deploy/README.txt。

9.6 dotnet publish 等价命令

脚本内部核心发布命令等价于：

dotnet publish .\src\WeldVision.App\WeldVision.App.csproj `
  -c Release `
  -r win-x64 `
  --self-contained true `
  -p:PublishSingleFile=false `
  -p:UseSharedCompilation=false `
  -o .\deploy\app

参数解释：

  • --self-contained true 打包 .NET 运行时，目标机器无需预装对应 .NET Runtime。
  • PublishSingleFile=false 保留目录结构，便于同时部署 Native DLL、Python 和数据文件。
  • UseSharedCompilation=false 避免 Roslyn 共享编译服务带来的环境差异问题。

9.7 关键路径变量说明

脚本中的几个关键变量：

  • $publishDir 整个打包根目录，即 deploy/
  • $appPublishDir WPF 应用和 Native DLL 放置目录，即 deploy/app/
  • $pythonDir Python 运行时放置目录，即 deploy/python/
  • $dataDir 打包后数据集目录，即 deploy/app/<数据集目录名>/
  • $nativeDll Native DLL 来源路径，即 native/build/Release/WeldVision.Algorithms.Native.dll

9.8 打包结果目录结构

成功后通常得到：

deploy/
├─ app/
│  ├─ WeldVision.App.exe
│  ├─ WeldVision.Algorithms.Native.dll
│  └─ <数据集目录名>/
│     ├─ weld_pipeline.py
│     ├─ *.ply
│     ├─ *.obj
│     └─ *.png
├─ python/
│  ├─ python.exe
│  └─ Lib/site-packages/...
└─ README.txt

9.9 包内运行逻辑

打包版启动后，应用会优先命中打包目录中的：

  • 数据集目录
  • Python 运行时

因此：

  • PythonVideoGenerationService 更容易直接找到 deploy/python/python.exe
  • ResolveWorkingDirectory() 更容易直接找到 deploy/app/<数据集目录名>

这正是该脚本把 Python 和数据集一并打包进去的原因。

9.10 包内依赖检查

脚本会检查这些 Python 包目录是否存在：

  • imageio
  • numpy
  • PIL
  • pillow.libs
  • imageio_ffmpeg

如果某些目录缺失，脚本只会给出 Write-Warning，不会立即失败。也就是说：

  • 打包成功不代表视频生成功能一定完整可用
  • 需要根据警告继续核对 Python 环境

10. 常见使用流程

10.1 开发调试流程

推荐顺序：

  1. 构建 Native DLL
  2. 构建 WPF App
  3. 运行 WeldVision.App.exe
  4. 检查总览页是否识别到数据集
  5. 检查 3D 视图、Seams、Planning 是否有内容
  6. 执行 Export JSON
  7. 执行 Generate Video

10.2 发布流程

推荐顺序：

  1. 确认 native/build/Release/WeldVision.Algorithms.Native.dll 已存在
  2. 确认 焊接测试/ 下存在 weld_pipeline.py 和一套完整数据
  3. 运行 deploy.ps1
  4. 检查 deploy/app/、deploy/python/ 和 deploy/README.txt
  5. 在打包目录中直接运行 deploy/app/WeldVision.App.exe

11. 常见问题

11.1 启动后没有识别到数据集

检查同一目录下是否同时存在：

  • *.ply
  • *.obj
  • *.png

并确认该目录在以下搜索范围之一：

  • 应用目录
  • 应用目录下的 data
  • 解决方案根目录递归范围

11.2 Native DLL 找不到

检查：

  • native/build/Release/WeldVision.Algorithms.Native.dll 是否存在
  • 打包后 deploy/app/WeldVision.Algorithms.Native.dll 是否存在

11.3 视频生成失败

检查：

  • weld_pipeline.py 是否存在
  • python 或 py 是否可用
  • Python 环境是否包含 numpy、Pillow、imageio、imageio_ffmpeg
  • exports/video/video-manifest.json 是否被生成

11.4 主题切换没有明显变化

通常不是主题服务没有执行，而是新控件没有接入动态资源。后续新增控件时，应优先复用现有 DynamicResource 颜色和样式。

12. 当前能力边界

当前已经完成：

  • Native 焊缝检测
  • WPF 三维可视化
  • 焊缝和规划段联动选择
  • 中英文切换
  • 浅色/深色主题切换
  • 历史记录持久化
  • JSON 导出
  • Python 视频生成链路
  • 一键打包脚本

当前尚未完成真实工业实现：

  • 真实机器人逆运动学求解
  • 精确碰撞检测与轨迹优化
  • 实时 SLAM 建图
  • ONNX / TensorRT 实际推理执行
  • 工艺参数优化
  • 质量监测闭环
# 开源 # c++ # c# # python
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

程序员学 AI（八）：AI Agent 到底是什么？从回答问题到完成任务

avatar AI Agent技术社区
cover

22道AI Agent 工程师必会的面试题，别啥都不会就出去找工作

avatar AI Agent技术社区

写给 TypeScript 工程师的 OpenClaw.NET 上手指南：用你熟悉的 TS 思维，跑起一个生产级 AI Agent

读代码层：TS 和 C# 本来就是「远房亲戚」——asyncawait??、接口、泛型、严格空检查，你的心智模型几乎无缝平移。真正要适应的只有两件事：类型是具名而非结构化的（多一句显式声明），以及 NativeAOT 下的「禁反射」约束。写扩展层：你甚至可以不怎么碰 C#——Node.js 插件桥意味着你的 TypeScript 插件就是一等公民，而且能在生产 aot 车道跑。内核给你 .NET

avatar AI Agent技术社区