Jak odczytać kod QR z PDF przy użyciu Javy

Wprowadzenie

Czy kiedykolwiek musiałeś wyodrębnić informacje o kodach kreskowych z setek faktur PDF, etykiet wysyłkowych lub dokumentów magazynowych? Ręczne przeglądanie stron jest żmudne i podatne na błędy. Niezależnie od tego, czy budujesz zautomatyzowany system przetwarzania dokumentów, czy weryfikujesz autentyczność produktów, efektywne znajdowanie kodów kreskowych w PDF może być wyzwaniem. Odczyt kodu QR z PDF szybko przy użyciu GroupDocs.Signature zamieni godziny ręcznej pracy w kilka linii kodu Java.

W tym przewodniku dowiesz się, jak odczytać kod QR z dokumentów PDF efektywnie, korzystając z API GroupDocs.Signature. Zobaczysz, jak skonfigurować bibliotekę, ustawić opcje wyszukiwania, filtrować po typie kodu kreskowego i obsługiwać wyniki w sposób skalowalny od jednego pliku do tysięcy.

Szybkie odpowiedzi

  • Czy GroupDocs.Signature potrafi odczytywać kody QR z PDF? Tak – wykrywa QR, Data Matrix, PDF417 i ponad 45 innych formatów kodów kreskowych.
  • Czy potrzebna jest licencja do użytku produkcyjnego? Wymagana jest licencja komercyjna; dostępna jest darmowa wersja próbna do oceny.
  • Jakiej wersji Javy wymaga? Java 8+ (zalecane Java 11+ dla lepszej wydajności).
  • Jak ograniczyć wyszukiwanie do konkretnych stron? Użyj BarcodeSearchOptions.setAllPages(false) i ustaw setPageNumber().
  • Czy API jest wątkowo‑bezpieczne przy przetwarzaniu wsadowym? Tak, pod warunkiem tworzenia osobnej instancji Signature dla każdego wątku.

Co to jest odczyt kodu QR z PDF?

Odczyt kodu QR z PDF oznacza programowe lokalizowanie i dekodowanie kodów QR osadzonych wewnątrz stron PDF. Dzięki GroupDocs.Signature możesz wyodrębnić zakodowany tekst, określić numer strony oraz uzyskać wymiary geometryczne każdego kodu, bez konieczności renderowania PDF do obrazu, co znacznie przyspiesza przetwarzanie.

Dlaczego warto wyszukiwać kody kreskowe w PDF?

Wyszukiwanie kodów kreskowych w PDF umożliwia firmom automatyzację ekstrakcji danych, redukcję błędów ręcznego wprowadzania i przyspieszenie przepływów pracy w finansach, logistyce i opiece zdrowotnej. Programowe odczytywanie osadzonych kodów pozwala natychmiastowo pobierać identyfikatory, śledzić przesyłki, weryfikować dokumenty i integrować informacje z systemami downstream, zapewniając szybsze i bardziej niezawodne operacje.

Typowe scenariusze biznesowe

  • Przetwarzanie faktur – Automatyczne wyodrębnianie numerów zamówień lub kodów śledzenia z faktur dostawców.
  • Zarządzanie zapasami – Skanowanie katalogów produktów i wyciąganie kodów SKU do aktualizacji bazy danych.
  • Wysyłka i logistyka – Weryfikacja kodów śledzenia w listach przewozowych.
  • Uwierzytelnianie dokumentów – Walidacja podpisanych dokumentów poprzez sprawdzenie osadzonych kodów bezpieczeństwa.
  • Rekordy medyczne – Wyodrębnianie identyfikatorów pacjentów lub kodów recept z medycznych PDF‑ów.

GroupDocs.Signature zajmuje się ciężką pracą – nie musisz pisać kodu przetwarzania obrazu ani martwić się o niuanse renderowania PDF. Biblioteka potrafi wykrywać ponad 50 formatów kodów kreskowych i przetwarza 300‑stronicowy PDF w mniej niż 5 sekund na typowym serwerze 8‑rdzeniowym.

Wymagania wstępne

