collector/docs/ui.md

ui/

定位

ui/ 是 DAQ 桌面主程序的 PyQt5 界面层：主窗口把设备枚举面板、多画面网格、录制控制、录制历史、任务选择、上传与回放全部串成图形界面，后台数据链路（管线、数据库、网络服务）均由本层发起的对象持有并注入。界面层本身不写数据文件，持久化一律经 config.settings 与 core.* 完成。

被以下模块引用（证据）：

• main.py from ui.main_window import MainWindow —— 主入口（Qt-Material 暗色主题），构造并 show()。
• tools/tests/ 多个回归/冒烟测试直接构造界面类：exposure_control_test.py、device_panel_gui_smoke_test.py、grid_drag_fps_test.py、test_playback_multifps.py（还 import _get_effective_fps）、d435_playback_test.py、glove_widget_test.py 等。
• 包内互引：ui/main_window.py（CameraGrid/DevicePanel/ExposureDialog/LoginDialog/GuideDialog/PlaybackDialog/UploadDialog/TaskSelectionPage）、ui/playback_dialog.py（ZoomableVideoWidget、CameraGrid 及两个分割条常量）、ui/camera_grid.py 与 ui/glove_widget.py（CameraWidget）、ui/login_dialog.py（复用 ui/guide_dialog.py 的 VisibleCheckBox）。

注：磁盘上存在 ui/hand_model/ 目录，但其中只剩未跟踪的 __pycache__/（已删除 __init__.py、state.py 的编译残留），无任何源码 .py，故不列入文件清单（其源码已在开源准备提交 8ea2f44 的死代码清理中移除）。

文件清单

文件	一句话作用
ui/main_window.py	主窗口：任务/采集双页面栈、设备面板路由（UVC/D435/S80M/蓝牙统一开关）、录制控制、录制历史表、上传与回放入口
ui/camera_grid.py	嵌套 QSplitter 多画面网格容器：画面拖拽调位、分割条调大小、空状态提示
ui/camera_widget.py	单路画面控件：ZoomableVideoWidget（滚轮缩放/拖拽平移/双击还原）+ CameraWidget（信息条、FPS、状态灯、☀ 曝光按钮）
ui/device_panel.py	左侧设备检测面板：已连接设备统一分组列表（UVC/D435/S80M/手套/其他蓝牙），勾选开关、双击命名
ui/exposure_dialog.py	每设备曝光设置对话框（自动曝光开关 + 滑块，量程/单位语义由调用方注入）
ui/glove_widget.py	BLE 手套仿生手掌画面控件，直接嵌入主网格，录制数据经 pipeline.write_sensor 落盘
ui/login_dialog.py	启动/切换账号登录对话框：账号登录（对话框内同步校验）或游客登录，关闭窗口等价游客；结果经 choice()/server_url()/username()/cookies() 等访问器读取
ui/guide_dialog.py	使用说明窗口（首次启动自动弹出、帮助菜单重开；中英 HTML 模板；「不再显示」持久化到 QSettings）+ VisibleCheckBox 复选组件
ui/playback_dialog.py	录制回放对话框：统一网格同步播放全部视频 + 传感器渲染，深度槽识别、手部关键点叠加、批量删除
ui/pose_view_qt.py	夹爪位姿视图控件：QPainter 手绘的实时轨迹 + 世界坐标轴 + 跟随夹爪的体轴三箭头 + 夹爪模型（两张夹板按开合度张合）
ui/task_page.py	启动时的任务选择页：任务表（5 列，含「来源」）、新建/改名/删除本机任务、服务器地址/凭据输入、连接状态、进入采集
ui/task_create_dialog.py	本机任务对话框：新建（名称/目标段数/描述 + 实时校验）与改名（已有录制目录时禁止），错误码本地化
ui/upload_dialog.py	录制会话一键打包上传对话框
ui/__init__.py	空包标记（0 行）

各文件详解

ui/main_window.py

作用：应用程序主窗口，界面层中枢。组合页面栈（任务选择页 + 数据采集页）、CameraGrid 主网格、左侧 DevicePanel 设备面板（_device_dock：可拖宽/拖窄，带 Closable 故标题栏有 × 可收起；宽度与收起状态经 server_config.json 的 device_dock 段跨启动保持，恢复入口为「视图 ▸ 设备检测栏」/ Ctrl+D；只有用户明确收起（点 × / 走菜单）才记偏好，正常关窗与最小化不算收起）、底部日志 dock、右侧录制历史 dock、工具栏与菜单；启动时经 _show_login_flow 弹 LoginDialog 确定账号/游客身份，首次启动经 _show_guide 弹 GuideDialog 使用说明；持有 CameraPipeline、DeviceScanner、TaskService、UploadManager 与 core.device_manager.DeviceManager 注册表（_workers 为其 entries 别名）等核心对象并负责信号接线。所有设备的开启/关闭都经左侧面板开关按 core.device_manager.dispatch_toggle 分派到 _open_*/_close_* 系列方法：S80M 双目子进程 + 管道解析在 core.s80m_manager.S80MDeviceManager，D435 worker 生命周期与帧口径在 core.d435_manager.D435DeviceManager，手套以 BLE 引擎 + 渲染定时器运行。

模块级辅助与常量（v1.0.3 后多为 core 模块的兼容 re-export，离线测试直接 patch 这些名字）：

名称	签名要点	作用	返回/副作用
_realsense_short / _slot_base / _normalize_original	—	core.device_naming 的 realsense_short/slot_base/normalize_original 旧名兼容别名	同 core 定义
_LEGACY_CAM_NAMES	常量	旧录制记录的退化相机名（"多路录制"/"Multi-Camera"/""），历史表自愈判据	—
_STEREO_AVAILABLE	常量	core.s80m_manager.STEREO_AVAILABLE 别名（自包含双目模块 tools/stereo_s80m/read_stereo_rgb.py，内含 libfays_vikit.so 3.9.0 与 yaml，与外部 SDK 目录独立）	—
_D435_AVAILABLE / D435Worker / list_d400_devices	常量	导入 core.d435_camera 并缓存 d435_available()；导入失败全置 None/False（模块全局保留供离线测试 patch）	—
_HAND_PROC_AVAILABLE	常量	core.hand_processor.SessionHandProcessor + core.auto_labeler.AutoLabeler 可选导入结果	—
_GLOVE_AVAILABLE	常量	ui.glove_widget.GloveWidget 可选导入结果（依赖 bleak 子系统）	—

类/信号（class MainWindow(QMainWindow)）：

名称	签名要点	作用	返回/副作用
stereo_frame_ready	pyqtSignal(str, np.ndarray, object, list)	双目帧信号（FIFO 读取线程 → 主线程），参数 slot_id, frame, hardware_ns, imu_samples	连接到 _on_stereo_frame。★ 封送坑：hardware_ns 必须用 object——PyQt5 队列信号把 Python int 按 C++ qint32 封送，超过 2^31（约 2.1s 纳秒）会静默截断为负数，录制数据受害
log_message	pyqtSignal(str)	跨线程日志信号（后台线程 → 主线程 QTextEdit.append）	_log() 在非主线程时经此投递
_upload_session_deleted	pyqtSignal(str, str)	上传后自动删除线程 → 主线程，参数 (session_path, error_msg)	连接到 _on_upload_session_deleted

相机管理（设备开启/关闭全在此区）：

