01Spatial Documentation

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

错误与故障排查

先确定问题发生在哪一层：上传、建图、地图浏览、定位请求，还是 AR 对齐。不要在没有证据时同时修改扫描数据、内参和坐标转换，否则很难判断真正原因。

上传与建图

现象首先检查
ZIP 无法识别文件是否真的为 ZIP，内部是否包含所选输入类型要求的文件。
设备类型不匹配是否选择了正确的 LiDAR 品牌，E57 是否来自该设备并保留元数据。
图片与位姿不匹配文件名、扩展名和大小写是否与位姿表完全一致。
密度过低移动式采集间距是否超过约 2 m，固定站是否超过约 5 m；门口和转角是否缺站。
Parsing 失败视频能否完整播放，格式是否为当前界面接受的 MP4/MOV/M4V，网盘链接是否直接指向单个可下载文件。
Building 失败保留地图 ID、失败时间、Input 和 Pipeline 版本；先按卡片提示重试一次，重复失败再联系支持。

定位 HTTP 状态

状态含义与处理
400请求字段、图片或四个内参缺失/无效。
401API Key 缺失、失效或格式错误。
403已识别用户，但无权访问 Map/Project，或 Key 组合不匹配。
422本次图片没有得到可靠位姿；换用更清晰、包含更多已建图固定细节的图片。
429请求过快；按响应提示退避，不要立即并发重试。
5xx服务暂时异常；保留当前 AR 对齐，稍后重试。

结果看起来不对

  • 内容镜像或旋转 180°：相机 CV→graphics 轴转换缺失或做了两次。
  • 响应回来时内容跳动：使用了“当前相机”而不是拍摄上传图片那一帧的 AR 变换。
  • 始终固定偏移：Content、地图 Origin 和定位位姿不在同一地图坐标系。
  • 只在某些设备失败：检查该设备上传图片的实际分辨率、旋转、裁剪与内参。
  • 一段区域持续失败：在 Space Studio 检查该区域建图相机与 Points 覆盖，必要时补扫并重建。

联系支持时请提供 Portal 环境、地图 ID、发生时间和时区、输入类型、Pipeline 版本、HTTP 状态及已去除 Key 的最小请求信息。不要发送 API Key、Map Key、Project Key 或包含客户数据的完整原始包，除非通过已确认的安全渠道。