etwen/STPViewer

Fork 0

Files

T

CarmandGitHub 6d48d7f852 feat(i18n): Add runtime language packs and language switching (#1 )

2026-10-20 09:46:47 +08:00

12 KiB

Raw Permalink Blame History

STPViewer

STP/STEP 3D 查看器（Windows 桌面程序，C# .NET 8 WPF）— 多文件导入、装配树、点/距离/边/面/圆测量。

📖 目录

✨ 功能特性
💻 系统需求
📥 安装
🚀 快速开始
📚 使用指南
🔨 从源代码构建
📁 项目结构
⚠️ 已知限制
🤝 贡献
📜 版本记录
🙏 致谢

✨ 功能特性

快速打开机械零件 STEP 文件进行查看和测量，无需安装 SolidWorks / Creo 等大型 CAD 软件。

多文件导入 — STEP / STL / DXF，工具栏导入（可多选）、拖放到窗口、命令行 STPViewer.exe a.stp b.stl，或最近文件下拉菜单（▾，最近 10 项）
装配树 — STEP product structure 还原为树（组件→零件）；逐节点显示/隐藏、更改颜色（作用于子节点）、缩放至节点；文件层级可移除、开关轮廓边线；按名称搜索过滤；右键 只显示此节点 / 反转显示 / 全部显示 / 计算体积与质心；提示信息显示外形尺寸 L×W×H

测量（工具栏切换模式或快捷键，点击模型）：

模式	快捷键	输出
📍 点	P	XYZ 坐标（自动吸附邻近 B-rep 顶点或圆心）
📏 距离	D	两点直线距离 + ΔX/ΔY/ΔZ — 点击两个孔缘自动吸附圆心，可直接测量孔中心距
📐 边	E	直线长 / 曲线长 / 圆弧长 + 半径
⬛ 面	F	面积（网格近似）+ 曲面类型（平面法向量、圆柱半径/轴向）
⭕ 圆	C	圆心 / 半径 / 直径 / 周长
∠ 角度	A	两面（法向量）/ 两条直线边的夹角 + 补角
⇔ 面距	M	面到面最短距离（网格近似）+ 最近点对
⚖ 体积	（树右键）	网格有符号体积 + 质心标记 + 外形尺寸（封闭实体）
⤚ 对齐（两点）		点「要移动零件」一点 + 目标点 → 纯平移使两点贴合
🎯 对齐（三点）		源文件 3 点 + 目标文件 3 对应点 → 旋转+平移一次贴合

再次按下同一快捷键退出模式；Esc 先取消当前选择、再按退出模式。

旋转 — 树面板选文件 + 工具栏 ↻X/↻Y/↻Z 绕中心 +90°（用于调整朝向，可重复旋转）
拖动 🖐 — 手形光标模式，左键按住零件沿屏幕平面拖动、放开定位（右键转视角不受影响）
操作器 ⊹ — 树面板选文件 → XYZ 三色箭头 + 旋转环（Fusion 360 风格）；拖箭头沿该轴移动（与视角无关）、拖环绕轴转。永远浮在最上层、不被实体遮挡
干涉检查 🧩 — 2 个以上可见文件两两配对检查：相交时显示红色干涉交线 + 相交的三角形对数；无相交时报告最小间隙（gap≈0 即为配合，共面贴合不算干涉）
剖面 ✂ — X/Y/Z 轴或在模型上点 3 点定义任意平面；位置滑块 + 数值输入 + 反向；CPU 网格裁切（背景平行运算），原始几何保留（测量仍精确）
单位 — mm ⇄ inch 一键切换，已有测量（列表与 3D 标签）实时换算
语言 — 在 视图 → 语言 中选择语言；启动时从 i18n/ 的 JSON 文件读取可用语言，并记住你的选择
导出 — 测量结果 CSV（UTF-8 BOM，Excel 中文不乱码）、3D 视图 2× PNG 截图、📤 STEP 导出：可见零件以当前对齐位置写成新 STEP 文件（源文件不动）
视角 — 右键旋转、滚轮缩放、中键平移、ViewCube；一键 等角/前/上/右 标准视图与 正交⇄透视 切换
设置保存 — 窗口位置和大小、单位、最近文件自动保存；左右面板可拖动调宽

测量原则：边长、圆半径、角度取 B-rep 精确值；面积为三角网格求和近似（三角化精度根据模型尺寸自适应 0.02–0.5 mm）。

💻 系统需求

项目	需求
操作系统	Windows 10 / 11（x64）
运行环境	.NET 8 Desktop Runtime（依赖框架版）— Portable 版则免装
构建 SDK	.NET 8 SDK（仅从源代码构建时需要）

📥 安装

下载发布版直接执行，免安装。

依赖框架版（文件较小）：需 .NET 8 Desktop Runtime，执行 STPViewer v0.5.0.exe。
Portable 版（self-contained）：内置运行环境，免安装 / 无需管理员权限，执行 STPViewer v0.5.0.exe。

或从源代码构建（见下）。

git clone https://github.com/ETWen/STPViewer.git
cd STPViewer
dotnet build STPViewer.sln

🚀 快速开始

# 构建并执行
dotnet build STPViewer.sln
dotnet run --project src/STPViewer

# 发布免安装文件夹
dotnet publish src/STPViewer -c Release -o publish/STPViewer

然后导入 .stp 文件（工具栏「导入」、拖放或命令行传入文件路径），选一个测量模式，点击模型即可。

📚 使用指南

导入一个或多个 CAD 文件，每个文件成为装配树的一个根节点，视角自动缩放至适合窗口。
操作树 — 按名称搜索、显示/隐藏（或右键隔离显示）、换色、缩放至某节点，或移除文件。
测量 — 在工具栏选择模式或按快捷键（P/D/E/F/C/A/M），点击模型；点击孔缘自动吸附圆心，点击两次即可测得孔中心距；Esc 取消。结果显示在右侧面板，可逐条删除或全部清除。
装配 — 使用对齐（两点/三点）、旋转、拖动、操作器摆位，再用干涉检查对所有可见文件两两检查，验证装配配合。
剖面 — 打开 ✂、选轴向或点 3 点定义任意平面、滑动（或输入 %）剖切；测量仍以原始几何精确计算。
导出 — 测量结果保存为 CSV、截取 2× PNG，或把对齐后的场景写成新 STEP 文件交接给 CAD。

无需启动界面的导入流程与几何运算验证：

dotnet run --project tools/SmokeTest -- "path\to\model.stp"   # 导入 + 装配树
dotnet run --project tools/SmokeTest -- --clip-test           # 剖切裁切数学
dotnet run --project tools/SmokeTest -- --interference-test   # 干涉 相交/分离/贴合
dotnet run --project tools/SmokeTest -- --align-test          # 三点对齐刚体变换数学
dotnet run --project tools/SmokeTest -- --localization-test   # 语言资源与实时切换
dotnet run --project tools/SmokeTest -- --export-test in.stp out.stp  # STEP 导出往返验证

🔨 从源代码构建

dotnet build STPViewer.sln -c Debug
dotnet run --project src/STPViewer
dotnet publish src/STPViewer -c Release -o publish/STPViewer

NuGet 依赖（自动还原）：CADability、HelixToolkit.Wpf、CommunityToolkit.Mvvm。

🌐 添加语言

程序启动时扫描可执行文件旁的 i18n/*.json。文件名去掉 .json 后就是语言 ID，例如 en.json 对应 en，zh_cn.json 对应 zh_cn。JSON 顶层的 key 是语言菜单中的显示名，data 是资源键到译文的映射：

{
  "key": "Français",
  "data": {
    "Ui.Language": "Langue",
    "Ui.Main.MenuImport": "📂 Importer…"
  }
}

参考 src/STPViewer/i18n/en.json 中的资源键，翻译其 data 内容，将新文件以 UTF-8 编码放入可执行文件旁的 i18n/。重启 STPViewer 后，新语言便会出现在菜单和快捷栏中，无需重新编译。

📁 项目结构

STPViewer/
├── ARCHITECTURE.md            # 设计、数据流、开发 阶段
├── CLAUDE.md                  # 项目记忆 & 开发规范
├── STPViewer.sln
├── src/STPViewer/
│   ├── STPViewer.csproj       # net8.0-windows、UseWPF、统一的版本号来源 <Version>
│   ├── MainWindow.xaml / .cs   # 布局 + 鼠标拾取转发
│   ├── i18n/                  # 复制到可执行文件旁的语言 JSON 文件
│   ├── Models/                 # FaceInfo、MeasureMode、MeasurementResult、UnitSystem
│   ├── Services/               # StepImport、Measurement、Interference、Section、RigidAlign、Settings
│   └── ViewModels/             # MainViewModel（partial：Drag/Gizmo/Section/Interference/Export）、ModelNodeViewModel
└── tools/SmokeTest/           # 无需 UI 导入 + 几何数学验证

⚠️ 已知限制

大型 STEP（数千面）导入需数十秒（CADability 解析成本），导入期间有进度提示、UI 不会卡住。
轮廓边线超过 30,000 线段的文件会默认关闭边线（WPF LinesVisual3D 转动视角时性能限制），可在树面板手动打开。
IGES 不支持（CADability 无 IGES reader）；STL 无 B-rep，仅支持点/距离/角度/面距测量；DXF 为线框查看。
剖切面无封口（cap），剖开处显示内部背面材质（深灰）。
STEP 导出为「当前位置的 Solid/Shell 扁平列表」，不保留原始装配层级与 product 名称；STL 网格、DXF 线框无 B-rep 不导出。
面积、面距、体积/质心为三角网格近似值；边长/圆半径/角度为 B-rep 精确值。
少数 AP242 文件 CADability 支持不完整，导入失败会提示消息（不会崩溃）。
只读查看器，不写入/修改原始文件。

🤝 贡献

Fork 并建立 feature 分支：git checkout -b feature/your-feature
遵循 Conventional Commits：feat(scope): summary
Push 后开 Pull Request

📜 版本记录

v0.5.0

功能扩展： 圆心吸附（点击两次测量孔中心距）、测量快捷键（P/D/E/F/C/A/M）+ Esc、标准视图（等角/前/上/右）+ 正交投影、装配树搜索/隔离显示/反转、体积与质心、3 点任意剖切平面 + 位置数值输入、干涉检查支持 3 个以上文件（两两配对）、对齐后场景导出 STEP、面板可调宽、窗口/单位/最近文件自动保存。

v0.4.0

性能： 剖面裁切改为后台并行运算（大文件拖动滑块时不再卡住 UI）；零件变换烘焙（拖动/操作器放开）并行化；干涉间隙精修以 AABB 快速排除加速。
稳定性： 全域例外处理（记 log 至 %LOCALAPPDATA%\STPViewer\error.log + 消息框，不会崩溃）；背景运算期间停用会改动几何的指令；导入防重入。

v0.3.2

性能： 大组件测量模式下转动视角不再卡顿。测量模式改为渲染合并网格（每个文件 1 个 model），并用命中三角形的顶点 index 反查回是哪个面，不再挂数万个逐面 model；逐面渲染只保留给剖面模式。
相机交互暂停事件额外监听 HelixViewport3D.CameraChanged，避免相机实例被换掉时失去订阅。

v0.3.1

操作器 always-on-top 叠图层（永远浮在零件上、不被实体遮挡）。

v0.3.0

旋转对齐：轴向旋转（↻X/↻Y/↻Z）、三点对齐，以及统一的 TransformRoot 刚体变换路径。

v0.2.x

拖动模式、两点对齐、干涉检查、剖面、角度/面距测量、装配树、STL/DXF 支持、mm ⇄ inch。

🙏 致谢

CADability — 纯 C# CAD kernel：STEP 导入、B-rep 几何、面三角化
HelixToolkit.Wpf — 3D viewport、相机操作、HitTest
CommunityToolkit.Mvvm — MVVM

详细设计与开发阶段见 ARCHITECTURE.md。

12 KiB Raw Permalink Blame History Unescape Escape