Zanim rozpoczniesz ten tutorial, upewnij się, że masz przygotowane:

Wymagane biblioteki i zależności

Musisz dodać bibliotekę GroupDocs.Signature do projektu Java. Oto jak zrobić to przy użyciu Maven lub Gradle:

Maven:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

Gradle:

implementation 'com.groupdocs:groupdocs-signature:23.12'

Uwaga: Zawsze sprawdzaj najnowszą wersję pod adresem GroupDocs.Signature for Java releases. Korzystanie z najnowszej wersji zapewnia poprawki błędów i nowe funkcje.

Konfiguracja środowiska

  • JDK 8 lub wyższy – GroupDocs.Signature wymaga przynajmniej Java 8 (zalecane Java 11+ dla lepszej wydajności).
  • IDE – IntelliJ IDEA lub Eclipse ułatwią pracę dzięki autouzupełnianiu i debugowaniu.
  • Dokument PDF – Przygotuj testowy PDF z kodami kreskowymi (faktury, etykiety wysyłkowe lub katalogi produktów sprawdzą się doskonale).

Wymagania merytoryczne

Powinieneś być zaznajomiony z:

  • Podstawową składnią Javy i koncepcjami obiektowymi
  • Obsługą wyjątków przy użyciu bloków try‑catch
  • Pracą z zewnętrznymi bibliotekami w IDE

Jeśli dopiero zaczynasz przygodę z bibliotekami firm trzecich, nie martw się – przeprowadzimy Cię krok po kroku.

Konfiguracja GroupDocs.Signature dla Javy

Rozpoczęcie pracy z GroupDocs.Signature zajmuje tylko kilka minut. Oto kompletny proces konfiguracji:

Krok 1: Dodaj zależność

Użyj Maven lub Gradle, aby dołączyć bibliotekę (zobacz kod powyżej). Po dodaniu zależności odśwież projekt, aby pobrać pliki JAR.

Krok 2: Uzyskanie licencji

GroupDocs oferuje kilka opcji licencjonowania:

Wskazówka: Zacznij od wersji próbnej, aby zbudować proof‑of‑concept, a następnie przejdź na licencję komercyjną, jeśli API spełni Twoje oczekiwania.

Krok 3: Podstawowa inicjalizacja

Klasa Signature jest punktem wejścia, który ładuje PDF do pamięci i udostępnia metody wyszukiwania, weryfikacji i ekstrakcji.

import com.groupdocs.signature.Signature;

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with your PDF path
Signature signature = new Signature(filePath);

Ważne: Upewnij się, że ścieżka do pliku używa podwójnych backslashy w systemie Windows (C:\\Documents\\file.pdf), aby uniknąć problemów z escapowaniem.

Przewodnik implementacji

Teraz najciekawsza część – napiszmy kod, który wyszukuje kody kreskowe w Twoim PDF.

Wyszukiwanie podpisów kodów kreskowych w dokumencie

Podzielimy implementację na trzy wyraźne kroki.

Krok 1: Inicjalizacja obiektu Signature

Signature to podstawowa klasa reprezentująca dokument PDF w pamięci.

import com.groupdocs.signature.Signature;

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with actual file path
Signature signature = new Signature(filePath);

Co się dzieje – Obiekt Signature otwiera Twój PDF i przygotowuje go do przetwarzania. To jak otwarcie pliku w edytorze tekstu; ładujesz dokument, aby móc go przeszukiwać.

Uwaga praktyczna – Przy przetwarzaniu PDF‑ów przesyłanych przez użytkowników zawsze weryfikuj ścieżkę i sprawdzaj, czy plik istnieje, zanim utworzysz obiekt Signature. Zapobiega to niejasnym błędom „file not found”.

Krok 2: Utworzenie BarcodeSearchOptions

BarcodeSearchOptions określa, czego silnik ma szukać i gdzie.

import com.groupdocs.signature.options.search.BarcodeSearchOptions;

// Configure options for searching barcodes
BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setAllPages(true); // Search every page in the document

Definicja: BarcodeSearchOptions konfiguruje parametry wyszukiwania kodów kreskowych, takie jak zakres stron, typy kodów i precyzję wykrywania.

