Visualización de Instancias

Separa la visualización del contenido de la anotación con el bloque de configuración instance_display.

Visualización de Instancias

Nuevo en v2.1.0

La visualización de instancias separa qué contenido mostrar a los anotadores de qué anotaciones recopilar. Esto permite mostrar cualquier combinación de tipos de contenido (imágenes, videos, audio, texto) junto con cualquier esquema de anotación (botones de radio, casillas de verificación, segmentos, etc.).

¿Por Qué Usar Visualización de Instancias?

Anteriormente, si querías mostrar una imagen con botones de radio para clasificación, tenías que añadir un esquema image_annotation con min_annotations: 0 solo para mostrar la imagen. Esto era confuso y semánticamente incorrecto.

Con instance_display, configuras explícitamente qué contenido mostrar:

yaml

# OLD (deprecated workaround)
annotation_schemes:
  - annotation_type: image_annotation
    name: image_display
    min_annotations: 0  # Just to show the image
    tools: [bbox]
    labels: [unused]
  - annotation_type: radio
    name: category
    labels: [A, B, C]
 
# NEW (recommended)
instance_display:
  fields:
    - key: image_url
      type: image
 
annotation_schemes:
  - annotation_type: radio
    name: category
    labels: [A, B, C]

Configuración Básica

Añade una sección instance_display a tu configuración YAML:

yaml

instance_display:
  fields:
    - key: "image_url"           # Field name in your data JSON
      type: "image"              # Content type
      label: "Image to classify" # Optional header
      display_options:
        max_width: 600
        zoomable: true
 
  layout:
    direction: "vertical"        # vertical or horizontal
    gap: "20px"

Tipos de Visualización Soportados

Tipo	Descripción	Objetivo de Segmento
`text`	Contenido de texto plano	Sí
`html`	Contenido HTML sanitizado	No
`image`	Visualización de imagen con zoom	No
`video`	Reproductor de video	No
`audio`	Reproductor de audio	No
`dialogue`	Turnos de conversación	Sí
`pairwise`	Comparación lado a lado	No
`code`	Código fuente con resaltado de sintaxis	Sí
`spreadsheet`	Datos tabulares (Excel/CSV)	Sí (fila/celda)
`document`	Documentos enriquecidos (Word, Markdown, HTML)	Sí
`pdf`	Documentos PDF con controles de página	Sí

Opciones de Tipo de Visualización

Visualización de Texto

yaml

- key: "text"
  type: "text"
  label: "Document"
  display_options:
    collapsible: false        # Make content collapsible
    max_height: 400           # Max height in pixels before scrolling
    preserve_whitespace: true # Preserve line breaks and spacing

Visualización de Imagen

yaml

- key: "image_url"
  type: "image"
  label: "Image"
  display_options:
    max_width: 800            # Max width (number or CSS string)
    max_height: 600           # Max height
    zoomable: true            # Enable zoom controls
    alt_text: "Description"   # Alt text for accessibility
    object_fit: "contain"     # CSS object-fit property

Visualización de Video

yaml

- key: "video_url"
  type: "video"
  label: "Video"
  display_options:
    max_width: 800
    max_height: 450
    controls: true            # Show video controls
    autoplay: false           # Auto-play on load
    loop: false               # Loop playback
    muted: false              # Start muted

Visualización de Audio

yaml

- key: "audio_url"
  type: "audio"
  label: "Audio"
  display_options:
    controls: true            # Show audio controls
    autoplay: false
    loop: false
    show_waveform: false      # Show waveform visualization

Visualización de Diálogo

yaml

- key: "conversation"
  type: "dialogue"
  label: "Conversation"
  display_options:
    alternating_shading: true    # Alternate background colors
    speaker_extraction: true     # Extract "Speaker:" from text
    show_turn_numbers: false     # Show turn numbers

Formato de datos para diálogo (cada línea en archivo JSONL):

json

{"id": "conv_001", "conversation": ["Speaker A: Hello there!", "Speaker B: Hi, how are you?"]}

O con datos estructurados:

json

{"id": "conv_001", "conversation": [{"speaker": "Alice", "text": "Hello there!"}, {"speaker": "Bob", "text": "Hi, how are you?"}]}

Visualización por Pares

yaml

- key: "comparison"
  type: "pairwise"
  label: "Compare Options"
  display_options:
    cell_width: "50%"           # Width of each cell
    show_labels: true           # Show A/B labels
    labels: ["Option A", "Option B"]
    vertical_on_mobile: true    # Stack vertically on mobile

Opciones de Diseño

Controla cómo se organizan múltiples campos:

yaml

instance_display:
  layout:
    direction: horizontal  # horizontal or vertical
    gap: 24px              # Space between fields

Soporte de Anotación de Segmentos

Los tipos de visualización basados en texto (text, dialogue) pueden ser objetivos para la anotación de segmentos:

