05 媒体文件与建模

Q：`getMediaFilesList()` 接口的 `fileTypes` 参数支持哪些值？响应数据中为何没有 `fileType` 字段？`deviceSn` 应传入什么？

查询过滤：fileTypes 参数支持过滤图片和视频类型的媒体："2"=图片，"3"=视频。

响应数据：无 fileType 字段，可通过以下字段区分：

item.getSuffix()：文件后缀名（jpg/mp4 等）

item.getExt().getImageType()：细分类型（WideCamera/ZoomCamera/InfraredCamera 等）

deviceSn：需传入机场（Dock）SN，而非无人机 SN。

Q：如何通过 SDK 获取媒体的访问地址url？`objectKey` 和 `fileId` 有什么区别？url地址是否有有效期？

需要访问媒体照片时，需要先获取媒体文件的 objectKey 或 fileId，调用 MediaServiceModule.getMediaFilesDownloadURL() 获取临时访问地址。

支持以下两种方式获取媒体访问地址：

方式一：实时监听（适用于展示最新照片）

调用：

监听媒体文件后处理事件，从回调参数 MediaFilePostProcess 中获取：

getObjectKey()：原图 objectKey

getPreviewObjectKey()：预览图 objectKey

随后调用：

即可获取图片访问 URL。

方式二：查询历史媒体（适用于展示历史照片）

调用：

获取媒体文件列表后，可以通过以下两种方式获取下载地址：

根据 fileId 调用：getMediaFilesDownloadURL(long fileId, callback)

根据 objectKey 批量调用：getMediaFilesDownloadURL(List<String> objectKeys, callback)

注意事项：

URL 有效期为 3600 秒（1 小时），过期后需重新调用接口获取新的下载地址。

getMediaFilesList 的 deviceSn 需传入机场 SN（Dock SN）。

缩略图展示建议优先使用 previewObjectKey 对应的 URL。

Q：媒体回传通知 `listenMediaFileDeviceUploadMessage()` 在哪些场景下会触发？飞行中拍照录像是否会触发？

媒体文件完成上传至对象存储后触发此通知。流程：飞行任务完成 → 飞机降落 → 机场上传媒体 → 推送通知。

飞行中拍照或录像不会触发该通知：飞行中拍摄的媒体存储于飞机本地，尚未上传至云端，仅飞机降落后、机场上传媒体时才会触发。

监听多个机场的媒体回传通知，性能影响可忽略。建议做法：设备离线时调用 cancelListenMediaFileDeviceUploadMessage() 取消订阅，避免资源泄漏。

Q：调用媒体后处理通知 `listenMediaFilePostProcessMessage()` 中`getPhotoPosition()` 和 `getShootPosition()` 有什么区别？如何获取照片拍摄时间？

photoPosition 与 shootPosition 区别：

MediaFilePostProcess.getImageMetadata().getPhotoPosition()（拍照位置）：相机镜头实际对准并成像的地面目标点坐标

MediaFilePostProcess.getImageMetadata().getShootPosition()（拍摄位置）：拍摄照片时无人机所在位置的坐标

拍摄时间获取： 照片拍摄时间通过 listenMediaFilePostProcessMessage 回调中的 MediaFileImageMetaData.getPhotoCreateTime() 获取。

Q：飞行任务完成后，MinIO 中没有生成媒体的缩略图和 WebP 格式图片，应如何处理？

任务完成后需调用回调接口触发后处理：

也可通过 listenMediaFileDeviceUploadMessage() 收到上传通知后再调用回调接口。

Q：媒体文件存储在 MinIO 中，是否会定期自动清理？如何删除？

不会自动清理。媒体文件会永久保留直至主动删除，可以通过 SDK 如下接口删除媒体文件：

Q：如何关联航线任务与任务产生的媒体文件？`task_uuid`、`flight_id` 和 `track_id` 有何关联？

listenWaylineTaskEvent 回调中的 uuid（任务 UUID）与 getMediaFilesList 返回的 flight_id 为同一值，使用该 uuid 匹配文件的 flight_id，即可关联该次航线任务及其产生的媒体文件。

三者关系如下：

字段	含义	产生时机
`task_uuid`	云端创建任务的唯一标识符	`createFlightTask()` 返回
`flight_id`	任务执行时的架次标识（值等于 `task_uuid`）	任务执行时赋值
`track_id`	飞控硬件起飞后生成的航迹 ID（36 位 UUID）	飞机起飞后生成

