De PDF Plano a UI Estruturada: Por Dentro do Pipeline PDF-to-Visual-Struct

Engineering2026-04-23

O problema com PDFs

PDFs estão em todo lugar — especificações de produto, relatórios financeiros, formulários de conformidade, entregas de design legadas — e são quase uniformemente hostis à automação. Um PDF é um fluxo plano de instruções de desenho: "mova para (120, 440), mostre o glifo 'H' em Helvetica 12, mova para a direita, mostre 'e'...". Não existe noção de botão, card ou cabeçalho. Não há hierarquia. Não há sequer um conceito confiável de palavra.

É essa lacuna que o PDF to Visual Struct foi criado para preencher. Envie um PDF para POST /v1/open/pdf_to_design e você recebe de volta o mesmo Visual Element Schema que alimenta o Codia Studio: uma árvore JSON hierárquica de elementos de UI tipados, com bounding boxes, configurações de layout e especificações de estilo. A árvore é legível por máquinas, legível por designers e está a uma transformação de distância de código executável.

Este post percorre o pipeline — o que a API faz, o schema que ela emite e o que você pode construir em cima disso.

Chamando a API

A requisição é um único POST multipart/form-data. Nenhum SDK é necessário.

bash

curl 'https://api.codia.ai/v1/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --form 'pdf_file=@"invoice.pdf"' \
  --form 'page_no="0"'

Duas entradas: o arquivo PDF e um número de página indexado em zero. Se você tem um documento de 40 páginas e quer todas, faça um loop e paralelize — a API é stateless por página e confortável sob concorrência. As metas anunciadas são 100+ páginas por documento, 50+ tipos de elementos e respostas em menos de dois segundos por página. Na prática, a maioria dos PDFs de página única retorna em 600–1200 ms depois que o arquivo chega ao nosso ingress.

Anatomia da resposta

O nível superior se parece com isto:

json

{
  "configuration": {
    "scalingFactor": 1,
    "baseWidth": 1940,
    "measurementUnit": "px"
  },
  "pages": [
    {
      "visualElement": { /* elemento raiz */ }
    }
  ],
  "size": {
    "height": 1080,
    "width": 1940
  }
}

configuration indica como as coordenadas devem ser interpretadas. baseWidth e measurementUnit são o quadro de referência — se você redimensionar sua viewport, escale cada bounding box pela proporção. size é o canvas normalizado para o qual o layout foi resolvido.

Cada página tem um único visualElement raiz. Percorrer seu array childElements é uma travessia recursiva em profundidade do documento. Cada nó carrega os mesmos campos essenciais:

json

{
  "elementId": "pdf_page_1",
  "elementName": "PDF Document Page",
  "elementType": "Panel",
  "displayName": "First Page",
  "displayOrder": 0,
  "boundingBox": [0, 0, 595, 842],
  "layoutConfig": {
    "positionMode": "Normal",
    "flexibleMode": "Absolute"
  },
  "styleConfig": {
    "widthSpec":  { "sizing": "FIXED", "value": 595 },
    "heightSpec": { "sizing": "FIXED", "value": 842 },
    "backgroundSpec": {
      "type": "COLOR",
      "backgroundColor": { "rgbValues": [255, 255, 255] }
    }
  },
  "processingMeta": {
    "surfaceArea": 501490,
    "detectionScore": 0.92,
    "textContainerized": false
  },
  "childElements": []
}

Os campos que vale conhecer:

elementType — o tipo forte. Panel, Text, Image, Icon, Button, Table, Chart e algumas dezenas mais. É isso que torna a saída acionável; você pode usar um switch sobre ele para gerar HTML, widgets Flutter ou componentes React sem heurísticas.
boundingBox — [x, y, width, height] no sistema de coordenadas base. Use para posicionar filhos em layouts absolutos ou para detectar sobreposições e agrupamentos no pós-processamento.
layoutConfig — indica se o pai organizou os filhos como flow, flex row/column ou posicionamento livre (Absolute). Inspirado no modelo de auto-layout do Figma, o que torna a ida e volta com o Figma trivial.
styleConfig — estratégia de dimensionamento de largura/altura (FIXED, FILL_CONTAINER, HUG_CONTENT), preenchimento de fundo, borda, raio de canto, tipografia. Espelha conceitos CSS de forma próxima o suficiente para que geradores consigam emitir folhas de estilo limpas.
processingMeta.detectionScore — uma confiança de 0 a 1 que o detector tem neste elemento. Útil quando você quer descartar nós de baixa confiança antes de gerar artefatos downstream.

