Humanidades digitales en Potato: IIIF, Web Annotation, PAGE XML, TEI y Zooniverse

Potato 2.12.0 lee y escribe cuatro formatos de intercambio que se usan en las humanidades digitales: manifiestos IIIF, W3C Web Annotation, PAGE XML y TEI. Cada importador construye un proyecto ejecutable a partir de un manifiesto de una biblioteca, una colección de anotaciones, una exportación de Transkribus o eScriptorium, o una edición TEI, y cada exportador vuelve a escribir el trabajo corregido en el formato del que procede. Un flujo de trabajo de Zooniverse y sus clasificaciones se importan del mismo modo.

Las anotaciones del origen llegan como preanotaciones, que un anotador ve como punto de partida y que solo se guardan cuando alguien guarda.

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>

Los archivos locales solo se copian desde la carpeta de entrada. Un importador copia una imagen o un texto local en la carpeta media/ del proyecto solo cuando el archivo está dentro de la carpeta que importas, o de una carpeta que nombras con --image-dir o --texts. Cualquier otra referencia, como una ruta absoluta, un URI file://, una ruta ../ o un enlace simbólico que salga de la carpeta, se omite con una advertencia, porque el servidor publica media/. Mueve el archivo a la carpeta de entrada y vuelve a importar.

Manifiestos IIIF

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

La entrada es un archivo de manifiesto, una carpeta que contenga uno, o una URL http(s). Una URL es la única entrada que hace que el importador use la red: descarga el manifiesto y las páginas de anotación que el manifiesto referencia por URL. Para un manifiesto local, las páginas referenciadas se leen de archivos del mismo nombre que estén a su lado.

Cada Canvas se convierte en un ítem. La imagen es el id del cuerpo de la anotación de pintura o, cuando el cuerpo no tiene un id utilizable o se indica --iiif-size, una petición al servicio Image del cuerpo con ese tamaño (por defecto !2000,2000). Las etiquetas y los metadata del manifiesto y del canvas se muestran encima de la imagen. Las páginas de anotación del canvas se convierten en formas de un esquema image_annotation llamado regions, con sus etiquetas tomadas de las etiquetas (tags) de las anotaciones. Las coordenadas del canvas se convierten, así que un canvas cuyo tamaño difiere del tamaño en píxeles de la imagen sigue coincidiendo. Los manifiestos de Presentation 2.x se leen en la medida de lo posible.

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

El exportador escribe una página de anotación por cada canvas anotado en out/annotations/<canvas>.json, y una copia del manifiesto en out/manifest.json con una referencia a cada página, en la misma versión que el manifiesto. Abre el manifiesto copiado en Mirador o Universal Viewer para ver las anotaciones. Los rectángulos se convierten en fragmentos #xywh=, los polígonos, polilíneas, elipses y formas a mano alzada se convierten en selectores SVG, los puntos de referencia se convierten en selectores de punto, y las respuestas a las preguntas se convierten en cuerpos textuales sobre el canvas, cada uno con el usuario de Potato que lo dibujó como creator. --option embed=true pone las páginas de anotación dentro de la copia del manifiesto, así que no hace falta alojar nada más. Las máscaras no tienen forma en IIIF y se dejan fuera.

El ejemplo examples/image/iiif-manifest/ tiene dos folios generados, uno de ellos con anotaciones ya hechas.

W3C Web Annotation

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

El importador acepta una AnnotationCollection, una AnnotationPage, una lista de anotaciones o de páginas, una sola Annotation, la respuesta de búsqueda de la API de Hypothesis y archivos sc:AnnotationList de IIIF 2.x.

Un tramo necesita el texto sobre el que se marcó, que el importador busca en --texts: una carpeta de archivos de texto con el nombre del último segmento de la ruta de cada destino, o un archivo JSONL o JSON de filas con text y uno de source, id, url, uri o iri. Cuando una posición y una cita no coinciden, el tramo se vuelve a localizar por su cita, y prefix y suffix deciden entre apariciones repetidas. Las regiones en píxeles necesitan el tamaño de la imagen, que procede de las filas de --texts, del archivo de imagen o del viewBox de un selector SVG. Las regiones en píxeles sobre una imagen de tamaño desconocido se dejan fuera con una advertencia, en lugar de colocarse a una escala supuesta.

El creator de cada anotación se convierte en la respuesta de esa persona, y con --keep-annotators esas respuestas se escriben como el trabajo guardado de cada persona. Un creador de tipo Software se registra como el modelo que hizo la sugerencia. La exportación web_annotation escribe web_annotations.jsonld, una AnnotationCollection con todos los tramos, regiones y respuestas.

