PDF-Annotation

Die Anzeige pdf rendert ein PDF im Browser mit PDF.js und legt die Annotationsfläche auf die gerenderte Seite statt auf vorab extrahierten Text. Annotierende sehen das echte Dokument, mit seinen Spalten, Tabellen, Abbildungen und Seitenumbrüchen, und vergeben die Label direkt darin. Die Anzeige verlangt einen einzigen Pflichtschlüssel, nämlich das Feld mit dem Pfad oder der URL des PDFs; alles Weitere ist eine Anzeigeoption.

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

view_mode nimmt scroll, paginated oder side-by-side. Beim fortlaufenden Scrollen liegen alle Seiten in einem Container, was zählt, sobald eine Annotation über einen Seitenumbruch hinweg reichen muss. Die paginierte Ansicht zeigt eine Seite auf einmal mit Navigationselementen und passt zu langen Dokumenten, die Seite für Seite bearbeitet werden.

Drei Annotationsmodi

annotation_mode bestimmt, was annotierende Personen zeichnen können, und ist damit die Option, die die Aufgabe selbst ändert und nicht nur ihr Aussehen. Die Vorgabe ist span.

Der Span-Modus setzt voraus, dass das PDF eine Textebene mitbringt. Jedes aus einer Textverarbeitung oder einem Satzsystem erzeugte PDF hat eine, ein Scan nicht. Der Bounding-Box-Modus braucht keine, deshalb lässt sich eine gescannte Seite ganz ohne Textextraktion nach Regionen labeln.

Weil die Anzeige pdf Spans über die Textebene von PDF.js verankert und nicht über den Wrapper .text-content, den andere Anzeigen verwenden, akzeptiert sie das Flag span_target nicht. Span-Annotation funktioniert trotzdem, über die eigene Textebene des PDFs.

Seitenübergreifende Verknüpfung

Der Link-Modus ist für Relationen gedacht, die über Seiten hinweg laufen, etwa eine Behauptung auf Seite 2, die sich auf eine Abbildung auf Seite 9 stützt. Die annotierende Person setzt zuerst Anker und zieht dann typisierte Verknüpfungen dazwischen; Potato speichert Anker und Verknüpfungen unter getrennten Schema-Namen.

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 und allowed_target_labels schränken ein, welche Anker ein Verknüpfungstyp verbinden darf. So wird aus einer Richtlinie etwas, das die Oberfläche durchsetzt, statt etwas, das die annotierende Person im Kopf behalten muss. Eine wie oben konfigurierte Verknüpfung refers_to kann nur bei claim beginnen und nur bei figure enden, eine von einer Abbildung zurück zu einer Behauptung gezogene Verknüpfung wird also abgelehnt. Für eine symmetrische Relation wie same_as setzen Sie directed: false.

Anker gibt es in zwei Ausprägungen, und beide lassen sich unabhängig abschalten. enable_text_anchors erlaubt das Hervorheben eines Textspans, enable_region_anchors das Zeichnen einer Regionsbox, was eine Abbildung oder eine Tabelle braucht. Ein vollständig durchgearbeitetes Beispiel liegt upstream unter examples/advanced/pdf-link-scroll/.

Gescannte Dokumente und OCR

ocr ist standardmäßig aus, und Potato liest die Option nur im Link-Modus. Ist sie gesetzt, werden Wörter serverseitig extrahiert und daraus eine clientseitige Textebene gebaut, sodass auch ein Scan ohne eingebetteten Text Textanker tragen kann. Die Option nimmt false, true oder auto; jeden anderen Wert weist Potato zurück.

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

Die drei Einstellungen unterscheiden sich darin, wann der Durchlauf stattfindet. false nutzt allein die eingebettete Textebene, true führt OCR immer aus, und auto greift nur dann auf OCR zurück, wenn die eingebettete Textebene leer zurückkommt. Bei einem gemischten Korpus ist auto vorzuziehen, denn OCR ist langsam und setzt eine Tesseract-Installation voraus. ocr_dpi steuert die Auflösung, mit der jede Seite vor dem OCR-Lauf gerastert wird; ein höherer Wert kostet auf jeder Seite Zeit. ocr_lang nimmt einen Tesseract-Sprachcode und steht standardmäßig auf eng.

Anzeigeoptionen

Word- und Markdown-Dateien

Eine DOCX- oder Markdown-Datei nutzt stattdessen die Anzeige document, die Überschriften- und Absatzstruktur des Dokuments erhält und span_target sehr wohl akzeptiert. Sie liest annotation_mode mit span oder bounding_box, und show_outline baut aus den Überschriften im Text ein Inhaltsverzeichnis. Potato schickt das gerenderte Markup durch eine Allowlist, bevor es die annotierende Person erreicht, sodass ein Korpusfeld mit einem ausführbaren Tag entfernt statt ausgeführt wird.

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

Weiterführendes

• Instanzanzeige listet jeden Anzeigetyp auf und welche davon Span-Targets akzeptieren.
• Span-Annotation behandelt die Label-Optionen, die ein Span-Schema nimmt.
• Dokumente annotieren arbeitet eine Dokumentenprüfung von Anfang bis Ende durch.
• Implementierungsdetails stehen in der Quelldokumentation.