`Shape`

Shape 是 NativeSession 与不透明 ShapeHandle 的不可变 Python 包装。用户应从 Model 获取 Shape；直接构造会让代码依赖底层所有权细节。

身份与所有权

即使几何等价，两个包装对象也可能引用不同原生 Handle。几何比较应使用测量、拓扑或导出证据，而不是 Python 对象身份。涉及多个 Shape 的操作要求完全相同的 Session。

with cad.Model() as model:
    left = model.box(10, 10, 10)
    right = model.translate(left, 20, 0, 0)
    clearance = left.distance_to(right)

成员	返回值	说明
`kind`	`str`	Solid、Face、Wire 等原生形状类别
`volume`	`float`	非体积几何通常为零
`area`	`float`	模型单位平方下的表面积
`length`	`float`	模型单位下的曲线或边长度
`center_of_mass`	`(x, y, z)`	均匀密度质量属性质心
`bbox`	六个浮点数	`(xmin, ymin, zmin, xmax, ymax, zmax)`
`topology`	`dict[str, int]`	Solid、Shell、Face、Wire、Edge 与 Vertex 数量
`distance_to(other)`	`float`	最小距离；只允许同 Session

describe(detail="summary") 把测量组合为 JSON-safe 列表和映射；detail="mesh" 还包含三角网格。其他 detail 值会抛出 ValueError。

validate() 返回 OperationReport，检查测量是否有限，并为通常预期单一 Solid 的 Shape 报告异常多实体状态。这是低成本结构检查，不能替代应用自己的尺寸或可制造性验证。

report = body.validate()
if not report.ok:
    raise RuntimeError(report.to_dict())

成员	契约
`mesh(deflection=0.1)`	返回展平的顶点与三角形索引数组
`preview_mesh_buffer(deflection=0.35)`	返回紧凑原生预览缓冲区
`preview_glb(deflection=0.35)`	把缓冲区转换为内存中的 GLB 字节
`export_preview_glb(path, deflection=0.35)`	写出浏览器可用的 GLB

更小的 deflection 通常产生更密集的近似网格和更大输出。三角网格是派生显示几何；需要精确几何时使用 STEP/BREP 与原生测量。

face_properties(u=0.5, v=0.5) 计算 Face 上的点和法向。surface_metrics() 返回仿真预处理需要的原生 Face 测量。contact_metrics(other) 返回两个同 Session Face 的接近程度与相对方向证据。

归一化 (u, v) 的含义和返回字段取决于曲面类型，不要假定所有曲面都提供完全相同的证据。

body.export_step("out/part.step")
body.export_stl("out/part.stl", binary=True)
body.export_preview_glb("out/part.glb")

STEP 保留精确交换几何；STL 与预览 GLB 是三角近似。导出方法写入给定路径并返回 None，调用方应创建父目录并验证产物。