Font Tools — Referensi Mendalam

Sekilas

Halaman ini adalah referensi tingkat-kontrak untuk NextPDF Pro Font Tools. Permukaannya adalah satu pemindai, NextPDF\Pro\FontTools\FontDesubsetter, dan dua value object imutabel, SubsetInfo dan DesubsetPlan. Pemindai membaca byte PDF mentah, melaporkan setiap entri /BaseFont yang berbeda, dan menandai entri yang mengikuti konvensi penamaan subset dari ISO 32000-2:2020 §9.9.2. Sebuah plan mengagregasi subset yang ditandai dan mengestimasi biaya byte untuk memulihkan program fon lengkap. Modul ini hanya menganalisis dan mengestimasi; ia tidak pernah menulis ulang program fon yang disematkan. Halaman ini menyatakan API publik, kontrak perilaku yang teramati, dan mode kegagalannya.

Ketersediaan & lisensi

Kapabilitas ini hadir di NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat-Pro. Sebuah deployment tanpa entitlement tersebut tidak memuat class kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada bendera lisensi per-fitur yang menggerbang modul ini. Class Font Tools tersedia kapan pun nextpdf/pro terpasang.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
FontDesubsetter	tidak ada	Pemindai stateless atas byte PDF mentah	—	—	final; aman digunakan ulang lintas dokumen
FontDesubsetter::analyzeSubsets()	string $pdfData	Melaporkan setiap entri /BaseFont yang berbeda, subset atau bukan, ditandai oleh isSubset	list<SubsetInfo>	InvalidArgumentException ketika estimasi subset dari lebar melampaui estimasi jumlah-penuh dari nama	Pemindaian tingkat-byte; object stream terkompresi tidak didekode
FontDesubsetter::isSubsetFont()	string $baseFontName	Mencocokkan konvensi prefiks enam-huruf-kapital-ditambah-+	bool	—	Dijangkarkan di awal nama
FontDesubsetter::extractSubsetPrefix()	string $baseFontName	Mengembalikan tag subset enam-huruf	string	—	String kosong untuk nama non-subset
FontDesubsetter::generateDesubsetPlan()	list<SubsetInfo> $subsets	Mengumpulkan entri yang isSubset-nya true dan menjumlahkan estimasi ukuran	DesubsetPlan	Tidak melempar	Entri non-subset dilewati secara diam-diam
SubsetInfo	konstruktor: $fontName, $baseFont, $subsetGlyphCount, $fullGlyphCount, $isSubset, $encoding	Deskripsi imutabel dari satu entri /BaseFont	—	InvalidArgumentException pada jumlah glyph negatif, atau jumlah subset di atas jumlah penuh	final readonly; semua properti publik
SubsetInfo::subsetPrefix()	tidak ada	Mengekstrak tag enam-huruf dari fontName	string	—	String kosong ketika bukan subset atau + berada jauh dari posisi enam
SubsetInfo::coveragePercent()	tidak ada	Porsi subset dari keseluruhan set glyph	float dalam [0.0, 100.0]	—	Mengembalikan 0.0 ketika fullGlyphCount bernilai 0
DesubsetPlan	konstruktor: list<SubsetInfo> $targets, int $estimatedSizeIncrease	Rencana de-subset imutabel	—	—	final readonly; semua properti publik
DesubsetPlan::count()	tidak ada	Jumlah fon yang ditargetkan	int	—	Sama dengan panjang targets
DesubsetPlan::totalGlyphsNeeded()	tidak ada	Glyph yang hilang dijumlahkan di seluruh target	int	—	Jumlah dari fullGlyphCount - subsetGlyphCount per target

Tanda tangan entry-point

public function analyzeSubsets(string $pdfData): array

public function isSubsetFont(string $baseFontName): bool

public function extractSubsetPrefix(string $baseFontName): string

public function generateDesubsetPlan(array $subsets): DesubsetPlan

public function __construct(
    public string $fontName,
    public string $baseFont,
    public int $subsetGlyphCount,
    public int $fullGlyphCount,
    public bool $isSubset,
    public string $encoding,
)

public function subsetPrefix(): string

public function coveragePercent(): float

public function __construct(
    public array $targets,
    public int $estimatedSizeIncrease,
) {}

public function count(): int

public function totalGlyphsNeeded(): int

Kontrak perilaku

Pemindaian dan deteksi subset

analyzeSubsets() mengekstrak token nama /BaseFont dari byte mentah dengan pencocokan pola tingkat-byte. Nama duplikat mengerucut menjadi satu entri; urutan mengikuti kemunculan pertama. Setiap nama yang berbeda menghasilkan sebuah SubsetInfo, baik ia subset maupun bukan. Sebuah nama adalah subset ketika ia dimulai dengan tepat enam huruf kapital ASCII diikuti +, konvensi §9.9.2. Untuk nama subset, baseFont adalah nama dengan prefiks tujuh-karakter dihapus. Untuk nama biasa, baseFont sama dengan fontName. Setiap nama subset yang berbeda dilaporkan sebagai entrinya sendiri, sesuai panduan §9.9.2 untuk memperlakukan subset sebagai entitas independen.

Deteksi pengodean

Untuk setiap fon, pemindai mencari sebuah jendela byte terbatas setelah kemunculan /BaseFont. Sebuah entri nama /Encoding di dalam jendela menang. Jika gagal, sebuah substring Identity-H atau Identity-V di dalam jendela dilaporkan. Jika keduanya gagal, entri melaporkan Unknown. Nilai pengodean yang tersimpan di dalam dictionary atau dijangkau melalui referensi tidak langsung melaporkan Unknown.

Penghitungan glyph

