Sessions, handles, and frames

NativeSession

NativeSession owns one native runtime session and all shape handles created through it. It exposes the C ABI operation set at a lower level than Model. Use it to implement adapters or to share one session across carefully scoped model frontends.

from cadflow import Model, NativeSession

session = NativeSession()
try:
    with Model(session) as model:
        body = model.box(10, 20, 3)
        print(body.volume)
    # The borrowed session remains open.
finally:
    session.close()

Session methods work with ShapeHandle, an opaque pair containing a session token and native value. Never fabricate, modify, or persist these fields. A handle is meaningful only to the live session that created it.

CoordinateFrame

CoordinateFrame is an immutable right-handed frame defined by origin and orthonormal axes. It converts local points and vectors, composes nested construction context, and serializes to a JSON-safe mapping.

Member	Purpose
point(local)	Apply rotation and translation
vector(local)	Apply rotation only
to_dict() / from_dict(data)	Serialize or restore the frame
WORLD_FRAME	Global identity frame
current_frame()	Read the context-local active frame
use_frame(frame)	Temporarily push a frame in a context manager

Frame construction rejects degenerate or non-orthogonal axis definitions. Keep coordinates finite and avoid nearly parallel normal and x_dir values.

Workplane

Workplane(origin, normal, x_dir, parent=None, model=None) derives a local frame. The origin and directions are interpreted relative to parent or the current frame. Entering the context temporarily makes the frame active.

Model-created workplanes attach the model and enable geometry helpers:

Member	Result
point(value) / vector(value)	Explicit world-space tuple
polyline(...), circle_profile(...), arc(...)	Model-owned native curve or wire
interpolate(...), helix(...)	Model-owned native curve
extrude(profile, vector)	Extrusion along the transformed local vector
sketch(name=None)	Declarative SketchDocument on the frame

A standalone Workplane can still transform points and create sketches, but geometry helpers that need a model raise RuntimeError.

Concurrency and nesting

The active frame stack uses Python context-local state, so nested contexts restore the previous frame even when an exception exits the block. A native session itself should be treated as an explicitly owned resource; do not assume arbitrary concurrent access unless the embedding application provides serialization.

Exact members: NativeSession, ShapeHandle, CoordinateFrame, and Workplane.