Skip to content
PDF Oxide

Primeiros passos com o PDF Oxide (Java)

O PDF Oxide é a biblioteca PDF mais rápida para Java na extração de texto — média de 0,8ms e 100% de aprovação em 3.830 PDFs do mundo real. O mesmo núcleo em Rust chega ao Python, Go, JS e C#; o binding Java é uma fina camada JNI com piso no JDK 11 LTS e interoperabilidade gratuita com Kotlin a partir do mesmo JAR.

Instalação

O JAR já traz embutidas as bibliotecas nativas para Linux (x86_64/aarch64), macOS (x86_64/aarch64) e Windows (x86_64). Sem compilador nem configuração extra — a biblioteca certa é extraída na primeira chamada.

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'

Início rápido

Abra um PDF e extraia o texto. PdfDocument é AutoCloseable, então use try-with-resources para liberar o handle nativo de forma determinística.

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
}

Você pode abrir a partir de uma string de caminho, um Path, um byte[] bruto ou um InputStream:

import fyi.oxide.pdf.PdfDocument;

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

Extração de texto

Percorra todas as páginas pelo índice baseado em zero:

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));
    }
}

Extração em nível de palavra

Um PdfPage expõe a geometria estruturada. words() devolve uma lista de TextWord, cada uma com seu texto, bounding box e confiança de 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 também oferece lines(), chars(), tables(), images(), annotations(), além de width(), height() e text(BBox region) para extrair de uma sub-região.

Conversão para Markdown

Converta uma única página ou o documento inteiro para Markdown com o utilitário MarkdownConverter (ou os métodos de conveniência 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
}

Busca

search() varre o documento inteiro e devolve uma lista de SearchMatch, cada um com seu índice de página, bounding box e o texto correspondente.

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());
    }
}

Criando PDFs

O tipo Pdf cria PDFs a partir de Markdown, HTML ou imagens. Ele é AutoCloseable e não tem rede de proteção via Cleaner, então sempre o feche explicitamente ou via 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
}

PDFs protegidos por senha

Passe uma senha para open(), ou chame authenticate() após capturar uma 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));
}

Tratamento de erros

PdfException extends RuntimeException (não verificada), com subclasses tipadas e um enum kind() para despacho via 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

O mesmo JAR funciona diretamente a partir de Kotlin — os acessadores de record viram propriedades.

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))
}

Próximos passos