Digital Humanities in Potato: IIIF, Web Annotation, PAGE XML, TEI und Zooniverse

Potato 2.12.0 liest und schreibt vier Austauschformate, die in den Digital Humanities verwendet werden: IIIF-Manifeste, W3C Web Annotation, PAGE XML und TEI. Jeder Importer baut ein lauffähiges Projekt aus einem Bibliotheksmanifest, einer Annotationssammlung, einem Transkribus- oder eScriptorium-Export oder einer TEI-Edition, und jeder Exporter schreibt die korrigierte Arbeit in das Format zurück, aus dem sie stammt. Ein Zooniverse-Workflow und seine Klassifikationen werden auf dieselbe Weise importiert.

Die Annotationen der Quelle kommen als Vorannotationen herein, die ein Annotator als Ausgangspunkt sieht und die erst gespeichert werden, wenn jemand speichert.

potato import -i <file or folder> -o <project folder> [-f <format>]
python potato/flask_server.py start <project folder>/config.yaml -p 8000
python -m potato.export -c <project folder>/config.yaml -f <format> -o <output folder>

Lokale Dateien werden nur aus dem Eingabeordner kopiert. Ein Importer kopiert ein lokales Bild oder einen lokalen Text nur dann in den Ordner media/ des Projekts, wenn die Datei in dem Ordner liegt, den Sie importieren, oder in einem Ordner, den Sie mit --image-dir oder --texts angeben. Jeder andere Verweis, etwa ein absoluter Pfad, eine file://-URI, ein ../-Pfad oder ein Symlink, der aus dem Ordner hinausführt, wird mit einer Warnung übersprungen, weil der Server media/ veröffentlicht. Verschieben Sie die Datei in den Eingabeordner und importieren Sie erneut.

IIIF-Manifeste

potato import -f iiif -i manifest.json -o book-project
potato import -f iiif -i https://example.org/iiif/book1/manifest.json -o book-project

Die Eingabe ist eine Manifestdatei, ein Ordner, der eine enthält, oder eine http(s)-URL. Eine URL ist die einzige Eingabe, bei der der Importer das Netzwerk verwendet: Er ruft das Manifest und alle Annotationsseiten ab, auf die das Manifest per URL verweist. Bei einem lokalen Manifest werden referenzierte Seiten aus gleichnamigen Dateien daneben gelesen.

Jedes Canvas wird zu einem Item. Das Bild ist die id des Bodys der Painting-Annotation oder, wenn der Body keine brauchbare id hat oder --iiif-size angegeben ist, eine Anfrage an den Image Service des Bodys in dieser Größe (Standard !2000,2000). Die Labels und metadata von Manifest und Canvas werden über dem Bild angezeigt. Annotationsseiten auf dem Canvas werden zu Formen in einem image_annotation-Schema namens regions, deren Labels aus den Tags der Annotationen stammen. Canvas-Koordinaten werden umgerechnet, sodass ein Canvas, dessen Größe von der Pixelgröße des Bildes abweicht, trotzdem passt. Manifeste der Presentation API 2.x werden nach bestem Vermögen gelesen.

python -m potato.export -c book-project/config.yaml -f iiif_annotations -o out \
    --option base_url=https://example.org/iiif-out/

Der Exporter schreibt eine Annotationsseite pro annotiertem Canvas nach out/annotations/<canvas>.json und eine Kopie des Manifests nach out/manifest.json mit einem Verweis auf jede Seite, in der eigenen Version des Manifests. Öffnen Sie das kopierte Manifest in Mirador oder Universal Viewer, um die Annotationen zu sehen. Boxen werden zu #xywh=-Fragmenten, Polygone, Polylinien, Ellipsen und Freihandformen zu SVG-Selektoren, Landmarken zu Punktselektoren und Antworten auf Fragen zu Text-Bodys auf dem Canvas, jeweils mit der Potato-Nutzerin oder dem Potato-Nutzer, die oder der sie gezeichnet hat, als creator. --option embed=true legt die Annotationsseiten in die Manifestkopie, sodass nichts weiter gehostet werden muss. Masken haben keine IIIF-Form und werden ausgelassen.

