Skip to content

Como anotar documentos e PDFs

Anote contratos, relatórios e artigos como documentos em vez de texto achatado, mantendo intactos o layout, os números de página e as referências entre páginas.

Anote um documento nas páginas renderizadas dele em vez de no texto extraído, porque o layout carrega um sentido que a extração descarta e porque quem revisa precisa achar o rótulo na página. Achatar um contrato até virar uma string faz perder o número da página, a ordem das colunas, a estrutura da tabela e a diferença entre uma nota de rodapé e o corpo do texto.

Anotação de documentos é o caso em que a montagem habitual de anotação de texto falha. Um PDF é uma descrição de marcas em páginas e não uma sequência de caracteres, então dois extratores diferentes vão te devolver duas strings diferentes do mesmo arquivo. Páginas de várias colunas se entrelaçam, cabeçalhos e rodapés aparecem no meio do fluxo, e tabelas viram corridas de espaço em branco. Quem rotula essa string está rotulando um artefato do extrator, e quem depois abre o original nem sempre consegue dizer a que passagem um trecho se referia.

Posição, número de página e estrutura de referência

Três propriedades de um documento sobrevivem na página e não no texto extraído dele. A posição diz a quem revisa se uma cláusula é um título, uma nota de rodapé ou corpo de texto, e a extração reduz as três à mesma corrida indiferenciada de caracteres. O número da página é como todo leitor posterior vai citar a passagem, e ele só existe enquanto as páginas existem. A estrutura de referência registra para o que uma passagem aponta, o que importa sempre que uma afirmação numa página se apoia numa tabela nove páginas adiante.

A terceira propriedade é a que mais frequentemente força uma troca de ferramenta. Estrutura de referência dentro de um documento é uma relação entre dois locais, e uma ferramenta que modela um documento como uma única string plana não tem onde pôr o segundo local. Revisão jurídica, verificação de afirmações científicas e análise de relatórios financeiros giram todas em torno dessa relação.

Três tipos de âncora

Uma anotação sobre um documento é ancorada de uma entre três maneiras, e a escolha decorre da pergunta e não da preferência.

  • Trechos de texto ancoram nas palavras selecionadas e servem para perguntas sobre a redação. Um trecho exige que o documento carregue uma camada de texto, que PDFs nascidos digitais têm e digitalizações não.
  • Caixas de região ancoram em coordenadas de página e servem para figuras, tabelas, carimbos, assinaturas e qualquer coisa que uma camada de texto nunca capturou. Funcionam numa digitalização sem nenhuma extração de texto.
  • Ligações unem duas âncoras e servem para a estrutura de referência. Uma ligação registra uma relação tipada, opcionalmente dirigida, entre dois pontos do documento.

Misturar tipos de âncora numa mesma tarefa é normal. Uma tarefa de verificação de afirmações marca as afirmações como trechos de texto, as tabelas como caixas de região, e une as duas com ligações.

Como configurar no Potato

A exibição pdf do Potato renderiza o arquivo com PDF.js e põe a superfície de anotação sobre a página renderizada. A opção annotation_mode seleciona o tipo de âncora e aceita span, bounding_box ou link. O modo de ligação é o que responde à pergunta das referências, e ele registra âncoras e ligações sob nomes de esquema separados para que as duas saiam distinguíveis da exportação.

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 empilha as páginas num único contêiner, de modo que uma ligação entre a página 2 e a página 9 pode ser traçada e vista como um arco só. A alternativa paginada mostra uma página por vez, o que se lê melhor num documento longo mas esconde a ponta distante de uma ligação entre páginas enquanto quem anota a traça.

allowed_source_labels e allowed_target_labels são o que transforma uma diretriz em algo que a interface faz cumprir. Configurada como acima, uma ligação refers_to só pode começar numa afirmação e só pode terminar numa figura, então quem anota não consegue registrar a relação ao contrário. Diretrizes que vivem apenas num documento são seguidas de forma desigual, e uma restrição que a ferramenta aplica não custa nada para ser cumprida.

Um arquivo Word ou Markdown usa a exibição document em vez dessa, que preserva a estrutura de títulos e parágrafos e aceita span_target, de modo que um esquema de trechos pode apontar direto para ela.

Documentos digitalizados

Uma digitalização não carrega camada de texto, então âncoras de texto não têm onde se prender. Existem duas opções e elas servem a corpora diferentes. Anotar por região não precisa de texto nenhum e funciona de imediato. Ligar o OCR constrói uma camada de texto no servidor e torna as âncoras de texto possíveis, ao custo de uma passagem lenta e de uma dependência do Tesseract.

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

auto roda o OCR apenas quando a camada de texto embutida volta vazia, que é o ajuste para um corpus que mistura arquivos nascidos digitais com digitalizações. O Potato lê a opção ocr apenas no modo de ligação.

A saída do OCR é imperfeita, e uma anotação ancorada numa palavra mal reconhecida herda o erro. Num corpus em que a qualidade de reconhecimento é ruim, âncoras de região dão um registro mais durável do que as de texto, porque uma caixa desenhada em volta de uma passagem continua certa sejam quais forem os caracteres lidos por baixo.

Conferir um rótulo contra a fonte

Toda anotação volta carregando a página em que está, e é isso que torna o rótulo conferível contra a fonte. Quem revisa e recebe um número de página e uma região pode abrir o original e confirmar o julgamento. Quem recebe um deslocamento de caracteres numa string concatenada em geral não pode, porque reproduzir o deslocamento significa reproduzir exatamente o extrator e a versão que o produziram.

Onde a abordagem custa mais do que devolve é num corpus de documentos curtos, de coluna única, nascidos digitais e sem estrutura de referência, em que a extração é confiável e o número da página não carrega nada. A anotação de trechos simples sobre texto extraído é mais simples ali e dá a mesma resposta.

Leitura adicional