名称	签名要点	作用	返回/副作用
_auto_detect_cameras	()	工具栏「🔍 扫描」：立即请求一次设备扫描（接入统一走面板开关，不自动打开画面）	记日志；DeviceScanner.request_scan()
_teardown_all_workers	()	委托 core.device_manager.DeviceManager.teardown_all(close_fns) 按 kind 分类关闭全部已开启设备	清空注册表
_open_uvc / _close_uvc	(dev) -> bool / (dev_key)	UVC 面板开关：增量建槽（settings._camera_slot_name(dev.video_index)）/ 按注册表拆槽；条目经 DeviceManager.uvc_entry 创建	bool 成功与否
_open_s80m	(dev) -> bool	面板开关打开 S80M 双目：先注入静态标定（config/s80m_stereo_calibration.json → StereoCalibration.load），创建 stereo_left/stereo_right 两槽并注册外部帧源（fps=settings.STEREO_RECORD_FPS=30）；s80m_depth_available() 时追加第三格 stereo_depth（set_depth_camera，PNG16，v1.0.11），随后子进程/Popen/管道/watchdog/读线程全部交 core.s80m_manager.S80MDeviceManager.spawn	bool；与 D435 互斥（共用 video0/video2，后开者弹窗拒绝）
_on_stereo_frame	(slot_id, frame, hardware_ns=0, imu_samples=None)	主线程槽（S80MDeviceManager.frame_ready 转投）：显示帧直推画面；录制时按 core.s80m_manager.frame_record_decision（1/30s 桶）抽帧；IMU 仅随 stereo_left 落盘	pipeline.write_external_frame(...)
_on_s80m_depth	(slot_id, depth, hardware_ns=0)	S80MDeviceManager.depth_ready 槽：depth_to_heatmap（固定色标 + 中值滤波）→ 深度格显示；录制中 pipeline.write_depth	—
_close_s80m	(dev_key)	委托 S80MDeviceManager.close（停 watchdog → 关 stdin → terminate/kill → join 读线程 → 清理临时文件），再注销两路外部帧源、clear_depth_camera(stereo_depth)、移除 UI 控件、清除本设备标定	—
_open_d435	(dev) -> bool	面板开关打开 RealSense：按 serial 活体复查 list_d400_devices()（不信任导入期缓存）、按 serial 查重、与 S80M 反向冲突检查；槽名 = core.device_naming.allocate_slot_names 派生 {base}_rgb + {base}_depth，RGB 注册外部帧源、深度注册深度伪相机（set_depth_camera，热力图 MP4 + PNG16 双通道，raw_depth=True）；worker 创建/信号接线/启动交 core.d435_manager.D435DeviceManager.spawn	bool；S80M 已开时弹窗拒绝
_on_d435_frames	(slot_id, frame, hardware_ns=0, imu_samples=None, dev_key=None)	委托 core.d435_manager.D435DeviceManager.process_frame（深度槽 → 热力图显示 + write_depth；RGB 槽 → 显示 + write_external_frame；首帧后标定送进管线 calibration/head_stereo.json）	已关闭设备的迟到信号直接丢弃
_close_d435	(dev_key)	委托 D435DeviceManager.close（断信号 → stop → deleteLater）→ 注销外部帧源 + 清除深度伪相机 + 清除标定 → 移除双槽	—
_add_camera_slot	(slot_id, camera_index, backend="", label="")	UVC 建槽：管线 add_camera + 网格 add_camera + _connect_slot_signals	失败仅记日志
_connect_slot_signals	(slot_id)	单个 CameraSlot 信号 → UI 回调：frame_ready/state_changed/error_occurred/camera_opened/fps_updated，以及 widget 的 remove_requested/exposure_clicked	—
_remove_camera / _remove_camera_slot_no_confirm	(slot_id)	移除单槽（录制中先弹确认）/ 不确认版；若槽属于某面板开启设备则整机关闭（d435 移除双槽之一即整机关）并取消勾选	同步面板勾选与高亮
_remove_all_cameras	()	工具栏「✕ 全部移除」：确认后先 _teardown_all_workers() 再逐槽移除	清面板勾选/高亮集合

设备面板路由与曝光：

名称	签名要点	作用	返回/副作用
_device_label	(dev) staticmethod	DeviceInfo → 日志显示标签（用户命名优先，有 serial 时附 — serial）	str
_on_devices_scanned	(devices)	扫描结果（每 2s 轮询，settings.DEVICE_POLL_INTERVAL_MS=2000）：填用户命名 → DevicePanel.set_devices + 恢复勾选/高亮 → 插拔 diff 日志（只记变化）→ 录制中拔线暂存 _lost_device_keys 重插恢复勾选 → 已开启但已消失的设备逐个 _handle_active_device_lost	—
_handle_active_device_lost	(key)	已开启设备被拔出：录制中不自动移除（重插恢复），否则按 kind 关设备	—
_on_device_toggled	(dev, on)	面板 device_toggled 路由：委托 core.device_manager.dispatch_toggle（录制锁双保险 + kind 路由到 _open_*/_close_* 回调，多路并发，互不拆台）；打开失败回退勾选	维护 _active_device_keys
_on_device_renamed	(dev, name)	面板双击命名后：刷新插拔标签缓存与 worker 注册表标签	持久化已在面板完成
_show_exposure_button	(slot_id)	在设备的「主槽位」（S80M 左目、D435 的 RGB 槽）信息条显示 ☀ 按钮	—
_open_exposure_dialog	(slot_id)	☀ 入口：对话框参数口径在 core.exposure_controller.exposure_dialog_params（D435：worker 读回 µs 量程；S80M：1.0~885.0，decimals=1；UVC 无曝光入口固定自动曝光）；按类型弹 ExposureDialog	模态 exec_()
_apply_exposure	(dev_key, entry, auto, value)	委托 core.exposure_controller.apply_exposure（d435 → worker.set_exposure；s80m → _s80m_set_exposure 回调）并持久化（下次开启自动应用）	—
_s80m_set_exposure	(dev_key, auto, value)	委托 S80MDeviceManager.send_exposure（stdin 行协议 "SET_EXPOSURE <float>"，-1.0=自动曝光），SDK 运行时生效无需重启	BrokenPipe 时记日志
_set_exposure_buttons_enabled	(enabled)	录制锁：所有已显示的 ☀ 按钮随录制状态禁用/恢复	用 isHidden() 判断（窗口未 show 时 isVisible 恒 False）
_open_glove / _close_glove	(dev) -> bool / (dev_key)	手套开关：广播名 L/R → settings.assign_glove_sensor_role 优先绑左右手；创建 GloveWidget（slot=sensor:{key}）注入管线并 start(address)，pipeline.register_sensor(role)；关闭时停 BLE、撤画面、注销传感器列	bool
_open_ble_placeholder / _close_ble_placeholder	(dev) -> bool / (dev_key)	无数据蓝牙（耳机类）：主网格显示「该设备无可视化数据」占位画面	bool

录制：

名称	签名要点	作用	返回/副作用
_reset_s80m_record_state	()	委托 DeviceManager.reset_s80m_record_state：录制起止时重置 S80M 50→30 抽帧状态（last_bucket 桶号 + pending_imu 缓冲）	—
_build_device_meta	() -> list	委托 DeviceManager.build_device_meta：手套无画面槽附 sensor_column；uvc/d435/s80m 附 slots（及 serial）；无数据蓝牙不进 devices 段	list[dict]
_record_all	()	工具栏「⏺ 全部录制」：任务名取自所选任务；所选任务进度已满（completed_count >= total_required，本地 load_tasks() 计数）时弹窗阻止；否则 pipeline.start_recording(首个槽, task_name=..., batch_index=已完成数+1, device_meta=...)	—
_stop_all	()	「⏹ 完成录制」：pipeline.finish_recording("") + 重置抽帧状态	—
_abort_recording	()	「⛔ 异常终止」：pipeline.abort_recording("")（永久删除本次文件）	记日志、刷新状态栏

信号处理器（管线 → 控件）：

名称	签名要点	作用	返回/副作用
_on_slot_added / _on_slot_removed	(_slot_id)	空实现（控件已在 _add_camera_slot 中创建/移除）	—
_on_frame	(slot_id, frame)	UVC 帧 → 画面（settings.CAMERA_MIRROR_HORIZONTAL 时先水平镜像）	w.update_frame
_on_camera_state	(slot_id, state)	状态 → 指示灯 + 日志；CameraState.DISCONNECTED 时 pipeline.record_event(slot_id, "disconnected")，否则记 "connected"	—
_on_camera_fps	(slot_id, fps)	UVC 由 CameraWorker 自带的 fps 信号 → 标签	—
_note_frame_arrival	(slot_id)	记录一帧到达时刻（D435/S80M 无 CameraWorker，主窗口统一计 FPS）	写入 _fps_ring
_update_fps_labels	()	每秒刷新非 UVC 槽的 FPS（过去 1 秒到达帧数）	—
_on_recording_started	(slot_id)	录制开始：锁死设备面板开关 + 禁用曝光按钮 + 日志（含编码与任务名）	—
_on_recording_finished	(slot_id, session_path)	录制完成：解锁面板/曝光；core.helpers.session_summary(session_path, pipeline.last_recording_frames) 算摄像机列/时长/大小 → RecordingRecord 存库 → 刷新历史；increment_task_completed(实际任务名) 更新任务进度；自动上传入队（开关开启且该会话尚未 completed 时 _upload_manager.add_task）；HAND_TRACK_ENABLED 时延迟 500ms 自动处理手部关键点（silent）	—
_on_recording_aborted	(slot_id)	异常停止：解锁面板/曝光，取消手部后处理与标注	—
_on_duration	(_slot_id, seconds)	录制时长 → 状态栏	—

录制历史：

名称	签名要点	作用	返回/副作用
_refresh_history	()	RecordingRepo.list_all(limit=100) → 表格 5 列：摄像机/文件/时长/大小/状态；旧记录自愈：退化值（无大小、_LEGACY_CAM_NAMES 相机名、无时长）实时从磁盘 session_summary 补算并回写 DB；状态列按 completed/uploaded/uploaded_deleted 绿色（uploaded 含自愈兜底：completed 且目录仍在、上传任务表记为 completed 的旧行也显示「已上传」）、其余（已丢弃）异常色	启动时即加载

上传 / 回放入口：

