add functions to merge images with validation. (#27)

* add functions to copy images with validation and check the video frame number.

* update README to clarify image file handling and maintain metadata structure

* Update utils/dataset_merging/merge_lerobot_dataset.py

[feat] accelerate the episode file finding with the ` episode_file_mapping`.

* Refactor image and video handling in dataset merging tool with enhanced validation

* [fix] If `images` directory exists, then use`early_validation`

* fix: Import `encode_video_frames` for video encoding in early validation

* fix: Add image copying option and update README for PNG support

* fix: Remove unused cv2 import from dataset merging utility

---------

Co-authored-by: Qizhi Chen <tavish9.chen@gmail.com>
Co-authored-by: zhipeng tang <2444198418@qq.com>

utils/dataset_merging/README.md

@@ -8,8 +8,11 @@ merge_lerobot_dataset是一个功能强大的Python脚本，专门用于合并
 2. **索引重编号**：重新编号所有的episode索引和任务索引，确保合并后数据的连续性和一致性。
 3. **向量维度填充**：自动检测并填充向量维度，使所有数据在observation.state和action等方面具有一致性。
 4. **统计信息合并**：智能合并多个数据集的统计信息，正确处理复杂的数据结构，如图像特征的嵌套结构。
-5. **视频文件处理**：正确处理和复制视频文件，保持视频与其他数据之间的正确索引关系，支持多种视频存储结构。
-6. **元数据更新**：更新所有元数据文件，准确反映合并后的数据集结构。
+5. **图像视频验证**：如果有图片 `images` 文件夹的话，自动检测视频 / 图像 / 元数据文件之间的数量关系。
+6. **视频文件处理**：正确处理和复制视频文件，保持视频与其他数据之间的正确索引关系，支持多种视频存储结构。
+7. **元数据更新**：更新所有元数据文件，准确反映合并后的数据集结构。
+8. **图像文件处理**：复制图像文件，保持图片与其他数据之间的正确索引关系。
+
 
 ## 三、安装
 本脚本依赖于以下Python库：
@@ -32,6 +35,7 @@ python dataset_merger.py --sources /path/to/dataset1 /path/to/dataset2 /path/to/
 - **--output**：输出数据集文件夹路径，用于指定合并后数据集的存储位置。
 - **--max_dim**：向量的最大维度，默认值为32。
 - **--fps**：数据集的帧率，默认值为20。
+- **--copy_images**: 是否将图像从源文件夹复制且合并到输出文件夹。(default: `False`)
 
 ### （三）示例
 ```bash
@@ -51,6 +55,9 @@ dataset/
 ├── data/                   # 包含parquet格式的episode数据
 │   └── chunk-xxx/
 │       └── episode_xxxxxx.parquet
+├── images/                   # 可选的图片文件
+│   └── episode_xxxxxx/
+│       └── frame_xxxxxx.png
 └── videos/                 # 可选的视频文件
     └── chunk-xxx/
         └── video_key/
@@ -63,11 +70,14 @@ dataset/
 3. **统计信息合并**：智能合并多个数据集的统计数据，能够正确处理复杂的数据结构，如图像特征的嵌套结构，确保统计信息的准确性和完整性。
 4. **视频文件处理**：正确复制视频文件，并保持视频与其他数据之间的正确索引关系，支持多种视频存储结构，保证视频数据与其他数据的同步性。
 5. **任务映射**：自动检测并合并相同的任务描述，创建新的任务索引映射，方便对任务进行统一管理和调用。
+6. **数据预验证**：在执行合并操作前对数据集执行全面的预验证，检查视频帧数、图片数量与元数据中记录的帧长度的一致性，确保合并后数据的准确性和完整性，并自动修复可修复的问题（从图片重新编码视频）。
+7. **图像文件管理**：复制和整理图像文件，保持正确的命名规则和目录结构，确保图像与视频和其他数据保持正确的索引对应关系，支持按需启用图像复制功能来优化存储空间使用。
 
 ## 七、注意事项
 1. 确保所有源数据集具有兼容的结构，否则可能导致合并失败或数据错误。
 2. 合并后的数据集可能占用较大磁盘空间，在进行合并操作前，请确保有足够的存储空间。
 3. 对于非常大的数据集，合并过程可能需要较长时间，请耐心等待。
+4. 图像文件夹占用磁盘空间很大，默认不开启 `copy_images` 参数。本工具在处理 `images` 文件夹下的图片时，**仅支持 PNG 格式的图片**，且要求图片文件名为 `frame_XXXXXX.png`（X为6位数字，例如 `frame_000001.png`）。合并过程中会自动检测并处理这些 PNG 图片。
 
 ## 八、常见问题
 1. **Q: 合并不同维度的数据集会发生什么？**