SCENE_GROUPING_GUIDE

按场景分组保存标注 - 使用说明

概述

从版本 1.3.4 开始，轨迹标注工具支持按场景分组保存标注文件，使标注数据更好地组织和管理。

新的文件结构

之前的结构

annotations/
├── episode_id_1.json
├── episode_id_2.json
├── episode_id_3.json
├── progress.json
└── backups/

新的结构

annotations/
├── scene_3/
│   ├── episode_id_1.json
│   └── episode_id_2.json
├── scene_24/
│   └── episode_id_3.json
├── progress.json
└── backups/

功能特性

🗂️ 自动场景分组

• 新保存的标注自动按 scene_id 创建子文件夹
• 文件夹命名格式：scene_{scene_id}
• 相同场景的标注文件保存在同一个文件夹中

🔄 向后兼容

• 自动兼容旧的平铺结构文件
• 加载标注时优先从场景文件夹查找，失败则回退到根目录
• 删除标注时支持两种结构

📤 导出按场景分组

• 导出功能也按场景创建子文件夹
• 导出的文件结构与保存结构一致
• 支持选择特定场景进行导出

迁移现有文件

如果您有现有的标注文件，可以使用迁移脚本将它们组织到新的结构中：

使用迁移脚本

python migrate_annotations.py

迁移过程

1. 自动备份：创建 migration_backup_时间戳 备份文件夹
2. 读取场景ID：从每个标注文件读取 scene_id
3. 创建场景文件夹：自动创建 scene_X 文件夹
4. 移动文件：将文件移动到对应的场景文件夹
5. 验证结果：检查迁移完成情况

迁移安全性

• ✅ 自动创建备份
• ✅ 跳过已存在的文件
• ✅ 保留原文件权限和时间戳
• ✅ 详细的迁移日志

使用方法

新用户

直接使用新版本，标注会自动按场景分组保存。

现有用户

1. 运行迁移脚本整理现有文件（可选）
2. 新的标注会自动使用新结构
3. 旧文件仍可正常加载和使用

技术实现

保存逻辑

# 创建场景文件夹
scene_dir = os.path.join(config.OUTPUT_DIR, f"scene_{annotation.scene_id}")
os.makedirs(scene_dir, exist_ok=True)

# 保存到场景文件夹
filepath = os.path.join(scene_dir, f"{annotation.episode_id}.json")

加载逻辑

# 优先从场景文件夹加载
for scene_folder in scene_folders:
    filepath = os.path.join(scene_folder, f"{episode_id}.json")
    if os.path.exists(filepath):
        return load_file(filepath)

# 回退到根目录（兼容性）
old_filepath = os.path.join(config.OUTPUT_DIR, f"{episode_id}.json")
if os.path.exists(old_filepath):
    return load_file(old_filepath)

优势

📁 更好的组织

• 场景相关的标注文件集中管理
• 便于查找和管理特定场景的标注
• 支持大规模数据集的组织

🔍 便于分析

• 可以快速统计每个场景的标注数量
• 支持按场景进行批量操作
• 便于场景级别的数据分析

🚀 性能提升

• 减少单个文件夹的文件数量
• 提高文件系统操作效率
• 便于并行处理不同场景

注意事项

1. 迁移前备份：建议在运行迁移脚本前手动备份重要数据
2. 场景ID必须存在：标注文件中必须包含有效的 scene_id 字段
3. 文件夹权限：确保有足够权限创建和移动文件
4. 磁盘空间：迁移过程需要额外空间用于备份

常见问题

Q: 旧文件还能正常使用吗？

A: 是的，系统会自动兼容旧的平铺结构，无需强制迁移。

Q: 迁移失败怎么办？

A: 迁移脚本会创建备份，可以从备份文件夹恢复原始文件。

Q: 可以手动组织文件吗？

A: 可以，只需按 scene_X 格式创建文件夹并移动文件即可。

Q: 导出的文件结构是什么样的？

A: 导出时也会按场景创建子文件夹，结构与保存时一致。

---

版本: 1.3.4+
更新时间: 2025-07-22
作者: Lozumi