名称	签名要点	作用	返回/副作用
_open_playback	()	「📂 回放」：PlaybackDialog(self, settings.RECORDING_DIR) 模态打开	—
_open_upload	()	「☁ 上传」：UploadDialog(self, settings.RECORDING_DIR, session=TaskService._session) 模态打开	—
_on_upload_task_done	(task_id)	自动上传完成：记日志；UPLOAD_DELETE_AFTER 开启时后台线程删本地目录，否则 RecordingRepo.mark_uploaded 标「已上传（本地保留）」并刷新历史	—
_delete_session_after_upload	(session_path, episode_index=0)	后台线程 delete_local_session（真删除 + 删除后校验，防大目录阻塞 UI），结果经 _upload_session_deleted 回主线程	—
_on_upload_session_deleted	(session_path, err)	删除收尾：失败（含校验残留）记日志；成功 RecordingRepo.delete_local_episode 真删录制行并刷新	—
_on_upload_task_failed	(task_id, error)	自动上传失败（重试 3 次后仍失败才触发）→ 日志	—
_on_upload_auto_toggled / _on_upload_delete_toggled	(on)	两个工具栏开关：settings.save_upload_auto_sync / save_upload_delete_after 持久化 + 运行时立即生效 + 按钮文字/样式刷新	—
_style_toolbar_toggle	(action)	开关类 QAction 按钮高亮样式（开启绿底白字加粗）	—

任务服务与页面切换：

名称	签名要点	作用	返回/副作用
_connect_task_service	()	TaskService 信号 ↔ TaskSelectionPage：tasks_updated/connection_status/login_result/identity_changed/identity_expired；任务页 refresh_requested→poll_now、switch_account_requested→_on_switch_account；错误首次出现只记一次（_last_task_error 判重）	轮询在身份确定后（_show_login_flow 末尾）才 start()
maybe_show_login / _show_login_flow	()	启动入口（main.py 调用）→ 登录流程：LoginDialog exec 后 save_server_url；账号登录成功经 TaskService.adopt_login 接管 cookie（save_remembered_username），否则 set_guest；同步 _upload_manager.server_url 与任务页 set_server_display 后 task_service.start()	—
_on_switch_account	()	任务页「切换账号」按钮 → 重开登录对话框	—
_on_identity_expired	()	登录态轮询遇 401/403 → 提示重登；关闭对话框（Esc）自动降级游客	—
_on_task_confirmed	(task)	选中任务进入采集页（index 1），更新窗口标题；不自动扫描，提示先选模式再点扫描	—
_on_page_changed	(index)	页面切换控制工具栏/dock 可见性；任务页停设备轮询，采集页立即扫描 + 启动 _device_timer（2s 轮询）；末尾统一调 _apply_device_dock_visibility（设备栏：任务页隐藏、采集页显示，但用户收起过就保持收起）	—
_go_back_to_task_selection	()	返回任务选择：录制中先确认（同意则 abort）；取消手部后处理/标注；_teardown_all_workers + 清网格 + 清面板状态；切回 index 0 并 poll_now() 刷新任务列表	—

其余（语言/视图/手部后处理/日志/退出）：

名称	签名要点	作用	返回/副作用
_on_language_changed	(lang)	中英文切换：菜单/工具栏/dock 标题/历史表头/手部模式下拉全部 tr() 重刷，并调 _task_page._on_language_changed	—
_reset_camera_sizes	()	视图菜单「重置画面大小」：grid._rebuild_layout() 等分	—
_apply_device_dock_visibility	()	设备栏可见性的唯一口径：当前页==1 且 用户未收起 → 先 _capture_device_dock_width（收起前记住栏宽）再 setVisible，显示且非浮动态才 resizeDocks 复原宽度；期间置 _device_dock_syncing 挡「程序化改动被当成用户收起」	末尾同步菜单勾选
_toggle_device_dock	(checked)	视图菜单「设备检测栏」/ Ctrl+D：置 _device_dock_user_hidden → 应用可见性 → 落盘	任务页只记偏好不显示
_on_device_dock_visibility	(visible)	设备栏可见性变化 → 同步菜单勾选 + 落盘（幂等）。不从可见性推断用户意图：关窗/最小化/切页都会让 dock 不可见，把它们当成「用户收起」会让每次正常退出都写坏偏好；_device_dock_syncing 置位时直接返回	用户收起只由 × 的 Close 认定（见 eventFilter）
_sync_device_dock_action	()	菜单勾选 = 用户是否想看设备栏（与当前页是否显示无关；blockSignals 防递归，C++ action 已删时吞 RuntimeError）	—
_save_device_dock_prefs	()	_capture_device_dock_width() 后 settings.save_device_dock_prefs(未收起, 栏宽)；写盘失败只丢一次偏好不抛异常（PyQt5 虚方法抛异常 = SIGABRT 134，会连带跳过停线程/拆 worker）	closeEvent 也调一次
_capture_device_dock_width	()	抓「此刻真实栏宽」：浮动态（width() 是浮动窗口宽）与不可见时直接返回。不跟随普通 Resize —— 窗口缩小/最大化时 Qt 会把 dock 压到最小宽，那不是用户拖出来的宽度	收起前 / 退出前各抓一次
eventFilter	(obj, event)	仅拦 _device_dock 的 QEvent.Close → 置 _device_dock_user_hidden=True + 抓栏宽，这是唯一认定「用户收起」的地方（点标题栏 × / 右键菜单关闭 / 浮动窗口关闭都走 close() 发 Close 事件；而主窗口关闭/最小化只发 Hide，不给 dock 发 Close —— 2026-10-13 实测）	其余事件走 super()
_update_status	()	状态栏：摄像机数（排除 sensor:/ble: 占位槽）+ 录制中标记与颜色	—
_process_hand_keypoints	(session_path="", silent=False)	后台提取手部关键点（SessionHandProcessor.process_session，mode 由手套/裸手下拉决定）；已有结果时弹确认（silent 模式跳过）；无路径用最近一条录制	—
_on_hand_proc_progress / _on_hand_proc_finished	(current, total) / (session_path, error)	进度 → 状态栏+按钮；完成后 300ms 自动触发 _auto_label（silent）	—
_auto_label / _on_auto_label_finished	(session_path="", silent=False) / (session_path, error)	基于关键点 parquet 自动生成手势标签（AutoLabeler.label_session）	—
_log	(msg)	时间戳日志：主线程直接 append，后台线程经 log_message 信号安全投递	—
_show_about	()	关于对话框（应用名/版本/功能简介）	—
closeEvent	(event)	安全退出：置 _shutting_down → 停轮询/扫描器 → 录制中 abort → 拆全部 worker → 移除全部槽 → 取消手部后处理 → 停 TaskService/UploadManager	accept

关键数据：

• _workers 设备注册表：DeviceManager.entries 的别名，key → {"kind": "uvc"|"d435"|"s80m"|"data_ble"|"ble", "slots": [网格槽位], "label": 日志标签}，另含 kind 专属字段（d435：worker/rgb_slot/depth_slot/near_mm/far_mm/smooth_k/temporal_alpha/heat_smoother/calib_sent/serial；s80m：proc/stdin/watchdog/reader_thread/stderr_file/config_file/original_exp/entry_depth/last_bucket/pending_imu；data_ble：sensor_column/glove）。
• 设备面板状态：_active_device_keys（勾选集合=UI 状态源）、_lost_device_keys（录制中拔线暂存）、_last_device_keys（key→标签，插拔 diff 日志）。
• FPS：_fps_ring（slot_id → 到达时刻 deque），1s 定时刷新。
• 历史表列名：摄像机 / 文件 / 时长 / 大小 / 状态。
• S80M 管道帧格式与曝光行协议见 core/s80m_manager.py，50→30 抽帧桶长 settings.STEREO_RECORD_MIN_INTERVAL_S。
• D435 槽名约定：RGB 槽 = 前缀 + _rgb，深度槽 = 前缀本身若以 _depth 结尾否则补 _depth；depth 后缀仅用于回放过滤，是否落盘由显式注册决定。
• meta 写入点：_build_device_meta() 产出 devices 段（key/kind/name/slots/serial/sensor_column）。

调用关系：被 main.py 构造。创建并持有：core.pipeline.CameraPipeline、core.device_detector.DeviceScanner、core.device_manager.DeviceManager、core.s80m_manager.S80MDeviceManager、core.d435_manager.D435DeviceManager、core.task_service.TaskService、core.uploader.UploadManager、core.recording_repository.RecordingRepo（静态调用）、ui 内全部其余组件。调用 core.d435_camera.D435Worker、core.stereo_depth.StereoDepthComputer/depth_to_heatmap/DepthHeatmapSmoother、core.calibration.StereoCalibration、core.task_record.load_tasks/increment_task_completed、core.helpers.session_summary/format_duration/format_size_mb/hand_kpts_parquet_path、core.device_naming/core.exposure_controller 口径；可选手部子系统 core.hand_processor.SessionHandProcessor、core.auto_labeler.AutoLabeler。

ui/camera_grid.py

作用：多画面网格容器 CameraGrid（继承 QScrollArea），把每路画面排进嵌套 QSplitter 布局；所有画面（相机 CameraWidget、回放传感器格、手套仿生手掌、占位画面）同格共存。提供两种交互：按住画面顶部信息条拖到另一画面上松手即互换位置（事件过滤器 + 鼠标抓取）；画面间的分割条加宽（8px）并带悬停/按住高亮，可拖动调大小。

类/函数：

