| # 蓝屏时序预处理脚本说明 |
|
|
| 本目录用于检测胃肠镜视频中的冻结蓝屏区段、细化时间边界，并将结果整理为可发布的数据集。所有检测脚本均以原始视频为只读输入，不会裁剪、覆盖或移动源视频。 |
|
|
| ## 推荐流程 |
|
|
| ```text |
| 视频目录 |
| -> 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` 表示产物一致性验收通过，不代表基于独立人工金标准计算的检测准确率。 |
|
|
