Articolo tecnico

Renderizzare pagine PDF in Bitmap in Delphi con HotPDF

Una striscia di miniature per un lotto di fatture di fornitori sembra a posto a un colpo d'occhio: righe delle tabelle al loro posto, logo nitido, colonne allineate. Ingrandite una e il nome del cliente è una fila di quadratini vuoti, mentre la colonna dei totali contiene lettere che non compongono nulla. Ogni fattura rotta usa lo stesso font, ABCDEF+Arial, e ognuna si legge bene in un visualizzatore PDF desktop sulla stessa macchina. Il codice delle miniature ha preso il nome del font, ha scartato il tag subset di sei lettere, ha chiesto Arial a Windows e gli ha passato i codici di carattere grezzi della pagina. Quei codici non erano mai stati di Arial. Ottenere una bitmap fedele da una pagina PDF richiede due cose: eseguire il content stream della pagina come un programma, e disegnare il testo dai contorni dei glifi conservati nel file invece che dai font che la macchina di rendering ha per caso installati

Una pagina PDF è qualcosa che si esegue

La ISO 32000-1 §8 descrive una pagina come un content stream: operatori che cambiano la matrice di trasformazione con cm, salvano e ripristinano lo stato grafico con q e Q, costruiscono percorsi, selezionano font con Tf, piazzano glifi con Tj, e dipingono immagini e form con Do. Nulla nel file registra l'aspetto di qualsiasi pixel. Per ottenere una bitmap, qualcosa deve eseguire quello stream contro una matrice di trasformazione corrente, uno stack di stati, un percorso di ritaglio e una coppia di spazi colore di riempimento e tratto, poi rasterizzare ciò che ne esce

RenderLoadedPageToBitmap di HotPDF è quell'interprete. Percorre gli operatori di una pagina caricata, tiene matrice e stato grafico come li definisce la specifica, risolve gli spazi colore, trasforma i percorsi PDF in percorsi GDI, e prende gli avanzamenti dei glifi dall'array /Widths del font anziché da GDI. Gli image XObject passano dagli stessi decoder che la libreria usa per l'estrazione, così ogni filtro immagine che HotPDF sa decodificare per l'estrazione, incluse le immagini JPEG 2000 compresse con JPXDecode, compare anche nella pagina renderizzata

Pipeline di rendering di pagina HotPDF: un interprete di content stream PDF traccia la matrice di trasformazione, lo stato grafico, gli spazi colore, i percorsi, le larghezze dei glifi e i contorni dei glifi incorporati, e restituisce un TBitmap RGB a 24 bit di proprietà del chiamante
Ogni operatore aggiorna la matrice, lo stato grafico, il colore, il percorso o lo stato del testo che tocca, e il risultato è un'unica bitmap di proprietà del chiamante

Renderizzare una pagina caricata su una TBitmap in Delphi

THotPDF.RenderLoadedPageToBitmap(PageIndex, DPI) prende un indice di pagina a base zero e una risoluzione in punti per pollice, dove 72 DPI mappano un'unità PDF su un pixel, e restituisce una nuova TBitmap RGB a 24 bit. Un indice fuori intervallo o una pagina che non si può costruire restituisce nil invece di sollevare. Va bene per un viewer, che dovrebbe saltare una pagina danneggiata e continuare con le altre. La bitmap appartiene al chiamante

var
  Pdf: THotPDF;
  Bmp: TBitmap;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report.pdf') > 0 then
    begin
      Bmp := Pdf.RenderLoadedPageToBitmap(0, 144);  // prima pagina a 144 DPI
      if Bmp <> nil then
      try
        Image1.Picture.Assign(Bmp);
      finally
        Bmp.Free;  // la bitmap restituita è del chiamante
      end;
    end;
  finally
    Pdf.Free;
  end;
end;

Le dimensioni in pixel seguono dall'area visibile della pagina. Il renderer prende /CropBox tagliata a /MediaBox, come la ISO 32000-1 §14.11.2 definisce la regione visibile, usa /MediaBox quando non c'è una crop box utilizzabile, scala di DPI/72 e arrotonda per eccesso. Una pagina US Letter senza crop box separata quindi torna esattamente 612×792 pixel a 72 DPI. Una pagina A4 (595.28×841.89 punti) a 96 DPI fa 794×1123, perché 793.7 e 1122.5 arrotondano entrambi per eccesso. Una /Rotate di 90 o 270 scambia larghezza e altezza, e il capovolgimento dall'origine in basso a sinistra del PDF a quella in alto a sinistra di GDI avviene dentro la matrice di pagina, così l'immagine arriva dritta senza post-elaborazione

