Como usar IronOCR com Cursor

Curtis Chau
Curtis Chau
Atualizado: 9 de outubro de 2026

A maior parte do código do IronOCR escrito por um agente de IA parece correto e muitas vezes funciona. Alguns não. Código que lê códigos de barras sem ativar a coleta de códigos de barras não retorna códigos de barras. Código que define o alemão como idioma sem instalar o pacote de idiomas alemão gera uma LanguagePackException. O modelo escreve a partir dos dados de treinamento, por isso é rápido e também por isso erra em detalhes como este.

Cursor é um editor de código de IA construído sobre a base de código do VS Code. Pode ler a documentação que você vincula e aplicar arquivos de regras compromissados ao seu repositório, para que suas sugestões sigam a API do IronOCR e as convenções da sua equipe. IronOCR é uma biblioteca C# que lê textos, códigos de barras e estruturas de tabelas localmente.

Cada filtro de limpeza é tanto um método na entrada quanto um valor em um enum de filtro, e o nome sozinho não diz qual o código precisa. Isso importa mais para mudanças precisas, como escolher o filtro para scans de baixa qualidade, lendo PDFs sem camadas de texto ou preservando estruturas de tabelas.

Ler manuscritos e fotografias com o IronOCR é abordado separadamente no guia de escrita à mão e no guia de leitura de fotos.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronOcr

Instale o IronOCR executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Dentro de um projeto C#, envie esta solicitação.

@Program.cs Read https://ironsoftware.com/ocr/csharp/llms-full.txt first.

In this C# project, read TestData/skewed-scan.png twice, once untouched and once
with a single correction filter applied to the input, and print both confidence
scores exactly as IronOCR returns them so I can compare them. Read the license
key from the IRONOCR_LICENSE_KEY environment variable and never print it. Use
only members that appear in the documentation.
Text

O guia de chave de licença mostra cada maneira de aplicar a chave.



Qual modelo Cursor você deve usar para trabalho com OCR?

Composer é o modelo agêntico próprio do Cursor. O seletor de modelos também oferece os modelos Grok da SpaceXAI, que o Cursor co-desenvolveu, e modelos da OpenAI, Anthropic, Google e outros laboratórios. O teste executado abaixo usou o Grok 4.7.

O trabalho com OCR consiste principalmente em ciclos curtos de adicionar um filtro, reconstruir e reler amostras, e um modelo rápido lida bem com isso. Quando um lote de digitalizações de produção retorna campos errados sem razão clara, mude para um modelo mais lento que raciocina mais tempo.

Como você fornece a documentação do IronOCR ao Cursor?

O arquivo de texto completo para LLMs resume 145 páginas de documentação em um URL. A partir de outubro de 2026, o menu @ do Cursor anexa arquivos, pastas, terminais, chats, diffs do Git e o navegador, então a documentação do IronOCR atinge o agente como um link.

Read https://ironsoftware.com/ocr/csharp/llms-full.txt

How do I read a scanned PDF and save a searchable copy, and how do I straighten
a slightly rotated page before reading it? Show the exact class and member names
from the documentation, and link the page you took them from.
Text

Como você escreve regras de projeto que codificam suas convenções do IronOCR?

Regras de projeto são armazenadas na pasta .cursor/rules na raiz do repositório. Como são comprometidas com o código, cada clone do repositório recebe um conjunto idêntico.

Regras são arquivos .mdc, escritos em Markdown com frontmatter YAML. Subpastas são lidas também. Cursor ignora um arquivo Markdown simples nesta pasta, porque o arquivo não tem frontmatter para dizer quando aplicá-lo. Aqui está o que uma regra IronOCR pode conter.

---
description: IronOCR conventions for scan reading in this project
globs: Imports/**/*.cs, Capture/**/*.cs
alwaysApply: false
---

# IronOCR conventions

- Use IronOCR for all OCR work. The NuGet package is IronOcr on Windows and
  IronOcr.Linux on Linux and Docker. The namespace is IronOcr. Do not add
  another OCR engine or a cloud OCR service.
- Documentation: https://ironsoftware.com/ocr/csharp/llms-full.txt
- Skill file with recipes: https://ironsoftware.com/ocr/csharp/skill.md
- Target the IronOcr version pinned in Directory.Packages.props. Do not upgrade
  it as part of an unrelated change.
- Never inline a license key. Read it from configuration or the
  IRONOCR_LICENSE_KEY environment variable.
- Dispose OcrInput with a using block.
- Any language other than English needs its IronOcr.Languages package first.
  Language packs keep their own version numbers, so pin the newest one on NuGet.
- Do not invent IronOCR API names. If a member is uncertain, say so and cite
  the documentation instead of guessing.
Markdown