O que o pipeline realmente faz

Transformar um PDF neste schema não é uma única chamada de modelo — é um pipeline curto:

Rasterizar + extrair. Fazemos o parse do fluxo PDF para extrair runs de texto, caminhos vetoriais e imagens raster embutidas. Páginas escaneadas passam por um processo de OCR que roda em paralelo.
Análise de layout. Um modelo de visão segmenta a página em regiões — cabeçalhos, blocos de corpo, barras laterais, figuras, tabelas, legendas — e atribui a cada uma um tipo grosseiro. É daí que vêm os limites dos Panel.
Detecção de elementos. Um modelo mais denso dentro de cada região identifica elementos de UI individuais — botões, ícones, campos de formulário, séries de gráficos. Essa etapa produz as classificações de elementType.
Agrupamento de texto. Posições brutas de glifos são agrupadas em palavras, linhas e parágrafos, e então vinculadas ao elemento container mais próximo.
Montagem do schema. A hierarquia é materializada, os links pai-filho são resolvidos e os estilos por elemento são computados. As coordenadas são normalizadas para baseWidth.

As etapas 2 e 3 representam a maior parte do orçamento de latência. Tudo antes e depois é comparativamente barato.

O que você pode construir em cima

O schema é deliberadamente genérico. Algumas coisas concretas que equipes têm entregado em cima dele:

Importação de design. Converta uma especificação PDF legada em frames editáveis no Figma em uma passada. Como a configuração de layout espelha a semântica de auto-layout do Figma, o auto-layout reconstrói corretamente na importação.

Modernização de legado. Pegue um manual PDF de 500 páginas e gere uma versão web responsiva. Cada página vira uma rota; os tipos de elementos dirigem a seleção de componentes.

Testes de regressão visual. Renderize uma página base em duas builds, passe ambas pela API e compare as árvores de elementos. Diffs em nível de elemento são muito mais estáveis que diffs de pixel sob mudanças de fonte ou anti-aliasing subpixel.

RAG com consciência de layout. Quando você indexa um PDF para recuperação, abandone o dump de texto bruto. Fragmente por elemento, preserve os relacionamentos pai-filho, e você pode responder "qual é o CTA na página 4" ou "qual é a terceira coluna da segunda tabela na página 11" sem heurísticas imprecisas.

Extração de gráficos. Nós de gráfico carregam metadados suficientes (rótulos de eixo, cores de série, texto agrupado) para que você possa transformá-los em componentes de gráfico interativos em vez de renderizar uma captura de tela.

Uma nota sobre precisão

A qualidade real de detecção depende da origem do PDF, da clareza do texto e da complexidade do layout. PDFs de design de produto tendem a ser mais fáceis de analisar; documentos jurídicos escaneados e formulários anotados à mão geram mais ruído de OCR e valores menores de detectionScore, então planeje filtrar.

Primeiros passos

Obtenha uma chave de API em codia.ai/dashboard/developer.
Teste o curl acima com qualquer PDF que você tenha em mãos.
Percorra a árvore de resposta com a linguagem de sua escolha — o schema é JSON puro, nenhum SDK é necessário.
Se quiser pular o parsing e ir direto para um arquivo Figma, confira o plugin PDF to Design para Figma construído sobre o mesmo pipeline.

A referência completa, formatos de requisição/resposta e códigos de erro estão na documentação para desenvolvedores. Entre em contato com [email protected] se precisar de limites de taxa mais altos ou uma implantação privada — o pipeline é entregue como um container isolado para empresas com requisitos de residência de dados.

PDFs não vão desaparecer. Eles têm sido a última milha teimosa para todo esforço de automação de design por uma década. Dar a eles uma estrutura limpa e tipada é o primeiro passo para torná-los cidadãos de primeira classe novamente.

#pdf#visual-struct#api#design-automation#schema

← Ver todos os artigos