名称	签名要点	作用	返回/副作用
add_camera	(slot_id: str, camera_name: str = "")	添加一个 CameraWidget 到网格	返回 CameraWidget
add_widget	(slot_id: str, widget: QWidget)	添加任意控件（手套仿生手掌/传感器格/占位等）；重复 slot_id 直接返回已有控件	返回 QWidget；触发重建布局
remove_camera	(slot_id: str)	移除指定控件：先 _end_drag() 复位拖拽状态（防抓取/光标残留），再 deleteLater()	触发重建布局
camera_widget	(slot_id: str)	按 slot_id 取控件	Optional[CameraWidget]
clear	()	移除所有画面	—
widget_count	() -> int	当前画面数量	int
slot_ids	() -> List[str]	全部 slot_id 列表（字典顺序即布局顺序）	list
eventFilter	(obj, ev)	拖拽手柄事件：顶部 DRAG_STRIP_H（32px）内按下左键→grabMouse 抓取 + 闭合手掌光标；移动→悬停目标高亮（DRAG_TARGET_BORDER）；松开→_swap_widgets 互换位置；双击信息条不触发缩放还原；带 _no_drag 属性的控件（曝光按钮、模式下拉等）直接放行	消费事件时返回 True
_rebuild_layout	()	按画面数重建布局：0 路=空提示文案（默认 i18n「尚未检测到摄像机…」，可 empty_text 覆盖）；1 路=填满；2 路=[A|B]；3 路=[A|B]/[C]；4 路=2×2；5+ 路按 ceil(sqrt(n)) 行列嵌套分割；初始等分	—
_install_drag_filter / _remove_drag_filter	(w)	给画面控件及其全部子控件装/卸事件过滤器（子控件才真正接收鼠标事件）	—
_root_widget / _in_drag_strip / _widget_at_global	辅助	事件来源控件沿父链找所属画面 / 判断全局坐标是否落在信息条内 / 命中画面	QWidget 或 None
_set_drag_hover / _swap_widgets / _end_drag	辅助	高亮悬停目标（恢复旧样式）/ 互换字典顺序并重建 / 释放抓取、还原光标与高亮	—

关键数据：

名称	值	说明
DRAG_STRIP_H	32	每画面顶部拖拽手柄信息条高度（像素）
SPLITTER_HANDLE_WIDTH	8	分割条宽度（被 ui/playback_dialog.py:29 复用）
SPLITTER_HANDLE_QSS	灰条 + 悬停/按住高亮	暗色主题下分割条可见性（被 ui/playback_dialog.py:29 复用）
DRAG_TARGET_BORDER	border:2px solid #4FC3F7	拖拽悬停目标边框高亮

调用关系：被 ui/main_window.py（主网格）、ui/playback_dialog.py（回放统一网格）使用；tools/tests/exposure_control_test.py、tools/tests/grid_drag_fps_test.py 直接构造。依赖 ui/camera_widget.py 的 CameraWidget 与 config.i18n.tr（空提示文案）。

ui/camera_widget.py

作用：单路画面的两个控件。ZoomableVideoWidget 是纯视频显示画布：接收 BGR np.ndarray 帧，内部 BGR→RGB 转 QImage.Format_RGB888（Qt x86 上 Format_BGR888 会红蓝互换），支持滚轮缩放（以鼠标位置为基准）、左键拖拽平移、双击还原、缩放百分比提示。CameraWidget 把视频画布 + 顶部覆盖条（名称、☀ 曝光按钮、FPS 标签、状态灯）组合成一路「画面」，供主网格与回放共用。

类/函数：

名称	签名要点	作用	返回/副作用
ZoomableVideoWidget.reset_view	()	还原缩放（1.0）与平移（0,0）	重绘
ZoomableVideoWidget.set_frame	(bgr_frame: np.ndarray, flip_vertical: bool = False)	传入 BGR 帧：可选上下翻转（摄像机视频需要，传感器渲染不需要），BGR→RGB 后存为 QPixmap	触发重绘
ZoomableVideoWidget.set_status_text	(text: str)	设置无画面时居中显示的文字（如「无信号」「已断开」）	清空画面
ZoomableVideoWidget.wheelEvent	(event)	滚轮缩放：1.08×/级，范围 0.25×~8.0×，以鼠标位置为基准调偏移，右下角短暂显示百分比	重绘
ZoomableVideoWidget.mousePressEvent / mouseMoveEvent / mouseReleaseEvent / mouseDoubleClickEvent	(event)	左键拖拽平移（闭合手掌光标）；双击 reset_view	—
CameraWidget（信号）	remove_requested(str) / exposure_clicked(str)	请求移除此摄像机 / 点击 ☀（主窗口按槽位所属设备弹曝光对话框）	由 MainWindow._connect_slot_signals 连接
CameraWidget.update_frame	(bgr_frame)	相机采集帧更新显示（flip_vertical=True 适配安装方向）	—
CameraWidget.update_fps	(fps: float)	更新 FPS: n 标签	—
CameraWidget.set_frame_number	(n: int)	回放用：信息条右侧显示当前帧号 #n（复用 FPS 标签位）	—
CameraWidget.set_camera_state	(state: str)	recording/error/disconnected/idle → 状态灯颜色与「已断开/等待中…」文字	—
CameraWidget.set_exposure_button_visible / set_exposure_enabled	(visible: bool) / (enabled: bool)	显示/隐藏 ☀（只对设备主槽位）；启用/禁用（录制中禁用，tooltip 随之切换）	—
CameraWidget._refresh_texts	(_lang="")	语言切换刷新文案	连接 lang_manager.language_changed
CameraWidget.resizeEvent	(event)	调整覆盖条宽度与位置	—

关键数据：

• ZOOM_MIN = 0.25、ZOOM_MAX = 8.0、ZOOM_STEP = 1.08。
• 覆盖条：固定高 28px、初始宽 260px（随 resize 收缩到 ≤300px），位于画面左上角；刻意不设 WA_TransparentForMouseEvents（会连 ☀ 按钮一起屏蔽），画面信息条拖拽由 CameraGrid 事件过滤器统一拦截。
• ☀ 按钮带 _no_drag 属性标记，CameraGrid.eventFilter 对按下直接放行（不触发拖拽/双击还原）。
• 注意：reset_view 在文件中定义了两次（第 74-78 行与第 109-113 行），后者覆盖前者，行为一致。

调用关系：被 ui/camera_grid.py、ui/glove_widget.py（GloveWidget 继承 CameraWidget）、ui/playback_dialog.py（ZoomableVideoWidget）使用。依赖 config.settings（FEED_MIN_WIDTH 等尺寸与颜色常量）、config.i18n.tr/lang_manager、core.helpers.format_duration（导入存在，当前代码未直接调用）。

ui/device_panel.py

作用：左侧停靠的设备检测面板。DeviceScanner（core/device_detector）每 2s 扫描的结果由 MainWindow._on_devices_scanned 调 set_devices 重建列表；三组展示（📷 相机 / 🧤 手套 / 🎧 其他蓝牙），「其他蓝牙」默认折叠、空组隐藏；每台设备带独立 QCheckBox，勾选发射 device_toggled(DeviceInfo, bool) 由主窗口路由到主网格显示；双击条目弹命名框并持久化到 device_names.json（此后每次连接显示用户命名）。

类/函数（class DevicePanel(QWidget)）：

名称	签名要点	作用	返回/副作用
device_toggled / device_renamed（信号）	pyqtSignal(object, bool) / pyqtSignal(object, str)	勾选变化（DeviceInfo, checked）/ 双击命名完成（DeviceInfo, new_name）	由 MainWindow 连接
set_devices	(devices: list)	blockSignals 下清空重建分组树；勾选状态由随后的 set_checked_keys 恢复；组展开状态跨重建保留	空列表显示「未检测到设备」占位
set_checked_keys	(keys: set)	按 key 集合静默勾选（不发信号）	—
set_checked	(key: str, on: bool)	程序化勾选单个（不发信号，供失败回退）	—
checked_keys	() -> set	当前勾选的设备 key 集合	set（开关状态=UI 状态源）
set_active_keys	(keys: set)	高亮正在显示中的设备（绿色前景），其余还原；空集合全还原	—
set_active_key	(key)	兼容旧调用：单 key 高亮（None 全还原）	—
set_locked	(on: bool)	录制中锁死全部开关（去 Qt.ItemIsEnabled，命名同步禁用）	—
key_for_kind	(kind: str)	列表中第一个 kind 匹配的设备 key	str 或 None
device_for_key	(key: str)	key → DeviceInfo（存在 Qt.UserRole）	DeviceInfo 或 None
key_for_serial	(serial: str)	按序列号找 key（多台 RealSense 时精确高亮）	str 或 None
key_for_video_index	(video_index: int)	第一个 video_index 匹配的设备 key	str 或 None
refresh_texts	()	语言切换刷新提示文字、组标题与占位项	—
_row_text	(dev) -> str	行文本 = 图标 + label（+ — serial）	—
_on_item_changed	(item, column)	勾选状态真正变化（用 _last_check 挡文字类变化与组标题）才发射 device_toggled	—
_on_item_double_clicked	(item, _column)	双击 → QInputDialog 命名 → settings.save_device_name(dev.stable_key, name) 持久化 → 更新行文本 + device_renamed；对话框打开期间列表可能已被 2s 轮询重建，必须用当前列表里的条目更新	—
gripper_recalibration_requested（信号）	pyqtSignal(object)	夹爪条目右键选「重新读取出厂标定」（v1.3.4）	由 MainWindow 连接
gripper_binding_requested（信号）	pyqtSignal(object)	夹爪条目右键选「读取/写入 Fays 绑定序列号」	由 MainWindow 连接
gripper_diagnostics_requested（信号）	pyqtSignal(object)	夹爪条目右键选「ESP32 串口诊断」	由 MainWindow 连接
_on_context_menu	(pos)	Qt.CustomContextMenu 回调：仅 dev.group == "gripper" 且非组标题/占位项才弹菜单（表驱动三项，顺序＝重读标定 / 配对序列号 / 串口诊断，顺序是契约的一部分，见 test_gripper_calibration_autogen.py §14）；_locked（录制中）时菜单项 setEnabled(False) 且选中后直接返回；按 chosen is action 判等，只弹不选不发信号	—
_refresh_hint_text	()	底部提示：有夹爪时追加「；右键夹爪可重读标定 / 配对序列号 / 串口诊断」	由 refresh_texts 调用

