Skip to content

Come annotare documenti e PDF

Annota contratti, report e articoli come documenti invece che come testo appiattito, conservando impaginazione, numeri di pagina e riferimenti tra pagine.

Annota un documento sulle sue pagine renderizzate invece che sul testo estratto da esso, perché l'impaginazione porta un significato che l'estrazione butta via e perché chi revisiona deve ritrovare l'etichetta sulla pagina. Appiattire un contratto in una stringa fa perdere il numero di pagina, l'ordine delle colonne, la struttura della tabella e la differenza fra una nota a piè di pagina e il corpo del testo.

L'annotazione di documenti è il caso in cui il solito impianto di annotazione testuale non regge. Un PDF è una descrizione di segni su pagine e non una sequenza di caratteri, quindi due estrattori diversi ti consegneranno due stringhe diverse dallo stesso file. Le pagine a più colonne si intrecciano, intestazioni e piè di pagina spuntano in mezzo al flusso e le tabelle diventano sequenze di spazi. Chi etichetta quella stringa sta etichettando un artefatto dell'estrattore, e chi apre poi l'originale non sempre riesce a dire a quale passaggio si riferisse uno span.

Posizione, numero di pagina e struttura dei riferimenti

Tre proprietà di un documento sopravvivono sulla pagina e non nel suo testo estratto. La posizione dice a chi revisiona se una clausola è un titolo, una nota a piè di pagina o corpo del testo, e l'estrazione riduce tutte e tre alla stessa sequenza indifferenziata di caratteri. Il numero di pagina è ciò con cui ogni lettore successivo citerà il passaggio, ed esiste solo finché esistono le pagine. La struttura dei riferimenti registra a cosa punta un passaggio, e questo conta ogni volta che un'affermazione su una pagina poggia su una tabella nove pagine più avanti.

La terza proprietà è quella che più spesso costringe a cambiare strumento. La struttura dei riferimenti dentro un documento è una relazione fra due posizioni, e uno strumento che modella un documento come un'unica stringa piatta non ha dove mettere la seconda posizione. Revisione legale, verifica di affermazioni scientifiche e analisi di bilanci ruotano tutte attorno a quella relazione.

Tre tipi di ancoraggio

Un'annotazione su un documento si ancora in uno di tre modi, e la scelta discende dalla domanda e non dalla preferenza.

  • Gli span di testo si ancorano alle parole selezionate e servono per le domande sulla formulazione. Uno span richiede che il documento abbia un livello di testo, che i PDF nati digitali hanno e le scansioni no.
  • I riquadri di regione si ancorano alle coordinate della pagina e servono per figure, tabelle, timbri, firme e tutto ciò che un livello di testo non ha mai catturato. Funzionano su una scansione senza alcuna estrazione di testo.
  • I collegamenti uniscono due ancoraggi e servono per la struttura dei riferimenti. Un collegamento registra una relazione tipizzata, eventualmente orientata, fra due punti del documento.

Mescolare tipi di ancoraggio in un'unica attività è normale. Un'attività di verifica delle affermazioni segna le affermazioni come span di testo, le tabelle come riquadri di regione e le unisce con collegamenti.

Come configurarlo in Potato

Il display pdf di Potato renderizza il file con PDF.js e mette la superficie di annotazione sulla pagina renderizzata. L'opzione annotation_mode seleziona il tipo di ancoraggio e accetta span, bounding_box o link. La modalità link è quella che risponde alla domanda sui riferimenti, e registra ancoraggi e collegamenti sotto nomi di schema separati, così i due escono dall'export distinguibili.

yaml
instance_display:
  fields:
    - key: pdf
      type: pdf
      label: "Document"
      display_options:
        annotation_mode: link
        view_mode: scroll
        zoom: page-width
        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
            allowed_source_labels: [claim]
            allowed_target_labels: [figure]

view_mode: scroll impila le pagine in un unico contenitore, così un collegamento fra pagina 2 e pagina 9 può essere tracciato e visto come un solo arco. L'alternativa paginata mostra una pagina per volta, cosa che si legge meglio su un documento lungo ma nasconde l'estremo lontano di un collegamento fra pagine mentre chi annota lo traccia.

allowed_source_labels e allowed_target_labels sono ciò che trasforma una linea guida in qualcosa che l'interfaccia fa rispettare. Con la configurazione qui sopra, un collegamento refers_to può partire solo da un'affermazione e finire solo su una figura, così chi annota non può registrare la relazione al contrario. Le linee guida che vivono solo in un documento vengono seguite in modo disomogeneo, e un vincolo che applica lo strumento non costa nulla da far rispettare.

Un file Word o Markdown usa invece il display document, che conserva la struttura di titoli e paragrafi e accetta span_target, così uno schema di span può puntarci direttamente.

Documenti scansionati

Una scansione non porta con sé un livello di testo, quindi gli ancoraggi testuali non hanno a cosa attaccarsi. Esistono due possibilità e servono per corpora diversi. Annotare per regione non richiede testo alcuno e funziona subito. Attivare l'OCR costruisce un livello di testo lato server e rende possibili gli ancoraggi testuali, al prezzo di una passata lenta e di una dipendenza da Tesseract.

yaml
instance_display:
  fields:
    - key: pdf
      type: pdf
      display_options:
        annotation_mode: link
        ocr: auto

auto esegue l'OCR solo quando il livello di testo incorporato torna vuoto, ed è l'impostazione da usare su un corpus che mescola file nati digitali e scansioni. Potato legge l'opzione ocr solo in modalità link.

L'output dell'OCR è imperfetto, e un'annotazione ancorata a una parola riconosciuta male ne eredita l'errore. Su un corpus in cui la qualità di riconoscimento è scarsa, gli ancoraggi di regione danno una traccia più durevole di quelli testuali, perché un riquadro tracciato attorno a un passaggio resta corretto comunque siano stati letti i caratteri sottostanti.

Verificare un'etichetta sulla fonte

Ogni annotazione torna indietro portando la pagina su cui si trova, ed è questo che rende l'etichetta verificabile sulla fonte. Chi revisiona e riceve un numero di pagina e una regione può aprire l'originale e confermare il giudizio. Chi riceve un offset di caratteri in una stringa concatenata di norma non può, perché riprodurre l'offset significa riprodurre esattamente l'estrattore e la versione che l'hanno prodotto.

Dove l'approccio costa più di quanto renda è un corpus di documenti brevi, a colonna singola, nati digitali e senza struttura di riferimenti, dove l'estrazione è affidabile e il numero di pagina non porta nulla. La semplice annotazione a span sul testo estratto lì è più semplice e dà la stessa risposta.

Approfondimenti