Selecione os globos com cuidado. Uma regra que sempre se aplica se liga a cada sessão de chat e usa contexto extra, então limite a regra do IronOCR às pastas que contêm código OCR.

Por favor, note: Cursor também lê um AGENTS.md raiz. Ele não tem frontmatter e, portanto, não possui globos, então um arquivo raiz se aplica a todo o repositório. Para limitar suas instruções, adicione outro no subdiretório que deveria abranger.

As regras se aplicam a solicitações de Agente. De acordo com a documentação do Cursor, elas não afetam o autocomplete da Tab, e regras de usuário não se aplicam a edições em linha. Verifique sugestões desses recursos contra a regra você mesmo.

Como você mapeia configurações do Tesseract para o IronOCR?

Um modelo que conhece melhor as linhas de comando do Tesseract do que o código IronOCR pode escrever uma flag do Tesseract ou nome de variável onde deveria haver uma configuração do IronOCR.

TesseractIronOCR
--psm 7Configuration.PageSegmentationMode = TesseractPageSegmentationMode.SingleLine
--oem 1Nada para configurar. LSTM é o único motor
-c tessedit_char_whitelist=...Configuration.WhiteListCharacters
Outras variáveis -cConfiguration.TesseractVariables
-l eng+deuAddSecondaryLanguage(OcrLanguage.German)
--tessdata-dir, TESSDATA_PREFIXUseCustomTesseractLanguageFile para um .traineddata arquivo, Installation.LanguagePackDirectory para uma pasta de .ocrdata arquivos

O assistente de filtro do IronOCR precisa do mesmo cuidado. Ele testa combinações de filtros e retorna o melhor como código C#, mas esse código constrói a entrada de um caminho de arquivo através de um construtor que o compilador sinaliza como obsoleto. O assistente também é lento. Uma página de 200 DPI levou quase nove minutos em nossa máquina de teste, então execute em uma única página.

Duas entradas adicionais no regulamento cobrem ambos os casos.

- Configure Tesseract through IronTesseract.Configuration properties, never raw
  tessedit_* variables or command-line flags. Use TesseractVariables only for a
  setting with no named property.
- Rewrite OcrInputFilterWizard output from new OcrInput(path) to new OcrInput()
  with LoadImage or LoadPdf before it reaches the codebase.
Markdown

Qual modo se encaixa na mudança?

Cursor oferece cinco maneiras de fazer uma alteração. Combine o recurso com o tamanho do trabalho.

RecursoUse-o quandoExemplo de OCR
AbaO próximo edit é previsívelRepetir uma opção de filtro
Edição inlineUm arquivo, uma sentençaUm filtro em um leitor
AgenteVários arquivos e um loop de compilaçãoUm leitor e o trabalho que o imprime
Modo PlanejamentoMuito grande para revisar depoisMigrando do Tesseract
Agente da NuvemTrabalho não supervisionadoTestes de páginas conhecidas

Para uma edição em linha, selecione as linhas relevantes, pressione Ctrl+K (Cmd+K no macOS) e descreva a alteração. Códigos de barras em uma nota de entrega são uma alteração do Agente.

@Imports/DeliveryNotes.cs @Imports/ImportJob.cs Read https://ironsoftware.com/ocr/csharp/skill.md first.

Also return every barcode and QR code on each delivery note, and have the notes
command print each one's format and value.
Text

Códigos de barras são coletados apenas quando Configuration.ReadBarCodes é configurado antes da leitura. Eles retornam no mesmo resultado que o texto, então uma leitura cobre ambos. O arquivo de habilidade mostra essa configuração.

O que uma menção @ adiciona a uma solicitação?

Referenciar o arquivo de leitura real é preferível a usar resumos, uma vez que resumos podem omitir detalhes importantes.

@Imports/InvoiceReader.cs @TestData/warehouse/

InvoiceReader reads every scan in TestData/warehouse/ without an error, but about
a third of the totals have one wrong digit. Fix the input preparation, not the
parsing. Explain which setting caused it, and report how many totals match
expected.csv before and after.
Text

Se você não tiver certeza de quais arquivos são relevantes, omita a menção e o Agente pesquisará o próprio código.

Inclua digitalizações de amostra no seu contexto também. Executar os arquivos reais através dos filtros mostra qual combinação os corrige. No nosso conjunto de armazém, Deskew sozinho leu 5 de 9 totais e DeNoise sozinho 2. A correção exigiu ambos, nessa ordem. O guia de correção de orientação de imagem e o guia de correção de qualidade de imagem cobrem os filtros relevantes.

Como planejar e executar uma migração para o IronOCR?

Mude para o Modo Planejamento e envie esta solicitação.

@Imports/ScanOcrService.cs

