相机、检测与 AI

这一页覆盖 4 个能力：cockpit:camera（拍照录像截帧）、cockpit:detection（AI 检测帧）、cockpit:ai-config（配置识别模型）、cockpit:smart-track（智能跟踪）。它们都要求在清单里声明同名权限，获取后判空使用。

⚠️ 相机和 AI 类命令由宿主串行执行，以避免并发命令误读设备状态。Promise 返回可能表示完成或确认，具体语义以各方法说明为准。

cockpit:camera：拍照、录像、截帧

状态

interface CameraState {
  availability: { status: 'available' | 'unavailable' | 'unsupported'; reason: string | null }
  mode: 'photo' | 'record' | null
  lens: 'wide' | 'zoom' | null
  zoom: number | null
  recording: boolean
}

availability.status !== 'available' 时其余字段为空，先处理不可用分支。

方法与完成条件

ensureMode(mode: 'photo' | 'record'): Promise<void>
switchLens(lens: 'wide' | 'zoom'): Promise<void>
ensureZoom(factor: number): Promise<void>
boundingZoom(rect: { x: number; y: number; width: number; height: number }): Promise<void>
takePhoto(): Promise<{ accepted: boolean; capturedAt: number }>
acquireRecording({ takeover?: boolean }): Promise<CameraRecordingHandle>
captureFrame({ scale, mime, quality?, requireGeometry? }): Promise<{
  blob: Blob; width: number; height: number; capturedAt: number; geometrySnapshotId: string | null
}>

每个方法"resolve"的含义不一样，这是最容易写错的地方：

方法	resolve 代表	超时
`ensureMode`	设备 `camera_mode` 已到达目标模式（已是目标模式则直接返回）	3s
`switchLens`	设备镜头已切换	3s
`ensureZoom`	变焦误差小于 0.1（已满足则直接返回）	3s
`boundingZoom`	仅 SDK 调用返回，不等变焦终态	SDK 决定
`takePhoto`	已观察到设备完整走完拍照状态（`photo_state: 1 -> 0`）；不代表媒体已上传	3s
`acquireRecording`	录像已启动并确认（`recording_state=1`）；`handle.stop()` 等到录像停止	5s
`captureFrame`	拿到当前直播画面的一帧 Blob；这不是设备拍照	SDK 决定

录像的所有权模型

录像句柄是"独占"的，规则要记牢：

设备已在录像且你没传 takeover: true → 抛 COCKPIT_SDK_ERROR。

新句柄接管后，旧句柄收到 superseded 并立即失效——旧句柄再调 stop() 不影响设备。

设备自己停止录像 → 当前句柄收到 device-state-changed。

句柄 dispose() 通常不停止设备录像，只是放弃所有权。

截帧与几何快照

captureFrame 默认 requireGeometry: true：宿主会在截帧前冻结一份几何快照（用于之后做"同帧投影"，见场景几何与直播指针），快照 ID 放在返回的 geometrySnapshotId。取不到几何时直接抛 CAPABILITY_NOT_AVAILABLE，不截帧。设为 false 可以拿纯截图（geometrySnapshotId 为 null）。

快照按插件隔离，全局最多 64 个，插件运行时结束自动回收；用完要主动 releaseSnapshot()。

示例

const camera = await ctx.capabilities.get('cockpit:camera')
if (!camera || (await camera.getState()).availability.status !== 'available') return

await camera.ensureZoom(2)
const photo = await camera.takePhoto()          // 设备完成拍照
ctx.logger.info('设备拍照完成', photo)

const frame = await camera.captureFrame({ scale: 1, mime: 'image/jpeg', quality: 0.9 })
// frame.geometrySnapshotId 可交给 cockpit:scene-geometry 做同帧投影，用完释放

cockpit:detection：AI 检测帧流

帧结构

interface DetectionFrame {
  frameId: string
  capturedAt: number              // 来自 AI SEI，不是浏览器时钟
  frameTimestampUs: number | null
  geometrySnapshotId: string | null
  targets: readonly {
    targetId: string
    type: string
    state: 'tracked' | 'vision-beacon-fused' | 'auxiliary-tracked' |
      'not-confident' | 'lost-predicting' | 'lost' | 'redetected' | 'invalid' | 'unknown'
    bbox: { x: number; y: number; width: number; height: number }   // 有效画幅内归一化坐标
  }[]
}

宿主会把设备原生的中心点框转成左上角 x/y/width/height，目标 ID/type 转成字符串；固件返回未知状态时映射为 unknown。

订阅频率规则

onFrame(handler, { maxFps?: 1 | 2 | 5 | 10 | 30 }): Disposable

运行在隔离环境（iframe 沙箱）里的插件：最高 10fps，上一帧没处理完时只保留最新帧。

请求超过当前上限会抛 CAPABILITY_RATE_UNSUPPORTED，不会静默降频。

帧坐标投影

每帧自带一个宿主私有几何快照（最多保留 2 秒、64 个）。用 frameId 把画面坐标投到地面（或反向）：

projectToGround(frameId, points, { groundHeight }): Promise<{ capturedAt; points } | null>
projectFromGround(frameId, points): Promise<{ capturedAt; points } | null>

快照过期或不存在的帧返回 null；一批点里个别点投不出去时，该位置返回 null，不影响其他点。