关键数据：

• _ICON = {"uvc": "📹", "d435": "🔭", "s80m": "👁", "data_ble": "🧤", "usb_glove": "🧤", "ble": "🎧", "gripper": "🤖"}；_GROUP_ORDER = ["camera", "glove", "gripper", "other_ble"]；_GROUP_TITLE 对应中文组标题。
• _items：device key → QTreeWidgetItem；_last_check：key → 上次勾选状态（防 itemChanged 误触发）；_group_expanded：组展开状态（初始 camera/glove 展开、other_ble 折叠）；_has_gripper：列表里是否有夹爪（决定底部提示是否提右键入口，两个分支都要更新，空设备分支需重置）。
• ⚠️ 面板内所有 QLabel 提示都必须 setWordWrap(True)：不换行的 QLabel，其 minimumSizeHint().width() 就是整行文字宽，会成为面板与停靠栏的硬地板。底部提示那句中文（「双击设备可重命名；右键夹爪可重读标定 / 配对序列号 / 串口诊断」）曾在夹爪在场时把栏宽地板顶到 289px，导致设备栏只能拖宽、拖不窄（2026-10-13 修）；面板另设 setMinimumWidth(settings.DEVICE_DOCK_MIN_WIDTH) 作为可拖到的最窄。回归哨兵见 tools/tests/device_dock_collapse_test.py。
• 命名持久化：config.settings.save_device_name（device_names.json）。

调用关系：由 ui/main_window.py 构造并连接 device_toggled/device_renamed/gripper_recalibration_requested/gripper_binding_requested/gripper_diagnostics_requested（信号名按字符串 connect，写错不会报错、只是永远不触发 —— tools/tests/test_gripper_esp_binding.py §9 静态比对两处名字）；tools/tests/device_panel_gui_smoke_test.py 直接构造。依赖 config.settings.save_device_name、config.i18n.tr。夹爪右键三条链路的完整链路（关夹爪 → 后台线程 → 完成后按原样开回）见 docs/core.md「夹爪」节与 ui/main_window.py 的 _on_gripper_recalibration / _on_gripper_binding / _on_gripper_diagnostics；三条共用 _gripper_offline_guard（序列号+录制检查）、_gripper_offline_take_over（让出串口）、_reopen_after_offline（善后）三件骨架。

ui/exposure_dialog.py

作用：每设备曝光设置模态对话框：自动曝光开关 + 曝光值滑块（内部统一 0..1000 刻度映射），拖动即时下发 apply_requested(auto, value)，勾选自动曝光立即生效。范围/值语义由调用方（MainWindow）按设备类型注入：UVC 是 V4L2 原始曝光值、D435/D405 是 µs（流启动后读 rs.option.exposure 量程）、S80M 是 SDK 曝光值 1.0~885.0（与 yaml stereo_init_exposure 同单位）。对话框只发参数不改持久化（持久化由主窗口统一处理）。

类/函数（class ExposureDialog(QDialog)）：

名称	签名要点	作用	返回/副作用
apply_requested（信号）	pyqtSignal(bool, float)	参数变化：apply(auto, value)（auto=True 时 value 忽略）	由 MainWindow._open_exposure_dialog 连接到 _apply_exposure
__init__	(parent, title, vmin, vmax, value, auto, decimals=0, original=None)	构造：自动曝光勾选框 + 0..1000 滑块 + 数值标签 + 「恢复默认」按钮（仅传入 original 时显示）+ 关闭	模态
_to_ticks / _from_ticks	(value) -> int / (ticks) -> float	曝光值 ↔ 0..1000 刻度线性映射	—
_fmt	(value) -> str	按 decimals 格式化数值标签	—
_on_auto_toggled	(checked)	自动曝光开关：禁用/启用滑块并立即 apply_requested.emit(checked, 当前值)	—
_on_moved / _on_released	(ticks) / ()	拖动中/松手时更新值并下发（auto 时忽略）	—
_on_reset	()	「恢复默认」：控件静默（blockSignals）回到「最一开始」曝光基线 (auto, value) 并下发一次	—

关键数据：_original = 设备首次开启、应用任何设置之前读回的 (auto, value) 基线（来源为 settings.device_original 或 worker 读回值，经 core.device_naming.normalize_original 归一化）。

调用关系：由 ui/main_window.py（_open_exposure_dialog）按设备类型构造并 exec_()；tools/tests/exposure_control_test.py 直接构造。依赖 config.i18n.tr。

ui/glove_widget.py

作用：BLE 手套仿生手掌画面控件（继承 CameraWidget，复用其覆盖条），直接嵌入主网格，替代旧的底部传感器 dock。面板开关打开手套后由主窗口创建；内部持有 core.ble_engine.SensorBLEEngine，30ms 渲染定时器处理一帧数据并用 core.render_engine.render_hand 画成 BGR 帧显示；录制中数据经 pipeline.write_sensor 写入 parquet 对应传感器列。

类/函数（class GloveWidget(CameraWidget)）：

名称	签名要点	作用	返回/副作用
__init__	(slot_id, address, sensor_column, label="", parent=None)	固定 _RENDER_W=1280×_RENDER_H=720 画布；左/右手套配置由 core.sensor_hand_config.load_sensor_hand_config(sensor_column) 加载（左/右不同配置文件）；启动 30ms 渲染定时器	—
start	(address: str = "")	连接 BLE 设备（懒创建引擎并连接 connected/disconnected/fps_updated/calibration_progress/error_occurred 信号）	画面显示「连接中…」
stop	()	断开连接、停止渲染	画面显示「已断开」
set_pipeline	(pipeline)	主窗口注入/清除当前录制管线引用	—
_on_connected / _on_disconnected	(addr) / ()	连接状态 → 画面文字 + pipeline.record_event(sensor_column, "connected"/"disconnected")	—
_on_error	(msg)	引擎错误显示到画面状态栏（失败原因不再只有控制台可见）	—
_on_fps	(fps)	硬件 FPS 显示到信息条（HW: n）	—
_on_calib_progress	(progress)	校准进度显示（校准中… n% / 校准完成）	—
_render_tick	()	定时器触发：engine.process_frame() 拿一帧；录制中 pipeline.write_sensor(processed, capture_ts, sensor_name=sensor_column)；render_hand(...) 渲染并传给画面（逻辑平移自旧 SensorPanel）	—
_display_frame	(frame)	渲染帧叠加传感器名 + 硬件 FPS + 数据帧龄（Age: n ms，按 <100/<300ms 绿/黄/红）	—

关键数据：

• 渲染配置常量 CONFIG_FILE/CONFIG_FILE_LEFT 定义在 core.render_engine（指向 config/sensors/hand_ble_config.json 与 hand_ble_config_left.json）；加载与合并口径在 core.sensor_hand_config.load_sensor_hand_config。
• _current_vmax 初始 5000.0，跨帧回传保持色标稳定。

调用关系：由 ui/main_window.py（try/except 可选导入）在 _open_glove 中创建。依赖 core.ble_engine.SensorBLEEngine、core.render_engine、core.sensor_hand_config、ui.camera_widget.CameraWidget；tools/tests/glove_widget_test.py import 本模块做自检。

ui/login_dialog.py

作用：登录对话框——启动时（或任务页点「切换账号」）弹出，确定会话身份。账号登录在对话框内同步校验（TaskService.verify_credentials，独立 requests.Session，≤8s），失败就地提示可重试，成功后携带 auth cookie 返回；游客登录直接进入（仅见公共任务）；关闭窗口（Esc/X）等价游客——后端不可达时不把用户锁死在启动页。

类/函数（class LoginDialog(QDialog)）：

