Uso de IronOCR con asistentes de codificación IA
IronOCR es una biblioteca comercial de OCR para .NET con más de seis millones de descargas en NuGet. Sus tutoriales, guías prácticas y notas de resolución de problemas han sido públicas durante años, por lo que los asistentes de codificación generalmente lo han visto en sus datos de entrenamiento.
Esa familiaridad no se extiende a cuál versión tu proyecto señala. Un asistente que lee la documentación de IronOCR tiene más probabilidades de escribir un código OCR que construya y devuelva texto preciso. Comparte la documentación antes de la primera solicitud.
Estas herramientas se dividen en dos categorías, que difieren en cuánto hacen antes de que revises el resultado.
- Un asistente trabaja dentro de una parte de tu flujo de trabajo. Completa una línea, explica un método o hace una pequeña edición, como lo hacen las sugerencias en línea de GitHub Copilot.
- Un agente toma una tarea de múltiples pasos, edita a través de archivos, ejecuta la compilación y las pruebas, y envía el resultado para revisión, como lo hacen Claude Code, ChatGPT Codex, Cursor y Google Antigravity.
La configuración es idéntica para ambos. Instala el paquete, aplica la clave de licencia desde una variable de entorno, proporciona la documentación legible por máquinas de IronOCR y verifica cada valor extraído en una página cuyo texto ya conoces. Esto se aplica tanto a imágenes como a PDFs escaneados, así como a hacer una búsqueda de escaneo, leer múltiples idiomas, extraer códigos de barras de la misma lectura o mejorar un escaneo de baja calidad.
Cómo usar IronOCR con un asistente o agente de codificación IA
- Descarga la biblioteca de OCR C# de NuGet
- Carga la clave de licencia desde una variable de entorno antes de la primera lectura
- Dale al asistente el índice
llms.txtde IronOCR antes de que escriba cualquier código - Registra las reglas de IronOCR donde sea que tu asistente mantenga las instrucciones del proyecto
- Comienza una nueva sesión con el mensaje de configuración única a continuación
- Compila, luego verifica el resultado de IronOCR con los valores que esperas en cada página de muestra
¿No puede mi asistente IA manejar el OCR por sí solo?
Sin documentación, un asistente se basa en cualquier código de OCR que absorbió en el entrenamiento, que a menudo mezcla configuraciones de envoltorios Tesseract sin procesar o una versión anterior de IronOCR.
IronOCR publica documentación diseñada para que las herramientas la lean, incluidos tutoriales, guías prácticas y más de cincuenta artículos de resolución de problemas. Una vez que el asistente la ha cargado, la documentación muestra cómo IronTesseract, OcrInput y OcrResult encajan juntos.
La selección del motor aún importa. Las envolturas gratuitas de Tesseract manejan bien una página limpia y vertical de inglés.
- La salida legible no garantiza una salida correcta: un resultado de OCR puede leerse de manera fluida y aún así convertir 589.50 en 580.50.
OcrResultinforma una puntuación de confianza para cada palabra para mostrar dónde mirar. - Los escaneos requieren preparación: las páginas torcidas, ruidosas o de baja resolución se leen mal en cualquier motor.
OcrInputlleva filtros que enderezan una página, eliminan el ruido, aumentan la resolución y más. - Ajustar manualmente un motor es costoso: cada intento que un asistente hace en configuraciones básicas de Tesseract gasta tokens en un trabajo que la biblioteca ya realiza, y el costo se repite con cada nuevo tipo de documento.
- El paquete depende de la plataforma:
IronOcrcubre Windows,IronOcr.MacOscubre Macs Intel yIronOcr.MacOs.ARMcubre el silicio de Apple. Un asistente también puede inventar un nombre de paquete plausible, y los atacantes registran tales nombres con código malicioso, una práctica llamada slopsquatting. Nombra el paquete en el mensaje. - La licencia es predecible: los servicios de OCR en la nube a menudo cobran por página o por llamada, y un asistente no mencionará esos términos por sí solo. IronOCR se ejecuta localmente bajo una licencia comercial perpetua con precios en niveles por desarrolladores, ubicaciones y proyectos, sin medición por página.
Paso 1: Instala IronOCR
Una vez que la referencia del paquete existe, el asistente puede ver los tipos reales de IronOCR mientras genera código.
Install the IronOcr NuGet package into this project and confirm it restores.
La guía de instalación avanzada de NuGet enumera las otras opciones de instalación.
Paso 2: Aplique su clave de licencia
IronOCR no tiene modo sin licencia con marca de agua. Construir un IronTesseract sin una clave funciona, pero la primera lectura lanza IronSoftware.Exceptions.LicensingException con el mensaje "Se requiere licencia de producción". Una clave presente pero mal escrita produce "Clave de licencia no reconocida" desde la misma llamada. Puedes obtener una clave de prueba gratuita a continuación.
Empiece a usar IronOCR en su proyecto hoy con una prueba gratuita.
Establece IronOcr.License.LicenseKey en el inicio de la aplicación, antes de cualquier otra llamada de IronOCR, y léela desde la variable de entorno IRONOCR_LICENSE_KEY para que nunca entre en el control de versiones. La misma clase también tiene un método que prueba una cadena de clave sin aplicarla.
Web.config y appsettings.json.Paso 3: Dirige a tu asistente a la documentación de LLM de IronOCR
llms.txtes el índice, una línea por página.- Resúmenes de 145 páginas llegan en una sola solicitud desde
llms-full.txt. llms-full-catalog.txtagrega el blog al índice.- La Referencia de API documenta cada tipo y miembro.
- Configuración, licencias, recetas y soluciones están en
skill.md. - La Hoja de información del producto IA resume el alcance, las plataformas y los límites.
Cuando una tarea depende del detalle de una guía, haz que el asistente abra la página de esa guía.
Proporciona una instrucción directa junto con el índice.
Before writing any IronOCR code, read https://ironsoftware.com/ocr/csharp/llms.txt
and use only APIs documented there. A read is assembled on an OcrInput, whose
Load overloads differ by source type, and run through IronTesseract.Read.
Confirm the overload you pick against
https://ironsoftware.com/ocr/csharp/object-reference/api/, and if you cannot find
it, say so instead of guessing.
Paso 4: Agrega contexto de IronOCR a tu proyecto
Coloca las reglas de IronOCR en el archivo que tu equipo ya mantiene. Claude Code lee CLAUDE.md, GitHub Copilot lee .github/copilot-instructions.md, y ChatGPT Codex y Google Antigravity leen AGENTS.md. Cursor lee .cursor/rules/*.mdc o AGENTS.md, y solo su archivo de reglas necesita formato MDC. Usa lo siguiente como punto de partida.
## OCR with IronOCR
This project uses IronOCR (NuGet package `IronOcr`, or `IronOcr.Linux` for Linux and Docker, namespace `IronOcr`) for all OCR work.
- Reference: https://ironsoftware.com/ocr/csharp/llms.txt
- Skill file: https://ironsoftware.com/ocr/csharp/skill.md
- Read with `IronTesseract` and an `OcrInput` inside a `using` block, and use the `OcrResult` it returns.
- Read the license key from the IRONOCR_LICENSE_KEY environment variable at startup. Never inline it.
- Every OCR change must be tested against sample pages whose text is known, reporting the values read and their confidence.
- Do not add another OCR engine or a cloud OCR service. If IronOCR cannot do something, say so.
El ejemplo de archivo de habilidad de archivo único todavía fija IronOcr 2026.7.2 mientras que NuGet ahora sirve 2026.10.2. También dice mantener cada paquete de Iron en la misma versión, lo cual los paquetes de idioma no pueden seguir, ya que IronOcr.Languages.German se publicó por última vez como 2020.11.2. Su receta ConvertToSearchablePdf de una línea falló en PDFs escaneados de solo imagen en nuestras pruebas, mientras que cargar el PDF, leerlo y llamar a SaveAsSearchablePdf en el resultado funcionó.
Paso 5: Prompt de Configuración de Un Solo Paso
Todo desde los Pasos 1 a 4 se puede enviar en un solo mensaje.
Use IronOCR for all OCR work in this project.
1. Install the IronOcr NuGet package (IronOcr.Linux when the app runs on Linux or Docker).
2. Apply the license key at application startup, before any other IronOCR call,
reading it from the IRONOCR_LICENSE_KEY environment variable. Never write
the key into source or into a committed file.
3. Read https://ironsoftware.com/ocr/csharp/llms.txt before writing OCR code
and work only from APIs documented there, checking the API reference when a
member is unfamiliar.
4. Load https://ironsoftware.com/ocr/csharp/skill.md if your tooling supports skill files.
5. Keep these instructions for future sessions in this project.
Paso 6: Patrones de Prompt que Producen Código Funcional
Los resultados débiles generalmente provienen de un mensaje que deja al asistente espacio para adivinar.
Nombra la entrada, los campos y el idioma.
Vago Lee las facturas con IronOCR.
Mejor Usando IronTesseract con un OcrInput que carga cada PDF escaneado, lee el número de factura y la línea que comienza con Total adeudado, y devuelve el monto con la confianza de esa línea.
Indica también la versión y el marco.
Mejor Apunta a .NET 9 con IronOcr 2026.9.4.
Solicita el archivo completo.
Mejor Devuelve el Program.cs completo, incluidas las directivas y la configuración de la licencia, listo para compilar sin ediciones.
Paso 7: Verifica lo que Recibes
Observa estos errores comunes.
- OCR en un PDF que ya tiene texto: extraer una capa de texto real es más rápido y más preciso que ejecutar OCR sobre las páginas. Verifica una capa de texto primero y ejecuta OCR solo en páginas escaneadas.
- Cada filtro a la vez: apilar una corrección tras otra en una página limpia puede reducir la precisión y siempre agrega tiempo. En un conjunto de facturas densas en nuestras pruebas,
DeNoiseconvirtió el último 1 de un número de factura girado en un 4, y agregarDilatecuró esa página pero le costó a otros conjuntos de una a tres filas. Aplica solo el filtro que corrija el defecto que ves. El archivo de habilidades de IronOCR da el mismo consejo, y la guía de corrección de calidad de imagen describe cuándo se aplica cada filtro.
Deja que el Agente Verifique su Propio Trabajo
Build and run this project in Release. Confirm that every IronOCR member you used
appears in the documentation, that IronOcr.License.IsLicensed returns true, and
that every sample page reads back with the values it is known to contain.
Report the build result and a table of page, expected value, value read, confidence, and match.
¿Cómo se leen idiomas diferentes al inglés?
El inglés es el único idioma en el paquete IronOcr. La lista de idiomas de IronOCR cubre 125. Dale estos datos al asistente.
- Otro idioma necesita su paquete, como
IronOcr.Languages.German, luegoLanguage = OcrLanguage.German. - Sin acceso a NuGet, usa el archivo
.ocrdatayInstallation.LanguagePackDirectory. - Las variantes rápidas y mejores como
OcrLanguage.GermanFastse envían en el mismo paquete. - Para una página en varios idiomas, llama a
AddSecondaryLanguage, los más comunes primero. - Las tablas financieras toman
OcrLanguage.FinancialdeIronOcr.Languages.Financial. - Un modelo entrenado en otro lugar se carga a través de
UseCustomTesseractLanguageFilecon un archivo.traineddata.
Un paquete faltante genera LanguagePackException en la primera lectura. Su mensaje nombra el paquete NuGet exacto y la alternativa .ocrdata, así que haz que el asistente instale lo que el mensaje nombra.
La guía de configuración rápida de IronOCR reporta un aumento del 17% al combinar EnglishFast con el apagado de lectura de códigos de barras. En diez de nuestras páginas, esa variante sola se mantuvo dentro del ruido de ejecución del inglés, así que mide las variantes en tus propias páginas antes de intercambiar precisión por velocidad.
La publicación ClickOnce omite los archivos .ocrdata de idiomas secundarios, como lo explica la nota ClickOnce. En Windows, agregar EnglishFast como idioma secundario puede atascarse en grandes PDFs en versiones 2025.12.3 a 2026.7.2, como lo registra esta entrada de resolución de problemas.
¿Qué configuraciones de IronOCR están activadas por defecto?
El código generado a menudo establece valores que ya son predeterminados, o falta una configuración que está desactivada por defecto. Estos son los valores iniciales en IronOcr 2026.9.4, leídos de un nuevo IronTesseract.
| Entorno | Default | Cámbialo por |
|---|---|---|
Language | Inglés | Otros idiomas |
Configuration.ReadBarCodes | apagado | Códigos de barras |
Configuration.ReadDataTables | apagado | Estructura de la tabla |
Configuration.RenderSearchablePdf | encendido | Saltar salida buscable |
Configuration.RenderHocr | apagado | Salida de hOCR |
Configuration.PageSegmentationMode | AutoOsd | Recortes de una sola línea o una sola palabra |
Configuration.EngineMode | LstmOnly | Raramente |
Configuration.WhiteListCharacters y BlackListCharacters | vacío | Conjuntos de caracteres estrechos |
Configuration.TesseractVariables | tres entradas preestablecidas | Variables de Tesseract sin procesar |
MultiThreaded | encendido | Raramente |
MaxDegreeOfParallelism | Environment.ProcessorCount | Lotes grandes con falta de memoria |
OcrInput.TargetDPI | 0 | Escaneos de baja resolución |
Más allá de la lectura estándar, IronTesseract proporciona lectores afinados para otras entradas. ReadPhoto maneja fotografías de documentos y ReadScreenShot maneja capturas de pantalla. El tutorial de documentos especializados todavía enumera IronOcr.Extensions.AdvancedScan para ellos, pero ese paquete se envió por última vez en 2025 y ningún lector lo necesitó. El mismo tutorial también cubre los lectores de pasaportes y matrículas.
Un Resultado que Puedes Reproducir
El prompt
Build a .NET 9 console app that reads totals from scanned invoices. Start in an empty folder; if it already holds code or project files, stop and report. Work start to finish alone: write, build, run, and fix, making sensible assumptions where anything is unspecified. Save every deliverable under the project root, in the folders named below.
1. Install the IronOcr NuGet package pinned to version 2026.9.4.
2. Read https://ironsoftware.com/ocr/csharp/llms.txt and the pages it links to, and use only IronOCR APIs documented there for the OCR work. Any .NET imaging library may draw the test images.
3. Read the license key from the IRONOCR_LICENSE_KEY environment variable at startup and never write it into source or any output file. If IronOcr.License.IsLicensed is false, stop and report that.
4. With random seed 2026, generate testset/invoice-01.png to invoice-10.png. Each is a US Letter page of exactly 1700 x 2200 pixels, saved as PNG with 200 DPI in the file metadata, with all text in Arial inside 0.75 inch margins, headings at 14 point bold and everything else at 11 point. Each invoice has an invoice number made of INV- and six random digits, a customer name, three line items with random prices in dollars and cents, and a total equal to their sum, with no two totals alike.
5. Rotate invoice-02 and invoice-07 by 3 degrees about the page center, keeping the 1700 x 2200 canvas. Add speckle noise to invoice-04 and invoice-09: dark square specks 1 or 2 pixels wide, placed anywhere including over the text, until they have darkened 1% of the page's pixels, counting a pixel as dark below 128 of 255. Leave the other six clean. Write manifest.csv with each file, invoice number, the three prices, total, and distortion (none, rotated, or speckled).
6. Before the first OCR call, check every saved image: 1700 x 2200 pixels, 200 DPI when rounded, and, measured on each page before distortion, the smallest distance from any ink to an edge, at least 0.75 inch. On each speckled page, check that speckling raised the share of dark pixels by 0.9 to 1.1 percentage points. Also draw a capital H with the 11 point font on a 200 DPI bitmap and check that its ink is 21 to 23 pixels tall. If a check fails, fix the generator. After the first OCR call, never regenerate or change the saved image files; filters applied in memory are expected.
7. Read all 10 images in one OcrInput with one set of filters for every page. Each run of the program uses one filter set; it must not try several or choose between them, and choosing filters is your job between runs. No manifest value, file name, or expected value may steer the OCR or the parsing of its text; read the manifest only to write roundtrip.md. The reader must hold no invoice number, price, or total as a literal and must run the same code for every page. Extract each page's invoice number and total, save each page's OCR text as ocr/invoice-01.txt to invoice-10.txt, and save the result as invoices-searchable.pdf.
8. Build in Release and run.
9. Write roundtrip.md: the step 6 checks as measured numbers for every image, not pass or fail words, the filter set used, then a table of file, distortion, expected invoice number, invoice number read, expected total, total read, the Confidence (0 to 100) of the OCR line holding the total or n/a, and match, then the page count of invoices-searchable.pdf loaded back with OcrInput. A row matches only when the invoice number read is identical to the expected one and the total read equals the expected total to the cent.
10. All 10 rows must match and the PDF must have 10 pages. If not, read the saved OCR text of the failing pages, change the filter set or the reader, rebuild, and run again. If rows still fail after eight such runs, stop and report which rows failed, the filter sets tried, and why.
11. Finish with a short report: build result, match count, filters used, font sizes used, and assumptions made.
Resultado
Esta es invoice-09, una de las dos páginas moteadas de la serie, recortada al área impresa. Una lectura simple coincidió con 8 de 10 facturas y se pasó por alto ambas páginas moteadas, devolviendo el número de factura de esta como ANV-938066, y Deskew solo no lo hizo mejor. Con DeNoise añadido, IronOCR devolvió INV-939066 y 1731.53, con 41.45 de confianza en la línea total, la más baja de la serie. La otra línea total moteada se leyó en 63.86 y las páginas limpias en aproximadamente 95. Claude Code eligió esos dos filtros en su primer borrador y los mantuvo durante las cinco ejecuciones del programa.
- Un chequeo independiente midió cada requisito nuevamente, y todas las 10 facturas coincidieron.
- ChatGPT Codex con GPT-6 Luna también coincidió 10 de 10 en el mismo mensaje.
roundtrip.mdse publica sin editar y
en tamaño reducido.
Lo que pasa
- El código no necesitó ediciones de tu parte.
- Abrir cualquier imagen muestra texto pequeño sin cortes en los bordes, y motas en el texto así como en los márgenes.
- Cada número de factura y total en
roundtrip.mdtambién aparece en el texto OCR guardado de esa página.
El récord de ejecución
- La máquina ejecuta Windows 11 x64 en un Core i9-14900KF con 64 GB de memoria.
- Cada proyecto apunta a .NET 9.
- Esta guía, Copilot y Cursor ejecutaron
IronOcr2026.9.4, mientras que Claude Code, Codex y Antigravity ejecutaron 2026.10.2. Copilot agregóIronOcr.Linux2026.9.4, y Codex, Cursor y Antigravity agregaronIronOcr.Languages.German2020.11.2. - Última prueba el 8 de octubre de 2026, con la ejecución de Cursor. Cada ejecución es del 6 de octubre.
| Guía | Asistente y versión | Modelo | Duración (minutos) |
|---|---|---|---|
| Esta guía | Claude Code 2.1.277, avisos de permiso desactivados | Claude Opus 5 | 20.8 |
| Claude Code | Claude Code 2.1.277 | Claude Sonnet 5 | 9.4 |
| ChatGPT Codex | Codex CLI 0.160.0 | GPT-6 Luna | 27.7 |
| GitHub Copilot | Modo agente de Copilot en VS Code 1.140 | GPT-6 Luna, dirigido por Auto | 22.0 |
| Cursor | Aplicación de escritorio Cursor 3.23.23 | Grok 4.7 | 83.5 |
| Google Antigravity | Antigravity CLI 1.3.0 | Gemini 3.8 Flash (Alto) | 32.7 |
Guías Específicas del Agente
Para pasos que se adaptan a una herramienta, abre su guía.
- Usar IronOCR con Claude Code
- Usar IronOCR con ChatGPT Codex
- Usar IronOCR con GitHub Copilot
- Usar IronOCR con Cursor
- Usar IronOCR con Google Antigravity
Solución de problemas
- Aplicar una clave de licencia en IronOCR
- Mejorar la precisión del OCR si el texto reconocido no coincide con la página
- Resolución general de problemas de OCR si aparecen errores después de la implementación
¿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.