Un gateway fax non vuole il tuo render di pagina a 24 bit. Nemmeno la pipeline di archiviazione che conserva un milione di fatture dall'aspetto scansionato, né il front-end OCR che soglia tutto in bianco e nero prima ancora di cercare un carattere. Tutti e tre vogliono la stessa cosa: una bitmap pulita a 1 bit, un bit per pixel, in cui ogni punto è inchiostro o carta. Se gli passi un BMP a colori, getteranno comunque via 23 bit per pixel, di solito con un passaggio di dithering peggiore di quello che avresti potuto fare tu. La domanda interessante è dove debba avvenire quella conversione verso il basso, e la risposta in PDF Library for Delphi finisce per dire qualcosa di utile su come estendere un renderer che preferiresti non riscrivere
PDF Library for Delphi è una libreria PDF nativa in Object Pascal per Delphi e C++Builder. Il suo core di rendering rasterizza una pagina in una bitmap e può produrre BMP, PNG, JPEG, WMF e una manciata di altri formati. Restituire una vera bitmap monocromatica e renderizzare solo una parte di una pagina sono entrambi disponibili dalla v3.83.0, ed entrambi sono costruiti come sottili layer di convenienza sopra il renderer esistente anziché come modifiche al rasterizzatore stesso. Quel vincolo è tutta la storia
Perché fare la conversione verso il basso dopo il rendering, non dentro il renderer
Il modo ovvio per produrre un'immagine a 1 bit è dire al rasterizzatore di disegnare in 1 bit. È anche il modo per rompere tutto il resto. La bitmap interna del renderer viene creata con un `PixelFormat := pf24bit` hardcoded nel costruttore `PDFlibRenderer`, e quella superficie a 24 bit è condivisa da ogni percorso di rendering: esportazione PNG, anteprima del device context, output JPEG, tutto. Se la porti a `pf1bit` alla fonte, non hai aggiunto una funzione monocromatica, hai peggiorato la fedeltà cromatica per tutti i chiamanti della libreria e ti sei impegnato a debuggare una dozzina di regressioni a valle PixelFormat := pf24bit in the PDFlibRenderer constructor, and that 24-bit surface is shared by every render path: PNG export, the device-context preview, JPEG output, all of it. Flip it to pf1bit at the source and you have not added a monochrome feature, you have degraded color fidelity for every caller in the library and signed up to debug a dozen downstream regressions
Quindi RenderPageToMonochromeFile prende la strada opposta. Renderizza normalmente la pagina, in un BMP temporaneo a 24 bit, e solo dopo la comprime a 1 bit come fase di post-elaborazione. Il renderer non viene toccato. Il comportamento monocromatico vive interamente nel metodo di convenienza, il che significa che non può influenzare nessuno che non lo chiami. È il tipo di compromesso che vale la pena nominare esplicitamente: un post-process paga una allocazione bitmap in più e un file temporaneo, e in cambio tiene un core portante completamente fuori dal perimetro. Per una funzione che esiste per servire casi limite di fax e archiviazione, è il lato giusto del bilancio
var
Pdf: TPDFlib;
begin
Pdf := TPDFlib.Create;
try
Pdf.LoadFromFile('invoice.pdf');
// 200 DPI è la classica risoluzione fax Group 4; l'indice pagina è 1-based
Pdf.RenderPageToMonochromeFile(200, 1, 'invoice-page1.bmp');
finally
Pdf.Free;
end;
end;
Come avviene davvero la compressione a 1 bit
La conversione verso il basso si appoggia a GDI invece che a un ciclo threshold scritto a mano, e la scelta conta per la qualità dell'output. Dentro il metodo la bitmap temporanea a 24 bit viene caricata in un TBitmap, una seconda TBitmap viene creata con PixelFormat := pf1bit alle stesse dimensioni, e i pixel passano con una sola blit:
// dentro RenderPageToMonochromeFile, dopo aver caricato il ColorBmp a 24 bit
MonoBmp.PixelFormat := pf1bit;
MonoBmp.Width := ColorBmp.Width;
MonoBmp.Height := ColorBmp.Height;
// HALFTONE dice a GDI di applicare il dithering della sorgente a 24 bit fino a 1 bit
SetStretchBltMode(MonoBmp.Canvas.Handle, HALFTONE);
StretchBlt(MonoBmp.Canvas.Handle, 0, 0, MonoBmp.Width, MonoBmp.Height,
ColorBmp.Canvas.Handle, 0, 0, ColorBmp.Width, ColorBmp.Height, SRCCOPY);
MonoBmp.SaveToFile('out.bmp');
Il trucco è SetStretchBltMode con HALFTONE. Anche se sorgente e destinazione hanno le stesse dimensioni, quindi non avviene alcuna scalatura, la modalità di stretch governa comunque il modo in cui GDI mappa i colori nella palette a 1 bit. HALFTONE fa applicare il dithering halftone, trasformando le regioni grigie e i bordi del testo antialias in pattern di punti bianchi e neri invece che in un taglio netto al colore più vicino tra due BLACKONWHITE, e il contenuto in scala di grigi si posterizza in forme a blocchi sogliate. Per output di documenti scansionati e di pre-elaborazione OCR, il risultato con dithering è quasi sempre quello che vuoi
Un dettaglio non è negoziabile ed è facile sbagliarsi: il rendering temporaneo deve essere un BMP. RenderPageToMonochromeFile chiama il renderer generale con un codice opzioni pari a 0, cioè BMP. L'argomento delle opzioni di RenderPageToFile è un piccolo enum intero, e i valori non sono intercambiabili per questo scopo: 0 è BMP, 1 JPEG, 2 WMF, 3 EMF, 5 PNG, e così via. Il convertitore verso il basso esegue quindi TBitmap.LoadFromStream sul file temporaneo. Dagli in pasto un WMF, passando 2, "Bitmap image is not valid", perché un Windows Metafile è uno stream di record vettoriali, non un DIB. La conversione monocromatica da un estremo all'altro è un'operazione raster, quindi l'intermedio deve essere un formato raster
Renderizzare solo una sotto-regione di una pagina
Il secondo metodo, RenderPageRegionToFile, renderizza solo un rettangolo della pagina invece dell'intero contenuto. I casi d'uso sono familiari non appena hai costruito un qualsiasi visualizzatore di documenti: ritagliare un blocco firma da un contratto, generare una tile per la mappa ingrandita di un disegno grande, oppure estrarre una regione timbrata per una miniatura senza pagare il costo di rasterizzare l'intera pagina ad alto DPI. La firma è semplice:
// Clip è "Left,Top,Width,Height" in punti PDF (72 pt = 1 pollice)
// Qui: un riquadro 2,5x1 pollici, a un pollice dall'angolo in alto a sinistra della pagina
Pdf.RenderPageRegionToFile(150, 1, '72,72,180,72', 'sig-block.bmp');
La stringa del clip è composta da quattro double separati da virgole in punti PDF, analizzati manualmente dentro il metodo per aggirare le stranezze della locale e di DelimitedText . Dalla larghezza e dall'altezza il metodo calcola la dimensione della bitmap di output come Round(Width * DPI / 72) per Round(Height * DPI / 72), alloca una bitmap pf24bit in memoria esattamente di quella dimensione e renderizza nel suo device context attraverso RenderPageToDCClip. Il file risultante contiene solo il rettangolo ritagliato, dimensionato sulla regione e non sull'intera pagina
Come il rettangolo di Clip arriva al device context
Il percorso delle regioni poggia su RenderPageToDCClip e sul suo parametro Clip, che la chiamata consegna a TPDFPageTree.RenderPageToDC. La trappola in un'API a layer come questa è un parametro accettato in cima e lasciato cadere da qualche parte lungo la discesa: il chiamante passa il rettangolo che vuole e riceve in silenzio l'intera pagina, e a seconda del layout nessuno se ne accorge
RenderPageToDC analizza lo stesso rettangolo di punti "Left,Top,Width,Height" e lo applica come una vera regione di clip GDI sul device context di destinazione prima che il renderer disegni. La conversione da punti a pixel del dispositivo usa il consueto fattore di scala DPI / 72, applicato a tutti e quattro i bordi. La sequenza attorno al render è la solita danza save/clip/restore:
// dentro TPDFPageTree.RenderPageToDC, quando Clip non è vuoto
ScaleFactor := DPI / 72;
SaveDC(TargetDC);
IntersectClipRect(TargetDC,
Round(ClipLeft * ScaleFactor),
Round(ClipTop * ScaleFactor),
Round((ClipLeft + ClipWidth) * ScaleFactor),
Round((ClipTop + ClipHeight) * ScaleFactor));
// ... il renderer disegna la pagina qui ...
// nel blocco finally:
RestoreDC(TargetDC, -1);
La coppia SaveDC / RestoreDC(-1) è ciò che rende sicura la chiamata ripetuta: la regione di clip viene spinta sullo stack di stato del DC, la pagina viene disegnata, e il clip originale viene ripristinato a prescindere da come termina il render. RestoreDC(TargetDC, -1) ripristina lo stato salvato più di recente, che è l'idioma standard per un save/restore bilanciato. Salta il restore e un chiamante che riutilizza lo stesso DC per un render a pagina intera successivo si ritroverebbe misteriosamente ritagliato sull'ultima regione. RenderPageRegionToFile ottiene lo stesso comportamento gratis, visto che passa esattamente da questo percorso
Un punto comportamentale da interiorizzare: il clip ritaglia, non scala. La pagina viene ancora rasterizzata al DPI che hai richiesto, nella sua posizione normale, e il clip region semplicemente scarta tutto ciò che sta fuori dal rettangolo. Non stai zoomando la regione per farla riempire l'output; stai ritagliando una finestra dal render a piena risoluzione. Se vuoi una regione ingrandita, alza il DPI. Le coordinate del rettangolo sono interpretate nello spazio del dispositivo dopo la scalatura da punti a pixel, misurate dall'angolo in alto a sinistra della superficie renderizzata, quindi pianifica il tuo Left e Top dall'alto della pagina verso il basso. Per un tour più approfondito di come PDF Library for Delphi guida un device context per l'output a schermo, il pezzo complementare su anteprima di stampa e output device-context percorre lo stesso plumbing DC dal lato della visualizzazione
Formato di output: una BMP a 1 bit non compressa
RenderPageToMonochromeFile produce una BMP pf1bit non compressa: il formato di pixel giusto, dithered e pronto. La maggior parte delle catene di strumenti fax, archiviazione o OCR lo ingerisce volentieri, o lo converte a suo tempo in TIFF CCITT Group 4 con un passaggio a valle, quindi se il tuo flusso fax o il tuo archivio TIFF si aspetta G4, pianifica quella fase di compressione nella tua pipeline
Entrambi i metodi sono deliberatamente piccoli, e questa è la lezione di design da portarsi via da questa pagina: un'API di convenienza che poggia su un renderer può aggiungere capacità reale, output monocromatico e ritaglio di regioni, senza entrare nel rasterizzatore e destabilizzare tutti gli altri chiamanti. Quando devi davvero scegliere tra motori di rendering per la rasterizzazione sottostante, la panoramica del rendering PDF multi-engine in Delphi esplora i trade-off a fondo. Per vedere la superficie di rendering completa e il resto dell'API, la pagina prodotto del PDF Library for Delphi ha il quadro completo