Session、Handle 与坐标系

NativeSession

NativeSession 持有一个原生运行时 Session 以及通过它创建的全部 Shape Handle。它在比 Model 更低的层级暴露 C ABI 操作集，适合实现适配器，或在边界明确的多个 Model 前端间共享一个 Session。

from cadflow import Model, NativeSession

session = NativeSession()
try:
    with Model(session) as model:
        body = model.box(10, 20, 3)
        print(body.volume)
    # 借入的 session 仍然有效。
finally:
    session.close()

Session 方法使用 ShapeHandle。它是包含 Session Token 与原生值的不透明数据对。不要伪造、修改或持久化这些字段；Handle 只对创建它的存活 Session 有意义。

CoordinateFrame

CoordinateFrame 是由原点和正交归一轴定义的不可变右手坐标系，用于转换局部点与向量、组合嵌套构造上下文以及序列化为 JSON-safe 映射。

成员	用途
point(local)	应用旋转和平移
vector(local)	只应用旋转
to_dict() / from_dict(data)	序列化或恢复坐标系
WORLD_FRAME	全局单位坐标系
current_frame()	读取当前上下文中的活动坐标系
use_frame(frame)	在上下文管理器内临时压入坐标系

构造时会拒绝退化或非正交轴。坐标必须有限，normal 与 x_dir 不应接近平行。

Workplane

Workplane(origin, normal, x_dir, parent=None, model=None) 派生局部坐标系。原点和方向相对于 parent 或当前 Frame 解释。进入上下文后，该 Frame 会暂时成为活动坐标系。

由 Model 创建的 Workplane 会附着 Model，并启用几何辅助方法：

成员	结果
point(value) / vector(value)	显式世界坐标元组
polyline(...)、circle_profile(...)、arc(...)	Model 持有的原生曲线或 Wire
interpolate(...)、helix(...)	Model 持有的原生曲线
extrude(profile, vector)	沿转换后的局部向量拉伸
sketch(name=None)	位于该 Frame 上的声明式 SketchDocument

独立 Workplane 仍可转换点和创建草图，但需要 Model 的几何辅助方法会抛出 RuntimeError。

并发与嵌套

活动 Frame 栈使用 Python 上下文本地状态，因此即使异常退出，嵌套上下文也会恢复之前的 Frame。原生 Session 是显式持有的资源；除非嵌入应用提供串行化，不要假定它支持任意并发访问。

精确成员见 NativeSession、ShapeHandle、CoordinateFrame 与 Workplane。