Skip to content

PDF 标注

在 Potato 中使用 pdf 显示类型标注 PDF，涵盖片段高亮、页面上的边界框、跨页连线，以及用于扫描件的 OCR。

pdf 显示类型用 PDF.js 在浏览器中渲染 PDF，并把标注层放在渲染后的页面上，而不是放在事先抽取出来的文本上。标注者看到的是真实文档，分栏、表格、插图和分页都原样保留，并直接在原处打标签。该显示类型只需要一个必填键，即保存 PDF 路径或 URL 的字段，其余都是显示选项。

yaml
instance_display:
  fields:
    - key: pdf
      type: pdf
      label: "Document"
      display_options:
        view_mode: scroll
        max_height: 760
        zoom: page-width

view_mode 接受 scroll、paginated 或 side-by-side。连续滚动把所有页面堆叠在一个容器里，当某条标注需要跨越分页时这一点很关键。分页视图一次显示一页并带有导航控件，适合标注者逐页处理的长文档。

三种标注模式

annotation_mode 决定标注者能画什么，它改变的是任务本身而不是外观。默认值是 span。

模式标注者的操作锚定在
span选中文本并施加标签PDF.js 的文本层
bounding_box在页面任意位置画框页面坐标
link先标出锚点，再把它们连起来文本片段与页面区域

片段模式依赖 PDF 自带文本层。由文字处理软件或排版系统生成的 PDF 都有文本层，扫描件则没有。边界框模式不依赖文本层，因此扫描页仍可按区域打标签，完全不需要抽取文本。

由于 pdf 显示类型通过 PDF.js 的文本层来锚定片段，而不是通过其他显示类型使用的 .text-content 包装器，它不接受 span_target 标志。片段标注照样可用，走的是 PDF 自身的文本层。

跨页连线

连线模式用于跨页的关系，例如第 2 页上的一个论断依据第 9 页上的一幅插图。标注者先标出锚点，再在锚点之间画出带类型的连线，Potato 会把锚点和连线记录在不同的 schema 名称下。

yaml
instance_display:
  fields:
    - key: pdf
      type: pdf
      label: "Document"
      display_options:
        annotation_mode: link
        view_mode: scroll
        enable_text_anchors: true
        enable_region_anchors: true
        anchor_schema: pdf_anchors
        link_schema: pdf_links
        anchor_labels:
          - name: claim
            color: "#dc2626"
          - name: figure
            color: "#2563eb"
        link_types:
          - name: refers_to
            directed: true
            color: "#dc2626"
            allowed_source_labels: [claim]
            allowed_target_labels: [figure]

allowed_source_labels 和 allowed_target_labels 限制某种连线类型可以连接哪些锚点，标注规范因此变成界面强制执行的规则，而不是标注者必须记住的规则。按上面方式配置的 refers_to 连线只能从 claim 出发、只能落在 figure 上，所以从插图反向连回论断的连线会被拒绝。对于 same_as 这类对称关系，设置 directed: false。

锚点分两种，两种都可以单独关闭。enable_text_anchors 允许高亮一个文本片段，enable_region_anchors 允许画出区域框，插图或表格需要的正是后者。上游在 examples/advanced/pdf-link-scroll/ 提供了一个完整的示例。

扫描文档与 OCR

ocr 默认关闭，且 Potato 只在连线模式下读取它。一旦设置，词语会在服务端被抽取出来，用于构建客户端文本层，于是没有嵌入文本的扫描件也能承载文本锚点。该选项接受 false、true 或 auto，Potato 会拒绝其他任何取值。

yaml
instance_display:
  fields:
    - key: pdf
      type: pdf
      display_options:
        annotation_mode: link
        ocr: auto
        ocr_dpi: 200
        ocr_lang: eng

三种设置的差别在于这一遍处理何时运行。false 只使用嵌入的文本层，true 始终运行 OCR，auto 只在嵌入文本层返回为空时才退回到 OCR。混合语料建议用 auto，因为 OCR 很慢，还需要安装 Tesseract。ocr_dpi 控制 OCR 读取前每一页被栅格化的分辨率，调高它会让每一页都多花时间。ocr_lang 接受 Tesseract 语言代码，默认为 eng。

显示选项

选项默认值作用
view_modescrollscroll、paginated 或 side-by-side
max_height700容器高度，单位像素
max_width无容器宽度
text_layertrue启用文本选择
show_page_controlstrue页面导航控件
initial_page1首先显示的页面
zoomautoauto、page-fit、page-width 或百分比
annotation_modespanspan、bounding_box 或 link
bbox_min_size10可接受的最小框，单位像素
bbox_colors无按标签区分的框颜色
show_bbox_labelstrue在框上绘制标签
thumbnail_sidebartrue分页视图中的页面缩略图
enable_text_anchorstrue文本片段可用作连线锚点
enable_region_anchorstrue区域框可用作连线锚点
anchor_schemapdf_anchors记录在锚点上的 schema
link_schemapdf_links记录在连线上的 schema
ocrfalsefalse、true 或 auto
ocr_dpi200OCR 渲染分辨率
ocr_langengTesseract 语言代码

Word 与 Markdown 文件

DOCX 或 Markdown 文件改用 document 显示类型，它保留文档的标题与段落结构，并且确实接受 span_target。它读取取值为 span 或 bounding_box 的 annotation_mode，而 show_outline 会依据正文中的标题生成目录。Potato 会先把渲染出的标记过一遍允许列表，然后才交给标注者，因此语料字段中带有可执行标签的内容会被剥离而不是被执行。

yaml
instance_display:
  fields:
    - key: report
      type: document
      label: "Report"
      display_options:
        show_outline: true
        max_height: 600

延伸阅读