Q：如何确认一键起飞或手动拍摄的媒体已全部上传？

航线任务： 监听 listenWaylineTaskEvent，当 mediaUploadStatus=2 时表示媒体上传结束。

一键起飞或暂停任务后手动拍摄： SDK 暂无方法判断一键起飞的媒体上传完成状态，可通过 listenMediaFileDeviceUploadMessage 按本次飞行的 flightId 查询媒体文件，再调用 getMediaFilesList 查询 total 进行核对。

Q：Terra 建模支持多少路任务并发？部署服务器有什么配置要求？

Terra 建模任务默认采用串行处理方式，同时提交多个任务时会按顺序执行。

部署配置建议：

GPU： GTX 1650 4GB 可满足基础建模需求，复杂场景或高质量建模建议使用 8GB 及以上显存。

CPU： 推荐 8 核。

内存： 建议 64GB 及以上。

硬盘： 3D 重建建议预留原始素材大小 6 倍以上的存储空间。

对显卡是否属于游戏卡或专业卡没有限制，但暂不建议使用 Blackwell 架构显卡，如 RTX 5090、B200，当前可能存在 Terra 建模无法正常运行的情况。

Q：`TerraBuildModule` 支持哪些三维重建与测绘场景？上云 API 2 是否集成了 DJI Terra 的建图能力？

是的，上云 API 2 内置 Terra 建模服务，三维重建需要 Terra 服务（包含 GPU 算法节点）配合上云 API 2 后端底座运行。通过 TerraBuildModule 接口可调用以下场景：

场景	所需航线	说明
地块测绘 / DOM/DEM	面状测绘航线	正射拍摄
三维建筑建模	面状测绘航线	覆盖目标建筑
全景拼接	全景拍摄航点	调用 `createPanorama()`

Q：完成航线任务并回传媒体文件后，如何发起三维重建（`createReconstruction`）？`folderId` 和 `fileUuid` 参数如何获取？

建模流程如下：

调用 MediaServiceModule.getMediaFilesList(params, callback) 获取媒体文件列表，从回调结果 MediaFilesListItemInfoData.getFilePath() 获取文件路径，例如 1/27/28，取第二段 27 作为 folderId。

将 folderId 设置到 TerraBuildCreateReconstructionParams.setFolderIds()，调用 TerraBuildModule.createReconstruction(params, callback) 发起建模任务。其中 fileUuid 参数的值等于对应飞行任务的 flight_id（即 task_uuid）。

调用 TerraBuildModule.listenReconstructionStatusChanged(callback) 监听建模进度及状态变化。

Q：如何监听三维重建任务的进度和状态变化？

调用 TerraBuildModule.listenReconstructionStatusChanged(callback) 即可监听建模任务的进度及状态变化。

Q：getMediaFilesList() 接口的 fileTypes 参数支持哪些值？响应数据中为何没有 fileType 字段？deviceSn 应传入什么？#

Q：如何通过 SDK 获取媒体的访问地址url？objectKey 和 fileId 有什么区别？url地址是否有有效期？#

Q：媒体回传通知 listenMediaFileDeviceUploadMessage() 在哪些场景下会触发？飞行中拍照录像是否会触发？#

Q：调用媒体后处理通知 listenMediaFilePostProcessMessage() 中getPhotoPosition() 和 getShootPosition() 有什么区别？如何获取照片拍摄时间？#

Q：飞行任务完成后，MinIO 中没有生成媒体的缩略图和 WebP 格式图片，应如何处理？#

Q：媒体文件存储在 MinIO 中，是否会定期自动清理？如何删除？#

Q：如何关联航线任务与任务产生的媒体文件？task_uuid、flight_id 和 track_id 有何关联？#

Q：如何确认一键起飞或手动拍摄的媒体已全部上传？#

Q：Terra 建模支持多少路任务并发？部署服务器有什么配置要求？#

Q：TerraBuildModule 支持哪些三维重建与测绘场景？上云 API 2 是否集成了 DJI Terra 的建图能力？#

Q：完成航线任务并回传媒体文件后，如何发起三维重建（createReconstruction）？folderId 和 fileUuid 参数如何获取？#

Q：如何监听三维重建任务的进度和状态变化？#