STEP 实例视图与技术插图
此技能驱动与 cad-to-facts 相同的本地 facts CLI。它为一个显式选定的STEP实例创建只读的OCCT隐藏线视图。源工件绝不修改。渲染是离线和确定性的;不调用LLM/VLM,也不上传模型或图像。
实现范围
facts resolve:精确的实例/定义名称、子字符串/别名、路径、定义、根/装配类型、状态和有界世界包围盒空间约束。返回resolved、ambiguous、unresolved或failed;它从不按遍历顺序从多个候选中选择一个。facts orient:六个相机候选,以及一个基于最大包围盒面、从装配中心向外启发式的可选recommended_view。推荐总是semantic_status=assumed。facts render对STEP:一个激活的occurrence:N、一个显式的ViewSpecification、一个新SVG和一个新的同级.view.json清单。- 全局轴相机预设和显式法线/右向量、可见/隐藏线输出、有界SVG点计数、带有精确目标绑定的工件/快照/输出哈希值,以及可选的用户选择或假设视图语义。
不支持PNG、剖面/分解/着色视图、照片级渲染、尺寸标注、源声明或功能性正面识别以及视觉推理。SVG是审查/文档工作产品,不是视觉或几何等效证明,也不是FactSet。
设置
使用仓库中安装的 facts CLI,或 uv run --project /path/to/cad-to-facts facts ...。参考环境是Python 3.13,带有锁定的OCCT依赖项。STEP SVG渲染不使用ODA、文本转CAD、Blender或网络服务。
先解析,后渲染
编写一个TargetSelector JSON文件,例如:
{"name_contains": "DOOR", "is_assembly": false}
然后运行:
facts resolve assembly.step --selector door-selector.json
读取 resolution.status、resolution.complete、resolution.discovery、候选和诊断信息。
name 和 name_contains 同时检查实例名称和零件定义名称,因为有些STEP文件只声明了PRODUCT名称。候选的 name_path 和 path 不同:前者用于显示,而后者连接快照作用域的实例ID,是精确的路径选择器形式。
resolved:恰好一个发现的候选;使用其occurrence_id。ambiguous:检查候选的路径、名称和放置包围盒,添加约束,或要求用户选择。切勿静默选择第一个。unresolved:未发现匹配的候选。这不证明工程不存在。failed:无法读取快照;不要从中渲染。
complete 意味着完整的实例发现以及每个返回候选的可测量放置包围盒。它不代表完整的形状验证、无诊断、成功的解析或全局唯一性。当发现完整时,一个模糊或未解析的结果也可以是完整的。在部分或未知发现情况下,唯一性仅限已发现,且 complete=false。
可选假设正面选择
对于唯一解析的目标,facts orient assembly.step --selector selector.json 返回六个世界包围盒投影候选。它仅选择唯一的最大面积轴,且其从装配中心向外的方向明确。否则返回 ambiguous 且无视图。将成功的 recommended_view 逐字复制到JSON文件中用于渲染;它已经具有 semantic_intent.basis=assumed。除非用户实际选择,否则不要重新标记为 user_selected,并且永远不要称其为源声明的正面。包围盒启发式可能选择错误的文档面,因此请披露该假设。
导出视图
编写一个ViewSpecification,例如 door-front-view.json:
{
"title": "门正面",
"camera": {"preset": "front"},
"display": {"show_hidden_lines": false},
"image": {
"width": 1200,
"height": 900,
"padding": 24,
"curve_deflection_mm": 0.1,
"max_points": 200000
},
"semantic_intent": {
"label": "front",
"basis": "user_selected",
"note": "用户选择了正面作为前面"
}
}
渲染已解析的目标:
facts render assembly.step \
--target occurrence:12 \
--view-spec door-front-view.json \
--output door-front.svg
这将创建 door-front.svg 和 door-front.view.json。两个路径都必须是新的;两者都不会被覆盖。如果任一已存在,则不会写入新对。清单绑定工件/快照身份、精确目标、完整视图规范、渲染器/版本、投影范围、边/点计数、图像SHA-256/大小和诊断信息。在向下游使用之前检查这些字节。
解析和渲染独立重新读取STEP文件;渲染不强制使用先前的解析ID。在依赖选择之前,比较解析的 artifact.sha256 和 snapshot.snapshot_id 与渲染的 artifact.sha256 和 snapshot_id。如果任一不同,丢弃先前的选择并重新解析。清单记录实际渲染的快照和目标。
相机语义不是设计语义
front 预设仅表示:观察者在全局 -Y 上,朝向 +Y,屏幕右为 +X 且屏幕上为 +Z。它不证明零件的功能正面。其他预设记录在视图合约中。
对于用户定义的方向,请使用显式的 normal 和 right 向量。normal 从模型指向观察者;normal × right 确定屏幕上方向。semantic_intent.basis 仅为:
user_selected:用户提供/确认了此含义;assumed:必须披露的显式代理假设。
当前合约不接受 declared 基础:不提取源文件正面侧声明。对于纯几何相机,省略 semantic_intent。永远不要将预设或假设的正面转变为声称源设计声明了该侧面。
诚实限制
- 实体/实例ID和路径是快照作用域的,不是跨修订的持久身份。
- 目标解析过滤器声明ID、路径、名称/别名、定义、根/装配种类、状态和有界世界包围盒空间关系。返回放置包围盒和空间证据。方向关系在显式相机中比较中心;
near需要显式的包围盒间隙限制。这些不是接触、包含、精确距离或功能特征的证明。未实现面/边选择器和源代码made_by映射。 - 解析几何不定位可编辑的源参数。现有的更改命令仍然需要其显式的ChangePreparationSpec和SourceManifest证据。
- OCCT HLR提供投影边;曲线被离散化为SVG折线。
skipped_edge_count和VIEW_EDGES_NOT_DISCRETIZED披露省略的路径。点计数有界,但HLR运行时间不是一般大型装配的保证。投影范围描述的是发出的离散化点集,而不是精确源尺寸。 - 渲染可以在部分发现或解析器诊断的情况下成功;这些保留在清单中,并阻止整体模型完整性声明。
- 绝不要从像素读取尺寸。使用Facts进行实施的测量,或使用语义PMI获取声明的注释值。
- 重点测试使用分析性OCCT生成的STEP夹具。这些测试和隔离的真实文件观察不建立导出器互操作性或一般大型装配渲染。
- 未经单独授权,请勿将源或派生SVG发送到外部视觉模型。
有关所有选择器、相机和清单字段,请参阅视图合约。