Il DPI è l'unico pomello di scala, e copre i lavori comuni. Miniature a 36 o 48 DPI sono piccole e veloci. Un'anteprima a schermo a 96 o 144 DPI combacia con la densità di visualizzazione tipica. L'export a 300 DPI dà output di qualità stampa, al prezzo di una bitmap 2550×3300 per ogni pagina Letter, circa 24 MiB l'una a tre byte per pixel

Perché i font sostituiti disegnano i glifi sbagliati?

Glifi sbagliati in un PDF renderizzato significano quasi sempre che il rasterizzatore ha sostituito un font installato a quello incorporato nel file. La scorciatoia dell'esempio della fattura è allettante perché spesso funziona: togliete il prefisso subset da /BaseFont, richiedete un font GDI con il nome rimasto, disegnate la stringa. Per testo in Arial o Times New Roman semplice con codifica standard, nessuno si lamenta

I font subset la rompono per primi. Un subset può portare solo i quaranta glifi che un documento usa, numerati in un ordine privato di quel file, così il codice 1 può essere "T" e il codice 2 "h". Un font installato non può saperlo. Le codifiche personalizzate, i font simbolo e per codici a barre, e qualunque carattere assente dalla macchina di rendering falliscono per lo stesso motivo. E anche quando il sostituto ha ogni carattere, i suoi avanzamenti differiscono dal carattere incorporato, così le linee si allungano o si accorciano e le colonne allineate a destra smettono di combaciare

HotPDF: la sostituzione con font di sistema rimuove il prefisso subset da ABCDEF+Arial e disegna glifi sbagliati, mentre il rendering dei glifi incorporati riproduce i contorni del FontFile per forme esatte
La sostituzione sopravvive solo sui font di sistema comuni e fallisce proprio sui font subset che hanno reso necessario l'incorporamento

Disegnare il testo dal programma di font incorporato

HotPDF disegna il testo dai programmi di font conservati nel PDF. Quando un font porta un programma TrueType incorporato (/FontFile2) o un programma CFF (/FontFile3), ogni glifo viene delineato da quei dati e riempito come percorso GDI, con corpo del font, matrice del testo e matrice di trasformazione corrente composti in una sola trasformazione. Font subset, codifiche private e caratteri mai visti dalla macchina escono con le loro forme vere. Come un codice di carattere raggiunge un glifo dipende dal tipo di font, e ogni tipo ha la sua trappola:

  • Contorni TrueType: i contorni vengono dalle tabelle glyf e loca. I segmenti quadratici vengono elevati alle Bézier cubiche che GDI disegna, una conversione esatta, il punto implicito sulla curva tra due punti fuori curva consecutivi viene ricostruito, e i glifi compositi ricorrono nei propri componenti con la trasformazione di ciascun componente applicata
  • TrueType a chiave CID: i font Type0 sopra CIDFontType2 raggiungono gli ID di glifo attraverso /CIDToGIDMap, sia Identity (anche il default quando la voce manca) sia uno stream di mappa esplicito, e prendono gli avanzamenti da /W e /DW, così il testo a due byte Identity-H avanza della quantità giusta. Le CMap CJK predefinite e gli stream CMap incorporati decodificano i codici a lunghezza variabile prima della ricerca
  • Programmi CFF: Type1C, CIDFontType0C e CFF avvolti in un contenitore OpenType passano per un interprete di charstring Type 2 che gestisce linee, curve, la famiglia flex, le maschere di hint, e le chiamate a subroutine locali e globali con il bias di subroutine applicato. I programmi a chiave CID mappano ogni codice attraverso il charset del font, cosa che conta per i subset il cui ordine dei glifi differisce dall'ordine dei CID, e selezionano il dizionario privato per glifo tramite FDArray e FDSelect
  • Font TrueType semplici: i codici a un byte passano per la cmap incorporata, provando prima le sottotabelle Unicode (3,1) e (3,10), poi la sottotabella simbolo (3,0) sia direttamente sia allo specchio U+F000 che usano i font simbolo, poi la vecchia tabella Macintosh (1,0)