名称	签名要点	作用	返回/副作用
choice	() -> str	结果："login"（点登录且校验成功）或 "guest"（游客/关闭窗口）	str
server_url	() -> str	地址输入框内容；空则回退 settings.SERVER_URL	str
username / password	() -> str	账号/密码输入框内容	str
remember_checked	() -> bool	「记住账号」勾选状态	bool
cookies	()	登录成功后的 auth cookie（失败/游客为 None）	cookie 或 None
_on_login_clicked	()	空用户名就地提示；同步校验（按钮置「登录中…」防误以为卡死），成功记 cookie 并 accept，失败 _show_error	—
_on_guest_clicked	()	choice="guest" 并 accept	—

关键数据：表单回填——服务器地址（与出厂默认相同则不回填、以 placeholder 显示）、用户名（settings.load_remembered_username）；错误提示仅登录失败时显示。

调用关系：由 ui/main_window.py（_show_login_flow）构造。依赖 config.settings、config.i18n.tr、core.task_service.TaskService.verify_credentials、ui.guide_dialog.VisibleCheckBox。

ui/guide_dialog.py

作用：使用说明窗口——首次启动自动弹出（guide/shown_once 未置位，或环境变量 DAQ_SHOW_GUIDE=1 强制），也可从菜单 帮助 → 使用说明 随时重开；「下次启动不再自动显示」勾选持久化到 QSettings（guide/dont_show，取消勾选即恢复自动弹出；每次关闭按当前勾选落盘并 sync() 立即写盘）。正文为整段 HTML 使用步骤（登录 → 设备 → 录制 → 回放 → 上传），按当前界面语言选择 GUIDE_HTML_ZH/GUIDE_HTML_EN 模板，与根目录 使用说明.md 内容一致。

类/函数：

名称	签名要点	作用	返回/副作用
guide_html	() -> str	按 lang_manager.current 返回当前语言的 HTML 正文	str
VisibleCheckBox	(QCheckBox)	暗色主题下勾选指示不明显：指示框加显式描边/填充，勾选时自绘白色 ✓（login_dialog.py 复用）	—
GuideDialog	(parent=None)	760×640 对话框：标题（APP_NAME + 版本）、QTextBrowser 渲染 HTML、底部 VisibleCheckBox + 「关闭」	—
dont_show_checked	() -> bool	供调用方持久化「下次不再显示」	bool

调用关系：由 ui/main_window.py（_show_guide，惰性 import）构造；VisibleCheckBox 被 ui/login_dialog.py 复用。依赖 config.settings、config.i18n。

ui/playback_dialog.py

作用：本地录制回放对话框。左侧会话列表（多选、按上传状态筛选、批量移入回收站），右侧复用 CameraGrid 的统一网格：摄像机格与传感器格同格共存，可拖拽调位、分割条调大小；底部播放控制（播放/暂停、逐帧、进度条、倍速 0.25~4×、手部关键点叠加开关、追踪模式、提取关键点）。时间戳对齐经 Parquet 统一时间线（frame_idx 与 timestamp_us）；会话加载（parquet 合并 + 手部关键点）全部放后台线程，视频打开与播放留在主线程（OpenCV FFmpeg 后端不承诺跨线程安全）。

模块级：

名称	签名要点	作用	返回/副作用
_get_effective_fps	(info: dict) -> float	core.session_catalog.get_effective_fps 的兼容别名（离线测试仍按旧名 import）	float

类/函数：

名称	签名要点	作用	返回/副作用
SessionLoader	(parent=None) QObject	core.session_loader.SessionLoader re-export：后台加载器，parquet 读取全在 worker 线程，loaded(str, object, int) 携带 {"timeline": SensorTimeline, "hand_kpts": dict}；load(session_dir, gen) 已有加载在跑时排队（新请求覆盖旧请求，过期结果被 gen 丢弃）；cancel() 取消	信号 loaded/failed(int, str)
PlaybackSensorWidget	(sensor_name, title="", parent=None) QFrame	单路传感器回放格：标题 + 模式下拉（🔥 热力图/📝 轨迹/📊 网格/🦾 仿生手掌/🕸 形变网格，默认仿生手掌）+ ZoomableVideoWidget + TS 标签；头部行 ≈32px 与网格拖拽手柄区对齐，mode_combo/ts_label 标 _no_drag 放行点击	—
PlaybackDialog._toggle_fullscreen	()	F11 切换全屏（QShortcut WindowShortcut 上下文，任意子控件聚焦时可用）	—
PlaybackDialog._rebuild_grid	()	按当前会话重建统一网格：先摄像机格（双目四路 stereo_left/right + _aux 保持 2×2 特殊排列），后传感器格（slot_id=sensor:{name}，与主窗口手套格约定一致）；摄像机格隐藏状态灯	—
_browse_dir / _refresh_list	()	选择录制目录 / 重建会话列表（core.session_catalog.list_sessions；每项含上传状态图标 ✅/❌/⬜、路数、FPS、时长、任务 tag）	—
_on_session_clicked	(item)	点击会话 → _load_session(path)	—
_filter_by_upload	(uploaded: bool)	「⬆ 选中已上传」/「⬇ 选中未上传」：按 UploadManager.get_upload_status 勾选	—
_delete_selected	()	勾选会话移入回收站：先停播并释放全部 cv2.VideoCapture 句柄（否则 Windows 阻止删除）+ 强制 GC；core.helpers.send_to_recycle_bin 逐个移入	可逆
_load_session	(session_dir)	加载会话：主线程同步读元数据（core.session_catalog.load_session_meta：格式探测 → EgoData metadata.json 或 meta/info.json；传感器列表读 info["sensors"]，无则从 info["features"] 的 observation.* 键推断，最旧格式回退 ["state"]）；parquet 合并 + 关键点交 SessionLoader 后台加载	—
_on_session_loaded	(gen, payload)	主线程槽：过期 gen 丢弃；过滤幽灵传感器列（时间线中确有 16×16=256 宽压力矩阵的才留，防 observation.imu 等非手套特征被误判）；打开每路 MP4（深度槽取 depth/<slot>/<slot>.mp4）；用户命名叠加（device_names + devices 段 slots/sensor_column → name）；算主时钟（info fps → 视频实际 fps → 全局兜底）、每路总帧数；重建网格、_seek(0)	—
_on_session_load_failed	(gen, error)	后台加载失败 → 信息标签	—
_toggle_play / _stop	()	播放/暂停切换；_stop 也用于切会话前收尾	—
_tick	()	定时器推进：按真实流逝时间补帧追赶（主线程被 seek/渲染拖慢时保持原速）；到末尾自动停	—
_prev_frame / _next_frame	()	逐帧进退	—
_seek	(idx: int)	主时钟帧号 → 每路帧号（t_s × fps_i 四舍五入，低帧率路按比例抽帧）；小步前进（≤5 帧，定时器抖动/追赶所致）顺序 read() 到底（每帧 1-2ms），随机大跳（拖进度条）才 set+read seek（43-89ms/路）——小步也 seek 会因 seek 耗时把追赶 steps 推大形成死亡螺旋（HEVC B 帧 seek 更贵）；随后 _update_sensor + 时间标签	—
_on_slider_pressed / _on_slider_moved / _on_slider_released	(value)	拖动中不 seek（每秒数十个 move 事件 × 单次 90-180ms 会卡死），松手单次 seek；点击滑槽未拖动也跳到点击处；原在播则恢复播放	—
_set_video_frame	(slot_id, frame, frame_num)	一帧显示到摄像机格 + 帧号 #n；可选手部关键点叠加（draw_kpts_overlay）；MP4 帧录制时已 np.flip(axis=0) 过，回放不再翻转	—
_on_sensor_mode_changed	(sensor_idx, mode_idx)	切换传感器可视化模式（heatmap/trace/grid/hand/deform），trace 时 clear_trace_canvas()，vmax 重置 5000.0	—
_update_sensor	(frame_idx, t_s=0.0)	渲染全部传感器：多帧率混合会话按主时钟时间二分（nearest_for_column_time），帧率一致会话走帧号二分（nearest_for_column，时间戳含暂停负跳变时更稳）；16×16 矩阵按模式调 render_heatmap/trace/grid/hand/deform_mesh；TS 标签显示传感器时间戳与 Δ（ms/帧）	—
_cycle_speed	()	倍速循环 0.25/0.5/1/2/4×，播放中即时改定时器间隔	—
_toggle_hand_overlay	(checked)	手部关键点叠加开关 → 重刷当前帧	—
_process_current_kpts / _on_hand_proc_finished	() / (session_path, error)	对当前会话后台提取手部关键点（主线程延迟创建 SessionHandProcessor 保证信号正常）；完成后 kpts-only 重载（load_timeline=False）	—
closeEvent	(event)	置 _closing（迟到 loader 回调丢弃）、取消手部处理、停播、释放全部 VideoCapture	—

关键数据：

