Cómo utilizar IronOCR con Cursor
La mayoría del código de IronOCR que escribe un agente de IA parece correcto y a menudo se ejecuta. Parte de él no lo hace. El código que lee códigos de barras sin habilitar la colección de códigos de barras no devuelve códigos de barras. El código que establece el alemán como idioma sin instalar el paquete de idioma alemán lanza una LanguagePackException. El modelo escribe a partir de sus datos de entrenamiento, por eso es rápido y también por eso comete errores en detalles como este.
Cursor es un editor de código de IA basado en el código base de VS Code. Puede leer la documentación que vinculas y aplicar archivos de reglas comprometidos en tu repositorio, de modo que sus sugerencias sigan la API de IronOCR y las convenciones de tu equipo. IronOCR es una biblioteca de C# que lee texto, códigos de barras y estructuras de tablas localmente.
Cada filtro de limpieza es tanto un método en la entrada como un valor en un enum de filtros, y el nombre por sí solo no dice cuál necesita el código. Eso importa más para cambios precisos, como elegir el filtro para escaneos de baja calidad, leer PDFs sin capas de texto o preservar estructuras de tablas.
Leer escritura a mano y fotografías con IronOCR se aborda por separado en la guía de escritura a mano y la guía de lectura de fotos.
Inicio rápidoDentro de un proyecto de C#, envía esta solicitud.
@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.
La guía de clave de licencia muestra cada forma de aplicar la clave.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de OCR C# de NuGet
- Compromete una regla de alcance de carpeta que mantenga el enlace de documentación de IronOCR
- Nombra el paquete de IronOCR en la misma regla y mantén su versión en
Directory.Packages.props - Apunta cada solicitud al código relevante y escaneos de muestra
- Compila y compara los valores extraídos con páginas conocidas
¿Qué modelo Cursor deberías usar para trabajos de OCR?
Composer es el modelo agente propio de Cursor. El selector de modelos también ofrece los modelos Grok de SpaceXAI, que Cursor co-desarrolló, y modelos de OpenAI, Anthropic, Google y otros laboratorios. La prueba a continuación utilizó Grok 4.7.
El trabajo de OCR consiste principalmente en ciclos cortos de añadir un filtro, reconstruir y releer muestras, y un modelo rápido maneja bien eso. Cuando un lote de escaneos de producción devuelve campos incorrectos sin razón clara, cambia a un modelo más lento que razona más tiempo.
¿Cómo proporcionas la documentación de IronOCR a Cursor?
El archivo de texto completo para LLMs resume 145 páginas de documentación en una URL. A partir de octubre de 2026, el menú @ de Cursor adjunta archivos, carpetas, terminales, chats, diferencias de Git y el navegador, por lo que la documentación de IronOCR llega al agente como un enlace.
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.
¿Cómo escribes reglas de proyecto que codifiquen tus convenciones de IronOCR?
Las reglas del proyecto se almacenan en la carpeta .cursor/rules en la raíz del repositorio. Debido a que se comprometen con el código, cada clon del repositorio recibe un conjunto idéntico.
Las reglas son archivos .mdc, escritos en Markdown con frontmatter YAML. Los subdirectorios también se leen. Cursor ignora un archivo Markdown simple en esta carpeta, porque el archivo no tiene frontmatter para decir cuándo aplicarlo. Aquí está lo que podría contener una regla de IronOCR.
---
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.
Selecciona cuidadosamente los globs. Una regla que siempre se aplica se adjunta a cada sesión de chat y utiliza contexto adicional, así que delimita la regla de IronOCR a las carpetas que contienen código OCR.
AGENTS.md. No tiene frontmatter y por lo tanto no tiene globs, así que un archivo raíz se aplica a todo el repositorio. Para delimitar sus instrucciones, agrega otro en el subdirectorio que debería cubrir.Las reglas se aplican a las solicitudes de Agent. Según la documentación de Cursor, no afectan el autocompletado de la pestaña, y las reglas de usuario no se aplican a las ediciones en línea. Verifique usted mismo las sugerencias de esas características contra la regla.
¿Cómo mapeas los ajustes de Tesseract a IronOCR?
Un modelo que conoce mejor las líneas de comandos de Tesseract que el código de IronOCR puede escribir un flag de Tesseract o nombre de variable donde pertenece una configuración de IronOCR.
| Tesseract | IronOCR |
|---|---|
--psm 7 | Configuration.PageSegmentationMode = TesseractPageSegmentationMode.SingleLine |
--oem 1 | Nada que establecer. LSTM es el único motor |
-c tessedit_char_whitelist=... | Configuration.WhiteListCharacters |
Otras -c variables | Configuration.TesseractVariables |
-l eng+deu | AddSecondaryLanguage(OcrLanguage.German) |
--tessdata-dir, TESSDATA_PREFIX | UseCustomTesseractLanguageFile para un archivo .traineddata, Installation.LanguagePackDirectory para una carpeta de archivos .ocrdata |
El asistente de filtro de IronOCR necesita el mismo cuidado. Prueba combinaciones de filtros y devuelve el mejor como código de C#, pero ese código construye la entrada a partir de un archivo de ruta a través de un constructor que el compilador señala como obsoleto. El asistente también es lento. Una página de 200 DPI tardó casi nueve minutos en nuestra máquina de prueba, así que ejecútalo en una sola página.
Dos entradas más en la regla cubren ambos 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.
¿Qué modo se adapta al cambio?
Cursor proporciona cinco maneras de hacer un cambio. Empareja la función con el tamaño del trabajo.
| Característica | Úselo cuando | Ejemplo de OCR |
|---|---|---|
| Tab | La próxima edición es predecible | Repetir una opción de filtro |
| Edición en línea | Un archivo, una oración | Un filtro en un lector |
| Agente | Varios archivos y un bucle de compilación | Un lector y el trabajo que lo imprime |
| Modo Planificación | Demasiado grande para revisar posteriormente | Migrando fuera de Tesseract |
| Agente en la Nube | Trabajo desatendido | Pruebas de páginas conocidas |
Para una edición en línea, selecciona las líneas relevantes, presiona Ctrl+K (Cmd+K en macOS) y describe el cambio. Los códigos de barras en una nota de entrega son un cambio del 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.
Los códigos de barras solo se recogen cuando Configuration.ReadBarCodes está configurado antes de la lectura. Vuelven en el mismo resultado que el texto, por lo que una lectura cubre ambos. El archivo de habilidades muestra esa configuración.
¿Qué añade una mención @ a una solicitud?
Referenciar el archivo de lector real es preferible a usar resúmenes, ya que los resúmenes pueden omitir detalles 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.
Si no estás seguro de qué archivos son relevantes, omite la mención y el Agente buscará la base de código él mismo.
Incluye escaneos de muestra en tu contexto también. Ejecutar los archivos reales a través de los filtros muestra qué combinación los corrige. En nuestro conjunto de almacén, Deskew solo leyó 5 de 9 totales y DeNoise solo 2. La corrección necesitó ambos, en ese orden. La guía de corrección de orientación de imágenes y la guía de corrección de calidad de imágenes cubren los filtros relevantes.
¿Cómo planificas y ejecutas una migración a IronOCR?
Cambia al Modo Planificación y envía esta solicitud.
@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.
Luego haz clic en Compilar o envía la solicitud a continuación en 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.
Un Agente en la Nube, anteriormente llamado Agente en Segundo Plano, requiere un plan de pago, se ejecuta en una VM en la nube y necesita un repositorio conectado para trabajar en tu código. Agrega IRONOCR_LICENSE_KEY como un secreto en el tablero de Agentes en la Nube antes de empezar. Comienza las pruebas después de que la migración esté fusionada.
@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.
La guía de asistentes de codificación de IA ejecuta una tarea completa con criterios de aprobación definidos.
¿Cómo depuras valores de OCR incorrectos o faltantes?
@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.
Si la excepción de un contenedor está en un terminal de Cursor, agrega @Terminals a la solicitud a continuación también.
@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.
¿Qué produjeron los prompts en una ejecución real?
Las nueve indicaciones fueron enviadas a Cursor en orden, contra una aplicación de importaciones de muestra. Es un proyecto de consola con gestión central de paquetes, lectores de facturas y notas de entrega de IronOCR, un servicio de escaneo en el envoltorio de Tesseract y escaneos con valores conocidos. La clave de licencia fue establecida solo en el entorno del editor. Después de la ejecución, nuevas compilaciones de Release de cada commit leyeron cada carpeta de pruebas nuevamente y reprodujeron las cifras a continuación.
- Los totales de facturas del almacén pasaron de 6 de 9 antes de la corrección a 9 de 9 después.
- Ningún código de barras de nota de entrega volvió antes de la corrección. Después de ella, las 8 de 8 notas tenían sus códigos y ninguno extra.
- En la rama de devolución de mercancía, los totales de facturas subieron de 4 de 6 a 6 de 6 y los códigos de barras de las notas de ninguna a 6 de 6.
- El escaneo inclinado leyó a 87.79 de confianza sin tocar y 96.41 después de
Deskew. - Después de la migración, las páginas conocidas todavía leían 10 de 10 y los totales alemanes 3 de 3, como antes.
- El conjunto de xUnit pasó 20 de 20 pruebas.
- Cada compilación de Release tuvo 0 errores y no necesitó ediciones a mano. La migración estableció el obsoleto
EngineMode, que dejó dos advertencias CS0618. - La respuesta del contenedor nombró
IronOcr.Linux, los paquetes apt de la guía de Docker y la clave faltante, y no cambió ningún archivo de C#. - Algunos pasos se ejecutaron de manera diferente a esta página. Las indicaciones fueron enviadas manualmente en la aplicación de escritorio, el plan fue aprobado enviando la siguiente indicación sin hacer clic en Compilar jamás, y la indicación del Agente en la Nube se ejecutó localmente. La octava indicación fue primero al chat anterior por error y fue restablecida y reenviada. Sin Docker en la máquina, la indicación del contenedor fue juzgada por su explicación y propuesta.
El registro de ejecución lista las versiones, el tiempo y la máquina de prueba para esta guía junto a las demás.
Solución de problemas
- Aplica una clave de licencia en IronOCR si el código generado lanza una excepción de licencia
- Lee códigos de barras con IronOCR si una lectura devuelve texto pero no códigos de barras
- Mejora la precisión de OCR si los valores leídos no coinciden con el escaneo
- IronOCR en Docker si las lecturas funcionan localmente y fallan dentro de un contenedor de Linux
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.