Annotate 用户指南

Annotate 是一款用于足球视频分析的本地应用。一个项目包含导入的视频、采集的片段、帧标记、标注数据、演示文稿、导出文件、缓存，以及可恢复的废纸篓。

片段标注是绘制在视频上的关键帧对象。帧标记标注是附在原视频某一精确帧上的文档，可以包含入场动画。跟踪会生成高亮的关键帧，单应性则为矩形和圆形提供球场坐标。

项目数据保存在所选的项目文件夹中。应用通过同一台电脑上的 Python 服务完成视频导入、跟踪、单应性计算和导出。桌面版自带并管理这项服务；浏览器开发环境中需单独运行。

从 GitHub Releases 下载 Mac 版 DMG 或 Windows 安装程序。在 macOS 上，打开 DMG 并把 Annotate 拖到“应用程序”中。在 Windows 上，运行安装程序，然后通过桌面快捷方式打开 Annotate。安装包适用于 macOS 14 或更高版本的 Apple Silicon Mac，以及 Windows 10/11 x64。

这些都是未签名的评估版本，即使 GitHub 将其标为 Latest。系统可能会要求你批准运行；请不要关闭系统的安全保护。Python、视频工具和模型均已内置，无需终端或单独的浏览器。服务随应用启动和退出；首次启动加载库时可能较慢。

桌面版服务日志位于 macOS 的 ~/Library/Application Support/Annotate/logs/services.log 和 Windows 的 %APPDATA%\Annotate\logs\services.log。片段编辑器和帧标记编辑器会在单独的窗口中打开。

浏览器开发环境仍支持 Chrome、Edge、Brave、Arc 或 Chromium；Safari 和 Firefox 无法授予所需的项目文件夹访问权限。旧版浏览器安装程序及其说明位于仓库的 legacy/browser-install 文件夹。

标签面板是固定的工作区，而不是菜单。点击一次标签块开始一个片段，再次点击同一个标签块结束它。正在记录的标签块会显示红点和起始帧，进行中的片段在结束前就会出现在时间轴上。不同类型的片段可以相互重叠。

修饰项会为最近开始的那个采集添加结构化信息，因此请在该采集进行时选择。可用的修饰项随标签块而变化，但面板本身位置不变。没有自动的前置或后置余量：你点击的帧就是片段的边界。

在时间轴或列表中点击片段即可选中它并跳到其开头。暂停时选择重新标记所选片段，再选择修饰项和新的标签块；片段保留原有帧范围，并移到列表中的新分组。也可以把片段拖到另一个分组上。打开编辑器会在单独的窗口中打开该片段，若已打开则切换到该窗口。

采集时间轴按分组分为多条轨道，重叠的片段放入子轨道。点击或拖动可以定位，横向滚动可以前后移动，缩放滑块可在逐帧查看和整场比赛之间切换。手动滚动后，播放头自动跟随会暂停五秒。

内置标签面板跟随页眉中选择的语言。自定义面板保留各自的标签。切换语言不会重命名已保存的片段，也不会取消进行中的采集。

片段编辑器包含原始视频、动画战术对象、属性检查器和逐帧关键帧时间轴。播放始终不会超出片段当前的起止范围。

绘制对象会在当前帧创建它的第一个位置关键帧。用逐帧按钮前进或点击时间轴跳到另一帧，然后在那一帧移动、缩放或旋转对象：Annotate 会添加一个关键帧，并在关键帧之间插值。点击某个关键帧可回到它所在的帧；在那里所做的修改会更新这个关键帧，而不是新建一个。

颜色、线宽、填充不透明度、线型、名称等样式属性属于整个对象，作用于每一帧。使用选择点击对象，或在空白区域拖动进行框选。按住 Shift 点击可在视频或对象列表中添加对象，此时检查器中的修改会作用于所有选中的对象。macOS 上按 Cmd 点击、Windows 上按 Ctrl 点击可取消选择。同类对象的位置关键帧互不重叠时，可使用合并对象。

选择裁剪，向内拖动任意一个控制点。摘要会显示裁剪将移除多少帧标记、关键帧和对象。应用裁剪确认新的范围，取消则保持不变。在进行其他片段编辑之前，撤销裁剪可以恢复原来的范围。裁剪只能缩短片段，不能超出原有范围延长。

跟丢时，跟踪高亮会隐藏，临时候选重新出现。选中正确的候选并选择继续；Annotate 会补齐中间的空缺并继续跟踪。如果这一帧没有检测到正确的球员，就逐帧前进直到检测到为止，再继续。有时需要重复几次。

如果跟踪跟到了错误的球员身上，回放到切换的位置，退回到最后一帧正确的画面，选择从此处重新跟踪。选中正确的球员并继续。完成会替换原跟踪的后半段；取消则保留原来的跟踪。

跟踪使用图像坐标，不需要单应性。跟踪编号只表示连续性，并不代表球员身份，因此在球员重叠、镜头切换或球员离开画面时，通常都需要人工修正。

