RTC 系列扫描仪通过 RestAPI 完整数据下载

通过受信任的本地网络，直接从移动设备读取已捕获的项目数据。

1. 简介

Cyclone FIELD 360 移动应用包含一个轻量的设备端 HTTP 服务器。受授权的配套应用或桌面客户端可使用 REST API 浏览并下载在移动设备上捕获或同步的数据。

1.1 典型集成工作流

1. 将客户端计算机与移动设备连接到同一受信任的 Wi-Fi 网络或设备热点。
2. 从受支持的应用或集成工作流获取移动设备 IP 地址和动态分配的 API 端口。
3. 调用版本端点以确认服务器可达并识别数据模型版本。
4. 列出作业，然后检索所需的设站、扫描、标签或其他资源。
5. 流式传输所需文件。对于需要断点续传的大型二进制负载，使用 HTTP range 请求。

1.2 集成特性

1.3 范围与限制

• 该 API 暴露当前在移动设备上可用的数据。
• 某些端点取决于作业类型以及所需源数据是否已同步到设备。
• 该 API 不提供 TLS 加密、用户身份验证或写入操作。
• 客户端必须发现所分配的 API 端口。不得假定固定端口。

2. 连接到 API

2.1 基础 URL

服务器监听移动设备的网络接口。使用移动设备 LAN 或热点 IP 地址以及 API 启动时分配的端口构建请求：

http://<DEVICE_IP>:<PORT>/api/v1/<resource>

2.2 连接性检查

使用版本信息端点作为首次连接性与 schema 检查：

curl http://192.168.1.42:8081/api/v1/versioninfo

成功响应返回一个包含数据模型 schema 版本的 JSON 对象。

2.3 端口选择

在启动时，应用从平台提供的范围内选择第一个可用端口。因此所选端口可能会变化。集成应通过受支持的应用或集成工作流获取当前端口，而非假定固定值。

2.4 安全要求

• 仅使用受信任的本地 Wi-Fi 网络或直接设备热点。
• 不要通过路由器、VPN 网关或公共隧道转发 API 端口。
• 不要在公共日志或支持附件中暴露设备 IP 地址和 API 端口。
• 根据贵组织的数据处理规则对待下载的点云、图像、标签和元数据。
• 数据传输完成后结束本地连接。

3. 请求与响应约定

3.1 支持的 HTTP 方法

3.2 查询参数

3.3 标准对象字段

序列化对象包含通用的生命周期字段，然后是资源特定的字段。与远程或设备来源相关的字段仅出现在适用的对象上。

{
  "id": "07210aea-f4bf-47e9-bb8f-35ed9d51b8bb",
  "remoteId": "...",
  "remoteIds": { "<ownerIdentifier>": "..." },
  "deviceModificationTime": 1718000000,
  "createdTime": 1717000000,
  "lastModifiedTime": 1717500000,
  "inDatabase": true,
  "modified": false,
  "deleted": false
}

3.4 状态码

4. 资源概览

本节中的所有路由都相对于以下基础路径：

http://<DEVICE_IP>:<PORT>/api

5. 核心项目数据

5.1 作业

作业是捕获项目的顶层容器。它可以引用设站、配准扫描束、标签、缩略图、控制点和标签分类法。

GET /v1/jobs
GET /v1/jobs/<id>
GET /v1/jobs?filter__job_type=<int>
GET /v1/jobs/<id>?full_nested

5.2 设站

设站表示一个扫描仪设站或位置及其关联的图像与扫描数据。设站列表返回属于某个作业的设站。

GET /v1/setups
GET /v1/setups/<id>
GET /v1/setups/<id>?full_nested

6. 扫描与可下载内容

6.1 扫描

扫描是设站内的单个扫描。扫描对象提供本地可访问数据的元数据、关系与可用性标志。

GET /v1/scans
GET /v1/scans/<id>

6.2 设站图像与导出

6.3 E57 导出

• E57 包含经过运动学校正、无颜色的点云。
• E57 在首次访问时由下载的源原始点云生成，并缓存在源文件旁边。
• 可用性跟随源原始数据，而非缓存。hasE57 扫描标志在不启动转换的情况下报告可用性。
• 当扫描未知或所需源原始数据不可用时，端点返回 404。

6.4 估算数据量

下载大小取决于所选扫描分辨率和该设站可用的数据。以下数值在具有代表性的测试作业上测得，仅作为存储与传输规划的实用参考。

额外测得的元数据量： 在 Job 25 mm 测量中，温度数据为 41.1 KiB。该值与测试中使用的点云分辨率无关。

近似值 这些测量仅为示例，并非限制或保证的文件大小。实际值可能更小或更大。客户在开始导出前应检查可用存储空间，尤其是高分辨率 E57 数据。

7. 图像、标签与支持的元数据

7.1 未处理图像

列表形式返回可用未处理帧相机图像文件名的排序 JSON 数组。下载形式流式传输一张所选图像。

GET /v1/scans/<id>/unprocessed-images
GET /v1/scans/<id>/unprocessed-images?image=<id>

• 图像 ID 必须是纯文件名。
• 包含 /、 或 .. 的 ID 会被拒绝并返回 404，以防止路径遍历。
• 未知的扫描或缺失的图像返回 404。没有图像的扫描返回空列表。
• hasUnprocessedImages 扫描标志报告可用性。

7.2 原始产物与图像信息

GET /v1/raw
GET /v1/raw/<id>
GET /v1/raw/<id>/blob
GET /v1/imageinfo/<id>

