工业模型轻量化平台用户操作手册
版本 v0.3.21 · 更新日期 2026-09-13 · 漂视 PICIMOS
本手册帮助模型处理人员完成上传、转换、参考图核对和构件清理，并为集成与运维人员提供接入入口。当前版本重点完善文件夹上传、双击聚焦、框选删除、清理副本与对比退出。任务显示完成后，仍需核对模型外观；任务完成不等于保真验收通过。
1 平台概述
平台接收工业、建筑和通用三维模型，输出 dpepack、GLB、FBX 和 3D Tiles。控制台与 DPE 编辑器独立运行；输出可通过 API 交付。在线地址：https://plw.picimos.com/ 。右上角和侧栏的“操作手册”均打开本手册。
- dpepack：用于平台构件查看、LOD 切换及保存清理副本，任务预览优先使用该格式。
- GLB：用于支持 glTF 的查看器；接收端需支持产物所用实例化、压缩扩展。
- FBX：选择 FBX 输出目标，完成后在产物仓库点击“下载 FBX”。Binary 7.4 文件保留独立构件、共享网格、材质颜色、UV 与内嵌 PNG 贴图，坐标为 Y 向上、米制。当前导出静态三角网格，不恢复 CAD 参数曲面或动画；含独立线段时明确报错。
- 3D Tiles：输出 1.1 tileset，保留整个目录的相对路径。默认本地坐标；用于地图时勾选“指定地理锚点”，填实际经度、纬度和椭球高（米）。默认输出 LOD0–3，“仅 lod0”输出单级。相同内容的 LOD 共用 GLB 文件，瓦片内嵌所需贴图。
不同源格式的几何、属性和材质覆盖范围不同。请以实际文件转换结果、任务日志和参考图验收为准，不能把列入格式清单理解为所有版本、所有实体都能无损转换。
2 快速开始
- 打开控制台，进入“新建转换”。开放模式无需令牌；启用鉴权时填写管理员提供的令牌。
- 单文件模型可直接选择；OBJ 等带外部资源的模型优先点击“选择文件夹”，选择包含模型、MTL 和贴图的共同上级目录。
- 在待上传列表中确认文件和主模型，点击“上传并使用”。上传完成后检查是否提示缺少依赖。
- 选择输出目标及转换参数，提交转换。到“任务中心”查看状态与日志。
- 任务完成后点击“预览”，先用 LOD0 核对整体、局部、颜色贴图与构件位置，再下载产物或保存清理副本。
2.1 文件夹与贴图上传
文件夹可以包含子目录；平台保留相对路径。也可以同时多选模型、MTL 和贴图，或拖入文件夹。浏览器只能读取您选中的文件，单选 OBJ 后无法自动读取旁边未选中的 MTL 或图片。
例如，下面三个文件应一起上传，主模型选择“仓库.obj”：
仓库/
仓库.obj
材质/仓库.mtl
贴图/墙面.pngOBJ 内的 mtllib 和 MTL 内的贴图路径应能对应到这些文件。出现缺失提示时，用界面补充附件并重新上传，确认依赖完整后再转换。重名资源无法唯一确定时，保留原目录结构；不要把多个不同目录的同名贴图全部摊平。
当前一次上传请求上限为 8 GiB，最多 20,000 个文件；代理或私有化配置可能进一步限制。目录中包含多个模型时，一次转换使用所选主模型，不会自动为每个模型建立任务。无需上传无关的缓存、视频或备份文件。
OBJ 当前读取 MTL 的颜色、透明度、漫反射贴图 map_Kd 及其缩放、偏移和重复设置。复杂着色器、凹凸或其他贴图通道不能据此视为已完整支持。材质缺失和几何转换成功应分别检查。
3 输入格式与转换参数
3.1 当前输入通道
| 输入 | 使用说明与边界 |
|---|---|
| OBJ / STL | OBJ 可保留分组和已支持的材质贴图；STL 通常没有材质和构件层级。 |
| FBX / GLB / glTF | 用于通用三维模型交换；外部资源需一起提交，材质与扩展需逐项检查。 |
| IFC / RVM | IFC 用于 BIM 交换；RVM 的同名 ATT/TXT 属性附件应一起上传。 |
| STEP | 通过部署的 CAD 解析通道处理；精度和单位设置会影响尺寸、三角数与耗时。 |
| SKP | SketchUp 解析通道；检查嵌套实例、材质、背面及离散构件位置。 |
| DXF / DWG | DWG 依赖服务器转换工具；3DSOLID 等实体不能假定受支持，必要时从源软件导出网格。 |
| GIM | 检查装配位置、图元、设备名称和属性；查看日志中的跳过或不支持项。 |
| 3DXML | 有 XML 网格及部分二进制解析通道；需核对装配、缺件及外观，不能保证所有 CATIA 导出版本。 |
Max、Blender、Maya、Revit、Bentley、Navisworks、CATIA、UG、Creo、SolidWorks 等软件的原生工程格式，不能一概当作直接输入通道。可先从源软件导出上述交换格式；RVT 常用 IFC，DGN 可按内容导出 IFC/DXF。OSGB、点云等能力仍需专项接入与验收。
3.2 参数怎么选
初次核对建议保持源坐标和单位，使用默认参数，以 LOD0 检查保真；确认源单位后再做单位换算。不要用坐标轴转换来掩盖构件装配错误。
| 参数 | 操作影响 |
|---|---|
| 输出目标 targets | 可选 dpepack、glb、fbx、3dtiles；需要清理副本时保留 dpepack。 |
| 生成 LOD | 提供不同细节级别；查看器可手动切换 0–3，具体简化程度以产物为准。 |
| STEP 几何精度 linearDeflection | 更细的曲面离散通常增加三角数和处理时间；仅用于适用的 STEP 通道。 |
| 源单位 sourceUnit | mm、cm、inch 等换算到米；错误选择会造成比例错误。 |
| 坐标轴 upAxis | zup2yup 用于已确认的 Z 向上源模型转换；不确定时保持源。 |
| LOD 误差 lodErrorScale | 调节简化质量与体积取舍；对照 LOD0 检查薄片、管线和小构件。 |
大模型处理时间受原型数、实例数、贴图、LOD 和解析器影响，增加 CPU 核数不会使所有阶段线性加速。服务器内存和磁盘需同时覆盖源文件、处理中间数据及各输出格式。
4 控制台和模型操作
4.1 任务中心
任务可按名称或 ID 搜索，并按状态、格式过滤。queued 表示排队，running 表示处理中，completed 表示产物生成完成，failed 表示失败，cancelled 表示取消。失败时先查看具体日志，再补充资源或调整参数重试。
“重转”会创建新任务；清理副本重转会沿用原清理条件。“删除任务”会删除该任务及产物，和视口中的“删除选中”含义不同。正在使用的产物不要通过删除任务清理。
4.2 导航与选择
| 按钮或手势 | 操作及退出方式 |
|---|---|
| 旋转、平移、缩放 | 左键旋转，右键平移，滚轮缩放；退出框选、测量或行走模式后再进行常规导航。 |
| 双击构件 | 聚焦该构件并显示属性，使用实例自身的范围；关闭属性面板可清除单选高亮。 |
| 主体视野 / 适配视野 / 离散对象 | 调整相机观察范围，不修改模型位置或删除构件。 |
| 目录树 | “构件”模式点击名称或勾选进行选择；点击定位图标聚焦。列表较长时用名称搜索。 |
| 框选 | 点击按钮后拖矩形；普通框选替换，Shift/Ctrl/Command 加选，Alt 减选；Esc 或再次点击退出。 |
| 隐藏 / 隔离 | 隐藏所选或只显示所选；“全部显示”恢复隐藏，已删除构件需“撤销删除”。 |
| LOD 0–3 | dpepack 手动切换细节；首次切换可能需要加载，切换时保留删除状态。 |
| 测量 | 点击两个模型表面点读取距离；Esc 或再次点击退出。数值单位取决于正确的源单位换算。 |
| 剖切 | 选择 X/Y/Z，拖动滑杆，可翻转方向；再次点击剖切按钮关闭。 |
| 行走 | WASD 移动，鼠标转向；无法锁定鼠标时拖动转向；Esc 退出。 |
| 视点 / 巡游 | 保存与跳转相机视角；保存多个视点后启动巡游，Esc 或再次点击巡游停止。 |
| 对比 | 选择另一模型，支持叠加、只看 A、只看 B、闪烁；再次点击“对比”、面板关闭按钮或 Esc 退出。 |
| 截图 | 将当前视口保存为 PNG，查看浏览器下载记录。 |
| 颜色 / 透明度 / 恢复 | 用于临时查看；共享材质的实例批次可能一起变化，不作为逐构件材质编辑与保存功能。 |
框选按构件包围盒与屏幕矩形相交判断，可能同时选到被遮挡的构件；它不是只选可见像素。先缩小观察范围，查看选中数量，再进行删除。模型原本只有一个合并网格时，无法凭空拆出其中的单个零件。
4.3 清理物流仓库的空中构件
- 从任务中心打开物流仓库的 dpepack 预览，用“离散对象”或旋转视角找到空中物体。
- 点击“框选”，拖框选择待清理构件。用 Alt 减选误选项，必要时结合目录树检查名称与数量。
- 点击“删除选中”检查剩余模型。发现误删就点“撤销删除”，可逐批撤销。
- 检查多个角度，确认主体构件完整后，点击“保存清理副本”。平台创建独立任务并输出 dpepack、GLB、3D Tiles，原模型保留。
- 等新任务完成，重新打开副本，确认空中构件已去除、主体和贴图正确。之后使用副本产物交付。
未保存的删除只属于当前视图，刷新或重新加载会丢失。隐藏或隔离不等于删除，保存副本只排除已删除的构件。当前副本清理要求 dpepack 稳定构件 ID，不允许删除全部构件，也暂不处理含独立线段的包；遇到提示请保留源任务。
空中物体可能来自源模型已有的离散内容，也可能涉及装配问题。清理前先对照源软件或参考图，避免把转换错误通过删除掩盖。
5 参考图与交付验收
参考图核对优先使用 LOD0，并调整到与参考图接近的视角、投影和观察范围。按下面顺序检查并保存记录：
- 整体：主体轮廓、朝向、尺寸比例和构件位置一致，没有非预期爆炸或塌缩。
- 局部：门窗、设备、薄片、曲面、小构件没有缺失、变形或重复。
- 材质：颜色、透明度、贴图方向、重复和接缝正确，没有缺图或意外变黑。
- 语义：名称、层级及业务属性满足本次交付要求；有构件语义的源模型应能正确选择。
- 输出：分别打开要求的输出格式；保存副本后重新打开验收，不能只看删除后的临时视图。
无参考图的 wulingzhiguang.3dxml 先按装配完整、比例合理、无异常缺件和穿插、日志无未解释错误检查，记录为“无参考图检查”，不标成“与参考图一致”。
任务完成、文件体积变小、三角数一致都不足以单独证明外观一致。验收记录应包含任务 ID、源文件、输出格式、版本、视角截图、异常和处理结论。
6 DPE 与 REST API 接入
DPE 使用平台地址连接并消费产物；启用鉴权时携带令牌。是否支持某种产物及其交互，需在实际 DPE 版本中完成导入、保存和重新打开检查。
启用鉴权的 API 可使用 Authorization: Bearer 或 X-Plw-Token。health 可用于读取在线版本；不要在分享链接或截图中放入令牌。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/health | 健康与版本 |
| GET | /api/v1/formats | 格式通道清单 |
| POST | /api/v1/uploads | multipart 上传 |
| POST | /api/v1/tasks | 新建转换或清理副本 |
| GET | /api/v1/tasks | 列表；支持 search、status、format |
| GET | /api/v1/tasks/:id | 任务详情、状态及产物 |
| GET | /api/v1/tasks/:id/artifacts/:type | 取得对应产物 |
| DELETE | /api/v1/tasks/:id | 删除任务及产物 |
单文件上传后，将返回的 path 用作 sourcePath：
curl -F 'file=@model.ifc' https://plw.picimos.com/api/v1/uploads
curl -H 'content-type: application/json' \
-d '{"sourcePath":"上传返回的path","targets":["dpepack","glb","3dtiles"]}' \
https://plw.picimos.com/api/v1/tasks文件夹上传使用 multipart 的 manifest 字段，以及与清单 field 对应的文件字段。示例清单如下；保留每个文件的相对路径：
{"primary":"仓库/仓库.obj","files":[
{"field":"file_0","path":"仓库/仓库.obj"},
{"field":"file_1","path":"仓库/材质/仓库.mtl"},
{"field":"file_2","path":"仓库/贴图/墙面.png"}
]}清理副本向 POST /api/v1/tasks 提交以下结构；ID 必须来自源 dpepack，不要使用任意网格序号代替：
{"cleanupOf":"源任务ID","excludedComponentIds":[12,34],
"targets":["dpepack","glb","3dtiles"]}7 MCP 接入
仓库提供 src/mcp-server.js，通过 PLW_API 指向平台后运行 npm run mcp。已有工具包括 list_formats、upload_model、convert_model、get_task、list_tasks、get_artifact_url、estimate_model；资源包括 plw://health、plw://formats、plw://tasks。
MCP 客户端的上传能力与网页文件夹上传不是同一个入口。需要资源包和清理副本的集成应按本手册的 REST 请求实现，并验证客户端实际支持的字段。
8 部署与运维
生产环境由 plw-dev.service 管理，程序目录与持久数据分离。发布前运行相关回归，确认没有运行或排队任务，备份程序并保留同一数据目录；发布后检查版本、原任务与产物可访问性。出现失败应回滚程序。不要用手动启动的第二个进程和服务管理器争抢同一端口。
| 变量 | 用途 |
|---|---|
| PLW_HOST / PLW_PORT | 监听地址和端口，服务默认端口 8800 |
| PLW_DATA | 持久任务及上传数据目录 |
| PLW_WORKERS | 并发数量；按单任务峰值内存设置，当前线上为 1 |
| PLW_TOKENS | 鉴权配置；未设置时为开放模式 |
| PLW_STEP_PYTHON | 部署使用的 STEP Python 运行入口 |
| PLW_RVMPARSER / PLW_DWG2DXF / PLW_SEVENZIP | 外部解析或解包工具位置 |
Linux 与 macOS 原生二进制不可混用。私有化时需按目标系统配置解析器，并使用实际样本测试。大模型不要仅按源文件体积估计浏览负载，实例数、原型数和可见三角数同样重要。
9 常见问题
提示缺少材质文件。 检查是否只选了 OBJ；选择共同上级文件夹，确认 MTL 和贴图一起上传，依赖路径正确。
双击后像看了全局。 确认点击的是目标构件；若源模型合并成一个网格，所选构件范围本来就是整块。分开的构件仍异常时，记录任务 ID、LOD 和点击位置。
框选拖动却在旋转。 先点击框选按钮进入模式。框选结束后按 Esc 恢复旋转；隐藏、剖切和当前视角都可能影响观察判断。
点击对比后无法操作。 再次点击“对比”、点面板关闭按钮或按 Esc 退出；仍有异常时刷新并确认在线版本。刷新前保存需要保留的清理副本。
删除后刷新又出现了。 临时删除未保存。使用“保存清理副本”，等任务完成后打开新的副本任务。
大模型旋转仍不流畅。 尝试 LOD1 或 LOD2，并关闭不需要的对比、线框；确认硬件加速开启。本版减少选择与显隐更新开销，但没有消除大场景绘制负载，不能保证固定帧率。
转换完成但外观不对。 保留原任务、日志和参考图，分别判断源模型离散内容、单位或坐标配置、缺材质、解析缺件等原因，再重转验证。
10 本版变化与后续优化
v0.3.21 增加 FBX 导出和独立读回核验；修正 3D Tiles 地理锚点矩阵、包围盒和默认 LOD，复用相同的 LOD 内容，并修正平台内 Tiles 预览朝向。同步更新在线与离线操作说明。
后续迭代重点为大模型空间索引与拾取、按需加载与绘制负载、格式保真回归、可保存编辑状态，以及开源和自研转换通道扩展。各项应以真实样本和保存后重新打开的结果验收，不把计划能力写成已上线功能。