图像视频标注编辑器

要解决的问题

在技术文档、故障复盘和教学演示中，经常需要从截图、照片或视频中提取局部证据，并加上箭头、框线、文字标签，甚至做前后对比拼图。传统做法要切换多个图像处理工具，手动定位坐标、调整尺寸、拼接图片，结果不仅效率低，还容易因标注不一致导致歧义。更关键的是，证据类图片不能为了美观而修改事实——抹掉什么、保留什么、放大哪里，都需要可控、可复核。

这个技能把常见的图像与视频标注操作收敛到一个统一的 workflow 里，用两个脚本分别处理静态图和视频帧，让输出结果直接可用于 Word、PDF、PPT 或公众号文章。

核心能力与工作流程

整个流程默认原图原视频只读，所有处理结果统一写到 E:\codexouput\tansuo\visual_outputs\_ 这样的独立目录，避免覆盖原始素材。

图片标注主要由 scripts/image_mark.py 承担。它把局部截图、遮挡、模糊、画框、箭头、编号、文字标签、局部放大、拼图、缩放、格式转换等操作抽象成一组命令行参数，例如：

• --crop x1,y1,x2,y2 精确截取局部区域，适合从整图中分离重点。
• --mask 与 --blur 分别用于遮盖无关内容或模糊隐私信息。
• --box、--arrow、--text、--badge 让标注元素带标签，方便正文逐项引用。
• --inset 可叠加局部放大图，但放大内容必须来自原图高清帧，而不是已经缩小的拼图。
• --collage grid|horizontal|vertical 支持将多图组成网格、横向或纵向拼图，并可用 --title 和 --caption 补充标题与图注。

视频抽帧由 scripts/video_frames.py 处理，支持按时间点、固定间隔或平均数量导出截图，例如 --timestamps 00:01:12,00:02:03.5、--interval 5、--count 12。导出后自动生成 frame_index.csv，记录文件名和对应时间点，方便后续在报告里精确引用。

标注原则与边界注意

标注不是美化，而是证据说明。图中标签默认使用简体中文短句，长解释放在图注或正文里；箭头必须指向具体对象，框线要覆盖完整证据区域，编号用于正文逐项解释。

• 不随意抹除证据。--mask 和 --blur 仅用于无关区域、隐私信息、广告或杂乱边缘，任何可能影响事实判断的部分都不能随意处理。
• 局部放大必须来自原始高清图或原始帧，不能从已缩小的拼图中二次截取，否则会丢失细节。
• 拼图要服务比较关系：前后对比、左右对比、步骤顺序、局部与整体，而不是单纯堆叠无关图片。
• 依赖环境要提前确认：图片处理优先用 Python 的 Pillow；视频抽帧优先找系统 FFmpeg，找不到时尝试 imageio-ffmpeg，都不可用才提示用户安装或改用其他工具。
• 隐私与敏感信息不能出现在日志、报告或发布包里。

最终输出会返回处理后图片的绝对路径，在 Codex 桌面里可用 Markdown 语法展示关键结果；若要给报告使用，还会附带原图、裁剪图、标注图、拼图的路径清单和一段简短图注，但不会描述工具执行过程，只说明图中标注代表什么、能证明什么、不能证明什么。处理失败时，会明确缺什么依赖、在哪一步失败、以及有哪些替代方案。