示例：跟踪检测目标的地面位置

const detection = await ctx.capabilities.get('cockpit:detection')
if (!detection) return

const off = await detection.onFrame(async (frame) => {
  const target = frame.targets.find(item => item.state === 'tracked')
  if (!target) return
  const center = { x: target.bbox.x + target.bbox.width / 2, y: target.bbox.y + target.bbox.height / 2 }
  const projected = await detection.projectToGround(frame.frameId, [center], { groundHeight: 0 })
  if (projected?.points[0]) ctx.logger.debug('同帧目标位置', projected.points[0])
}, { maxFps: 10 })

注意：检测帧是机载 AI 的逐帧输出流，和"把截图传给后端识别"是两回事。

cockpit:ai-config：配置识别模型与目标

状态与方法

interface AiConfigState {
  availability: CapabilityAvailability
  model: string | null
  recognitionEnabled: boolean
  targetTypes: readonly string[]
}

ensure({
  model?: 'dji-visible'
  recognitionEnabled?: boolean
  targetTypes?: readonly string[]
}): Promise<{ confirmed: boolean; reason: string | null }>

当前只支持 visible 槽的 dji-visible 模型。目标类型的语义映射：person=2、vehicle=3、boat=4、moving-target=34；⚠️ visible 链路明确拒绝 moving-target（它只适用于红外）。

ensure 的行为

ensure() 按"选模型 → 开关识别 → 替换目标类型全集"串行执行，每步最多等 5 秒权威状态；状态已满足就不重复下发。targetTypes: [] 表示清空全部类型，不等于关闭识别。

返回 { confirmed: false, reason } 表示业务前提不满足（比如 visible 用了 moving-target、识别没开就配类型），这是正常返回不是异常；SDK 错误、超时、宿主销毁才走异常。

示例

const ai = await ctx.capabilities.get('cockpit:ai-config')
if (!ai) return
const result = await ai.ensure({
  model: 'dji-visible',
  recognitionEnabled: true,
  targetTypes: ['person', 'vehicle'],
})
if (!result.confirmed) ctx.logger.warn(result.reason ?? 'AI 配置未确认')

cockpit:smart-track：智能跟踪

状态与方法

interface SmartTrackState {
  availability: CapabilityAvailability
  phase: 'off' | 'selecting' | 'confirming' | 'tracking' |
    'lost' | 'stopping' | 'error' | 'unknown'
  targetId: string | null
  exitReason: string | null
}

start(target:
  | { kind: 'detection-target'; targetId: string }
  | { kind: 'rect'; bbox: { x: number; y: number; width: number; height: number } }
): Promise<SmartTrackState>
stop(): Promise<SmartTrackState>

start() 两种用法：

从检测目标接续：传 detection-target + 目标 ID（必须是无符号整数的规范字符串）。下发后要求连续稳定 tracking 1 秒才算成功（总等待 5.5 秒）；目标短暂丢失时会在最新检测帧里选同类型、框最大的目标接力（最多重试 3 次）。

从画框开始：传 rect + 归一化框，走 selectRect → confirm → tracking。

stop() 会先呈现 stopping，最终必须回到 phase=off（最多等 5 秒）。targetId 只在 tracking/lost 阶段有值。

示例

const tracking = await ctx.capabilities.get('cockpit:smart-track')
if (!tracking) return
const terminal = await tracking.start({ kind: 'detection-target', targetId: target.targetId })
if (terminal.phase !== 'tracking') throw new Error('未进入跟踪终态')
// 业务完成时：
await tracking.stop()

注意：没有 updateTarget 方法——换目标就是重新 start()。

常见问题

现象	原因与处理
`takePhoto` 返回但消息中心没图	拍照完成 ≠ 媒体已上传；媒体文件要等上传后通过后端/媒体能力查询
想要"当前画面截图"却触发了设备拍照	用 `captureFrame`（只截直播画面），不要用 `takePhoto`
`captureFrame` 抛 `CAPABILITY_NOT_AVAILABLE`	`requireGeometry: true` 但当前拿不到几何；不需要投影就设 `false`
请求 30fps 报错	你的插件运行时上限是 10fps；改用 `maxFps: 10`
录像句柄突然失效	被其他调用者 `takeover` 了；监听句柄的 `superseded`/`device-state-changed` 做善后
`ensure` 报 moving-target 不支持	visible 链路不支持该类型；红外能力当前未开放

cockpit:camera：拍照、录像、截帧#

状态#

方法与完成条件#

录像的所有权模型#

截帧与几何快照#

示例#

cockpit:detection：AI 检测帧流#

帧结构#

订阅频率规则#

帧坐标投影#

示例：跟踪检测目标的地面位置#

cockpit:ai-config：配置识别模型与目标#

状态与方法#

ensure 的行为#

示例#

cockpit:smart-track：智能跟踪#

状态与方法#

示例#

常见问题#

cockpit:camera：拍照、录像、截帧

状态

方法与完成条件

录像的所有权模型

截帧与几何快照

示例

cockpit:detection：AI 检测帧流

帧结构

订阅频率规则

帧坐标投影

示例：跟踪检测目标的地面位置

cockpit:ai-config：配置识别模型与目标

状态与方法

ensure 的行为

示例

cockpit:smart-track：智能跟踪

状态与方法

示例

常见问题