Kluczowe opcje konfiguracyjne

  • setAllPages(true): Przeszukuje wszystkie strony. Ustaw false i podaj setPageNumber(), gdy znasz dokładną stronę.
  • setEncodeType(BarcodeEncodeType.QR): Ogranicza wyszukiwanie do kodów QR, skracając czas przetwarzania nawet o 60 % w dużych PDF‑ach.

Dlaczego to ważne – Jeśli Twoje faktury zawsze umieszczają kody QR na stronie 1, skanowanie całego dokumentu marnuje zasoby CPU.

Krok 3: Wykonanie wyszukiwania i obsługa wyników

Uruchom wyszukiwanie, a następnie iteruj po wynikach.

import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import java.util.List;

try {
    // Execute the barcode search
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    
    // Check if any barcodes were found
    if (signatures.isEmpty()) {
        System.out.println("No barcode signatures found in the document.");
    } else {
        System.out.println("Found " + signatures.size() + " barcode signature(s):\n");
        
        // Loop through each barcode and display details
        for (BarcodeSignature barcodeSignature : signatures) {
            System.out.println("----------------------------------------");
            System.out.println("Barcode Type: " + barcodeSignature.getEncodeType().getTypeName());
            System.out.println("Barcode Text: " + barcodeSignature.getText());
            System.out.println("Page Number: " + barcodeSignature.getPageNumber());
            System.out.println("Position: X=" + barcodeSignature.getLeft() + 
                             ", Y=" + barcodeSignature.getTop());
            System.out.println("Size: Width=" + barcodeSignature.getWidth() + 
                             ", Height=" + barcodeSignature.getHeight());
            System.out.println("----------------------------------------\n");
        }
    }
} catch (Exception e) {
    System.err.println("Error searching for barcodes: " + e.getMessage());
    e.printStackTrace();
} finally {
    // Always dispose of the signature object to free resources
    if (signature != null) {
        signature.dispose();
    }
}

Definicja: BarcodeSignature reprezentuje wykryty kod kreskowy, udostępniając typ, zdekodowany tekst, numer strony oraz granice geometryczne.

Co robi ten kod

  1. Wywołuje signature.search(), aby uzyskać listę obiektów BarcodeSignature.
  2. Sprawdza, czy znaleziono jakiekolwiek kody, aby uniknąć wyjątków typu null‑pointer.
  3. Wyciąga typ, tekst, numer strony i wymiary dla każdego dopasowania.
  4. Całą operację otacza blokiem try‑catch, aby elegancko obsłużyć uszkodzone PDF‑y lub brakujące pliki.
  5. W bloku finally zwalnia zasoby poprzez zamknięcie instancji Signature.

Zastosowanie w praktyce – W przepływie pracy etykiet wysyłkowych zapiszesz getText() (numer śledzenia) w bazie danych i użyjesz getPageNumber(), aby powiązać etykietę z oryginalnym plikiem wsadowym.

Filtrowanie po typie kodu kreskowego

Jeśli znasz dokładny format kodu, przefiltruj go, aby przyspieszyć wykrywanie:

import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setEncodeType(BarcodeTypes.QR); // Only search for QR codes
options.setAllPages(true);

Kiedy filtrować – Ograniczenie wyszukiwania do jednego typu (np. QR) może zmniejszyć zużycie CPU o 30‑50 % w dokumentach zawierających wiele elementów graficznych.

Obsługiwane typy kodów kreskowych

GroupDocs.Signature potrafi wykrywać szeroką gamę formatów. Oto szybka referencja:

Kody 1D (liniowe)

  • Code128 – powszechny w wysyłce i opakowaniach
  • Code39 – używany w motoryzacji i obronności
  • EAN13/EAN8 – kody produktów detalicznych
  • UPC‑A/UPC‑E – standard północnoamerykański
  • Interleaved2of5 – magazyny i dystrybucja

Kody 2D (matrycowe)

  • QR Code – najpopularniejszy, przechowuje URL‑e, dane Wi‑Fi itp.
  • Data Matrix – kompaktowy, idealny dla małych komponentów
  • PDF417 – dokumenty rządowe, karty pokładowe, prawo jazdy
  • Aztec Code – bilety transportowe