• 深度槽判定（_on_session_loaded）：cameras[slot] 的 type == "depth" 或槽名以 _depth 结尾（槽名约定与主窗口 _open_d435 一致）；深度槽仅当其热力图 MP4（depth/<slot>/<slot>.mp4）存在时加入回放列表。
• 双目四路特殊排序：_STEREO_IDS = {"stereo_left", "stereo_right", "stereo_left_aux", "stereo_right_aux"} 四路齐备时按固定顺序排列。
• 传感器状态列表：_sensor_modes/_sensor_vmax_list/_sensor_mesh_states/_sensor_widgets/_sensor_ts_labels/_sensor_hand_configs/_sensor_cells 按 info["sensors"] 动态创建。
• meta 字段读取点：cameras[].fps、cameras[].type、sensors、features、device_names、devices[].slots/sensor_column/name/kind、task_name、fps（info["fps"] 兜底）；EgoData 会话的 devices 全量段在 metadata.json、device_names 在 meta/info.json，两处合并读。
• 会话列表项把上传状态存在 Qt.UserRole + 1。

调用关系：由 ui/main_window.py（_open_playback）构造；tools/tests/test_playback_multifps.py、tools/tests/d435_playback_test.py 直接构造。依赖 core.session_timeline.load_timeline/SensorTimeline、core.session_catalog（fps/扫描/元数据）、core.session_loader.SessionLoader、core.render_engine 五种渲染器与 CONFIG_FILE/CONFIG_FILE_LEFT、core.sensor_hand_config、core.helpers 路径与扫描函数、core.uploader.UploadManager.get_upload_status；可选手部叠加来自 core.hand_tracking。

ui/pose_view_qt.py

作用：夹爪位姿视图控件（QWidget 子类），挂在采集页网格的 pose 槽里，把夹爪的实时 SLAM 位姿画成一幅三维示意：轨迹折线（跟随夹爪累计的点）、世界坐标三箭头（固定在原点）、跟随夹爪的体轴三箭头（画的是发布姿态的三列），以及夹爪模型（两块夹板按 set_grip_state 的开合度张合）。视角可用鼠标拖拽旋转、滚轮缩放、双击复位，视野在轨迹走近边缘时自动扩张。

模块级常量：

常量	值	说明
DISPLAY_TRAJECTORY_MAX_POINTS	6000	显示上限（原 400 太小，见 docs/postmortem_trajectory_and_rgb.md）；超出按 2 的幂翻倍 stride 抽稀
TRAJECTORY_UPDATE_MIN_INTERVAL	1/25 秒	轨迹重算节流（位姿本身不受影响）
SPAN_EXPAND_TRIGGER / SPAN_EXPAND_TARGET / SPAN_EXPAND_ANIM_SECONDS	0.85 / 1.35 / 0.3	视野自动扩张的触发比、目标比、动画时长
AZIMUTH_DEFAULT / ELEVATION_DEFAULT	-150° / 30°	初始视角
BG / TITLE / TRAJECTORY / PLATE_GRIP / PLATE_OPEN / CONNECTOR / CAM_ORIGIN	暗色主题配色	背景、标题、轨迹、合拢/张开夹板、连接件、相机原点
WORLD_AXES / CAM_AXES	颜色 + 轴名	世界三箭头与跟随夹爪三箭头的配色（WORLD_AXES 的标签恰好是 ["X","Y","Z"]，被测试断言）
_BODY_RELABEL	帧 id → 换基矩阵	见下：新帧 = M，旧帧 = 单位阵；把模型顶点从旧体轴搬到新体轴
TITLE_TOP	2.0	画布上两行字（标题、坐标帧）的顶；行高取字体实测高度不写死像素（写死会裁掉中文笔画，而帧那行正是「一眼确认改没改」的入口）

★ 坐标帧契约（v1.3.13）：发布侧 core/gripper/slam/protocol.py 给位姿做了两次左乘 + 一次右乘（右乘 = 体轴改名），本控件是那个契约的另一半：

• _draw_frame_axes 画的是 rotation 的三列（= 夹爪体轴），不是三行。同一张 M 也在发布侧给体轴改了名，所以重新锚定那一瞬发布姿态 = M·Mᵀ = 单位矩阵，跟随夹爪的三箭头与世界三箭头重合，标签同写 下/左/前。
• _draw_gripper 用 _BODY_RELABEL（与发布侧同一张 M）把模型顶点从旧体轴坐标搬到新体轴坐标，于是 position + R·(M·v) == position + R_旧·v，夹爪的物理朝向与画面逐像素与改前相同（该恒等式对任意 R、v 代数上精确成立 —— M·R·Mᵀ·M·v = M·R·v，因为 MᵀM = I；渲染侧由 test_pose_view_qt.py::check_gripper_model_frame_invariant 逐像素钉住）。★式中的 R_旧 是改前那次发布的姿态（已含发布侧左乘的 M），不是夹爪自己的相对姿态 R_rel —— 拿 R_rel 代进去会差一个 M，算出"夹爪歪了 0.3–0.4 m"的假警报；对照：两处都改时残差只在浮点噪声量级，只改一半就是 0.3–0.4 m 的实偏差。
• 后果：只改发布侧不改这里（或反过来）夹爪会被画歪 120°，而两种改法各自都"看起来自洽"——别只动一处。测试见 tools/tests/test_pose_view_qt.py。
• 三箭头的轴名来自 config.settings.GRIPPER_SLAM_FRAME_AXES_CN，不自己抄（屏幕上的字与落进 info.json 的 frame_axes 必须同源）。

关键方法：

方法	签名	说明
update_pose	(position, rotation, trajectory=())	主入口：更新位姿与轨迹，节流重算
set_grip_state	(percentage, gripped)	夹板开合度与抓取态（决定配色 PLATE_GRIP/PLATE_OPEN）
set_localization_backend / reset	(backend) / ()	标题栏后端标注 / 清空轨迹与视角（换夹爪、重新录制时调）
paintEvent / _draw_static	—	全部绘制走 QPainter；静态层（世界轴、模型）进缓存，只有轨迹逐帧重画

调用关系：由 ui/main_window.py:1616 惰性 import 后构造（pose_view = PoseViewQt()），放进该夹爪的 entry["pose_view"]；位姿经 _on_gripper_pose → update_pose，抓取态经 set_grip_state，reset() 在换设备/重录时调。tools/tests/test_pose_view_qt.py 直接构造并离屏渲染（QT_QPA_PLATFORM=offscreen）。依赖 PyQt5、config.settings（GRIPPER_SLAM_FRAME_AXES_CN 等）、numpy。lite 包里没有本控件（lite 不含位姿视图）。

ui/task_page.py

作用：启动时显示的任务选择页（页面栈 index 0）。顶栏只读显示服务器地址（set_server_display）与当前身份，附「切换账号」「＋ 新建任务」「🔄 刷新」按钮；中部任务表（5 列，含「来源」），底部「→ 进入采集」「✏ 改名」「🗑 删除」。任务数据来自 data/tasks.json（core.task_record.load_tasks），后端任务经 merge_backend_tasks 合并，并 set_identity 按身份过滤（游客仅见公共任务）；用户选中任务点「进入采集」发射 task_selected(dict)，主窗口切换到数据采集页。

采集端自建任务：顶栏「＋ 新建任务」打开 TaskCreateDialog，落库为 source="local"（id 前缀 local-、created_by 记当前身份）。本机任务仅创建者可见（过滤在 core.task_record.filter_by_identity），进度只在本机累计、不上报服务器；「来源」列显示「本机」，服务端任务显示「服务端」。本机任务可「✏ 改名」（已有录制目录时拒绝）与删除（真删数据 + remove_local_task 整条移除，无 hidden 墓碑）；服务端任务删除仍走 mark_hidden 墓碑。

模块级：

名称	签名要点	作用	返回/副作用
_compute_status	(task: dict) -> str	按 total_required/completed_count 算状态：pending/in_progress/completed	str
_tid	(task: dict) -> str	取任务 id（id 或 task_id）	str
_format_date	(iso_str: str) -> str	日期截取前 10 字符	str

类/函数（class TaskSelectionPage(QWidget)）：

