OCR

1. Visão Geral

O componente OCR (ocr) extrai texto de uma imagem usando reconhecimento óptico de caracteres (OCR). É útil para ler documentos escaneados, fotos de comprovantes, capturas de tela com texto, entre outros.

Use quando o fluxo precisa transformar uma imagem em texto pesquisável. Não é indicado para PDFs com texto nativo (nesse caso, o componente PDF Reader é mais adequado, pois lê o texto diretamente sem precisar de OCR).

2. Pré-requisitos

Não há credenciais externas — o reconhecimento de texto roda localmente (motor Tesseract), sem chamadas para serviços externos.

3. Autenticação e Conexão

Não aplicável.

4. Configuração / Operações Suportadas

O componente tem uma única operação: extrair texto de uma imagem.

Campo	Obrigatório	Tipo	Descrição	Exemplo
image	Sim	Texto	Nome da propriedade da mensagem onde está a imagem.	"comprovante"
format	Não	Texto: text ou markdown	Formato do texto extraído. markdown adiciona quebras de linha compatíveis com Markdown. Valor padrão: "text".	"markdown"
language	Não	Texto	Código do idioma do texto na imagem. Valor padrão: "eng" (inglês).	"por" (português)
dpi	Não	Número	Resolução (DPI) informada ao motor de OCR. Valor padrão: 300.	300
pageSegMode	Não	Número	Modo de segmentação de página do motor de OCR (controla como o texto é identificado no layout da imagem). Valor padrão: 6.	6
blockSize	Não	Número	Parâmetro técnico do pré-processamento de imagem (binarização). Valor padrão: 15.	15
thresholdOffset	Não	Número	Parâmetro técnico do pré-processamento de imagem (binarização). Valor padrão: 10.	10

⚠️ CONFIRMAR: os valores de pageSegMode seguem a numeração padrão do Tesseract (por exemplo, 6 = "bloco uniforme de texto"), mas o código não documenta a tabela completa de valores possíveis.

5. Exemplos Práticos

Exemplo simples: extrair o texto de um comprovante de pagamento em imagem, recebido em português.

Entrada (imagem já anexada por um passo anterior, por exemplo um upload):

{
  "comprovante": "<arquivo de imagem, disponibilizado por um passo anterior>"
}

Configuração do componente:

{
  "componentName": "ocr",
  "configurations": {
    "image": "comprovante",
    "language": "por"
  }
}

Resposta:

{
  "text": "COMPROVANTE DE PAGAMENTO\nValor: R$ 150,00\nData: 20/07/2026",
  "format": "text",
  "language": "por",
  "length": 58
}

Exemplo avançado: extrair o texto de uma imagem já em formato Markdown (para exibir preservando quebras de linha), ajustando os parâmetros de pré-processamento para uma imagem de baixa qualidade.

Configuração do componente:

{
  "componentName": "ocr",
  "configurations": {
    "image": "fotoDocumento",
    "language": "por",
    "format": "markdown",
    "blockSize": "25",
    "thresholdOffset": "15"
  }
}

Resposta:

{
  "text": "DOCUMENTO DE IDENTIDADE  \nNome: Maria Silva  \nCPF: 123.456.789-00",
  "format": "markdown",
  "language": "por",
  "length": 63
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"An image file is required but has not been configured."	O campo image não foi preenchido.	Preencher image com o nome da propriedade que contém a imagem.
"File [nome] not found inside the execution context."	A imagem referenciada não está disponível na mensagem com esse nome.	Confirmar que um passo anterior disponibilizou a imagem com esse nome exato.
"Unsupported or corrupted image format"	O arquivo enviado não é uma imagem válida ou está corrompido.	Verificar se o arquivo é realmente uma imagem em formato suportado (ex.: JPG, PNG).
"OCR processing failed: ..."	Falha interna do motor de OCR ao processar a imagem.	Tentar com uma imagem de melhor qualidade/resolução, ou revisar os parâmetros de pré-processamento.
Texto extraído com muitos erros/ruído	Imagem de baixa qualidade, idioma incorreto configurado, ou parâmetros de pré-processamento inadequados para o tipo de imagem.	Ajustar language para o idioma correto do texto e testar diferentes valores de blockSize/thresholdOffset.