Das Beispiel examples/image/iiif-manifest/ enthält zwei generierte Folios, eines davon mit bereits vorhandenen Annotationen.

W3C Web Annotation

potato import -f web_annotation -i annotations.jsonld -o project --texts documents/

Der Importer akzeptiert eine AnnotationCollection, eine AnnotationPage, eine Liste von Annotationen oder Seiten, eine einzelne Annotation, die Suchantwort der Hypothesis-API und IIIF-2.x-Dateien vom Typ sc:AnnotationList.

Ein Span braucht den Text, auf dem er gezeichnet wurde, und der Importer sucht ihn in --texts: einem Ordner mit Textdateien, die nach dem letzten Pfadsegment jedes Ziels benannt sind, oder einer JSONL- oder JSON-Datei mit Zeilen, die text und eines von source, id, url, uri oder iri enthalten. Wenn eine Position und ein Zitat nicht übereinstimmen, wird der Span über sein Zitat neu gefunden, wobei prefix und suffix zwischen wiederholten Vorkommen entscheiden. Pixelregionen brauchen die Bildgröße, die aus Zeilen in --texts, aus der Bilddatei oder aus der viewBox eines SVG-Selektors kommt. Pixelregionen auf einem Bild unbekannter Größe werden mit einer Warnung ausgelassen, statt in einem geschätzten Maßstab platziert zu werden.

Der creator jeder Annotation wird zur Antwort dieser Person, und mit --keep-annotators werden diese Antworten als die gespeicherte Arbeit jeder Person geschrieben. Ein Creator vom Typ Software wird als das Modell erfasst, das den Vorschlag gemacht hat. Der Export web_annotation schreibt web_annotations.jsonld, eine AnnotationCollection aus allen Spans, Regionen und Antworten.

PAGE XML und Korrektur von HTR-Zeilen

potato import -f page_xml -i transkribus-export/ -o htr-project                 # lines (default)
potato import -f page_xml -i transkribus-export/ -o layout-project --page-xml-mode regions

Die Eingabe ist eine einzelne .xml-Datei oder ein Ordner, der rekursiv durchsucht wird, sodass ein Transkribus-Export mit seinem Unterordner page/ funktioniert. Das Bild jeder Seite wird neben der XML-Datei, einen Ordner höher und in --image-dir gesucht. Gelesen werden die Schemaversionen 2013-07-15 und 2019-07-15.

Der Zeilenmodus, der Standard, erzeugt ein Item pro TextLine in der Lesereihenfolge der Seite. Der Annotator sieht die Zeile, mit der Anzeige image_region aus der Seite ausgeschnitten, und korrigiert den erkannten Text in einem text_edit-Schema, das vom Text der Zeile ausgeht und einen Wortvergleich (Diff) dazu zeigt. Wenn die Erkennung eine Konfidenz gespeichert hat, wird sie als htr_confidence übernommen. Der Regionenmodus erzeugt ein Item pro Seite, wobei jede Region und jede Textzeile als Polygon in einem image_annotation-Schema namens layout erscheint, beschriftet nach Regionstyp.

image_region zeigt ein Rechteck aus einem größeren Bild. Der Browser lädt das Seitenbild einmal herunter und schneidet es zu, sodass das Wechseln zwischen den Zeilen einer Seite es nicht erneut herunterlädt:

instance_display:
  fields:
    - key: line_image
      type: image_region
      label: Line
      padding: 12

{"image": "/media/page-001.png", "width": 2480, "height": 3508,
 "region": [412, 980, 1630, 96],
 "polygon": [[412, 980], [2042, 984], [2040, 1076], [410, 1072]]}

python -m potato.export -c htr-project/config.yaml -f page_xml -o out

