Skip to content
PDF Oxide

Primeros pasos con PDF Oxide (Java)

PDF Oxide es la librería PDF para Java más rápida en extracción de texto: 0,8 ms de media y 100 % de aciertos en 3830 PDF del mundo real. El mismo núcleo en Rust llega a Python, Go, JS y C#; el binding de Java es una capa JNI ligera con un mínimo de JDK 11 LTS e interoperabilidad con Kotlin gratis desde el mismo JAR.

Instalación

El JAR incorpora las librerías nativas para Linux (x86_64/aarch64), macOS (x86_64/aarch64) y Windows (x86_64). Sin compilador ni configuración adicional: la librería correcta se extrae en la primera llamada.

Maven

<dependency>
  <groupId>fyi.oxide</groupId>
  <artifactId>pdf-oxide</artifactId>
  <version>0.3.69</version>
</dependency>

Gradle

// Kotlin DSL
implementation("fyi.oxide:pdf-oxide:0.3.69")

// Groovy
implementation 'fyi.oxide:pdf-oxide:0.3.69'

Inicio rápido

Abre un PDF y extrae su texto. PdfDocument implementa AutoCloseable, así que usa try-with-resources para liberar el handle nativo de forma determinista.

import fyi.oxide.pdf.PdfDocument;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("report.pdf"))) {
    System.out.println("Pages: " + doc.pageCount());
    System.out.println(doc.extractText(0)); // zero-based page index
}

Puedes abrir desde una ruta en forma de cadena, un Path, un byte[] sin procesar o un InputStream:

import fyi.oxide.pdf.PdfDocument;

byte[] pdfBytes = downloadFromS3();
try (PdfDocument doc = PdfDocument.open(pdfBytes)) {
    String text = doc.extractText(0);
}

Extracción de texto

Recorre todas las páginas mediante su índice de base cero:

import fyi.oxide.pdf.PdfDocument;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("book.pdf"))) {
    for (int i = 0; i < doc.pageCount(); i++) {
        System.out.println("--- Page " + (i + 1) + " ---");
        System.out.println(doc.extractText(i));
    }
}

Extracción a nivel de palabra

Un PdfPage expone la geometría estructurada. words() devuelve una lista de TextWord, cada uno con su texto, su bounding box y su nivel de confianza del OCR.

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.PdfPage;
import fyi.oxide.pdf.text.TextWord;
import fyi.oxide.pdf.geometry.BBox;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("paper.pdf"))) {
    PdfPage page = doc.page(0);
    for (TextWord word : page.words()) {
        BBox b = word.bbox();
        System.out.printf("'%s' at (%.1f, %.1f) conf=%.2f%n",
            word.text(), b.x0(), b.y0(), word.confidence());
    }
}

PdfPage ofrece además lines(), chars(), tables(), images(), annotations(), junto con width(), height() y text(BBox region) para extraer de una subregión.

Conversión a Markdown

Convierte una sola página o el documento completo a Markdown con el helper MarkdownConverter (o con los métodos de conveniencia doc.toMarkdown(...)).

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.MarkdownConverter;
import java.nio.file.Files;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("report.pdf"))) {
    String md = MarkdownConverter.toMarkdown(doc); // whole document
    Files.writeString(Path.of("report.md"), md);

    String pageMd = doc.toMarkdown(0); // single page
    String pageHtml = doc.toHtml(0);   // or HTML
}

Búsqueda

search() recorre todo el documento y devuelve una lista de SearchMatch, cada uno con su índice de página, su bounding box y el texto coincidente.

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.search.SearchMatch;
import fyi.oxide.pdf.geometry.BBox;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("manual.pdf"))) {
    for (SearchMatch m : doc.search("configuration")) {
        BBox b = m.bbox();
        System.out.printf("Page %d: '%s' at (%.0f, %.0f)%n",
            m.pageIndex(), m.text(), b.x0(), b.y0());
    }
}

Creación de PDF

El tipo Pdf construye PDF a partir de Markdown, HTML o imágenes. Implementa AutoCloseable y no tiene red de seguridad con Cleaner, así que ciérralo siempre de forma explícita o con try-with-resources.

import fyi.oxide.pdf.Pdf;
import java.nio.file.Path;

try (Pdf pdf = Pdf.fromMarkdown("# Hello\n\nThis is a PDF.")) {
    pdf.saveTo(Path.of("out.pdf"));
}

try (Pdf pdf = Pdf.fromHtml("<h1>Invoice</h1><p>Amount: $42</p>")) {
    byte[] bytes = pdf.save(); // serialize to memory instead of disk
}

PDF protegidos con contraseña

Pasa una contraseña a open(), o llama a authenticate() tras capturar una PdfEncryptedException.

import fyi.oxide.pdf.PdfDocument;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("confidential.pdf"), "secret")) {
    System.out.println(doc.extractText(0));
}

Manejo de errores

PdfException extends RuntimeException (no comprobada), con subclases tipadas y un enum kind() para despachar con switch.

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.exception.PdfEncryptedException;
import fyi.oxide.pdf.exception.PdfException;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("document.pdf"))) {
    String text = doc.extractText(0);
} catch (PdfEncryptedException e) {
    System.err.println("Password required");
} catch (PdfException e) {
    switch (e.kind()) {
        case PARSE -> System.err.println("Malformed PDF");
        case IO    -> System.err.println("I/O error");
        default    -> System.err.println("PDF error: " + e.getMessage());
    }
}

Kotlin

El mismo JAR funciona directamente desde Kotlin: los accesores de los records se convierten en propiedades.

import fyi.oxide.pdf.PdfDocument
import java.nio.file.Path

PdfDocument.open(Path.of("report.pdf")).use { doc ->
    println("Pages: ${doc.pageCount()}")
    println(doc.extractText(0))
}

Siguientes pasos