用于轨迹视频标注的图形用户界面工具，提供GUI界面，支持使用预录制的轨迹视频进行句子级别的标注。
- 💾 标注双写保护：保存轨迹时同步更新场景目录与根目录旧版文件，保证任意入口读取到最新标注数据
- 📁 最新优先加载：加载标注时自动挑选最近更新的文件，彻底解决个别轨迹编辑保存后不生效的问题
- 🎥 编辑状态保持：分段编辑保存后仍停留在当前分段和对应视频帧，避免状态被自动重置
- 🛡️ 进度文件容错：为进度文件读写增加空值守卫，提升初始化阶段的稳定性
- 🧩 标注帧区间智能检测：缺失/越界/全0/乱序时弹窗提示，可一键自动修复补全
- 📐 重分配算法：按动作权重或平均分配帧，确保覆盖范围并使相邻分段共享 1 帧
- 🔢 1-based 导出：内部 0-based，导出 JSON 统一 1…N；导入自动识别并转换
- 🛠 旧数据兼容：自动识别 1-based 输入，避免人工迁移
- 🎬 精确寻帧：修复首帧偶发无法显示与拖动跳帧问题
- 🧪 稳定性提升：修复失败时保留原数据并安全回退
- 🆕 补全指令勾选框始终可用，自动/手动分段模式下均可控制补全指令区域显示
- 📝 未勾选补全指令时，原始指令标签切换为“指令文本”
- 🎛️ UI逻辑优化，提升分段指令填写的灵活性和直观性
- 💾 分段编辑自动保存：编辑分段后，内容会立即保存到标注文件，无需再点击保存标注按钮
- ⏱️ 操作效率提升：分段编辑完成后自动写入标注文件，提升数据安全性和效率
- 🛡️ 数据安全：每次编辑分段都自动保存，防止数据丢失
- 🎨 轨迹选中高亮修复：轨迹列表刷新后自动恢复选中行，选中颜色不会消失，始终保持高亮
- 🎨 视觉一致性：为所有主要列表添加统一的选中着重标记，提升界面识别度
- 🟠 分段列表样式：添加橙色选中背景和悬停效果，完善视觉反馈系统
- 🔵 场景列表样式：蓝色选中背景，增强场景切换的视觉反馈
- 🟢 轨迹列表样式：绿色选中背景，提供清晰的轨迹选择标识
- 🌈 色彩体系：建立三色区分系统(蓝-场景/绿-轨迹/橙-分段)，直观的功能区域识别
- 🔄 界面文案优化：将"自动填入句子分段"改为"自动分段"，文案更简洁明确
- 🎛️ 智能控制：根据自动分段勾选状态控制原始指令显示和加载按钮可用性
- 📝 条件显示：勾选自动分段时显示当前分段原始指令，不勾选时不显示
- 📐 空间优化：分段指令区域始终显示，但根据模式调整交互方式
- ✋ 手动分段增强：手动分段模式下填写补全指令后才能标记帧
- 🐞 修复导出标注时 trajectory_id 字段与 episode_id 重复的问题，现已严格区分并导出真实 trajectory_id
- 🛠️ 细节完善：缩放相关功能归入子菜单，菜单结构更清晰
- ✨ UI自适应：主界面和标注面板支持高DPI缩放，所有字体和控件自适应屏幕比例
- 🟦 轨迹信息区优化：补全了自动填入句子分段勾选、加载句子分段按钮、标记不合格按钮，按钮宽度统一
- 📝 句子分段体验：支持自动填入、手动加载分句，分段与句子一一对应，分段进度清晰可见
- 🔄 细节完善：修复补全指令区重复、轨迹信息区内容缺失等问题，提升整体交互体验
- ✅ 功能集成: 将"新增分段"功能从弹出窗口移至主界面的"当前分段"模块
- ✅ 原地操作: 所有分段操作现在都在同一个界面完成，无需在多个窗口间切换
- ✅ 模式切换: 新增专门的"新增模式"，与现有的编辑和查看模式保持一致
- ✅ 文件组织: 标注文件按scene_id自动保存到对应的scene_X文件夹
- ✅ 向后兼容: 完全兼容旧的平铺结构，自动在两种结构间查找文件
- ✅ 导出分组: 导出功能也按场景创建子文件夹，保持结构一致
- ✅ 迁移工具: 提供自动迁移脚本，安全地整理现有文件到新结构
- ✅ 操作简化: 点击"新增分段"按钮后直接在当前分段区域进行编辑
- ✅ 界面一致性: 所有分段操作使用统一的界面布局和交互方式
- ✅ 流程优化: 简化新增分段的操作流程，提高标注效率
- ✅ 文件管理: 相同场景的标注文件集中管理，便于查找和维护
- ✅ 状态管理: 完善的模式切换和状态跟踪机制
- ✅ 代码优化: 统一分段操作的代码逻辑和用户界面处理
- ✅ 向后兼容: 保持所有现有功能的完整性和稳定性
- ✅ 性能提升: 减少单个文件夹的文件数量，提高文件系统操作效率
- ✅ 准确定位: 第N个分段时自动显示第N句话，而不是显示所有句子
- ✅ 动态计算: 根据已完成分段数量智能计算当前应显示的句子
- ✅ 进度同步: 分句显示与标注进度完全同步，准确反映当前状态
- ✅ 焦点明确: 用户始终看到当前需要标注的具体句子内容
- ✅ 减少干扰: 避免显示无关句子，提高标注专注度
- ✅ 逻辑一致: 各种操作场景下的句子显示逻辑完全统一
- ✅ 算法改进: 优化句子索引计算逻辑，确保准确性
- ✅ 状态同步: 完善分段状态与句子显示的同步机制
- ✅ 边界处理: 正确处理边界情况和异常状态
- ✅ 标题统一化: 将"当前分段（新增中）"更新为"当前分段（新增标注中）"，使界面文案更加准确
- ✅ 状态一致性: 确保所有状态切换方法中的标题文案保持一致
- ✅ 智能填充: 在新增标注状态下自动填充轨迹的原始指令到分段指令框
- ✅ 状态感知: 有标注数据时不进行自动填充，保持界面状态清晰
- ✅ 重置优化: 重置分段状态时在无标注情况下自动填充原始指令
- ✅ 清空处理: 清空所有标注后自动恢复原始指令填充状态
- ✅ 减少操作步骤: 用户无需手动复制粘贴原始指令，提升标注效率
- ✅ 智能判断: 系统自动判断是否需要填充，避免覆盖用户已编辑的内容
- ✅ 一致性保证: 确保在各种操作场景下的行为一致性
- ✅ 原地编辑系统: 实现分段的原地编辑功能，无需弹出对话框，直接在当前分段区域编辑
- ✅ 智能状态管理: 根据标注数据自动切换界面状态（新增中/已标注/编辑中/查看中）
- ✅ 分段查看模式: 点击已标注分段自动加载数据到当前分段栏目，支持只读查看
- ✅ 动态标题更新: 当前分段组标题实时反映操作状态
- ✅ 分段编辑对话框: 新增专用的分段编辑对话框，支持帧范围和指令编辑
- ✅ 分段排序功能: 添加上移/下移按钮，支持分段顺序调整
- ✅ 重叠验证优化: 允许合理的分段重叠（<50%），防止完全包含
- ✅ 补全指令存储: 分段数据模型支持completed_instruction字段
- ✅ 双击编辑: 双击分段表格项目直接进入编辑模式
- ✅ 按钮状态管理: 编辑模式下按钮文本和状态智能切换（保存编辑/取消编辑）
- ✅ 4列表格显示: 分段列表扩展为4列（分段号、帧范围、指令、补全指令）
- ✅ 状态指示优化: 不同状态使用不同颜色和文本提示
- ✅ 编辑状态跟踪: 新增is_editing、editing_segment、editing_row状态变量
- ✅ 信号连接优化: 完善分段选择和视频跳转的信号处理
- ✅ 数据同步机制: 编辑后实时更新表格显示和统计信息
- ✅ 测试覆盖: 添加comprehensive test suite验证所有编辑功能
- ✅ 补全指令功能: 在分段指令下方新增补全指令文本框，两个框平分高度空间
- ✅ 补全标准按钮: 添加"补全标准"按钮，提供详细的指令补全指导规范
- ✅ 指令优化指导: 提供动作细化、地标描述、方向信息、距离位置等补全标准
- ✅ 用户体验提升: 支持基于标准的指令完善和细化流程
- ✅ 界面优化: 优化按钮布局，轨迹模块按钮平均占满宽度
- ✅ 轨迹排序: 新增轨迹点数量显示和多种排序方式（按轨迹点数量/Episode ID，升序/降序）
- ✅ 导出优化: 导出对话框新增轨迹点数列，序号与主界面完全一致（全局序号）
- ✅ 界面优化: 将所有列表转换为表格格式
- ✅ 新增功能: 添加"标记轨迹为不合格"功能，支持跳过不合格轨迹
- ✅ 界面优化: 重新设计布局，数据导入和场景选择区域并排显示，节省垂直空间
- ✅ 性能提升: 优化视频检测算法，移除对特定文件夹结构的依赖，提升导入效率
- ✅ 缓存优化: 改进视频文件缓存机制，加快文件查找速度
- ✅ 响应性: 增强界面布局响应性，更好适配不同屏幕尺寸
- 🎉 首次发布: 基础功能完整实现
- 🎥 视频播放: 支持多种视频格式，自适应显示
- 📝 标注功能: 句子级别轨迹标注
- 📊 数据管理: 标注进度跟踪和数据导出
- 🔍 搜索功能: 场景和轨迹智能搜索
- 🎥 视频播放: 支持多种视频格式，自适应显示比例（1344x736）
- 📝 句子标注: 自动句子分割，支持轨迹片段的句子级别描述
- 🎯 可视化标注: 在视频上直观显示标注片段和进度条
- 📊 数据管理: 运行时数据导入，自动保存和导出标注数据
- 🌐 场景管理: 支持场景和轨迹选择，智能搜索和筛选
- ⚡ 高效处理: 优化的视频文件检测和缓存机制
trajectory-annotation-gui/
├── src/ # 源代码目录
│ ├── gui/ # GUI组件
│ │ ├── main_window.py # 主窗口 - 数据导入、场景选择
│ │ ├── video_player.py # 视频播放器 - 自适应播放
│ │ └── annotation_panel.py # 标注面板 - 句子标注
│ ├── core/ # 核心功能
│ │ ├── data_loader.py # 数据加载器 - 视频关联
│ │ └── annotation_manager.py # 标注管理器 - 保存导出
│ ├── models/ # 数据模型
│ │ ├── trajectory_data.py # 轨迹数据模型
│ │ └── annotation_data.py # 标注数据模型
│ └── utils/ # 工具模块
│ └── config.py # 配置管理 - 句子分割
├── main.py # 程序入口
├── requirements.txt # 依赖包列表
└── README.md # 项目文档- GUI框架: PyQt5 - 提供现代化的桌面应用界面
- 视频处理: OpenCV - 高性能视频处理和显示（支持1344x736分辨率）
- 数据处理: NumPy, JSON - 高效的数据操作和存储
- 配置管理: JSON配置文件 - 灵活的参数设置
- Python 3.7 或更高版本
- PyQt5 GUI框架
- OpenCV 视频处理库
- 操作系统: Windows 10+, macOS 10.14+, Ubuntu 18.04+
-
获取代码:
# 下载或克隆代码到本地 cd trajectory-annotation-gui
-
创建虚拟环境 (推荐):
python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate
-
安装依赖:
pip install -r requirements.txt
-
验证安装:
python main.py
-
启动应用:
python main.py
-
导入数据:
- 点击"导入数据文件"按钮，选择轨迹数据JSON文件
- 点击"导入视频文件夹"按钮，选择包含视频文件的目录
-
开始标注:
- 在场景列表中选择要标注的场景
- 在轨迹列表中选择具体的轨迹
- 使用播放控制器浏览视频
- 点击"开始分段"开始标注，"结束分段"完成一个片段
-
保存和导出:
- 点击"保存标注"保存当前轨迹的标注
- 点击"导出标注"导出整个场景的标注到JSON文件
Ctrl+O: 加载数据Ctrl+S: 保存标注Ctrl+E: 导出标注Space: 播放/暂停视频←/→: 逐帧导航
轨迹数据JSON文件应包含以下结构：
{
"scene_id": {
"episode_id": {
"instruction": "完整的指令文本。包含多个句子。",
"reference_path": [[x, y, z, ...], ...],
"actions": [action_data, ...]
}
}
}视频文件应按以下命名规则组织：
video_folder/
├── scene_id/
│ ├── episode_id.mp4
│ └── ...
└── ...
输出的标注文件格式：
{
"episode_id": {
"episode_id": "episode_id",
"trajectory_id": "trajectory_id",
"scene_id": "scene_id",
"original_instruction": "原始完整指令",
"segments": [
{
"start_frame": 0,
"end_frame": 30,
"instruction": "分段指令句子",
"start_position": [x, y, z],
"end_position": [x, y, z],
"actions": [...],
"reference_path": [...]
}
]
}
}应用支持通过配置文件自定义行为：
- 支持的视频格式
- 默认播放速度
- 帧率显示设置
- 地标类型列表
- 句子类型选项
- 自动保存间隔
- 窗口大小和布局
- 字体和颜色主题
- 语言设置
-
安装PyInstaller:
pip install pyinstaller
-
基础打包:
pyinstaller --onefile --windowed --name=TrajectoryAnnotationTool main.py
-
优化打包:
pyinstaller build_exe_lite.spec
--onefile: 打包成单个可执行文件 (~90MB)--onedir: 打包成目录模式 (启动更快)--windowed: Windows下隐藏控制台窗口--name: 指定可执行文件名称--exclude-module: 排除不需要的模块以减小文件大小
- GUI层: 负责用户界面和交互
- 核心层: 处理业务逻辑和数据操作
- 模型层: 定义数据结构和验证
- 工具层: 提供通用功能和配置
要添加新功能，请遵循以下模式：
- 在相应的模型中定义数据结构
- 在核心模块中实现业务逻辑
- 在GUI组件中添加用户界面
- 更新配置和文档
版本: 1.3.3
最后更新: 2025年7月
维护者: Lozumi