名称	签名要点	作用	返回/副作用
task_selected / refresh_requested / switch_account_requested（信号）	pyqtSignal(dict) / pyqtSignal() / pyqtSignal()	点击「进入采集」/ 点击「🔄 刷新」/ 点击「切换账号」	由 MainWindow._connect_task_service 连接
update_tasks	(tasks: list[dict])	后端任务列表到达：merge_backend_tasks 合并（空则回退本地 load_tasks）→ 重算状态 → 重建表	—
update_task_progress	(task_id: str, completed_count: int)	录制完成回写进度：refresh_progress() 后按 _tid 找行刷新	—
set_connection_status	(connected: bool)	更新连接圆点与「后端已连接/未连接」文案	—
on_login_result	(ok: bool, msg: str)	登录结果反馈（登陆成功 / 登陆失败: msg[:30]）	—
set_identity	(identity: str | None)	更新当前身份（"guest" 或用户名）并即时按新身份重滤任务表（含本机任务可见性）	—
set_server_display	(url)	更新顶栏服务器地址显示与 tooltip（登录对话框改地址后由主窗口调用）	—
current_task	() -> dict | None	当前选中行任务	dict 或 None
_on_cell_changed	(row, _col, _pr, _pc)	选行联动：completed 任务禁用「进入采集」；本机任务才启用「✏ 改名」，任一选中行启用「🗑 删除」	—
_on_double_clicked / _on_enter_clicked	()	双击行=快捷进入；进入前 completed 任务弹警告	发射 task_selected
_on_new_task_clicked	()	打开 TaskCreateDialog（传入当前身份）→ create_local_task → _refilter → 选中新行；校验失败弹「创建失败」	写 tasks.json
_on_rename_clicked	()	仅本机任务：打开 TaskRenameDialog → rename_local_task → _refilter → 保持选中；失败弹「改名失败」	写 tasks.json
_select_task_by_id	(task_id) -> int	按 id 选中行（新建/改名后保持选中）	行号或 -1
_task_error_message	(code) -> str	TaskValidationError.code → 本地化弹窗文案（has_data/name_too_long 补默认参数）	str
_do_delete_task	()	删除任务（按钮与右键菜单共用）：二次确认后 delete_local_session 真删该任务录制目录 + RecordingRepo.delete_local_dir 删录制行；本机任务调 remove_local_task 整条移除，服务端任务调 mark_hidden 留墓碑 → 重载列表；目录没删净则弹错并不删除任务。删除目标先做兜底校验（必须是 RECORDING_DIR 的直接子目录）——_sanitize_tag 把纯空白任务名清洗成空串后 task_dir_of 会退化成 RECORDING_DIR 本身，不拦就会把所有任务的录制整根 rmtree	—
_refresh_after_delete	()	删除后重载列表并清空选中态（三个操作按钮禁用）	—
_on_context_menu	(pos)	右键菜单：服务端任务只有「🗑 删除任务」，本机任务多一项「✏ 改名任务…」；先 setCurrentCell 到右键行，避免操作落到之前选中的别的任务	—
_on_refresh_clicked	()	发射 refresh_requested，按钮 1.5s 内显示「刷新中…」禁用	—
_on_language_changed	(lang)	5 列表头/按钮文字（新建/改名/删除等）刷新并重建表	—

关键数据：

• 表格 5 列：任务名称 / 来源 / 状态 / 进度 / 发布时间（_COL_NAME=0、_COL_SOURCE=1、_COL_STATUS=2、_COL_PROGRESS=3、_COL_DATE=4；列宽 90/150/110/130）。来源列「本机」绿色、「服务端」灰色；状态列用彩色方块+文字的 badge（_STATUS_CONFIG：pending 灰 #757575、in_progress 蓝 #42A5F5、completed 绿 #66BB6A）；进度列 completed/total 右对齐；名称 tooltip 显示描述。
• 身份与地址：服务器地址/记住账号由 LoginDialog 校验后经 MainWindow._show_login_flow 写入（settings.save_server_url / save_remembered_username）；登录态 cookie 由 TaskService.adopt_login 接管；身份过滤 scope 经 _identity_scope() 传给 core.task_record。

调用关系：由 ui/main_window.py 构造；任务服务信号在 _connect_task_service 中双向接线。依赖 core.task_record（load_tasks/merge_backend_tasks/refresh_progress/mark_hidden/is_local_task/create_local_task/rename_local_task/remove_local_task/TaskValidationError）、ui.task_create_dialog、config.settings、config.i18n。

ui/task_create_dialog.py

作用：本机任务对话框（v1.3.16）。TaskCreateDialog 采集「任务名称 + 目标段数 + 描述」，TaskRenameDialog 只改名称；两者都做实时校验并在对话框内拦住非法输入。落盘由调用方（ui/task_page.py）经 core.task_record 完成，本模块不写文件。名称规则与 core.task_record.validate_task_name 一致：只允许字母/数字/汉字/下划线/连字符（空格、点、斜杠等一律拒绝），去首尾空白后 ≤64 字符，拒绝 Windows 保留名与重名；因此任务名 = 录制目录名 = 上传会话/项目名。新建时显示本机目录预览与「仅当前身份可见」提示；若同名目录已存在（无任务记录的孤儿目录）给出追加录制警告（允许创建）。改名时若本机已有录制目录则禁用确认按钮并说明原因（改名不迁移数据）。

模块级：

名称	签名要点	作用	返回/副作用
_ERROR_TEXT	dict	错误码 → 中文源文案（缺失键回退「操作失败：code」）	—
task_error_text	(code, *args) -> str	错误码经 tr() 本地化（英文文案在 config/i18n.py）	str
_identity_display	(identity) -> str	"guest" 显示「游客」，其余原样	str
_label / _cancel_button / _ok_button	控件工厂	与 LoginDialog 一致的深色样式	控件

类/函数：

名称	签名要点	作用	返回/副作用
TaskCreateDialog	(parent=None, identity="guest")	新建任务对话框；exec_() 后 name()/total_required()/description() 取值	—
_validate	() -> str	名称/段数/描述校验，返回错误码（空串=通过）	str
_refresh_state	()	实时刷新目录预览、错误/警告行、创建按钮可用性	—
accept	()	再次校验后 QDialog.accept()（非法输入不关闭）	—
TaskRenameDialog	(parent=None, task=None)	改名对话框；new_name() 取值；本机已有录制目录时 _has_data=True 禁止确认	—
_refresh_state / accept	()	校验新名称与目录占用，重复/非法/已有数据时保持打开	—

调用关系：仅被 ui/task_page.py 构造；依赖 core.task_record（校验/常量）、core.helpers（task_dir_of/list_task_episodes）、config.settings、config.i18n。

ui/upload_dialog.py

作用：录制数据一键上传对话框：顶部服务器地址 + 「测试连接」（core.api_client.APIClient.health_check），中部会话列表（多选、全选、按上传状态筛选），底部进度条与状态栏。「⬆ 一键上传」把勾选会话入队 UploadManager（复用已认证的 requests.Session）；每项成功后遵循「上传后自动删除」开关：开启时后台线程删本地目录并把 recording 记录标记为 uploaded_deleted，否则标 uploaded（本地保留）；成功/失败结果均经 _parent_log 写进主窗口日志面板（与自动上传同一口径）。

模块级：

名称	签名要点	作用	返回/副作用
（无）	—	会话扫描用 core.session_catalog.list_recordings（轻量版，不读元数据）	按名称倒序

类/函数（class UploadDialog(QDialog)）：

名称	签名要点	作用	返回/副作用
_session_deleted（信号）	pyqtSignal(str, str)	后台删除线程 → 主线程：(session_path, error)	连接 _on_session_deleted
__init__	(parent=None, data_dir="", session=None)	session 为复用已认证的 requests.Session；QTimer.singleShot(50, _init_manager) 延迟建 UploadManager（读 _url_edit 当前值）	—
_refresh_list	()	重建会话列表：每项图标按 UploadManager.get_upload_status（✅ completed / ❌ failed / ⬜ pending），默认勾选未完成项；「全选」用 blockSignals 复位防 _toggle_all 连锁	—
_on_item_clicked	(item)	点击整行切换勾选（不必精确点复选框）	—
_toggle_all	(checked)	全选/全不选	—
_filter_uploaded	(uploaded)	「⬆ 选中已上传」/「⬇ 选中未上传」	—
_test_connection	()	APIClient(url).health_check() 弹结果框	—
_start_upload	()	勾选会话（过滤不存在的目录）_manager.add_tasks(valid) 入队并 start()；_task_path_map 记 task_id → session_path；禁用上传按钮	—
_on_status	(task_id, msg)	串行处理时状态栏显示「第 x/y 条 [会话名] 当前动作」	—
_on_progress	(task_id, ratio)	总进度 =（已完成数 + 当前比例）/ 总数	进度条
_on_task_done	(task_id)	单条完成：刷新列表；UPLOAD_DELETE_AFTER 开启时 _delete_after_upload（与主窗口自动上传同规则），否则 RecordingRepo.mark_uploaded + 主窗口日志「☁ 上传完成（本地保留）」	—
_delete_after_upload	(session_path, episode_index)	后台线程 delete_local_session（真删除 + 删除后校验），结果经 _session_deleted 回主线程	—
_on_session_deleted	(session_path, err)	删除收尾：失败仅提示（含校验残留）；成功 RecordingRepo.delete_local_episode 真删录制行 + 刷新列表 + 主窗口日志「☁ 上传完成，本地文件已删除」	—
_on_task_failed / _on_all_done	(task_id, error) / ()	失败：状态栏「❌ 上传失败」+ 主窗口日志 + 刷新列表 / 全部完成：恢复按钮、进度条 100、状态「全部完成」	—
closeEvent	(event)	停止 _manager	—

关键数据：

• 上传状态来源 UploadManager.get_upload_status(path)：completed/failed/pending。
• _task_path_map：task_id → session_path（删除与状态显示用）。
• 「上传后自动删除」开关 settings.UPLOAD_DELETE_AFTER 对自动与手动上传统一生效。

调用关系：由 ui/main_window.py（_open_upload）构造。依赖 core.uploader.UploadManager、core.api_client.APIClient（测试连接）、core.recording_repository.RecordingRepo、core.session_catalog.list_recordings、config.settings、config.i18n.tr。

ui/init.py

作用：ui 包的空标记文件（0 行），仅使目录成为可导入包。无类、无函数、无数据。