WeldVisionWeldVision 是一个面向焊缝检测、三维可视化、路径规划演示、结果导出和 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 - AtomGit1. 项目结构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.md2. 总体架构设计2.1 四层分层仓库主体采用四层结构src/WeldVision.AppWPF 表现层负责窗口、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。启动流程如下创建ServiceCollection。解析默认工作目录MainWindow.ResolveWorkingDirectory()。注册语言服务、主题服务、数据服务、Native 检测服务、路径规划服务、感知服务、导出服务、历史记录服务和视频生成服务。构造MainWindowViewModel。设置默认语言为中文、默认主题为浅色。解析并显示MainWindow。当前主要注册关系ILocalizationService - LocalizationServiceIThemeService - ThemeServiceIWorkpieceDataService - WorkpieceDataServiceISeamDetectionEngine - NativeSeamDetectionEngineIVisualizationSceneBuilder - VisualizationSceneBuilderIPathPlanningService - IntegratedRobotPathPlanningServiceIPerceptionIntegrationService - PerceptionIntegrationServiceIWorkbenchHistoryStore - JsonWorkbenchHistoryStoreIWorkbenchExporter - JsonWorkbenchExporterIVideoGenerationService - PythonVideoGenerationServiceIWorkbenchOrchestrator - WorkbenchOrchestrator这意味着MainWindow和MainWindowViewModel不再手工 new 后端服务后续替换底层模块时只需要替换 DI 注册。2.3 关键工作流核心编排在 WorkbenchOrchestrator.cs。AnalyzeAsync()调用链IWorkpieceDataService.DiscoverDefaultDataSetISeamDetectionEngine.DetectAsyncIPathPlanningService.PlanAsyncIPerceptionIntegrationService.RunAsyncIVisualizationSceneBuilder.BuildScene生成默认导出路径写入history/workbench-history.json汇总为WorkbenchSnapshot界面上的三个主命令分别对应AnalyzeExport JSONGenerate Video其中ExportLatestAsync()会把最近一次WorkbenchSnapshot序列化到exports/workbench-*.jsonGenerateVideoAsync()会调用 Python 管线并把结果回填到当前快照3. 详细模块设计3.1 WPF 表现层主界面位于MainWindow.xamlMainWindow.xaml.csMainWindowViewModel.cs界面层职责包括展示工作目录、数据集摘要、检测摘要、规划摘要、视频摘要和错误信息。展示焊缝列表、规划列表、模型绑定、感知结果和历史记录。维护Viewport3D场景内容Model3DGroup。在 3D 视图中处理旋转、平移、缩放、重置视角和选中对象聚焦。在 3D 视图中叠加起点/终点标签。响应语言切换和主题切换。3.2 3D 视图交互设计MainWindow中的 3D 交互不是占位实现而是完整的窗口内交互逻辑左键拖动绕场景旋转相机。右键拖动平移相机。滚轮缩放。中键重置视角。选中焊缝或规划段后自动聚焦到选中对象。此外还包含右上角独立方向轴视图。起点/终点标签投影到 2D Overlay。焊缝与规划段的选中高亮。“3D Validation Guide”和图例面板。相机预设逻辑在ApplyCameraPreset()会根据选中对象和场景半径自动设定观察距离和视场角。3.3 语言与主题设计语言和主题服务位于LocalizationService.csThemeService.cs当前支持中文 / EnglishLight / Dark语言切换后不仅会刷新普通标签文本还会刷新3D 标签文案列表列头选中对象说明状态文本检测/规划/视频摘要历史记录、能力状态等 ViewModel 的本地化字段主题切换通过Application.Resources内的动态资源实现常见控件如Button、Border、TabItem、ComboBox、DataGrid均已接入统一资源。3.4 数据集发现策略数据发现有两层逻辑MainWindow.ResolveWorkingDirectory()负责在应用启动时寻找“默认工作目录”。WorkpieceDataService.DiscoverDefaultDataSet()负责在工作目录下找到首个合法数据集目录。合法数据集目录要求同一目录下至少存在*.ply*.obj*.png默认工作目录搜索顺序AppContext.BaseDirectoryAppContext.BaseDirectory\data解决方案根目录下递归搜索因此开发环境和打包后的目录结构都能被同一套逻辑识别。3.5 Native 焊缝检测链路Native 检测服务位于 NativeSeamDetectionEngine.cs。调用链是通过NativeLibraryResolver确保 Native DLL 可解析。调用NativeMethods.RunSeamDetection(pointCloud, obj, png)。Native 侧返回 UTF-8 JSON 字符串指针。.NET 侧反序列化为 DTO。DTO 再映射为领域模型SeamDetectionResult。Native 返回结果包含点云/模型/参考图路径点云点数和模型顶点数检测中心与局部基坐标前后平面和内外边界元数据局部焊缝段与世界坐标焊缝段这条链路是当前系统里最接近“生产逻辑”的部分。3.6 路径规划骨架路径规划服务位于 IntegratedRobotPathPlanningService.cs。它不是简单复制焊缝段而是对每条焊缝做了这些处理从焊缝起点和终点计算切向量。使用焊缝的Approach生成工具接近方向。构造工具法向。根据场景中心估算“远离场景中心”的粗粒度避碰抬升方向。叠加粗粒度可达性偏置形成最终Approach。当前已实现的是姿态对齐粗粒度避碰方向估计粗粒度可达性偏置当前尚未实现的是机器人品牌/型号级逆运动学求解真实关节约束离散碰撞检测轨迹平滑和速度规划3.7 感知集成适配器感知服务位于 PerceptionIntegrationService.cs。当前内置两个模块Scene SLAM MapperSeam DL Inference这两个模块当前做的是“环境探测 接口描述 结果回传”不是直接执行完整感知任务SLAM模块会检查ROS_DOMAIN_ID和ros2(.exe)。Deep Learning模块会检查TENSORRT_ROOT、CUDA_PATH、onnxruntime_perf_test.exe、trtexec.exe。返回结果会体现在界面的Model BindingsInference ResultsCapability 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。执行流程查找weld_pipeline.py创建输出目录workingDirectory/exports/video解析 Python 启动器启动 Python 进程执行脚本读取video-manifest.json反序列化为VideoGenerationResultPython 解析顺序AppContext.BaseDirectory/python/python.exeAppContext.BaseDirectory/../python/python.exepy -3python脚本必须生成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其中WPF 应用项目在 WeldVision.App.csprojInfrastructure 项目在 WeldVision.Infrastructure.csproj5. 环境要求推荐开发环境Windows 10/11.NET SDK 10Visual Studio 2022 或 Visual Studio 2022 Build ToolsCMake 3.20可选 Python 3.12 / 3.13 / 3.14如需执行视频生成Python 环境建议包含numpyPillowimageioimageio_ffmpeg6. 开发构建方法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.dll6.2 构建 WPF 应用推荐使用项目级构建命令$env:DOTNET_CLI_HOME$PWD/.dotnet $env:DOTNET_SKIP_FIRST_TIME_EXPERIENCE1 $env:DOTNET_CLI_TELEMETRY_OPTOUT1 dotnet build .\src\WeldVision.App\WeldVision.App.csproj -c Release --nologo --disable-build-servers -p:UseSharedCompilationfalse产物通常位于artifacts/bin/WeldVision.App/Release/说明当前仓库更适合使用项目级构建而不是优先使用整个sln。DOTNET_CLI_HOME被显式设置到仓库内是为了避免全局环境污染和首启写入问题。--disable-build-servers和UseSharedCompilationfalse有助于减少构建环境不稳定时的缓存干扰。7. 运行方法7.1 开发环境直接运行确保已经满足Native DLL 已成功构建。仓库内存在包含*.ply、*.obj、*.png的数据集目录。然后任选其一在 Visual Studio 启动WeldVision.App直接运行artifacts/bin/WeldVision.App/Release/WeldVision.App.exe程序启动后会自动搜索默认工作目录自动触发一次分析加载 3D 视图、焊缝列表、规划列表和历史记录7.2 打包后运行打包完成后直接运行.\deploy\app\WeldVision.App.exe打包版优先使用deploy/python/python.exedeploy/app/数据集目录这保证打包后的应用尽量不依赖目标机器上的系统 Python 和额外数据目录。8. 界面使用说明8.1 Overview总览页用于快速判断当前工作流是否正常主要展示工作目录数据集摘要检测摘要路径规划摘要视频摘要当前错误信息能力路线图8.2 3D View3D 页用于校验焊缝和规划结果是否与工件几何一致包含点云显示焊枪网格显示焊缝段显示规划段显示选中对象信息面板起点/终点标签方向轴图例和验证说明鼠标操作左键拖动旋转右键拖动平移滚轮缩放中键重置相机“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.pngweld_comparison.pngweld_path.jsonweld_result.mp4video-manifest.json8.8 Settings设置页支持Language: 中文 / EnglishTheme: Light / Dark切换后会立即作用于当前窗口和当前数据展示。9.deploy.ps1详细解释打包脚本位于 deploy.ps1。它的目标不是单纯执行dotnet publish而是把运行 WeldVision 所需的几类资源一起整理到deploy/目录中WPF 自包含应用Native 焊缝检测 DLL数据集weld_pipeline.pyPython 运行时启动说明文件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:\Python3149.2 支持参数脚本参数.\deploy.ps1 [-Configuration Release] [-Runtime win-x64] [-PythonHome path]参数说明Configuration发布配置默认ReleaseRuntime目标运行时默认win-x64PythonHome显式指定 Python 根目录目录下应包含python.exe9.3 Python 解析顺序脚本中的Resolve-PythonHome会按顺序尝试-PythonHome环境变量WELDVISION_PYTHON_HOME环境变量PYTHONHOME常见安装路径C:\Python314C:\Python313C:\Python312C:\Program Files\Python314C:\Program Files\Python313C:\Program Files\Python312py.exe先试py -3.14再退回py -3如果这些位置都找不到会直接抛错并停止打包。9.4 数据集与脚本发现逻辑脚本会先递归搜索weld_pipeline.py然后把该脚本所在目录视为数据集目录并从该目录查找第一个*.ply第一个*.obj第一个*.png如果任一文件缺失脚本会中止因为打包版必须带一套可直接运行的数据和 Python 脚本。9.5 脚本逐步执行流程deploy.ps1实际做的事如下计算仓库根目录、deploy/、deploy/app/、deploy/python/路径。搜索weld_pipeline.py。解析 Python 根目录。推导数据集目录名称。校验数据集中*.ply、*.obj、*.png是否存在。清理旧的deploy/app、deploy/python和旧数据集目录。设置DOTNET_CLI_HOME、DOTNET_SKIP_FIRST_TIME_EXPERIENCE、DOTNET_CLI_TELEMETRY_OPTOUT。执行dotnet publish输出自包含 WPF 应用。把 Native DLL 复制到deploy/app/。把weld_pipeline.py和数据集文件复制到deploy/app/数据集目录名/。把整个 Python 运行时复制到deploy/python/。检查Lib/site-packages中若干关键包目录是否存在。生成deploy/README.txt。9.6dotnet publish等价命令脚本内部核心发布命令等价于dotnet publish .\src\WeldVision.App\WeldVision.App.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFilefalse -p:UseSharedCompilationfalse -o .\deploy\app参数解释--self-contained true打包 .NET 运行时目标机器无需预装对应 .NET Runtime。PublishSingleFilefalse保留目录结构便于同时部署 Native DLL、Python 和数据文件。UseSharedCompilationfalse避免 Roslyn 共享编译服务带来的环境差异问题。9.7 关键路径变量说明脚本中的几个关键变量$publishDir整个打包根目录即deploy/$appPublishDirWPF 应用和 Native DLL 放置目录即deploy/app/$pythonDirPython 运行时放置目录即deploy/python/$dataDir打包后数据集目录即deploy/app/数据集目录名/$nativeDllNative DLL 来源路径即native/build/Release/WeldVision.Algorithms.Native.dll9.8 打包结果目录结构成功后通常得到deploy/ ├─ app/ │ ├─ WeldVision.App.exe │ ├─ WeldVision.Algorithms.Native.dll │ └─ 数据集目录名/ │ ├─ weld_pipeline.py │ ├─ *.ply │ ├─ *.obj │ └─ *.png ├─ python/ │ ├─ python.exe │ └─ Lib/site-packages/... └─ README.txt9.9 包内运行逻辑打包版启动后应用会优先命中打包目录中的数据集目录Python 运行时因此PythonVideoGenerationService更容易直接找到deploy/python/python.exeResolveWorkingDirectory()更容易直接找到deploy/app/数据集目录名这正是该脚本把 Python 和数据集一并打包进去的原因。9.10 包内依赖检查脚本会检查这些 Python 包目录是否存在imageionumpyPILpillow.libsimageio_ffmpeg如果某些目录缺失脚本只会给出Write-Warning不会立即失败。也就是说打包成功不代表视频生成功能一定完整可用需要根据警告继续核对 Python 环境10. 常见使用流程10.1 开发调试流程推荐顺序构建 Native DLL构建 WPF App运行WeldVision.App.exe检查总览页是否识别到数据集检查 3D 视图、Seams、Planning 是否有内容执行Export JSON执行Generate Video10.2 发布流程推荐顺序确认native/build/Release/WeldVision.Algorithms.Native.dll已存在确认焊接测试/下存在weld_pipeline.py和一套完整数据运行deploy.ps1检查deploy/app/、deploy/python/和deploy/README.txt在打包目录中直接运行deploy/app/WeldVision.App.exe11. 常见问题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_ffmpegexports/video/video-manifest.json是否被生成11.4 主题切换没有明显变化通常不是主题服务没有执行而是新控件没有接入动态资源。后续新增控件时应优先复用现有DynamicResource颜色和样式。12. 当前能力边界当前已经完成Native 焊缝检测WPF 三维可视化焊缝和规划段联动选择中英文切换浅色/深色主题切换历史记录持久化JSON 导出Python 视频生成链路一键打包脚本当前尚未完成真实工业实现真实机器人逆运动学求解精确碰撞检测与轨迹优化实时 SLAM 建图ONNX / TensorRT 实际推理执行工艺参数优化质量监测闭环