Due regole stanno sopra tutto ciò. Il dizionario /Encoding di un font semplice viene risolto nell'ordine che la ISO 32000-1 §9.6.6 prescrive: /Differences scavalca la codifica di base, che a sua volta scavalca la mappa integrata del programma. TeX e altre catene di strumenti derivate da PostScript ci contano parecchio, quindi sbagliare l'ordine scombina esattamente il testo matematico e simbolico dove un glifo sbagliato è più difficile da notare. I font Type3, i cui glifi sono piccoli content stream a sé, vengono riprodotti attraverso lo stesso interprete con matrice del font, corpo e matrice del testo composti; i /Widths in spazio glifo passano per /FontMatrix come richiede la §9.6.5, e una procedura di glifo che dichiara un riquadro d1 viene ritagliata ad esso, così un glifo per codici a barre malformato non può dipingere fuori dalla propria cella

Quando un singolo codice non si può mappare, perché il programma è danneggiato o il subset manca di quel glifo, quel solo carattere viene disegnato con il font installato dello stesso nome e il resto della sequenza usa ancora i contorni incorporati. Buttare via l'intera sequenza nasconderebbe il problema; una lettera strana si nota più facilmente. I font senza programma incorporato utilizzabile seguono la strada dei font installati descritta in renderizzare font non incorporati con caratteri di sistema

Come si tengono veloci i render ripetuti?

Per qualsiasi cosa interattiva, chiamate RenderLoadedPageToBitmapCached invece del metodo semplice. Tiente le pagine renderizzate di recente in una cache most-recently-used con chiave indice di pagina, DPI e impostazioni di render correnti (intent colore, anteprima overprint, politica di fallback e quali livelli optional content sono visibili), e un hit restituisce una copia fresca di proprietà del chiamante senza reinterpretare il content stream. Passare da una pagina all'altra, o un ridimensionamento che richiede di nuovo la stessa pagina allo stesso DPI, becca la cache ogni volta. Per un export monouso che visita ogni pagina una volta, il semplice RenderLoadedPageToBitmap è la chiamata migliore, visto che la variante in cache copia ogni bitmap che restituisce e terrebbe in giro pagine che nessuno richiederà più

HotPDF: flusso della cache MRU delle pagine renderizzate: un hit restituisce una copia fresca del TBitmap senza reinterpretare la pagina, un miss renderizza e memorizza fino a RenderCacheCapacity pagine
Un hit di cache salta del tutto lo stream di contenuto, mentre invalidazione e budget di memoria tengono i render ripetuti corretti e sicuri
// Striscia di miniature: la prima passata renderizza, tornare indietro prende la cache
Pdf.RenderCacheCapacity := 32;   // limite di voci; il default è 8
for I := 0 to Pdf.LoadedPageCount - 1 do
begin
  Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 48);
  if Bmp <> nil then
  try
    ThumbList.AddThumbnail(I, Bmp);  // il vostro codice UI
  finally
    Bmp.Free;
  end;
end;

// Da mettere in cache anche le pagine a 300 DPI? Date alla cache raster
// un budget di byte più grande (Policy: THPDFCacheAdmissionPolicy)
if Pdf.GetCacheAdmissionPolicy(clkRaster, Policy) then
begin
  Policy.MaxTotalBytes := Int64(512) * 1024 * 1024;
  Pdf.SetCacheAdmissionPolicy(clkRaster, Policy);
end;

// Dopo aver modificato direttamente il contenuto della pagina:
Pdf.InvalidateRenderedPageCache;  // il prossimo render riflette la modifica

RenderCacheCapacity è solo uno dei due limiti. La cache raster ha anche un budget in byte, 128 MiB per default, con un tetto di 64 MiB per voce, e conta quattro byte per pixel quando fa il budget. Supponete un viewer che mette in cache pagine Letter a 300 DPI: ogni voce viene contata circa 32 MiB, quindi ne entrano solo tre, qualunque cosa dica RenderCacheCapacity. A 48 DPI la stessa pagina viene contata circa 0.82 MiB, e fino a 32 miniature del ciclo qui sopra restano residenti in meno di 27 MiB. Quando la cache è piena, una pagina richiesta una volta può non spostare una pagina richiesta spesso; viene comunque renderizzata e restituita, solo non conservata. Se un viewer gira le pagine in un ordine prevedibile, PrefetchLoadedPages riempie la stessa cache su un thread di lavoro in anticipo sull'utente