Filtrowanie po typie (jak pokazano wyżej) pomaga skupić się na dokładnie tym formacie, którego potrzebujesz.

Przykłady zastosowań w rzeczywistym świecie

1. Zautomatyzowane przetwarzanie faktur

Scenariusz: Dział księgowości otrzymuje ponad 500 faktur od dostawców dziennie w formacie PDF.
Rozwiązanie: Skanuj każdy PDF pod kątem kodów Code39 zawierających numery faktur, a następnie automatycznie dopasowuj je do zamówień w systemie ERP. Eliminujesz ręczne wprowadzanie danych i redukujesz błędy o 85 %.

// Pseudo-code workflow
for (PDF invoice : invoiceBatch) {
    List<BarcodeSignature> barcodes = searchBarcodes(invoice);
    String invoiceNumber = barcodes.get(0).getText();
    updateERPSystem(invoiceNumber, invoice);
}

2. Aktualizacje stanów magazynowych

Scenariusz: Magazyn otrzymuje przesyłki z listami pakowania w PDF, które zawierają kody SKU w formacie EAN13.
Rozwiązanie: Wyodrębniaj wszystkie kody z list, aktualizuj stany magazynowe automatycznie i oznaczaj niezgodności do ręcznej weryfikacji.

3. Uwierzytelnianie dokumentów

Scenariusz: Umowy prawne zawierają kody QR z podpisami kryptograficznymi w celu weryfikacji autentyczności.
Rozwiązanie: Szukaj kodów QR w podpisanych kontraktach, dekoduj dane podpisu i weryfikuj je w stosunku do zaufanego urzędu certyfikacji. Gwarantuje to, że dokumenty nie zostały zmodyfikowane.

4. Zarządzanie rekordami medycznymi

Scenariusz: Pliki pacjentów zawierają wyniki badań w PDF z kodami Code128 identyfikującymi próbki.
Rozwiązanie: Automatycznie wyciągaj identyfikatory próbek i łącz wyniki z rekordami pacjentów w systemie HIS, skracając czas wyszukiwania z minut do sekund.

Typowe problemy i ich rozwiązania

Problem 1: „Nie znaleziono kodów” (choć istnieją)

Możliwe przyczyny

  • Niska rozdzielczość obrazu (poniżej 200 DPI)
  • Kod jest zbyt mały dla silnika wykrywania
  • Nieprawidłowy filtr typu kodu

Rozwiązania

  1. Zwiększ DPI – Skanuj w 300 DPI lub wyżej.
  2. Usuń filtr typu – Najpierw przeszukaj wszystkie typy, potem zawęź wyniki.
  3. Sprawdź jakość wizualną – Otwórz PDF w Adobe Acrobat, przybliż do 200 % i upewnij się, że kod jest ostry.

Problem 2: OutOfMemoryError przy dużych PDF‑ach

Przyczyna – Ładowanie 500‑stronicowego PDF‑a z wysokiej rozdzielczości obrazami zużywa dużo pamięci heap.

Rozwiązanie – Przetwarzaj strony partiami zamiast ładować cały plik:

for (int startPage = 1; startPage <= totalPages; startPage += 50) {
    BarcodeSearchOptions options = new BarcodeSearchOptions();
    options.setPageNumber(startPage);
    options.setPagesSetup(new PagesSetup());
    options.getPagesSetup().setLastPage(Math.min(startPage + 49, totalPages));
    
    List<BarcodeSignature> batchResults = signature.search(BarcodeSignature.class, options);
    // Process results...
}

Rozważ także zwiększenie przydziału pamięci JVM (-Xmx4g) przy bardzo dużych wsadach.

Problem 3: Wolna wydajność przy dokumentach wielostronicowych

Przyczyna – Sekwencyjne skanowanie każdej strony może być czasochłonne.