yaml

instance_display:
  fields:
    - key: "document"
      type: "text"
      span_target: true  # Enable span annotation on this field
 
annotation_schemes:
  - annotation_type: span
    name: entities
    labels: [PERSON, LOCATION, ORG]

Múltiples Objetivos de Segmentos

Puedes tener múltiples campos de texto que soporten anotación de segmentos:

yaml

instance_display:
  fields:
    - key: "source_text"
      type: "text"
      label: "Source Document"
      span_target: true
 
    - key: "summary"
      type: "text"
      label: "Summary"
      span_target: true
 
annotation_schemes:
  - annotation_type: span
    name: factual_errors
    labels: [contradiction, unsupported, fabrication]

Cuando se utilizan múltiples objetivos de segmentos, las anotaciones se almacenan con asociación de campo:

json

{
  "factual_errors": {
    "source_text": [],
    "summary": [
      {"start": 45, "end": 67, "label": "unsupported"}
    ]
  }
}

Vincular Esquemas de Anotación a Campos de Visualización

Para esquemas de anotación multimedia (image_annotation, video_annotation, audio_annotation), vincúlalos a campos de visualización usando source_field:

yaml

instance_display:
  fields:
    - key: "image_url"
      type: "image"
 
annotation_schemes:
  - annotation_type: image_annotation
    source_field: "image_url"  # Links to display field
    tools: [bbox]
    labels: [person, car]

Calificaciones por Turno de Diálogo

Añade widgets de calificación en línea a turnos individuales del diálogo:

yaml

instance_display:
  fields:
    - key: conversation
      type: dialogue
      label: "Conversation"
      display_options:
        show_turn_numbers: true
        per_turn_ratings:
          speakers: ["Agent"]          # Only show ratings for these speakers
          schema_name: "turn_quality"  # Name for the stored annotation data
          scheme:
            type: likert
            size: 5
            labels: ["Poor", "Excellent"]

Los círculos de calificación aparecen en línea debajo del turno de cada hablante correspondiente. Las calificaciones se llenan hasta el valor seleccionado, y todas las calificaciones por turno se almacenan como un solo objeto JSON:

json

{
  "turn_quality": "{\"0\": 4, \"2\": 5, \"4\": 3}"
}

Ejemplo: Clasificación de Imágenes

yaml

annotation_task_name: "Image Classification"
 
data_files:
  - data/images.json
 
item_properties:
  id_key: id
  text_key: image_url
 
task_dir: .
output_annotation_dir: annotation_output
 
instance_display:
  fields:
    - key: image_url
      type: image
      label: "Image to Classify"
      display_options:
        max_width: 600
        zoomable: true
 
    - key: context
      type: text
      label: "Additional Context"
      display_options:
        collapsible: true
 
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "What category best describes this image?"
    labels:
      - nature
      - urban
      - people
      - objects
 
user_config:
  allow_all_users: true

Archivo de datos de ejemplo (data/images.json) en formato JSONL:

json

{"id": "img_001", "image_url": "https://example.com/image1.jpg", "context": "Taken in summer 2023"}
{"id": "img_002", "image_url": "https://example.com/image2.jpg", "context": "Winter landscape"}

Ejemplo: Anotación Multimodal

Video junto con una transcripción con anotación de segmentos:

yaml

annotation_task_name: "Video Analysis"
 
instance_display:
  layout:
    direction: horizontal
    gap: 24px
 
  fields:
    - key: video_url
      type: video
      label: "Video"
      display_options:
        max_width: "45%"
 
    - key: transcript
      type: text
      label: "Transcript"
      span_target: true
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    labels: [positive, neutral, negative]
 
  - annotation_type: span
    name: highlights
    labels:
      - key_point
      - question
      - supporting_evidence

Compatibilidad con Versiones Anteriores

Las configuraciones existentes sin instance_display siguen funcionando sin cambios
El text_key de item_properties se sigue usando como respaldo
La detección heredada de multimedia mediante esquemas de anotación sigue funcionando
Aparece una advertencia de deprecación en los registros cuando se usa el patrón antiguo de solo visualización

Migración desde Patrones de Solo Visualización

Si estabas usando esquemas de anotación solo para mostrar contenido:

Antes (deprecado):

yaml

annotation_schemes:
  - annotation_type: image_annotation
    name: image_display
    min_annotations: 0
    tools: [bbox]
    labels: [unused]

Después (recomendado):

yaml

instance_display:
  fields:
    - key: image_url
      type: image

Lectura Adicional

Formatos de Datos - Formatos de datos de entrada soportados
Configuración de UI - Personalización de la interfaz
Personalización de Diseño - Plantillas HTML personalizadas
Anotación de Imágenes - Herramientas de anotación de imágenes

Para detalles de implementación, consulta la documentación fuente.