Caricare un nuovo documento svuota la cache. Diverse chiamate di editing di pagina della libreria stessa, come FlattenLoadedFormFields, scartano da sole le pagine interessate; dopo qualsiasi modifica che fate voi direttamente a oggetti di pagina o content stream, chiamate InvalidateRenderedPageCache, perché la cache non può sapere che i byte dietro una pagina sono cambiati. Sotto siede un secondo deposito per gli image XObject decodificati, limitato da ImageCacheMaxBytes (32 MiB per default), così un logo o una testata ripetuti su ogni pagina si decodificano una volta per caricamento del documento invece che una volta per operatore Do. InvalidateRenderedPageCache svuota anche quello. Se le miniature devono sopravvivere a un riavvio dell'applicazione, il livello disco della cache di render copre quel caso

Scoprire quando una pagina è stata approssimata

La maggior parte delle pagine non prende mai un fallback, perché il renderer copre molto più di testo e immagini. Gli spazi colore CalGray, CalRGB, Lab e basati su ICC vengono convertiti con l'intent di rendering in vigore, che RenderColourIntent può scavalcare, e ConfigureRenderICCWorkflow prende profili ICC di proof e output per il soft-proofing. Le palette Indexed, le tinte Separation e DeviceN e le ricerche colore campionate di funzione Type 0 sono coperte. Gli shading a funzione, assiali, radiali e a mesh si renderizzano sia attraverso l'operatore sh sia attraverso i pattern di shading, e i gruppi di trasparenza, i gruppi knockout e le soft mask di alpha o luminosità si compositano con i loro blend mode, come descritto in gruppi a blend mode e maschere di luminosità

I file reali contengono ancora cose che non si possono disegnare esattamente: una risorsa che la pagina nomina ma non definisce mai, un'immagine i cui dati non si decodificano, un Form XObject che dipinge se stesso. RenderFallbackPolicy decide cosa succede allora. Il default, rfpIgnore, disegna l'approssimazione più vicina e va avanti. rfpReport fa lo stesso ma registra una diagnostica per ogni fallback, fino a RenderFallbackDiagnosticLimit voci (256 per default). rfpStrict solleva un'eccezione invece di restituire una bitmap approssimata. L'annidamento delle form si ferma a 32 livelli e una form che rimanda a se stessa viene saltata, così un file rotto o ostile non può ricorrere senza limiti

// rfpReport e THPDFRenderFallbackDiagnostics sono dichiarati in HPDFPageRenderer
var
  Diags: THPDFRenderFallbackDiagnostics;
  J: Integer;
begin
  Pdf.RenderFallbackPolicy := rfpReport;
  Bmp := Pdf.RenderLoadedPageToBitmap(PageIndex, 150);
  try
    Diags := Pdf.GetLastRenderFallbackDiagnostics;
    for J := 0 to High(Diags) do
      Log.Add(Format('page %d: %s %s - %s', [PageIndex + 1,
        string(Diags[J].OperatorName), string(Diags[J].ObjectName),
        string(Diags[J].Reason)]));
    if Pdf.LastRenderFallbackDroppedCount > 0 then
      Log.Add(Format('%d more fallbacks not recorded',
        [Pdf.LastRenderFallbackDroppedCount]));
  finally
    Bmp.Free;  // Free è sicuro su nil
  end;
end;

Eseguite le build di QA e di ingestione con rfpReport. La bitmap è identica a quella che produce rfpIgnore, e il log mostra quali pagine sono state approssimate e perché, prima che un cliente segnali che la pagina 14 sembra strana. Tenete rfpStrict per la conversione d'archivio, dove una pagina approssimata in silenzio è peggio di una fallita. Un hit di cache ripristina le diagnostica registrate quando quella pagina è stata renderizzata la prima volta, così GetLastRenderFallbackDiagnostics dà la stessa risposta che la variante in cache abbia lavorato o no

RenderLoadedPageToBitmap, la variante in cache e il percorso di testo a glifi incorporati fanno parte dello HotPDF Delphi Component, una libreria VCL nativa per Delphi e C++Builder senza DLL esterne, che crea, modifica ed estrae testo dagli stessi documenti caricati che renderizzate