Telar: Docs Telar: Documentación

Integración IIIF

Telar usa el Marco Internacional de Interoperabilidad de Imágenes (IIIF) para mostrar imágenes de alta resolución que pueden ampliarse, desplazarse y explorarse en detalle.

¿Qué es IIIF?

IIIF (pronunciado “triple-i-efe”) es un conjunto de estándares abiertos para entregar objetos digitales de alta calidad y atribuidos en internet. Te permite:

Aprende más sobre IIIF

Opción 1: imágenes locales

Sube tus propias imágenes y Telar generará automáticamente teselas (tiles) IIIF.

Agrega imágenes locales

Desde la interfaz web de GitHub:

  1. Navega a components/images/ en tu repositorio
  2. Haz clic en Add file → Upload files
  3. Arrastra imágenes al área de carga
  4. Nombra archivos para que coincidan con IDs de objeto (ej., textile-001.jpg)
  5. Confirma cambios

En desarrollo local:

  1. Agrega imágenes de alta resolución a components/images/
  2. Genera teselas IIIF: 
    python3 scripts/generate_iiif.py --base-url http://localhost:4001

Procesamiento a partir de CSV/Sheets Desde la v0.5.0, Telar solo genera teselas (tiles) IIIF para los objetos que aparecen en la hoja objects de Google Sheets o en objects.csv, siempre y cuando estos no tengan un manifiesto IIIF externo. Esto es automático: simplemente agrega tus imágenes y ejecuta el script.

Requisitos de archivo

Las fotos de iPhone funcionan directamente Desde la v0.5.0, las fotos HEIC de iPhone funcionan de manera nativa - no necesitas convertirlas a otro formato manualmente. El generador IIIF las convierte automáticamente a JPEG durante la generación de teselas (tiles) preservando tus archivos originales.

Convención de nombres Usa IDs simples y descriptivos sin espacios y sin caracteres especiales: textile-001.jpg, ceramic-bowl-blue.jpg

Cómo funciona

Cuando agregas una imagen:

  1. El generador IIIF crea versiones en teselas a múltiples niveles de zoom
  2. Las teselas se guardan en iiif/objects/[object-id]/
  3. Un archivo de manifiesto describe la estructura de la imagen
  4. El UniversalViewer carga teselas progresivamente según sea necesario

Esto permite un zoom fluido incluso en imágenes muy grandes.

Opción 2: recursos IIIF externos

Referencia imágenes IIIF de museos, bibliotecas y otras instituciones de todo el mundo.

Encuentra recursos IIIF

Muchas instituciones proporcionan manifiestos IIIF:

Agrega IIIF externo

En tu CSV de objetos u hoja de Google:

  1. Crea un object_id (ej., museum-textile-001)
  2. Agrega la URL del manifiesto IIIF en la columna source_url: 
    https://example.org/iiif/image/abc123/info.json

Formatos de URL de manifiesto

Las URLs IIIF típicamente se ven así:

Telar soporta ambos formatos.

Mezcla local y externo

Puedes usar imágenes IIIF locales y externas en el mismo proyecto:

object_id,title,...,source_url
local-textile-001,Mi Textil,,,
museum-textile-002,Textil de Museo,...,https://example.org/iiif/manifest.json
local-ceramic-001,Mi Cerámica,,,

Deja source_url en blanco para imágenes locales.

Autorrelleno de metadatos

Telar v0.4.0+ puede extraer automáticamente metadatos de objetos desde manifiestos IIIF, lo que reduce la carga de digitación manual y mejora la consistencia.

Cómo funciona

Cuando proporcionas una URL en source_url, Telar intenta extraer automáticamente:

Versiones de IIIF compatibles

Telar es compatible con las dos versiones de la API de Presentación de IIIF:

El sistema detecta automáticamente la versión y usa la estructura de metadatos correspondiente.

Cómo usarlo

Simplemente agrega la URL del manifiesto IIIF a tu CSV de objetos o a la hoja de Google y deja los demás campos vacíos:

object_id,title,description,source_url,creator,period,location,credit
map-001,,,https://example.org/iiif/manifest.json,,,,

Cuando el sitio se construye, Telar:

  1. Obtiene el manifiesto IIIF
  2. Extrae los campos de metadatos disponibles
  3. Llena los campos vacíos con la información extraída
  4. Respeta los valores que tú hayas escrito en el CSV

Control de sobrescritura

Tu CSV siempre tiene prioridad. Puedes:

Ejemplo - sobrescritura parcial:

object_id,title,description,source_url,creator,period,location,credit
map-001,Mi título personalizado,,https://example.org/manifest.json,,,,

Telar hará lo siguiente:

Detección de idioma

La extracción respeta la configuración telar_language en _config.yml:

Si el manifiesto ofrece metadatos multilingües, Telar selecciona el idioma más apropiado para tu sitio.

Detección inteligente de créditos

Para el campo credit, Telar aplica una lógica de respaldo inteligente:

  1. Busca campos llamados “Attribution” o “Rights”
  2. Filtra texto legal (URLs de Creative Commons, avisos de derechos)
  3. Usa el nombre del repositorio si no encuentra una atribución específica

Así obtienes líneas de crédito útiles en lugar de texto legal extenso.

Validación

Durante la build, Telar valida los manifiestos IIIF:

Revisa los registros de la build para conocer el estado de la extracción y posibles advertencias.

Procesamiento durante la build

La extracción de metadatos ocurre durante el paso python3 scripts/csv_to_json.py:

GitHub Pages: Se ejecuta automáticamente durante el despliegue. Desarrollo local: Ejecútalo manualmente cuando actualices manifiestos:

python3 scripts/csv_to_json.py

Ejemplo de flujo de trabajo

  1. Busca una URL de manifiesto IIIF de un museo o biblioteca
  2. Agrégala a tu CSV de objetos con solo object_id y source_url
  3. Construye tu sitio
  4. Revisa la página del objeto: los metadatos deberían aparecer completos
  5. Sobrescribe cualquier campo que necesite ajustes

Campos comunes de metadatos

Cada institución nombra los campos de manera diferente. Telar busca variaciones frecuentes:

Para title:

Para description:

Para creator:

Para period:

Para location:

Para credit:

Cuándo sobrescribir

Quizás quieras sobrescribir metadatos extraídos cuando:

Limitaciones

Sistema de coordenadas

Las coordenadas IIIF en Telar usan valores normalizados (0-1):

Cómo encontrar coordenadas

Usa la herramienta de identificación de coordenadas integrada:

  1. Navega a cualquier página de objeto
  2. Haz clic en el botón Identify coordinates
  3. Desplaza y amplía a la vista deseada
  4. Copia los valores X, Y y Zoom
  5. Pega en tu CSV de historia o hoja de Google

Consejo pro La herramienta de coordenadas tiene un botón “Copy entire row” que copia una plantilla de fila CSV completa con las coordenadas ya llenadas.

Solución de problemas

La imagen no carga

Para imágenes locales:

Para IIIF externo:

Visualización de baja calidad

Carga lenta

Próximos pasos