Skip to content
PDF Oxide

Початок роботи з PDF Oxide (Java)

PDF Oxide — це найшвидша бібліотека PDF для Java для витягання тексту: середній час 0.8 мс і 100% успішних проходжень на 3830 реальних PDF. Те саме ядро на Rust постачається до Python, Go, JS і C#; біндинг для Java — це тонкий шар JNI з мінімальною підтримкою JDK 11 LTS і безкоштовною сумісністю з Kotlin із того самого JAR.

Встановлення

JAR містить вбудовані нативні бібліотеки для Linux (x86_64/aarch64), macOS (x86_64/aarch64) і Windows (x86_64). Жодного компілятора чи додаткового налаштування — потрібна бібліотека розпаковується під час першого виклику.

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'

Швидкий старт

Відкрийте PDF і витягніть текст. PdfDocument реалізує AutoCloseable, тому використовуйте try-with-resources, щоб детерміновано звільнити нативний дескриптор.

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
}

Можна відкрити з рядка зі шляхом, з Path, із сирого byte[] або з InputStream:

import fyi.oxide.pdf.PdfDocument;

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

Витягання тексту

Проходьте по кожній сторінці за її індексом, що починається з нуля:

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

Витягання на рівні слів

PdfPage надає структуровану геометрію. words() повертає список TextWord, кожен зі своїм текстом, обмежувальною рамкою та впевненістю 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 також пропонує lines(), chars(), tables(), images(), annotations(), а також width(), height() і text(BBox region) для витягання з підобласті.

Конвертація в Markdown

Конвертуйте окрему сторінку або весь документ у Markdown за допомогою помічника MarkdownConverter (чи зручних методів 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
}

Пошук

search() сканує весь документ і повертає список SearchMatch, кожен зі своїм індексом сторінки, обмежувальною рамкою та знайденим текстом.

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

Створення PDF

Тип Pdf будує PDF із Markdown, HTML або зображень. Він реалізує AutoCloseable і не має резервного Cleaner, тож завжди закривайте його явно або через 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, захищені паролем

Передайте пароль у open() або викличте authenticate() після перехоплення 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));
}

Обробка помилок

PdfException extends RuntimeException (unchecked), має типізовані підкласи та enum kind() для диспетчеризації через 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

Той самий JAR працює безпосередньо з Kotlin — аксесори record стають властивостями.

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

Наступні кроки