Internal Mesin Pemrosesan PDF

Internal Mesin Pemrosesan PDF

Document, Page, dan Annotation kelas yang Anda gunakan untuk pemrosesan PDF sehari-hari adalah sebuah fasad di atas paket aspose_pdf.engine tingkat lebih rendah. Mesin ini mengimplementasikan mekanika PDF yang sebenarnya: model objek COS (Carousel Object Structure) yang menjadi dasar setiap file PDF, parser dan penulis yang mengonversi antara objek COS dan byte PDF, sintesis tampilan anotasi, rasterisasi halaman, internal codec font dan gambar, serta primitif kriptografi di balik enkripsi dokumen dan tanda tangan digital. Kebanyakan aplikasi tidak pernah perlu mengimpor langsung dari aspose_pdf.engine — namun itu adalah tempat yang tepat untuk dicari ketika Anda memerlukan alat khusus, inspeksi forensik PDF, atau perilaku yang tidak diungkapkan oleh API tingkat tinggi.

Menghasilkan Tampilan untuk Satu Anotasi

Anotasi interaktif seperti kotak, lingkaran, dan stempel tidak secara otomatis membawa aliran tampilan normal (/AP /N). Memanggil Annotation.generate_appearance memicu internal sintesis tampilan mesin untuk membuatnya sesuai permintaan dari properti anotasi.

from aspose_pdf import Document

doc = Document()
doc.pages.add()
ann = doc.pages[0].annotations.add(
    "Square", (100, 100, 200, 200), "", properties={"C": [1, 0, 0], "IC": [0, 1, 0]}
)

print(ann.has_appearance)  # False -- no appearance stream yet
ann.generate_appearance()
print(ann.has_appearance)  # True -- the engine synthesised one
print(b"1 0 0 RG" in ann.appearance_normal)  # True -- red stroke operator
print(b"0 1 0 rg" in ann.appearance_normal)  # True -- green fill operator

Pembuatan Tampilan Secara Batch di Seluruh Halaman dan Dokumen

AnnotationCollection.generate_appearances menyintesis tampilan untuk setiap anotasi yang memenuhi syarat pada sebuah halaman dalam satu panggilan, melewatkan subtipe yang tidak dapat dirender oleh mesin (seperti Text):

from aspose_pdf import Document

doc = Document()
doc.pages.add()
page = doc.pages[0]
page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

print(page.annotations.generate_appearances())  # 2

Document.generate_appearances melakukan hal yang sama di seluruh halaman dalam dokumen, dan bersifat idempotent — panggilan kedua tidak melakukan apa-apa setelah tampilan sudah ada:

from aspose_pdf import Document

doc = Document()
doc.pages.add()
doc.pages.add()
doc.pages[0].annotations.add("Square", (0, 0, 50, 50), "")
doc.pages[1].annotations.add(
    "Line", (0, 0, 50, 50), "", properties={"L": [0, 0, 50, 50]}
)

print(doc.generate_appearances())  # 2 -- one per page
print(doc.generate_appearances())  # 0 -- already generated, no-op

Meratakan Anotasi menjadi Konten Halaman Statis

Document.flatten() menggambar tampilan setiap anotasi langsung ke dalam aliran konten halaman (sebagai pemanggilan XObject Do) dan kemudian menghapus objek anotasi itu sendiri, sehingga halaman ditampilkan secara identik pada penampil yang sepenuhnya mengabaikan anotasi:

from aspose_pdf import Document

doc = Document()
doc.pages.add()
doc.pages[0].annotations.add(
    "Square", (100, 100, 200, 200), "", properties={"C": [0, 0, 0]}
)

doc.flatten()

Setelah pemanggilan ini, aliran konten halaman menjadi lebih panjang daripada sebelumnya (sekarang berisi persegi yang di-inline) dan doc.pages[0].annotations tidak lagi berisi anotasi yang telah diratakan.

Membuat Kunci Enkripsi Berbasis Kata Sandi (Revisi 4 / AES-128)

EncryptionUtils mengimplementasikan derivasi kunci penangan keamanan standar PDF dan primitif AES-CBC secara langsung, terlepas dari Document API. Ini berguna untuk alat khusus atau inspeksi forensik PDF yang terenkripsi:

import os
from aspose_pdf.engine.encryption import EncryptionUtils

file_id = os.urandom(16)
user_pwd = "mypassword"

# Derive the owner (O) and user (U) key material for Revision 4 (128-bit AES)
o_value = EncryptionUtils.compute_owner_key_v4("owner", user_pwd, 16, 4)
u_value, enc_key = EncryptionUtils.compute_user_key_v4(
    user_pwd, o_value, -4, file_id, 16, 4
)

# Encrypt data with the derived file-encryption key
plaintext = b"Confidential PDF content"
ciphertext = EncryptionUtils.encrypt_aes_cbc(enc_key, plaintext)

