Een HEIC-foto van een telefoon gaat in een door Delphi gegenereerd rapport, de PDF oogt goed op het scherm, en de afgedrukte pagina komt terug met verschoven roodtinten en een uitgesneden logo op een massief vlak. De foto werd onderweg via een platform-bitmap gedecodeerd; laad hem in plaats daarvan met AddModernImageFromFile in PDF Library for Delphi, en AVIF-, HEIF- en JPEG XL-afbeeldingen houden standaard alfa, het ICC-profiel en 16-bits kanalen vast
Deze formaten bereikten documentworkflows vooral via telefoons. iPhones slaan al jaren standaard HEIC op, Android-apparaten produceren AVIF, en JPEG XL duikt op in archief- en fotografiepijplijnen. Een rapportgenerator die om JPEG en PNG heen is ontworpen, heeft twee opties zodra er zo'n bestand aankomt: het bestand weigeren, of het openen via welke decoder het besturingssysteem ook aanbiedt en een afgeplatte 8-bits bitmap accepteren. Dit artikel neemt een derde route, waarin de bibliotheek het formaat zelf herkent, het decodeert via een codec die u kiest en het resultaat insluit met zijn diepte- en kleurgegevens intact
Wat verliest een bitmap-roundtrip?
Een platform-bitmapconversie verliest drie dingen in één stap: transparantie, het ingesloten kleurprofiel en elke kanaaldiepte boven 8 bits. Elk ervan heeft een workflow die ervan afhangt. Alfa telt voor logo's en uitgesneden productbeelden die over pagina-inhoud worden geplaatst. Het ICC-profiel telt voor alles dat wordt afgedrukt of tegen een referentie kleurgematcht, want zonder het profiel veronderstelt de viewer sRGB en wordt een beeld met brede gamut opnieuw geïnterpreteerd. En 16-bits kanalen tellen voor medische, wetenschappelijke en inspectiebeelden, waar kwantiseren naar 8 bits precies de gradaties uitwist waarvoor het beeld werd vastgelegd
Niets hiervan produceert een foutmelding. De pagina rendert, de foto is herkenbaar, en het probleem wacht tot iemand een afdruk naast het origineel legt. Daarom behandelen we behoud als de standaard in plaats van als iets waar aanroepers voor moeten kiezen: AddModernImageFromFile, AddModernImageFromStream en AddModernImageFromString nemen allemaal een Options-parameter die standaard op 8 staat, en optie 8 is de instelling die alfa, ICC en 16-bits samples samen in het PDF-afbeeldingsobject brengt
Een 16-bits afbeelding verandert ook het bestand dat u produceert. PDF Library for Delphi hijst het document op naar minstens PDF 1.5 wanneer een afbeelding 16-bits samples draagt, want dat is de versie waarin 16 bits per component geldig werd voor image XObjects. Als een downstream-systeem op PDF 1.4 blijft staan, kunnen die eis en 16-bits foto's niet allebei worden gehonoreerd, en beter ontdekt u dat tijdens het ontwerp
Een telefoonfoto op een pagina zetten
De moderne afbeeldingsaanroepen geven bij succes een afbeeldings-ID groter dan nul terug en 0 bij falen, en de ID gaat daarna naar DrawImageAndRelease of naar het gebruikelijke paar SelectImage / DrawImage. De schets hieronder bevat de ene terugval die echte telefoonuploads nodig hebben, en die wordt meteen erna uitgelegd:
uses
PDFlibrary;
var
Lib: TPDFlib;
ImageID: Integer;
begin
Lib := TPDFlib.Create;
try
Lib.NewDocument;
Lib.SetPageSize('A4'); // NewDocument heeft pagina 1 al aangemaakt
Lib.SetOrigin(1); // Top vanaf de bovenrand meten
// Options heeft standaard 8: alfa, ICC-profiel en 16-bits kanalen
ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');
// De extensie zegt HEIC, maar de bytes kunnen een gewone JPEG zijn
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;
De terugval bestaat omdat bestandsnamen liegen. Deelbladen, chatapps en uploadformulieren zetten HEIC onderweg om naar JPEG terwijl ze de originele naam houden, of hernoemen bestanden naar wat het ontvangende formulier verwacht. AddModernImageFromFile kijkt nooit naar de extensie. Hij bekijkt de eerste bytes, en zijn het geen AVIF, HEIF of JPEG XL, dan geeft hij 0 terug zonder de decoder aan te raken. Een JPEG met een .heic-achtervoegsel faalt daarom bij de moderne aanroep en slaagt via de algemene AddImageFromFile, die op dezelfde manier aan de inhoud ruikt en JPEG, PNG, TIFF en de andere klassieke formaten aankan
Waarom niet alles door AddImageFromFile sturen? Hij herkent de moderne formaten ook, maar de moderne aanroepen maken de intentie expliciet en leveren optie 8 wanneer u niets doorgeeft, dus we zien ze liever op de aanroeplek staan wanneer de invoer een telefoonfoto zou moeten zijn
Hoe onderscheidt de bibliotheek AVIF van HEIC?
PDF Library for Delphi bepaalt het formaat uit een begrensde headerlezing van hooguit 4096 bytes en zet daarna de streampositie van de aanroeper terug waar die stond. JPEG XL is het makkelijke geval: een rauwe codestream begint met FF 0A, en de containervorm begint met een vaste signature-box van 12 bytes. AVIF en HEIF zijn lastiger, want beide wonen in het ISO base media file format, dezelfde boxstructuur als MP4, en verschillen alleen in de brands die in de ftyp-box staan
De valkuil is dat de brandlijsten overlappen. Een AVIF-bestand vermeldt normaliter mif1 onder zijn compatible brands, want AVIF is gebouwd op hetzelfde image file-profiel als HEIF. Een detector die HEIF teruggeeft zodra hij mif1 ziet, etiketteert een flink deel van de echte AVIF-bestanden verkeerd. De bibliotheek scant daarom eerst de hele brandlijst en laat avif of avis winnen van de HEIF-familie (heic, heix, hevc, hevx, heim, heis, mif1, msf1)
Detectie vóór decoding is ook een veiligheidseigenschap. Een onbekende of vermomde invoer bereikt de externe codec nooit, dus een hernoemd uitvoerbaar bestand of een misvormde upload wordt afgewezen met enkele tientallen bytevergelijkingen in plaats van door een grote afbeeldingsdecoder die hem had moeten parsen
Waar de decoding gebeurt
PDF Library for Delphi compileert geen AVIF-, HEIF- of JPEG XL-codec in zichzelf. Die codecs zijn groot, ze veranderen vaak, en een toepassing die nooit een telefoonfoto ziet hoort er niet voor te betalen. De standaardbackend laadt bij eerste gebruik een ImageMagick-MagickWand-module in-process en zoekt hem in een vaste volgorde: het bestand of de directory die via SetModernImageCodecLibrary is ingesteld, daarna de omgevingsvariabele PDFLIB_MODERN_IMAGE_CODEC, daarna de directory van de executable, daarna het normale systeemzoekpad. Op Windows probeert hij in elke locatie CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll en MagickWand-7.Q16-10.dll
Twee praktische gevolgen volgen daaruit. Lever een Q16-build van de codec mee, want een build met 8-bits kwantum kan geen 16-bits samples overdragen, welke optie u ook doorgeeft. En bevat de codecdirectory een submap modules\coders, dan vult de bibliotheek MAGICK_HOME, MAGICK_CONFIGURE_PATH en MAGICK_CODER_MODULE_PATH voor u in, maar alleen die variabelen die het hostproces nog niet zelf heeft gezet. Een toepassing met zijn eigen runtime-indeling houdt die
Onze aanbeveling is het pad expliciet in te stellen en niet op het systeemzoekpad te vertrouwen. Een machine die toevallig een andere ImageMagick op PATH heeft, beslist anders welke codec uw rapportgenerator gebruikt, en dat is het soort verschil dat alleen op de server van één klant opduikt
Toepassingen die al een decoder meeleveren, of die geen externe module mogen laden, registreren in plaats daarvan een callback. De callback is een kale functie die de bronstream leest, PNG-bytes naar de uitvoerstream schrijft en de oriëntatievlag honoreert. De registratie geldt procesbreed en wordt door een lock beschermd, dus doe het één keer bij het opstarten in plaats van per document:
uses
Classes, PDFlibModernImage,
AppCodec; // uw eigen unit die de codec verpakt die u al meelevert
function MyModernDecoder(InStream, OutPNG: TStream;
ImageFormat: TPDFlibModernImageFormat;
ApplyOrientation: Boolean): Boolean;
begin
// InStream staat op positie 0, OutPNG is leeg
Result := (ImageFormat <> mifUnknown) and
AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;
initialization
RegisterModernImageDecoderBackend(MyModernDecoder);
finalization
ClearModernImageDecoderBackend; // terug naar de MagickWand-backend
Wanneer een afbeelding aan een document wordt toegevoegd, vraagt de bibliotheek altijd dat de oriëntatie wordt toegepast. Telefooncamera's bewaren het sensorbeeld routinegewijs op zijn zij en leggen de bedoelde rotatie vast als metadata, dus een callback die ApplyOrientation negeert, produceert staande foto's die op hun kant liggen. Een eigen backend maakt deze fout gemakkelijk, en de fout is gemakkelijk te missen wanneer alle testbeelden liggend zijn geschoten
Waarom in het geheugen naar PNG decoden?
De backend zet het gedecodeerde beeld om naar een PNG in het geheugen en voert die PNG aan de bestaande PNG-insluitroute. Dat oogt als een omweg naast het overdragen van een rauwe pixelbuffer, maar het is de goedkopere correcte optie. PNG kan alles uitdrukken dat moet overleven (alfa, kleurtype, 8 of 16 bits per sample en een ingesloten ICC-profiel) en PDF Library for Delphi heeft al een volwassen route van PNG naar een PDF-afbeeldingsobject met de juiste filters, soft mask en kleurruimte. Moderne formaten erven dat werk in plaats van een parallelle implementatie te krijgen met zijn eigen bugs om te vinden. De decoderuitvoer wordt genormaliseerd naar 16 bits wanneer de bron meer dan 8 bits per kanaal heeft, en anders naar 8 bits
Er worden geen tijdelijke bestanden geschreven, dus na een crash is er niets op te ruimen. Eén kromming vroeg om expliciete afhandeling. Tijdens de ontwikkeling bleek dat de codec het ICC-profiel kon laten vallen bij het omschakelen van het in-geheugenbeeld naar PNG, wat precies de kleurverschuiving opnieuw had geïntroduceerd die dit pad moet voorkomen. De backend leest het bronprofiel nu vóór de formaatwissel, comprimeert het met Flate, schrijft het in een geldige iCCP-chunk met herberekende CRC en verwijdert elke sRGB-chunk die daarmee zou knijpen. In een Win64-run op een echte AVIF hield de uitvoer 16-bits RGBA met 16-bits alfa vast, en het uit de PDF gehaalde profiel was 60.960 bytes met een SHA-256 identiek aan het bronprofiel
De codec bij het opstarten controleren
Toets de codec zodra de toepassing start, voordat de eerste foto binnenkomt. ModernImageCodecAvailable geeft 1 terug wanneer er ofwel een geregistreerde callback ofwel een laadbare MagickWand-module aanwezig is, en SetModernImageCodecLibrary richt de lader op een specifiek bestand of directory:
procedure CheckModernImageSupport(Lib: TPDFlib);
var
CodecDir: string;
begin
CodecDir := ExtractFilePath(ParamStr(0)) + 'codecs';
// Geeft 0 terug zodra er in dit proces al een codecmodule is geladen
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;
Twee gedragingen zijn het weten waard voordat u dit in een installer of een service verwerkt. Een mislukte laadpoging wordt onthouden, dus de bibliotheek doorzoekt de schijf niet opnieuw bij elke afbeelding. Toetst uw service voordat de installer klaar is met het kopiëren van de codecmap, dan blijft hij de codec als onbeschikbaar melden tot SetModernImageCodecLibrary opnieuw wordt aangeroepen, wat die onthouden mislukking wist. Het omgekeerde geldt ook: zodra er een module is geladen, geeft SetModernImageCodecLibrary 0 terug en blijft het pad staan voor de levensduur van het proces, want het lossen van een native codec onder lopende conversies is niet iets dat we impliciet willen doen
Houd ook de grootte van de uitvoer in de gaten. Een 16-bits RGBA-foto met zijn profiel is een groot afbeeldingsobject, en een rapport met veertig daarvan wordt snel zwaar. Voor documenten die alleen op het scherm worden gelezen, is downsamplen vóór insluiten de juiste afweging, en de algemene groteregelaars worden behandeld in PDF-bestandsgrootte-optimalisatie. Kleurbeleid verdient ook een bewuste beslissing. Elk bronprofiel behouden is correct voor archief- en drukwerk, terwijl alles omzetten naar één documentbrede kleurruimte past bij een set foto's van verschillende telefoons die naast elkaar consistent moeten ogen; die route wordt beschreven in een document omkleuren naar een andere kleurruimte. Om te bevestigen wat er werkelijk in het bestand is beland, rapporteert de inspectieroute in tekst-, afbeeldings- en fontextractie de afbeeldingsobjecten die een document draagt
AVIF-, HEIF- en JPEG XL-invoer staat naast PNG-, JPEG-, TIFF- en WebP-invoer, kleurruimteconversie en afbeeldingsoptimalisatie in dezelfde bibliotheek voor Delphi, C++Builder en Free Pascal. Licenties, platformondersteuning en de volledige API-referentie staan op de productpagina van PDF Library for Delphi