原始资源提供产物类型、大小、格式代码以及可选的 image-info 引用。图像信息可包括宽度、高度、值范围、曝光、投影与变换。

7.3 标签与附件

GET /v1/tagattachments/<id>/blob
GET /v1/tagattachments/<id>/thumbnail

7.4 传感器数据

传感器数据资源可包含 GNSS 纬度、经度、海拔、HDOP 以及原始 NMEA GGA 消息，连同气压海拔与罗盘航向、精度及可用性标志。

8. 数据存储、保留与删除

REST API 为只读，无法删除 FIELD 360 数据。数据保留通过扫描仪、FIELD 360 作业浏览器和作业存储设置控制。本指南未定义固定的自动保留时长。

8.1 创建作业时配置原始数据存储

创建作业时，使用存储设置控制哪些扫描数据保留在移动设备上：

• 启用原始数据存储以导出为标准文件格式：当不需要保留原始扫描数据以供后续导出时，清除此选项。原始扫描数据可能非常大，会迅速占用平板上的可用存储空间。

Cyclone FIELD 360 中的作业存储设置

重要：关闭原始数据存储选项会移除该作业此前存储的原始数据。

所需存储量可能有显著差异。在测得的示例中，E57 点云范围从约 48.1 MiB（25 mm 作业）到约 9.5 GiB（1.6 mm 作业）不等。全景相机图像约为 128.7 至 129.0 MiB（36 个 JPEG 文件）。这些数值仅为代表性测量，对于其他作业、扫描仪或软件版本可能有所不同。

8.2 完全移除项目数据

要完全移除一个项目及其本地存储的数据，需从两个存储位置删除该项目：

• 从扫描仪中删除项目。 使用扫描仪项目管理工作流移除存储在扫描仪上的项目与扫描数据。
• 在 Cyclone FIELD 360 中删除相应的作业。 使用 FIELD 360 作业管理工作流删除存储在移动设备上的作业与数据。
• 确认移除。 确认项目不再列于扫描仪上，且作业不再列于 FIELD 360 中。

8.3 对 API 访问与导出的影响

• 在 FIELD 360 作业被删除后，其作业、设站、扫描、图像、附件及相关元数据不再通过设备端 REST API 可用。
• E57 和未处理图像的可用性取决于所需源数据是否存在。如果禁用了原始数据存储，或源项目或作业已被删除，相关的原始下载与导出可能不再可用。
• 此前导出或下载到其他系统的任何副本不在设备端删除工作流范围内，必须在目标系统中单独删除（如需要）。

8.4 保留摘要

9. 下载大文件

二进制端点支持 HTTP Range 头，使集成能够检索文件的一部分并续传中断的传输。

9.1 支持的 range 形式

9.2 部分下载示例

curl -H "Range: bytes=0-1048575" \
  http://192.168.1.42:8081/api/v1/raw/367d8b01-24c4-4c17-9332-31e95412539b/blob \
  -o chunk.bin

有效的 range 请求返回 206 Partial Content。无效的 range 返回 416 Range Not Satisfiable。

9.3 推荐客户端行为

• 在处理响应前检查 HTTP 状态码。
• 当客户端支持续传时，对大型二进制负载使用 Range 请求。
• 不要将缓存的 E57 视为独立可用。检查 hasE57 标志或端点响应。
• 使用可用性标志以避免对缺失负载发起不必要的请求。
• 仅将下载的客户数据存储到经审批的目标位置。

10. 使用示例

以下示例假设设备 IP 地址为 192.168.1.42，动态分配端口为 8081。请将 ID 替换为设备返回的值。

检查 schema 版本

curl http://192.168.1.42:8081/api/v1/versioninfo

列出作业

curl http://192.168.1.42:8081/api/v1/jobs

检索带嵌套资源的作业

curl "http://192.168.1.42:8081/api/v1/jobs/e6bd578d-8ae2-4f80-b1e0-4fa5a19ee3bc?full_nested"

下载 E57 点云

curl http://192.168.1.42:8081/api/v1/scans/07210aea-f4bf-47e9-bb8f-35ed9d51b8bb/e57 \
  -o scan.e57

列出并下载未处理图像

curl http://192.168.1.42:8081/api/v1/scans/07210aea-f4bf-47e9-bb8f-35ed9d51b8bb/unprocessed-images
# 列表响应示例：["image_0001.jpg", "image_0002.jpg"]
curl "http://192.168.1.42:8081/api/v1/scans/07210aea-f4bf-47e9-bb8f-35ed9d51b8bb/unprocessed-images?image=image_0001.jpg" \
  -o image_0001.jpg

检索强度 cube face

curl "http://192.168.1.42:8081/api/v1/setups/07210aea-f4bf-47e9-bb8f-35ed9d51b8bb/cubeface/posx?layer=intensity" \
  -o posx_intensity.bin

11. 故障排除

11.1 联系支持前

• 记录 FIELD 360 应用版本与移动操作系统。
• 记录响应状态码与请求路由，但酌情移除客户敏感值。
• 在本地确认设备 IP 与当前端口。不要包含网络凭据。
• 检查 /v1/versioninfo 并记录 modelVersion。
• 说明作业类型以及所需数据是否存在于移动设备上。

附录 A. 快速参考

附录 B. 文档说明

本面向客户的指南描述了为 iOS 和 Android 上的 Cyclone FIELD 360 提供的设备端 REST API 契约（按观察所得）。端点可用性取决于设备上存在的数据，对于导出路由，还取决于适用的作业与源数据条件。