Rozwiązania

  1. Skup się na konkretnych stronach – Jeśli kody zawsze są na stronie 1, ustaw setAllPages(false) i setPageNumber(1).
  2. Cache’uj wyniki – Przechowuj dane kodu po pierwszym skanie, aby uniknąć ponownego przetwarzania tego samego pliku.
  3. Używaj dysków SSD – Szybszy I/O może skrócić czas ładowania o 60‑70 % w porównaniu z HDD.

Problem 4: Fałszywe trafienia (losowe wzory uznane za kody)

Przyczyna – Tabele lub linie siatki mogą być pomylone z kodami.

Rozwiązanie – Waliduj długość i wzorzec zdekodowanego tekstu przed zaakceptowaniem:

for (BarcodeSignature barcode : signatures) {
    String text = barcode.getText();
    
    // Example: Invoice numbers are always 10 digits
    if (text.matches("\\d{10}")) {
        // Valid invoice number
        processBarcode(barcode);
    } else {
        System.out.println("Skipping invalid barcode: " + text);
    }
}

Wskazówki wydajnościowe dla dużych dokumentów

1. Strategia przetwarzania wsadowego

Wykorzystaj pulę wątków do równoczesnego przetwarzania wielu PDF‑ów:

ExecutorService executor = Executors.newFixedThreadPool(4); // 4 parallel threads

for (String pdfPath : pdfFiles) {
    executor.submit(() -> {
        try (Signature sig = new Signature(pdfPath)) {
            List<BarcodeSignature> results = sig.search(BarcodeSignature.class, options);
            // Process results...
        } catch (Exception e) {
            e.printStackTrace();
        }
    });
}

executor.shutdown();
executor.awaitTermination(1, TimeUnit.HOURS);

Rezultat: Przetworzenie 1 000 plików spada z ~2 godzin do ~30 minut na maszynie czterordzeniowej.

2. Ogranicz zakres wyszukiwania

Jeśli kody zawsze pojawiają się w tym samym obszarze, zdefiniuj obszar poszukiwań:

// Only search the top‑right corner where barcodes are typically placed
options.setRectangle(new Rectangle(400, 50, 150, 150)); // X, Y, Width, Height

Rezultat: 40‑60 % przyspieszenia w dokumentach o stałym układzie.

3. Monitoruj zużycie pamięci

W długotrwałych zadaniach wsadowych okresowo wywołuj garbage collection:

Runtime runtime = Runtime.getRuntime();
long usedMemory = runtime.totalMemory() - runtime.freeMemory();

if (usedMemory > (runtime.maxMemory() * 0.8)) {
    System.gc(); // Suggest garbage collection
}

Najlepsze praktyki

1. Zawsze zwalniaj obiekty Signature

Signature implementuje AutoCloseable; użycie try‑with‑resources zapewnia czyste zamknięcie:

try (Signature signature = new Signature(filePath)) {
    // Your search code here...
} // Automatically disposed

2. Waliduj pliki wejściowe

Nigdy nie ufaj ścieżkom zewnętrznym bez sprawdzenia. Najpierw zweryfikuj istnienie i poprawność PDF‑a:

File pdfFile = new File(filePath);
if (!pdfFile.exists() || !pdfFile.canRead()) {
    throw new FileNotFoundException("PDF not found or not readable: " + filePath);
}

// Optional: Verify it's actually a PDF (check magic bytes)

3. Loguj wyniki wykrywania kodów

Utrzymuj dziennik zdarzeń dla celów zgodności i debugowania:

Logger logger = Logger.getLogger(BarcodeSearcher.class.getName());

for (BarcodeSignature barcode : signatures) {
    logger.info(String.format("Detected %s barcode '%s' on page %d at (%.2f, %.2f)",
        barcode.getEncodeType().getTypeName(),
        barcode.getText(),
        barcode.getPageNumber(),
        barcode.getLeft(),
        barcode.getTop()));
}

4. Obsługuj różne formaty kodów

Stwórz elastyczną metodę przyjmującą listę wartości BarcodeEncodeType, aby móc łatwo dodawać nowe standardy bez modyfikacji kodu:

