01Spatial Documentation

Machine-readable: manifest · index · 简体中文 Markdown

坐标系与位姿约定

定位成功后，01Spatial 返回相机在地图坐标系中的位姿。正确理解矩阵方向和相机轴，是避免内容镜像、旋转或固定偏移的关键。

变换命名

使用 T_A_B 表示“把 B 坐标中的点变换到 A 坐标”。

  • M：地图坐标系。
  • A：当前 AR Session 坐标系。
  • C：相机坐标系。
  • T_M_C：相机到地图的变换，也就是 API 的 camera_to_world。

matrix_column_major 是完整的 4 × 4 列主序矩阵。Three.js 的 Matrix4.fromArray() 可以直接读取，不要再次转置。

相机轴

API 位姿采用计算机视觉相机轴：

轴方向
+X向右
+Y向下
+Z向前

WebXR / OpenGL 风格相机通常是 +X 向右、+Y 向上、-Z 向前，因此使用：

D_cv_to_graphics = diag(1, -1, -1, 1)

对齐地图内容

拍摄查询图片时保存同一帧的 AR 相机到 Session 变换 T_A_C_graphics。图片没有旋转时：

T_A_M = T_A_C_graphics × D_cv_to_graphics × inverse(T_M_C)

把 T_A_M 应用到地图内容的共同根节点，不要覆盖 AR 相机。若物体在地图中的变换为 T_M_O：

T_A_O = T_A_M × T_M_O

上传图片发生旋转时，还必须加入同一图片旋转的逆变换；只交换宽高或调整内参不够。Rig.v2 返回的位姿可能属于任一上传帧，必须使用 poses[0].image 对应帧保存的 AR 变换。

地图经过真实尺度配置时，平移单位为米。不要假设不同地图共享同一个向上轴；以各地图保存的 Origin 为准。