选中一个高亮，在名称中输入球员名字。勾选显示名称即可在视频上显示，并可按需调整文字大小。名字也会作为该对象在时间轴中的标签。

箭头、高球、防守覆盖阴影和多边形都可以连接到高亮上。选择箭头后，先点一个高亮，再点另一个：两端都会连接上，箭头会跟随球员的跟踪移动，无需重新绘制。

帧标记标出片段中的某一精确帧。在片段编辑器中选择添加帧标记，帧标记会在单独的窗口中、恰好在该帧打开。帧标记编辑器使用与片段编辑器相同的绘图工具，从一个高亮画到另一个高亮的箭头会同时连接在两者上。选择保存，再选择关闭帧标记即可回到片段。

按住 ← 或 → 可以查看帧标记前后最多五秒的视频；离开帧标记所在帧时，标注会隐藏、编辑会锁定。按空格键回到可编辑的那一帧。当同一时刻需要不同的讲解时，一个帧标记还可以包含多个命名的标注集；导入片段会把当前标注集复制到片段中帧标记所在的帧。

在帧标记编辑器中打开动画，选中一个图形，再选择添加。每个步骤都有效果（出现、淡入、放大或擦除）和触发方式（单击时、与上一动画同时或上一动画之后），并可调整延迟和时长。默认是淡入、单击时。没有添加步骤的图形从一开始就显示。预览和下一步可以逐步查看动画顺序。

片段播放到带动画的帧标记时，会停在帧标记处，并隐藏带动画的图形。播放、空格键或点击视频都会依次执行每个单击步骤；最后一步之后再点击一次，片段就会继续播放。

要直接在球场上绘制，片段需要单应性。选择计算 H。进度条会先显示模型加载，再显示整个片段中采样帧的标定进度；启动应用后的第一次计算会更慢。取消会停止计算，不会替换已有结果。结果会被缓存，重新计算 H会替换它们。

显示 H会叠加球场网格，方便与场地标线对照。有了单应性后，矩形和圆形会画在球场上（绘制：球场）：它们呈现球场的透视，控制点在球场上移动，镜头移动时也始终停在同一片草皮上。而用图像坐标绘制的图形则固定在屏幕上。

删除 H会移除单应性，绘制恢复为图像坐标。帧标记的标定提供同样的自动计算，并可在单帧上改用手动 H。跟踪不需要单应性。

在项目页面新建演示文稿：输入名称，选择创建，然后选择打开。编辑界面包括素材浏览器、实时预览、横向幻灯片序列和检查器。

点击素材即可预览；只有把它拖入演示文稿后才会添加。展开片段的帧标记，可以把其中一个单独拖入作为幻灯片。用添加标题添加标题、章节或分隔卡片，拖动缩略图可以调整顺序。选中片段幻灯片，可以选择它在哪些帧标记处暂停。

演示会隐藏编辑界面并铺满窗口。片段幻灯片播放原视频及其动画标注，并在所选帧标记处暂停；点击会先显示帧标记的动画步骤，然后片段继续或演示前进到下一张。直接切换会直接进入下一张幻灯片；同一视频中按时间顺序排列的帧标记之间可使用比赛视频。

项目页面上的导出报告…会在项目文件夹的 exports/report/ 中写入 clips.csv、clips.json，并为每个帧标记标注集生成一张与视频分辨率相同的 PNG。PNG 显示的是完整的标注，而不是动画中的某一瞬间。

要移除片段，在采集播放器中选中它并选择删除片段。删除片段、帧标记和标注集时，会先把它们复制到 .trash/；立即使用撤销删除即可恢复。清空废纸篓会永久删除保留的恢复数据。

要移除视频，在项目页面上点击它旁边的删除，并选择删除视频及片段确认。这会永久删除项目中的视频副本及其所有片段、帧标记和标注集。原始导入文件和演示文稿不受影响；相关幻灯片会提示来源缺失。删除视频无法撤销。

项目页面的完整性报告会列出缺失的媒体、无法读取的文档和无法解析的演示文稿引用。它只用于诊断：Annotate 不会自行猜测如何改写你的作品。为确保安全，请备份整个项目文件夹。

箭头、高球、防守覆盖阴影以及多边形的每个顶点都可以连接到高亮上。连接后的图形会跟随高亮移动，无论高亮是手动移动还是跟踪移动。只有矩形和圆形使用球场坐标；其他工具都使用图像坐标。

项目就是一个普通文件夹。清单文件是 project.json；源媒体在 media/ 中；片段及其标注文档在 analysis/ 中；演示文稿、导出文件、缓存和废纸篓各有对应的文件夹。

项目打开时，请不要重命名或移动内部文件。要备份或移动项目，请先关闭它，再复制整个文件夹。视频会被复制到项目中，因此导入期间需要同时容纳源文件和项目副本的空间。

Annotate 0.2 项目使用 project.v2 模型，与 Annotate 0.1 不兼容。请为旧项目保留一个 0.1 版本的安装。