跳到主要内容

Vfp.axis_convention()

asset.axis_convention() -> dict[str, str]

读取并验证 VFP authored-space 的方向约定。返回的新字典固定包含 up、forward 与 handedness；VFP 1.3 Orientation Profile v1 的有效结果为：

{"up": "+Z", "forward": "+Y", "handedness": "RIGHT_HANDED"}

coordinateSystem="Z_UP" 只声明上轴，不能独立确定模型的正面或转台 yaw=0。相机、GLB 转换器和引擎适配层应使用本方法，而不是自行假设 +Y、+Z 的前后关系。

示例​

from voxelkit import Vfp, VfpError

asset = Vfp.parse("house.vfp")
try:
    axis = asset.axis_convention()
except VfpError as error:
    raise RuntimeError("不支持的资产方向约定") from error

assert axis["up"] == "+Z"
assert axis["forward"] == "+Y"

兼容与错误​

  • 对缺少 axisConvention 的早期 VFP 1.3，SDK 返回上述稳定 v1 默认值。
  • META 的 coordinateSystem 不是 Z_UP、存在但不完整的 axisConvention，或取值不是 v1 固定值时，方法抛出 VfpError；不会猜测、镜像或静默翻转模型。
  • 此方法只读取 META，不恢复 VOX0，也不建立 source-hash 可信边界。需要可信资产时继续调用 validate()。