# Re-derive the key from the password before trusting it to decrypt
verified_key = EncryptionUtils.verify_password_v4(
    user_pwd, u_value, o_value, -4, file_id, 16, 4
)
print(verified_key is not None)  # True -- password matches

decrypted = EncryptionUtils.decrypt_aes_cbc(verified_key, ciphertext)
print(decrypted == plaintext)  # True

Mengenkripsi Konten Mentah dengan AES-CBC

Untuk kebutuhan tingkat rendah, EncryptionUtils.encrypt_aes_cbc() dan decrypt_aes_cbc() bekerja langsung pada kunci berukuran 16, 24, atau 32 byte tanpa melalui proses derivasi kunci berbasis kata sandi sama sekali:

import os
from aspose_pdf.engine.encryption import EncryptionUtils

key = os.urandom(32)  # AES-256; 16 and 24-byte keys are also accepted
plaintext = b"Hello, PDF AES 256!"

ciphertext = EncryptionUtils.encrypt_aes_cbc(key, plaintext)
decrypted = EncryptionUtils.decrypt_aes_cbc(key, ciphertext)
print(decrypted == plaintext)  # True

Tips dan Praktik Terbaik

• Gunakan antarmuka tingkat tinggi Document, Page, dan Annotation untuk pemrosesan dokumen sehari-hari. Paket aspose_pdf.engine adalah implementasi internal tempat kelas-kelas tersebut dibangun — gunakan hanya ketika Anda membutuhkan alat khusus, inspeksi forensik, atau perilaku yang tidak dipaparkan oleh antarmuka.
• Sesuaikan argumen revision dengan penangan keamanan yang Anda targetkan: compute_owner_key_v4/compute_user_key_v4 mencakup Revisi 2–4 (RC4/AES 40-bit dan 128-bit), sementara compute_hash_v5 mengimplementasikan algoritma Revisi 5/6 yang digunakan oleh AES-256. Mencampur revisi dan panjang kunci secara diam-diam menghasilkan kunci yang salah.
• Document.generate_appearances dan AnnotationCollection.generate_appearances bersifat idempotent — panggil secara defensif sebelum merender atau meratakan dokumen yang tidak Anda buat sendiri.
• Document.flatten() bersifat destruktif: ia menghapus setiap anotasi yang digambarnya ke dalam konten halaman. Selesaikan penyuntingan anotasi lain terlebih dahulu, atau kerjakan pada salinan.
• Tidak setiap subtipe anotasi memiliki sintetis tampilan bawaan — Text dan Popup adalah contoh umum. Periksa has_appearance setelah memanggil generate_appearance() alih-alih mengasumsikan bahwa itu berhasil.

Masalah Umum

FAQ

Apakah saya perlu mengimpor dari aspose_pdf.engine untuk pemrosesan dokumen sehari-hari?

Tidak. Kelas Document, Page, dan Annotation mencakup alur kerja dokumen standar. Lapisan mesin adalah tempat perilaku kelas-kelas tersebut diimplementasikan, dan paling berguna untuk alat khusus atau memeriksa internal PDF secara langsung.

Apa perbedaan antara Annotation.generate_appearance dan AnnotationCollection.generate_appearances?

Yang pertama menyintesis aliran tampilan untuk satu anotasi dan mengembalikan bool. Yang kedua melakukan hal yang sama untuk setiap anotasi yang memenuhi syarat dalam sebuah koleksi (anotasi pada sebuah halaman, atau, melalui Document.generate_appearances, setiap halaman dalam dokumen) dan mengembalikan jumlah tampilan yang dibuatnya.

Mengapa metode derivasi kunci mengambil argumen revision?

Penangani keamanan standar PDF telah berkembang melalui revisi ISO 32000 — Revisi 2 menggunakan RC4 40-bit, Revisi 3/4 mendukung RC4 128-bit atau AES, dan Revisi 5/6 (digunakan untuk AES-256) menggunakan algoritma hashing yang sepenuhnya berbeda (compute_hash_v5). Argumen revision memilih derivasi mana yang akan dilakukan oleh metode EncryptionUtils.

Apakah saya dapat memeriksa atau membangun objek PDF mentah secara langsung?

Ya. aspose_pdf.engine.cos mengekspos model objek COS — PdfObject, PdfDictionary, PdfArray, PdfStream, PdfName, dan tipe terkait — yang PdfCosWriter dan PdfCosParser menyerialisasi ke dan mengurai dari byte PDF.

Di mana proses rendering halaman ke gambar terjadi?

Document.render_page mengembalikan sebuah RasterizedPage, objek tingkat mesin dengan metode to_png(), to_tiff(), dan save() untuk mengubah halaman yang dirender menjadi berkas gambar.

Ringkasan API Reference

Lihat Juga

• Aspose.PDF for Python — Enterprise Documentation