switch (barcode.getEncodeType().getTypeName()) {
    case "QR":
        // QR codes might contain URLs or JSON data
        processQRCode(barcode.getText());
        break;
    case "Code128":
        // Code128 typically contains alphanumeric order/tracking numbers
        processTrackingNumber(barcode.getText());
        break;
    default:
        logger.warning("Unexpected barcode type: " + barcode.getEncodeType());
}

5. Testuj na rzeczywistych dokumentach

Używaj zeskanowanych faktur z plamami kawy, faxowanych etykiet z szumem oraz zdjęć telefonem komórkowym przekonwertowanych do PDF. Dzięki temu odkryjesz przypadki brzegowe, które nie występują w idealnych przykładach.

Jak GroupDocs.Signature wykrywa kody QR w PDF?

Załaduj PDF przy pomocy instancji Signature, skonfiguruj BarcodeSearchOptions tak, aby celował w kody QR, i wywołaj search(). Silnik wewnętrznie renderuje każdą stronę do bitmapy przy 150 DPI, uruchamia szybki dekoder oparty na Z‑Bar i zwraca obiekty BarcodeSignature zawierające zdekodowany tekst oraz dane geometryczne. Proces zajmuje mniej niż 5 sekund dla 300‑stronicowego dokumentu na typowym serwerze 8‑rdzeniowym.

Najczęściej zadawane pytania

P: Czy mogę odczytywać kod QR z PDF bez licencji?
O: Darmowa wersja próbna pozwala na odczyt kodu QR z PDF w celach ewaluacyjnych, ale do wdrożeń produkcyjnych wymagana jest licencja komercyjna.

P: Czy API obsługuje PDF‑y zabezpieczone hasłem?
O: Tak. Przekaż hasło przy tworzeniu obiektu Signature, np. new Signature(filePath, "password").

P: Jak poprawić wykrywanie przy skanach niskiej rozdzielczości?
O: Skanuj przynajmniej w 200 DPI, włącz setEncodeType(BarcodeEncodeType.QR) i rozważ wstępne przetworzenie PDF‑a filtrami odszumiającymi.

P: Czy wyszukiwanie jest wątkowo‑bezpieczne przy przetwarzaniu równoległym?
O: Każdy wątek powinien tworzyć własny obiekt Signature. API jest wątkowo‑bezpieczne przy takiej praktyce.

P: Z jaką wersją GroupDocs.Signature testowano ten tutorial?
O: Kod został zweryfikowany z GroupDocs.Signature 23.12, który obsługuje ponad 50 formatów kodów kreskowych i potrafi przetwarzać wielostronicowe PDF‑y bez ładowania całego pliku do pamięci.

Zakończenie

Właśnie nauczyłeś się, jak odczytywać kod QR z dokumentów PDF przy użyciu Javy i API GroupDocs.Signature. Krótkie podsumowanie:

  • Konfiguracja – Dodaj zależność Maven/Gradle, zdobądź licencję i zainicjalizuj Signature.
  • Implementacja – Skonfiguruj BarcodeSearchOptions, uruchom search() i przetwarzaj wyniki BarcodeSignature.
  • Obsługiwane typy – Ponad 50 formatów, w tym QR, Data Matrix, PDF417, Code128 i EAN13.
  • Scenariusze biznesowe – Automatyzacja faktur, aktualizacje zapasów, uwierzytelnianie dokumentów, zarządzanie rekordami medycznymi.
  • Rozwiązywanie problemów – Porady dotyczące brakujących kodów, błędów pamięci, wąskich gardeł wydajności i fałszywych trafień.
  • Wydajność – Przetwarzanie wsadowe, ograniczanie zakresu stron i użycie SSD znacząco przyspieszają działanie.

GroupDocs.Signature abstrahuje skomplikowane kroki renderowania PDF i dekodowania kodów, pozwalając skupić się na logice biznesowej. Niezależnie od tego, czy tworzysz małe narzędzie, czy rozbudowaną linię przetwarzania dokumentów, masz teraz solidne, wydajne rozwiązanie.

Ostatnia aktualizacja: 2026-07-15
Testowane z: GroupDocs.Signature 23.12
Autor: GroupDocs

Powiązane tutoriale