pipelines/Tr006_V2/project/data_preprocessing/README.md

蓝屏时序预处理脚本说明

本目录用于检测胃肠镜视频中的冻结蓝屏区段、细化时间边界，并将结果整理为可发布的数据集。所有检测脚本均以原始视频为只读输入，不会裁剪、覆盖或移动源视频。

推荐流程

视频目录
  -> process_blue_screen_dataset.py
  -> results/{intervals.csv,videos.jsonl,per_video/,evidence/,summary.json}
  -> 结果验收及 validation.json
  -> prepare_blue_screen_hf_release.py
  -> 可上传的 HF Dataset 目录

正式批量处理优先使用 process_blue_screen_dataset.py。blue_screen_detector.py、fast_blue_screen_detector.py 和 refine_blue_intervals.py 主要用于方法验证、单视频诊断和边界复核，不应替代正式批处理入口。

脚本清单

process_blue_screen_dataset.py

正式的全数据集粗到细检测入口。

• 输入：包含 .avi、.mp4、.mov 或 .mkv 视频的目录。
• 粗检：顺序解码视频，每秒抽取一次圆形内镜 ROI，对 ROI 像素计算哈希和蓝色比例，定位连续静止蓝屏候选区段。
• 精修：只对候选区段及其前后缓冲区逐帧扫描，以原生 FPS 确定准确的开始帧和结束帧。
• 判定：ROI 解码帧哈希完全相同，同时蓝色比例达到阈值并满足最短持续时间。
• 支持 --resume，可复用已经完成的逐视频 JSON 结果。
• 输出：
  • intervals.csv：每个蓝屏区段一行，是主要时序标注。
  • videos.jsonl：每个视频一行，包含视频信息和全部区段。
  • per_video/<video_id>.json：逐视频检查点和详细结果。
  • evidence/<video_id>/：每个区段的前一帧、起始帧、结束帧和后一帧证据图。
  • summary.json：全数据集汇总统计。

正式 HeiCo 运行使用的主要参数为：1 秒粗采样、最短静止 6 秒、蓝色比例阈值 0.45、候选区段前后各扩展 5 秒、粗检尺寸 96、精修尺寸 160。

fast_blue_screen_detector.py

单视频快速哈希检测工具，用于验证“蓝屏期间抽样帧是否完全相同”的假设。

• 顺序解码视频，但默认只每秒生成一个 ROI 哈希和蓝色比例。
• 将连续相同哈希且持续时间足够长的样本合并为粗粒度区段。
• 可通过重复传入 --reference START END 与用户提供的参考区段计算近似秒级 precision/recall。
• 输出单个 JSON；时间边界精度由 --sample-seconds 决定，不能代替逐帧精修结果。

refine_blue_intervals.py

针对已知粗区段的单视频逐帧边界精修工具。

• 通过一个或多个 --interval START END 接收粗区段。
• 在粗区段前后增加 --pad 秒扫描范围。
• 逐帧计算圆形 ROI 蓝色比例，并通过连续确认帧抑制孤立噪声。
• 输出精修后的帧号、秒级时间、持续时长和平均蓝色比例。
• 适合人工复核或早期实验；正式批处理采用 process_blue_screen_dataset.py 内置的“完全重复帧哈希 + 蓝色比例”精修实现。

blue_screen_detector.py

早期单视频候选检测工具，用于验证基于颜色和纹理的蓝屏判定方法。

• 自动估计圆形内镜 ROI，忽略外围黑色区域。
• 稀疏抽帧后计算蓝色比例、拉普拉斯纹理强度、平均色相和有效像素比例。
• 将高蓝色比例、低纹理且持续时间足够长的样本合并为候选区段。
• 输出详细 JSON 和区段 CSV。
• 该方法没有完全相同帧哈希约束，结果属于候选范围，不作为当前正式蓝屏时序标注。

prepare_blue_screen_hf_release.py

将已经验收通过的运行结果整理为可移植的 Hugging Face Dataset 发布目录。

• 要求源运行包含 run.json、results/intervals.csv、videos.jsonl、summary.json、validation.json 和 evidence/。
• 只有 validation.json 状态为 PASS 时才允许打包。
• 删除结果中的服务器绝对视频路径，改用 video_id 和 video_filename。
• 复制边界证据图并生成便携的 provenance、summary、validation 和 release manifest。
• 对视频数、区段数和证据图数量进行一致性核验。
• 为避免误覆盖，目标输出目录已存在时会直接停止。

时间区间语义

蓝屏区段统一使用半开区间 [start_seconds, end_seconds)：开始时间包含在区段内，结束时间指向蓝屏结束后的第一个时间位置。逐帧结果同时提供 start_frame 和 end_frame，其中帧号边界为首尾均包含。

依赖与运行环境

• Python 3
• OpenCV (cv2)
• NumPy

FVQA 项目中的正式运行应使用 fvqa-harness.yaml 指定的 Conda 环境。蓝屏检测只使用 CPU，不需要占用 GPU。

当前正式结果

HeiCo 30 个视频的已验收结果位于 HF Dataset 仓库 Gbone3176/orena-seg 的 blue_screen_temporal_annotations/ 子目录：共 323 个蓝屏区段和 1,291 张边界证据图。该结果通过了文件覆盖、逐帧解码、区段边界和汇总一致性检查；这里的 PASS 表示产物一致性验收通过，不代表基于独立人工金标准计算的检测准确率。