PAGE XML y corrección de líneas de HTR

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

La entrada es un archivo .xml o una carpeta, que se recorre de forma recursiva, así que funciona una exportación de Transkribus con su subcarpeta page/. La imagen de cada página se busca junto al XML, una carpeta más arriba y en --image-dir. Se leen las versiones del esquema 2013-07-15 y 2019-07-15.

El modo de líneas, el modo por defecto, crea un ítem por cada TextLine, en el orden de lectura de la página. El anotador ve la línea recortada de la página con la visualización image_region y corrige el texto reconocido en un esquema text_edit, que parte del texto de la línea y muestra una diferencia por palabras respecto a él. Cuando el reconocedor guardó una confianza, llega como htr_confidence. El modo de regiones crea un ítem por página, con cada región y línea de texto como un polígono en un esquema image_annotation llamado layout, etiquetado según el tipo de región.

image_region muestra un rectángulo de una imagen más grande. El navegador descarga la imagen de la página una sola vez y la recorta, así que pasar de una línea a otra de la misma página no la vuelve a descargar:

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

El exportador abre la copia de cada archivo que tiene el proyecto, cambia solo lo que se corrigió y vuelve a escribir todo lo demás como estaba, incluidos los metadatos, el orden de lectura y la versión del esquema. Una línea corregida recibe su texto nuevo, y se elimina la confianza del reconocedor. En el modo de maquetación, las formas movidas actualizan las coordenadas de su elemento, las formas nuevas se convierten en líneas o regiones nuevas, y las eliminadas se quitan junto con su referencia en el orden de lectura. Las líneas que nadie anotó se dejan sin cambios.

El ejemplo examples/text/htr-line-correction/ tiene una imagen de página generada con cinco líneas y un archivo PAGE XML cuyo texto reconocido tiene errores que corregir.

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 fija qué cuenta como un ítem: p (párrafos, encabezados y grupos de versos, el valor por defecto), div, s o l. Los elementos en línea <persName>, <placeName>, <orgName>, <geogName>, <name>, <date> y <time> se convierten en tramos etiquetados con el nombre del elemento, y <rs type="ship"> se etiqueta como ship. El texto del ítem es un texto de lectura: <choice> toma la forma regularizada, corregida o desarrollada, <del>, <note> y <fw> se dejan fuera, <lb/> es un salto de línea y <gap/> es [...].

La exportación tei escribe un documento TEI por archivo de origen, y envuelve cada tramo en su etiqueta cuando la etiqueta es un elemento de nombre de TEI y en <rs type="LABEL"> en caso contrario. Un tramo que se cruza con otro no puede anidarse en XML, así que va a <standOff><listAnnotation> como una anotación string-range, y el resumen de la exportación informa de cuántos lo hicieron. El exportador construye un documento nuevo a partir del proyecto y no edita el archivo de origen, así que los metadatos de la cabecera distintos del título no se trasladan.

Zooniverse

potato import lee las exportaciones de un proyecto de Zooniverse: las tareas del flujo de trabajo se convierten en esquemas de anotación, los sujetos se convierten en ítems, y las clasificaciones de los voluntarios pueden llegar como su trabajo guardado. Sirve para ejecutar un flujo de trabajo en privado, con datos no publicados, un equipo de laboratorio o anotadores remunerados, o para calcular la concordancia sobre las clasificaciones de un proyecto existente.

Desde Lab → Data Exports del proyecto, solicita las exportaciones del flujo de trabajo, de las clasificaciones y de los sujetos, y pon los tres archivos CSV en una carpeta:

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

Zooniverse muestra las tareas una detrás de otra, y Potato las muestra en una sola página, y revela cada una cuando se dan las respuestas que llevan a ella. Se importa una versión del flujo de trabajo, por defecto la versión principal más reciente que usan las clasificaciones. Las tareas de tipo survey (identificación de especies con preguntas de seguimiento), las preguntas de subtareas de dibujo, las tareas de transcripción y las clasificaciones que abarcan varios sujetos se cuentan en la salida y no se importan. Los voluntarios que no habían iniciado sesión aparecen como anon_<id>, así que una misma persona puede aparecer como varias.

Lecturas adicionales

• Importar proyectos - Todos los formatos que lee potato import
• Anotación de imágenes - Rectángulos, polígonos y puntos de referencia
• Cámaras trampa - Revisión de imágenes de ciencia ciudadana con la salida de un detector
• La concordancia entre anotadores - Concordancia sobre clasificaciones de voluntarios importadas

Para detalles de implementación, consulta la documentación fuente sobre los formatos de humanidades digitales y sobre Zooniverse.