Ein HEIC-Foto von einem Handy landet in einem Delphi-generierten Report, das PDF sieht auf dem Bildschirm richtig aus, und die gedruckte Seite kommt mit verschobenen Rottönen zurück und einem freigestellten Logo auf einem Kasten in Vollton. Das Foto wurde auf dem Weg hinein über eine Plattform-Bitmap dekodiert; laden Sie es stattdessen mit AddModernImageFromFile in PDF Library for Delphi, und AVIF-, HEIF- und JPEG-XL-Bilder behalten Alpha, das ICC-Profil und 16-Bit-Kanäle standardmäßig
Diese Formate haben den Dokumenten-Workflow vor allem über Handys erreicht. iPhones speichern seit Jahren HEIC standardmäßig, Android-Geräte produzieren AVIF, und JPEG XL taucht in Archiv- und Fotografie-Pipelines auf. Ein Report-Generator, der um JPEG und PNG herum entworfen wurde, hat zwei Optionen, wenn eines ankommt: die Datei ablehnen, oder sie durch den Dekoder öffnen, den das Betriebssystem anbietet, und eine geplättete 8-Bit-Bitmap akzeptieren. Dieser Artikel behandelt einen dritten Weg, bei dem die Bibliothek das Format selbst erkennt, es durch einen Codec Ihrer Wahl dekodiert und das Ergebnis mit Tiefen- und Farbdaten unversehrt einbettet
Was verliert ein Bitmap-Roundtrip?
Eine Plattform-Bitmapkonvertierung verliert drei Dinge in einem Schritt: Transparenz, das eingebettete Farbprofil und jede Kanaltiefe über 8 Bits. Zu jedem davon gibt es einen Workflow, der davon abhängt. Alpha zählt für Logos und Produkt-Freisteller über Seiteninhalten. Das ICC-Profil zählt für alles, was gedruckt oder gegen eine Referenz farblich abgeglichen wird, denn ohne es nimmt der Viewer sRGB an, und ein Breitbild-Kamerafoto wird neu interpretiert. Und 16-Bit-Kanäle zählen für medizinische, wissenschaftliche und Inspektions-Bilder, wo das Quantisieren auf 8 Bits exakt die Abstufungen auslöscht, für die das Bild aufgenommen wurde
Keines davon erzeugt einen Fehler. Die Seite rendert, das Foto ist erkennbar, und das Problem wartet, bis jemand einen Druck mit dem Original vergleicht. Deshalb behandeln wir Bewahrung als Standard statt als etwas, wofür sich Aufrufer entscheiden müssen: AddModernImageFromFile, AddModernImageFromStream und AddModernImageFromString nehmen alle einen Options-Parameter entgegen, der auf 8 voreingestellt ist, und Option 8 ist die Einstellung, die Alpha, ICC und 16-Bit-Samples gemeinsam in das PDF-Bildobjekt trägt
Ein 16-Bit-Bild ändert auch die Datei, die Sie erzeugen. PDF Library for Delphi hebt das Dokument auf mindestens PDF 1.5 an, wenn ein Bild 16-Bit-Samples trägt, denn das ist die Version, in der 16 Bits je Komponente für Image-XObjects gültig wurden. Besteht ein nachgelagertes System auf PDF 1.4, lassen sich diese Forderung und 16-Bit-Fotografien nicht beide erfüllen, und es ist besser, das zur Entwurfszeit herauszufinden
Ein Handyfoto auf eine Seite bringen
Die modernen Bild-Aufrufe geben bei Erfolg eine Bild-ID größer null zurück und 0 bei Fehlschlag, und die ID geht dann an DrawImageAndRelease oder an das übliche Paar SelectImage / DrawImage. Die Skizze unten enthält den einen Fallback, den echte Handy-Uploads brauchen, der direkt danach erklärt wird:
uses
PDFlibrary;
var
Lib: TPDFlib;
ImageID: Integer;
begin
Lib := TPDFlib.Create;
try
Lib.NewDocument;
Lib.SetPageSize('A4'); // NewDocument hat Seite 1 bereits angelegt
Lib.SetOrigin(1); // Top von der oberen Kante aus messen
// Options ist mit 8 vorbelegt: Alpha, ICC-Profil und 16-Bit-Kanäle
ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');
// Die Endung sagt HEIC, aber die Bytes können ein gewöhnliches JPEG sein
if ImageID = 0 then
ImageID := Lib.AddImageFromFile('uploads\pump-housing.heic', 0);
if ImageID > 0 then
Lib.DrawImageAndRelease(ImageID, 40, 40, 515, 340)
else
Lib.DrawText(40, 40, 'Photo could not be decoded');
Lib.SaveToFile('inspection-report.pdf');
finally
Lib.Free;
end;
end;
Der Fallback existiert, weil Dateinamen lügen. Share-Sheets, Messaging-Apps und Upload-Formulare wandeln HEIC auf dem Weg hinaus in JPEG um und behalten den originalen Namen, oder benennen Dateien um, in was das empfangende Formular erwartet. AddModernImageFromFile schaut nie auf die Endung. Es inspiziert die ersten Bytes, und sind sie nicht AVIF, HEIF oder JPEG XL, gibt es 0 zurück, ohne den Dekoder anzufassen. Ein JPEG mit einem .heic-Suffix scheitert also am modernen Aufruf und besteht durch das allgemeine AddImageFromFile, das Inhalte genauso erschnüffelt und JPEG, PNG, TIFF und die anderen klassischen Formate beherrscht
Warum nicht alles durch AddImageFromFile schicken? Es erkennt die modernen Formate ebenfalls, aber die modernen Aufrufe machen die Absicht explizit und liefern Option 8, wenn man nichts übergibt, also sehen wir sie an der Aufrufstelle lieber, wann immer die Eingabe ein Handyfoto sein soll
Wie unterscheidet die Bibliothek AVIF von HEIC?
PDF Library for Delphi entscheidet das Format aus einem begrenzten Header-Lesen von höchstens 4096 Bytes und setzt die Stream-Position des Aufrufers danach zurück, wo sie war. JPEG XL ist der einfache Fall: Ein Roh-Codestream beginnt mit FF 0A, und die Container-Form beginnt mit einer festen 12-Byte-Signatur-Box. AVIF und HEIF sind schwerer, denn beide leben im ISO base media file format, derselben Box-Struktur wie MP4, und unterscheiden sich nur in den Marken, die in der ftyp-Box gelistet sind
Die Falle ist, dass sich die Markenlisten überlappen. Eine AVIF-Datei listet mif1 normalerweise unter ihren kompatiblen Marken, weil AVIF auf dasselbe Bild-Dateiprofil wie HEIF gebaut ist. Ein Detektor, der HEIF zurückgibt, sobald er mif1 sieht, wird einen großen Anteil echter AVIF-Dateien falsch etikettieren. Die Bibliothek scannt deshalb zuerst die gesamte Markenliste und lässt avif oder avis über die HEIF-Familie (heic, heix, hevc, hevx, heim, heis, mif1, msf1) gewinnen
Erkennung vor dem Dekodieren zu laufen ist auch eine Sicherheitseigenschaft. Eine unbekannte oder getarnte Eingabe erreicht den externen Codec nie, also wird eine umbenannte ausführbare Datei oder ein missgestalteter Upload von ein paar Dutzend Byte-Vergleichen abgewiesen statt von einem großen Bild-Dekoder, der sie hätte parsen müssen
Wo das Dekodieren passiert
PDF Library for Delphi kompiliert keinen AVIF-, HEIF- oder JPEG-XL-Codec in sich selbst hinein. Diese Codecs sind groß, sie ändern sich oft, und eine Anwendung, die nie ein Handyfoto sieht, soll nicht für sie zahlen. Das Standard-Backend lädt bei der ersten Verwendung ein ImageMagick-MagickWand-Modul in den Prozess und sucht in fester Reihenfolge danach: die Datei oder das Verzeichnis, gesetzt über SetModernImageCodecLibrary, dann die Umgebungsvariable PDFLIB_MODERN_IMAGE_CODEC, dann das Verzeichnis der ausführbaren Datei, dann den normalen System-Suchpfad. Unter Windows versucht es CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll und MagickWand-7.Q16-10.dll an jedem Ort
Zwei praktische Konsequenzen folgen. Shippen Sie einen Q16-Build des Codecs, denn ein 8-Bit-Quantum-Build kann keine 16-Bit-Samples übergeben, egal welche Option man übergibt. Und enthält das Codec-Verzeichnis einen modules\coders-Unterordner, füllt die Bibliothek MAGICK_HOME, MAGICK_CONFIGURE_PATH und MAGICK_CODER_MODULE_PATH für Sie auf, aber nur die Variablen, die der Host-Prozess nicht bereits gesetzt hat. Eine Anwendung mit ihrem eigenen Runtime-Layout behält es
Unsere Empfehlung ist, den Pfad explizit zu setzen und sich nicht auf den System-Suchpfad zu verlassen. Eine Maschine, die zufällig ein anderes ImageMagick auf PATH hat, entscheidet sonst, welchen Codec Ihr Report-Generator verwendet, und das ist die Art von Unterschied, die nur auf dem Server eines einzigen Kunden auftaucht
Anwendungen, die bereits einen Dekoder mitbringen oder denen nicht erlaubt ist, ein externes Modul zu laden, registrieren stattdessen einen Callback. Der Callback ist eine schlichte Funktion, die den Quell-Stream liest, PNG-Bytes in den Ausgabestream schreibt und das Orientation-Flag beehrt. Die Registrierung ist prozessweit und durch eine Sperre geschützt, also einmal beim Start tun statt je Dokument:
uses
Classes, PDFlibModernImage,
AppCodec; // Ihre eigene Unit, die den Codec wrappt, den Sie bereits mitbringen
function MyModernDecoder(InStream, OutPNG: TStream;
ImageFormat: TPDFlibModernImageFormat;
ApplyOrientation: Boolean): Boolean;
begin
// InStream steht an Position 0, OutPNG ist leer
Result := (ImageFormat <> mifUnknown) and
AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;
initialization
RegisterModernImageDecoderBackend(MyModernDecoder);
finalization
ClearModernImageDecoderBackend; // zurück zum MagickWand-Backend
Wird ein Bild zu einem Dokument hinzugefügt, verlangt die Bibliothek immer, dass die Orientation angewandt wird. Handy-Kameras speichern das Sensorbild routinemäßig seitlich und vermerken die beabsichtigte Drehung als Metadaten, also liefert ein Callback, der ApplyOrientation ignoriert, Hochformat-Fotos auf der Seite liegend. Ein selbstgestricktes Backend macht das leicht falsch, und der Fehler fällt leicht nicht auf, wenn die Testbilder alle im Querformat geschossen waren
Warum nach PNG im Speicher dekodieren?
Das Backend wandelt das dekodierte Bild in ein In-Memory-PNG um und füttert dieses PNG in den bestehenden PNG-Einbettungspfad. Das sieht neben der Übergabe eines rohen Pixel-Puffers wie ein Umweg aus, ist aber die billigere korrekte Option. PNG kann alles ausdrücken, was überleben muss (Alpha, Farbtyp, 8 oder 16 Bits je Sample und ein eingebettetes ICC-Profil), und PDF Library for Delphi hat bereits eine ausgereifte Route von PNG zu einem PDF-Bildobjekt mit den richtigen Filtern, Softmask und Farbraum. Moderne Formate erben diese Arbeit, statt eine parallele Implementierung mit eigenen Bugs zu bekommen. Die Dekodier-Ausgabe wird auf 16 Bits normalisiert, wenn die Quelle mehr als 8 Bits je Kanal hat, sonst auf 8 Bits
Keine temporären Dateien werden geschrieben, also gibt es nach einem Absturz nichts aufzuräumen. Eine Kleinigkeit brauchte explizite Behandlung. Während der Entwicklung stellten wir fest, dass der Codec das ICC-Profil fallen lassen konnte, während er das In-Memory-Bild nach PNG umschaltete, was exakt den Farbverschiebe-Fall wieder eingeführt hätte, gegen den dieser Pfad existiert. Das Backend liest nun das Quellprofil vor dem Formatwechsel, komprimiert es mit Flate, schreibt es in einen gültigen iCCP-Chunk mit neu berechneter CRC und entfernt jeden sRGB-Chunk, der ihm widersprechen würde. In einem Win64-Lauf an einer echten AVIF blieb die Ausgabe 16-Bit-RGBA mit 16-Bit-Alpha, und das aus dem PDF extrahierte Profil war 60.960 Bytes groß mit einem SHA-256 identisch zum Quellprofil
Den Codec beim Start prüfen
Testen Sie den Codec, wenn die Anwendung startet, bevor das erste Foto ankommt. ModernImageCodecAvailable gibt 1 zurück, wenn entweder ein registrierter Callback oder ein ladbares MagickWand-Modul vorhanden ist, und SetModernImageCodecLibrary richtet den Loader auf eine bestimmte Datei oder ein Verzeichnis:
procedure CheckModernImageSupport(Lib: TPDFlib);
var
CodecDir: string;
begin
CodecDir := ExtractFilePath(ParamStr(0)) + 'codecs';
// Gibt 0 zurück, sobald in diesem Prozess bereits ein Codec-Modul geladen ist
if Lib.SetModernImageCodecLibrary(CodecDir) = 0 then
Log('Codec already loaded, path change ignored');
if Lib.ModernImageCodecAvailable = 0 then
Log('No AVIF/HEIF/JPEG XL decoder in ' + CodecDir +
' - phone photos will be rejected');
end;
Zwei Verhalten lohnt es sich zu kennen, bevor Sie das in einen Installer oder einen Dienst einwicken. Ein gescheitertes Laden wird gemerkt, also durchsucht die Bibliothek die Platte nicht erneut für jedes Bild. Testet Ihr Dienst, bevor der Installer das Codec-Verzeichnis fertig kopiert hat, meldet er weiter, dass der Codec nicht verfügbar ist, bis SetModernImageCodecLibrary erneut aufgerufen wird, was das gemerkte Versagen löscht. Das Gegenteil gilt ebenfalls: Sobald ein Modul geladen ist, gibt SetModernImageCodecLibrary 0 zurück und der Pfad bleibt für die Lebensdauer des Prozesses, wie er ist, denn ein nativen Codec unter laufenden Konvertierungen zu entladen ist nichts, was wir implizit tun wollten
Achten Sie auch auf die Größe der Ausgabe. Ein 16-Bit-RGBA-Foto mit seinem Profil ist ein großes Bildobjekt, und ein Report mit vierzig davon wird schnell schwer. Für Dokumente, die nur am Bildschirm gelesen werden, ist das Heruntertakten vor dem Einbetten der richtige Tausch, und die allgemeinen Größen-Hebel sind in PDF-Dateigrößen-Optimierung behandelt. Auch die Farbpolitik verdient eine überlegte Entscheidung. Jedes Quellprofil zu behalten ist für Archiv- und Druckarbeit richtig, während alles in einen dokumentweiten Farbraum zu konvertieren zu einem Satz Fotografien von verschiedenen Handys passt, die nebeneinander konsistent aussehen müssen; dieser Weg ist in ein Dokument in einen anderen Farbraum umfärben beschrieben. Um zu bestätigen, was tatsächlich in der Datei gelandet ist, meldet der Inspektionspfad in Text-, Bild- und Font-Extraktion die Bildobjekte, die ein Dokument trägt
AVIF-, HEIF- und JPEG-XL-Eingabe sitzt neben PNG-, JPEG-, TIFF- und WebP-Eingabe, Farbraum-Konvertierung und Bild-Optimierung in derselben Bibliothek für Delphi, C++Builder und Free Pascal. Lizenzierung, Plattform-Support und die vollständige API-Referenz stehen auf der Produktseite von PDF Library for Delphi