ScanOcrService reads scans with the Tesseract NuGet package. Plan a migration of
it to IronOCR.

List every read it performs, with the settings it uses (language, page
segmentation, preprocessing, region, output format), map each one to its IronOCR
equivalent, and name the files that change. Keep existing public method
signatures so callers don't change. If anything is ambiguous, choose and state
your assumption, and do not ask. Don't write code yet.
Text

Então clique em Compilar ou envie a solicitação abaixo no Agente.

@Imports/ Implement the approved plan. Then run dotnet build, fix what breaks, confirm
every page in TestData/known/ still returns its expected values, and show me the
diff. Don't add new packages beyond IronOcr and any language packs the plan names.
Text

Um Agente da Nuvem, anteriormente chamado de Agente de Fundo, requer um plano pago, funciona em uma VM na nuvem e precisa de um repositório conectado para trabalhar em seu código. Adicione IRONOCR_LICENSE_KEY como um segredo no painel do Cloud Agents antes de começar. Comece os testes após a migração ser mesclada.

@Imports/ @TestData/ Write xUnit tests for the migrated OCR service in a
tests/Imports.Tests project that Imports.csproj does not compile. Every page in
TestData/known/ returns its expected invoice number and total, a page without a
total returns null, DeliveryNotes returns the codes in TestData/notes/expected.csv,
and a read with OcrLanguage.French, whose language pack is not installed,
produces a clear error. The tests read the license key from IRONOCR_LICENSE_KEY
and never print it. Assert on extracted fields, never on full page text. Run
dotnet test and fix what fails.
Text

O guia de assistentes de codificação de IA executa uma tarefa completa com critérios de aprovação definidos.

Como depurar valores de OCR errados ou ausentes?

@Imports/InvoiceReader.cs @Imports/DeliveryNotes.cs @TestData/returns/

Returned-goods invoices come back with a wrong digit in the total, and delivery
notes return no barcodes even though every note has one. Explain the cause of
each before changing anything, then fix both.
Text

Se a exceção de um container estiver em um terminal do Cursor, adicione @Terminals à solicitação abaixo também.

@Dockerfile @Imports.csproj Read https://ironsoftware.com/ocr/csharp/skill.md first.

Reads work on Windows but fail when this app runs in our Linux container. Check
which IronOCR package the project references, whether the container image has
the native dependencies IronOCR needs, and whether the license key reaches the
container. Explain the cause, then propose the change. Don't modify C# code
unless the cause is there.
Text

O que os prompts produziram em uma execução real?

Os nove prompts foram para o Cursor em ordem, contra um aplicativo de importações de amostra. É um projeto de console com gerenciamento central de pacotes, leitores de nota fiscal e de entrega do IronOCR, um serviço de digitalização no wrapper do Tesseract e digitalizações com valores conhecidos. A chave de licença foi configurada apenas no ambiente do editor. Após a execução, compilações de Release frescas de cada commit leram novamente cada pasta de teste e reproduziram os números abaixo.

  • Totais de nota fiscal do armazém foram de 6 de 9 antes da correção para 9 de 9 após.
  • Nenhum código de barras de nota de entrega voltou antes da correção. Após isso, todas as 8 de 8 notas tinham seus códigos e nenhum extra.
  • No ramo de devolução de mercadorias, os totais das notas fiscais subiram de 4 de 6 para 6 de 6 e os códigos de barras das notas de nenhuma para 6 de 6.
  • A digitalização inclinada foi lida com 87,79 de confiança inalterada e 96,41 após Deskew.
  • Após a migração, as páginas conhecidas ainda leram 10 de 10 e os totais alemães 3 de 3, como antes.
  • O conjunto xUnit passou em 20 de 20 testes.
  • Cada build Release teve 0 erros e não precisou de edições manuais. A migração configurou o obsoleto EngineMode, o que deixou dois avisos CS0618.
  • A resposta do container nomeou IronOcr.Linux, os pacotes apt do guia do Docker e a chave faltante, e não alterou nenhum arquivo C#.
  • Algumas etapas foram executadas de forma diferente desta página. Os prompts foram enviados manualmente no app de desktop, o plano foi aprovado ao enviar o próximo prompt sem nunca clicar em Compilar, e o prompt do Agente de Nuvem foi executado localmente. Oito prompts foram para o chat anterior por engano e foram redefinidos e reenviados. Sem Docker na máquina, o prompt do container foi julgado por sua explicação e proposta.

O registro de execução lista as versões, o tempo e a máquina de teste para este guia junto com os outros.


Solução de problemas


Questões?

Se você tiver dúvidas, entre em contato com support@ironsoftware.com

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Pronto para começar?

Downloads no NuGet 6,394,824Versão:2026.11recém-lançado