Kedua jumlah glyph adalah estimasi. subsetGlyphCount diturunkan dari array lebar yang terlihat di dekat entri fon: sebuah array /W CIDFont menghasilkan kira-kira satu glyph per triple lebar, dan sebuah array /Widths simple-font menghasilkan satu glyph per entri numerik. Ketika tidak ada array yang terlihat di dalam jendela, sebuah default tetap kecil berlaku. Ketika kemunculan /BaseFont tidak dapat ditemukan kembali untuk pencarian jendela, jumlahnya adalah 0. fullGlyphCount diturunkan dari heuristik nama-keluarga: sebuah tabel keluarga Latin yang terkenal, satu set indikator nama-keluarga CJK, dan sebuah batas bawah generik selebihnya. Program fon yang disematkan tidak pernah diurai. Tabel, ukuran jendela, dan konstanta spesifik adalah detail implementasi, tidak dipublikasikan, dan dapat berubah antar rilis.

Pembuatan rencana

generateDesubsetPlan() menyaring input ke entri yang isSubset-nya true. Setiap target menyumbangkan jumlah glyph-hilangnya, dikalikan dengan konstanta rata-rata-byte-per-glyph tetap, ke estimatedSizeIncrease. Rencana ini adalah proyeksi untuk keputusan kapasitas, bukan delta yang terukur. Mengeksekusi sebuah rencana — menulis ulang program fon — berada di luar modul ini.

Determinisme

Keseluruhan permukaan adalah fungsi murni dari inputnya. Byte yang identik menghasilkan hasil yang identik. Tidak ada keacakan, tidak ada panggilan jaringan, dan tidak ada akses filesystem.

Kasus tepi & mode kegagalan

• Konstruksi SubsetInfo menolak keadaan tidak valid: jumlah glyph negatif, atau jumlah subset di atas jumlah penuh, melempar InvalidArgumentException.
• analyzeSubsets() dapat merambatkan exception tersebut dalam satu sudut: sebuah fon yang namanya cocok dengan keluarga yang dikenal tetapi array lebar yang terlihat menghasilkan estimasi subset lebih besar daripada angka jumlah-penuh keluarga tersebut.
• Deteksi beroperasi pada representasi byte. Entri /BaseFont yang diserialisasi di dalam object stream terkompresi tidak terlihat; dekompresi stream tersebut sebelum memindai.
• Entri yang kunci dan nilai /BaseFont-nya dipisahkan oleh whitespace selain satu spasi tunggal tetap terdeteksi, tetapi pencarian jendela per-fon gagal menemukannya kembali. Entri semacam itu melaporkan pengodean Unknown dan jumlah glyph subset 0.
• Nama PDF yang menggunakan byte ber-escape # dilaporkan dalam bentuk ber-escape mentah; escape tidak didekode.
• Nama /BaseFont duplikat mengerucut menjadi satu entri. Dua objek fon berbeda yang berbagi satu nama tidak dapat dibedakan oleh pemindai ini.
• generateDesubsetPlan() tidak pernah gagal pada input non-subset; entri dengan isSubset disetel false sekadar dikecualikan dari targets.
• Semua jumlah dan estimatedSizeIncrease adalah heuristik. Jangan perlakukan sebagai nilai yang terukur; gunakan hanya untuk triase dan perencanaan kapasitas.
• Tidak ada operasi kriptografis yang terjadi di modul ini, jadi tidak ada perilaku spesifik-mode-FIPS.

Kesesuaian

Klaim	Standar	Klausa
Deteksi subset cocok dengan konvensi penamaan subset: sebuah tag enam huruf kapital diikuti + yang diprefikskan ke nilai BaseFont.	ISO 32000-2:2020	§9.9.2
Setiap nama subset yang berbeda dilaporkan secara independen, mengikuti rekomendasi untuk memperlakukan banyak subset sebagai entitas terpisah.	ISO 32000-2:2020	§9.9.2

Semua klausa diparafrasakan; NextPDF tidak mereproduksi teks normatif. Ini adalah pernyataan kapabilitas, bukan sertifikasi. NextPDF tidak memegang sertifikasi dan tidak memberikan sertifikasi apa pun. Modul ini menegaskan deteksi konvensi penamaan dan pelaporan deterministik; ia tidak menegaskan akurasi estimasi jumlah-glyph atau ukuran.

Catatan pengembangan

• Pasang dengan composer require nextpdf/pro:^3. Tersedia sejak nextpdf/pro 1.9.0; kini di nextpdf/pro 3.1.0.
• FontDesubsetter bersifat stateless. Buat sekali dan gunakan ulang lintas dokumen dan alur kerja.
• Umpankan byte terdekompresi ke analyzeSubsets() ketika cakupan subset penting; dictionary fon yang dikemas dalam object stream jika tidak akan terlewat.
• Bercabanglah pada SubsetInfo::isSubset sebelum bertindak; daftar hasil sengaja menyertakan fon non-subset untuk tujuan inventaris.
• Gunakan DesubsetPlan::totalGlyphsNeeded() dan estimatedSizeIncrease untuk memutuskan apakah de-subset sepadan dengan biaya ukuran-file sebelum menyediakan program fon lengkap.
• Pemindaian bersifat linear terhadap panjang input dengan pencarian jendela per-fon yang terbatas. Modul ini tidak menyimpan apa pun dan tidak memancarkan telemetri.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang teramati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, class pembantu, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Font Tools (kapabilitas) — pemasangan, mulai cepat, dan contoh alur kerja perencanaan.
• Optimizer — Referensi Mendalam — permukaan pengurangan-ukuran sejawat, termasuk optimasi terkait-fon.
• Modul font Core — penyematan dan subset fon selama pembuatan dokumen di NextPDF Core.