Der Exporter öffnet die Kopie jeder Datei im Projekt, ändert nur das Korrigierte und schreibt alles andere unverändert zurück, einschließlich Metadaten, Lesereihenfolge und Schemaversion. Eine korrigierte Zeile erhält ihren neuen Text, und die Konfidenz der Erkennung wird entfernt. Im Layoutmodus aktualisieren verschobene Formen die Koordinaten ihres Elements, neue Formen werden zu neuen Zeilen oder Regionen, und gelöschte werden samt ihrem Verweis in der Lesereihenfolge entfernt. Zeilen, die niemand annotiert hat, bleiben unverändert.

Das Beispiel examples/text/htr-line-correction/ enthält ein generiertes Seitenbild mit fünf Zeilen und eine PAGE-XML-Datei, deren erkannter Text zu korrigierende Fehler enthält.

TEI P5

potato import -f tei -i edition/ -o tei-project              # one item per block
potato import -f tei -i letters.xml -o tei-project --tei-unit div

--tei-unit legt fest, was als ein Item zählt: p (Absätze, Überschriften und Zeilengruppen, der Standard), div, s oder l. Inline-Elemente <persName>, <placeName>, <orgName>, <geogName>, <name>, <date> und <time> werden zu Spans, die mit dem Elementnamen beschriftet sind, und <rs type="ship"> erhält das Label ship. Der Item-Text ist ein Lesetext: <choice> nimmt die normalisierte, korrigierte oder aufgelöste Form, <del>, <note> und <fw> werden ausgelassen, <lb/> ist ein Zeilenumbruch, und <gap/> ist [...].

Der Export tei schreibt ein TEI-Dokument pro Quelldatei und umschließt jeden Span mit seinem Label, wenn das Label ein TEI-Namenselement ist, und sonst mit <rs type="LABEL">. Ein Span, der einen anderen kreuzt, lässt sich in XML nicht verschachteln, daher kommt er als string-range-Annotation in <standOff><listAnnotation>, und die Exportzusammenfassung berichtet, wie viele das betraf. Der Exporter baut ein neues Dokument aus dem Projekt und bearbeitet die Quelldatei nicht, sodass Header-Metadaten außer dem Titel nicht übernommen werden.

Zooniverse

potato import liest die Exporte eines Zooniverse-Projekts: Die Tasks des Workflows werden zu Annotationsschemata, die Subjects zu Items, und die Klassifikationen der Freiwilligen können als deren gespeicherte Arbeit übernommen werden. Das eignet sich, um einen Workflow privat auszuführen, mit unveröffentlichten Daten, einem Laborteam oder bezahlten Annotatoren, oder um die Übereinstimmung auf den Klassifikationen eines bestehenden Projekts zu berechnen.

Fordern Sie im Projekt unter Lab → Data Exports die Workflow-, Klassifikations- und Subject-Exporte an und legen Sie die drei CSV-Dateien in einen Ordner:

potato import -i zooniverse-exports/ -o my-project --keep-annotators

Zooniverse zeigt Tasks nacheinander, Potato zeigt sie auf einer Seite und blendet jeden ein, sobald die Antworten gegeben sind, die zu ihm führen. Eine Workflow-Version wird importiert, standardmäßig die neueste Hauptversion, die die Klassifikationen verwenden. Survey-Tasks (Artbestimmung mit Folgefragen), Fragen in Zeichen-Subtasks, Transkriptions-Tasks und Klassifikationen, die mehrere Subjects umfassen, werden in der Ausgabe gezählt und nicht importiert. Freiwillige, die nicht angemeldet waren, erscheinen als anon_<id>, sodass eine Person als mehrere auftauchen kann.

Weiterführende Informationen

• Projekte importieren - Alle Formate, die potato import liest
• Bildannotation - Boxen, Polygone und Landmarken
• Kamerafallen - Bildsichtung in der Bürgerwissenschaft mit Detektorausgabe
• Inter-Annotator-Übereinstimmung - Übereinstimmung bei importierten Klassifikationen von Freiwilligen

Implementierungsdetails finden Sie in der Quelldokumentation zu Formaten der Digital Humanities und zu Zooniverse.