# =============================================================================
# devices/cameras/realsense/manifest.yaml
#
# Intel RealSense 相机驱动清单。覆盖两种型号：
#   D405 —— 腕部相机，眼在手上，参与跟踪与手眼标定
#   D435 —— 手外相机，顶视，参与粗定位兜底与手眼标定
#
# 这里【不放现场数值】。序列号 / 分辨率 / 曝光一律在 config/site.yaml。
# =============================================================================

id: realsense
label: Intel RealSense D405 / D435
kind: camera
vendor: intel
version: "pyrealsense2"

# 从哪里读出「当前用哪个型号」。值是 config_schema 里的 field key。
model_selector: model

description: >
  RealSense 深度相机。D405 装在法兰/夹爪上做腕部视觉（眼在手上），
  D435 架在双臂中间做顶视（眼在手外）。USB 独占，同一时刻只能一个进程打开。

# --- 厂商物料放置要求 ------------------------------------------------------
assets:
  - path: driver
    required: false
    what: 厂商驱动（若使用 pyrealsense2 则无需放置，由 conda 环境提供）
    format: 厂商原始格式
    naming: 保持原样
    where_used: driver 通过 pyrealsense2 或官方 ROS 2 包访问相机

# --- 适配器 ----------------------------------------------------------------
driver:
  package: arm_driver_realsense
  executable: realsense_publisher
  build: colcon

# --- 能力声明 --------------------------------------------------------------
capabilities:
  - color
  - depth
  - aligned_depth_to_color
  - infrared_left
  - infrared_right
  - query_intrinsics       # 手眼标定必需
  - set_exposure

# --- 型号与角色 ------------------------------------------------------------
models:
  - id: d405
    label: D405 腕部相机
    roles: [wrist_eye_in_hand]
    default_resolution: "848x480"
    default_fps: 30
    notes: >
      腕部使用，必须关闭红外投射器（emitter_enabled: false），
      否则投射的红外点阵会污染跟踪图像。

  - id: d435
    label: D435 手外顶视相机
    roles: [overhead_eye_to_hand]
    default_resolution: "1280x720"
    default_fps: 30
    notes: >
      手外使用，通常需要开启红外投射器以提升无纹理表面的深度质量。
      当前尚未完成手眼标定。

# --- 配置项声明 ------------------------------------------------------------
config_schema:
  - key: model
    site_path: cameras[].model
    type: str
    required: true
    doc: >
      相机型号。必须与上面 models 列表里的某个 id 一致（d405 或 d435）。
      型号决定默认分辨率与是否应开启红外投射器。

  - key: serial
    site_path: cameras[].serial
    type: str
    required: true
    doc: >
      相机序列号。用 scripts/list_realsense.sh 查看当前接入的全部序列号并映射角色。
      每个角色必须是不同的序列号，否则两台相机抢同一台设备。

  - key: role
    site_path: cameras[].role
    type: str
    required: true
    doc: >
      相机角色，合法值: left_wrist | right_wrist | overhead_eye_to_hand。
      以 _wrist 结尾表示装在法兰上（眼在手上，手眼标定用 eye_in_hand）；
      overhead_eye_to_hand 表示固定安装（眼在手外，手眼标定用 eye_to_hand）。
      角色决定该相机参与哪条流程，所以必须与物理安装位置一致。

  - key: width
    site_path: cameras[].width
    type: int
    unit: px
    required: true
    doc: 彩色流宽度。注意 USB2 链路会自动降到 640 并告警。

  - key: height
    site_path: cameras[].height
    type: int
    unit: px
    required: true
    doc: 彩色流高度。注意 USB2 链路会自动降到 480 并告警。

  - key: fps
    site_path: cameras[].fps
    type: int
    unit: Hz
    required: false
    default: 30
    doc: 帧率。

  - key: auto_exposure
    site_path: cameras[].auto_exposure
    type: bool
    required: false
    default: true
    doc: 自动曝光。

  - key: ae_limit_us
    site_path: cameras[].ae_limit_us
    type: float
    unit: us
    required: false
    doc: >
      曝光上限。腕部 D405 建议限到 4000us 以内 —— 跟踪时曝光过长会导致运动拖影。
      0 表示不封顶。

  - key: emitter_enabled
    site_path: cameras[].emitter_enabled
    type: bool
    required: true
    doc: >
      红外投射器。腕部必须 false（投射点阵污染跟踪图像），
      手外通常 true（提升无纹理表面深度质量）。