Zdjęcie HEIC z telefonu trafia do raportu generowanego w Delphi, PDF na ekranie wygląda dobrze, a wydruk wraca z przesuniętymi czerwieniami i wyciętym logo siedzącym na pełnym prostokącie. Zdjęcie było dekodowane przez platformową bitmapę po drodze; wczytaj je zamiast tego przez AddModernImageFromFile w PDF Library for Delphi, a obrazy AVIF, HEIF i JPEG XL zachowają domyślnie kanał alfa, profil ICC i kanały 16-bitowe
Te formaty trafiły do obiegów dokumentowych głównie przez telefony. iPhone'y od lat zapisują domyślnie HEIC, urządzenia z Androidem produkują AVIF, a JPEG XL pojawia się w obiegach archiwizacyjnych i fotograficznych. Generator raportów zaprojektowany wokół JPEG i PNG ma przy takim pliku dwie opcje: odmówić, albo otworzyć go przez dowolny dekoder oferowany przez system operacyjny i przyjąć spłaszczoną bitmapę 8-bitową. Ten artykuł opisuje trzecią drogę: biblioteka sama rozpoznaje format, dekoduje go przez kodek, który wybierzesz, i osadza wynik z nienaruszoną głębią i danymi koloru
Co gubi przejście przez bitmapę?
Konwersja przez platformową bitmapę gubi trzy rzeczy za jednym zamachem: przezroczystość, osadzony profil kolorów i wszelką głębię kanałów powyżej 8 bitów. Każda z nich ma obieg pracy, który na niej polega. Alfa ma znaczenie dla logotypów i wyciętych produktów kładzionych na treść strony. Profil ICC ma znaczenie dla wszystkiego, co pójdzie do druku albo będzie dopasowane kolorystycznie do wzorca, bo bez niego przeglądarka zakłada sRGB i szerokopasmowy obraz z kamery jest reinterpretowany. A kanały 16-bitowe mają znaczenie dla obrazowania medycznego, naukowego i kontrolnego, gdzie kwantyzacja do 8 bitów wymazuje dokładnie te gradacje, dla których obraz był rejestrowany
Żadne z tego nie produkuje błędu. Strona się renderuje, zdjęcie jest rozpoznawalne, a problem czeka, aż ktoś zestawi wydruk z oryginałem. Dlatego traktujemy zachowanie jako domyślne, a nie jako coś, do czego wywołujący musiałby się dopisać: AddModernImageFromFile, AddModernImageFromStream i AddModernImageFromString wszystkie biorą parametr Options domyślnie równy 8, a opcja 8 to ustawienie, które niesie alfa, ICC i próbki 16-bitowe do obiektu obrazu PDF razem
Obraz 16-bitowy zmienia też produkowany plik. PDF Library for Delphi podnosi dokument do co najmniej PDF 1.5, gdy obraz niesie próbki 16-bitowe, bo od tej wersji 16 bitów na składową jest ważne dla image XObject. Jeśli system po drodze upiera się przy PDF 1.4, żądania tego i fotografii 16-bitowych nie da się pogodzić — lepiej przekonać się o tym na etapie projektowania
Dodawanie zdjęcia z telefonu do strony
Wywołania nowoczesnych obrazów zwracają przy sukcesie identyfikator obrazu większy od zera, a przy porażce 0, po czym identyfikator idzie do DrawImageAndRelease albo do zwykłej pary SelectImage / DrawImage. Szkic poniżej zawiera jedno omijanie, którego naprawdę potrzebują wysyłki z telefonów, i jest ono wyjaśnione zaraz pod nim:
uses
PDFlibrary;
var
Lib: TPDFlib;
ImageID: Integer;
begin
Lib := TPDFlib.Create;
try
Lib.NewDocument;
Lib.SetPageSize('A4'); // NewDocument już utworzył stronę 1
Lib.SetOrigin(1); // pomiar Top od górnej krawędzi
// Options domyślnie 8: kanał alfa, profil ICC i kanały 16-bitowe
ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');
// Rozszerzenie mówi HEIC, ale bajty mogą być zwykłym JPEG-iem
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;
To omijanie istnieje, bo nazwy plików kłamią. Arkusze udostępniania, komunikatory i formularze wysyłkowe konwertują HEIC na JPEG przy wyjściu, zachowując oryginalną nazwę, albo przemianowują pliki na to, czego oczekuje formularz przyjmujący. AddModernImageFromFile nigdy nie patrzy na rozszerzenie. Ogląda pierwsze bajty i jeśli nie są to AVIF, HEIF ani JPEG XL, zwraca 0, nie dotykając dekodera. JPEG noszący sufiks .heic polegnie więc na nowoczesnym wywołaniu i powiedzie się przez ogólne AddImageFromFile, które wącha zawartość tak samo i obsługuje JPEG, PNG, TIFF i inne klasyczne formaty
Czemu nie wysyłać wszystkiego przez AddImageFromFile? Ono też rozpoznaje nowoczesne formaty, ale wywołania nowoczesne czynią zamiar jawnym i podają opcję 8, gdy nie podasz niczego, więc woleliśmy widzieć je w miejscu wywołania, ilekroć na wejściu oczekiwane jest zdjęcie z telefonu
Skąd biblioteka wie, że to AVIF, a nie HEIC?
PDF Library for Delphi rozstrzyga format na podstawie ograniczonego odczytu nagłówka, najwyżej 4096 bajtów, po czym oddaje pozycję strumienia wywołującego tam, gdzie była. JPEG XL to łatwy przypadek: surowy codestream zaczyna się od FF 0A, a forma kontenerowa od stałego 12-bajtowego pola sygnatury. AVIF i HEIF są trudniejsze, bo oba mieszkają w ISO base media file format — tej samej strukturze pól co MP4 — i różnią się tylko markami wypisanymi wewnątrz pola ftyp
Pułapką jest to, że listy marek nachodzą na siebie. Plik AVIF zwykle wypisuje mif1 wśród marek zgodnych, bo AVIF jest zbudowany na tym samym profilu pliku obrazowego co HEIF. Detektor, który zawraca HEIF w chwili, gdy zobaczy mif1, błędnie okaże dużą część prawdziwych plików AVIF. Biblioteka skanuje więc najpierw całą listę marek i pozwala, by avif albo avis wygrało z rodziną HEIF (heic, heix, hevc, hevx, heim, heis, mif1, msf1)
Detekcja przed dekodowaniem jest też własnością bezpieczeństwa. Nieznane albo przebrane wejście nigdy nie dociera do zewnętrznego kodeku — przemianowany plik wykonywalny albo zniekształcona wysyłka zostaje odprawiona kilkudziesięcioma porównaniami bajtów zamiast dużego dekodera obrazów, który musiałby to parsować
Gdzie odbywa się dekodowanie
PDF Library for Delphi nie kompiluje kodeka AVIF, HEIF ani JPEG XL do siebie. Te kodeki są duże, często się zmieniają, i aplikacja, która nigdy nie zobaczy zdjęcia z telefonu, nie powinna za nie płacić. Domyślny backend wczytuje moduł ImageMagick MagickWand wewnątrz procesu przy pierwszym użyciu i szuka go w stałej kolejności: plik lub katalog ustawiony przez SetModernImageCodecLibrary, potem zmienna środowiskowa PDFLIB_MODERN_IMAGE_CODEC, potem katalog pliku wykonywalnego, potem normalna ścieżka przeszukiwania systemu. Na Windows w każdym z tych miejsc próbuje CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll i MagickWand-7.Q16-10.dll
Płyną z tego dwie praktyczne konsekwencje. Wysyłaj kompilację kodeka Q16, bo kompilacja o kwancie 8-bitowym nie odda próbek 16-bitowych, cokolwiek byś nie podał w opcjach. A jeśli katalog kodeka zawiera podkatalog modules\coders, biblioteka uzupełni za ciebie MAGICK_HOME, MAGICK_CONFIGURE_PATH i MAGICK_CODER_MODULE_PATH — ale tylko te zmienne, których proces gospodarza jeszcze nie ustawił. Aplikacja z własnym układem czasu działania zachowa go
Nasza rekomendacja to ustawić ścieżkę jawnie i nie polegać na systemowej ścieżce przeszukiwania. Maszyna, która ma na PATH przypadkiem inny ImageMagick, zdecyduje inaczej, którego kodeka używa twój generator raportów — a to właśnie ten rodzaj różnicy, która wychodzi tylko na serwerze jednego klienta
Aplikacje, które już wysyłają własny dekoder albo nie mogą wczytywać zewnętrznego modułu, rejestrują zamiast tego callback. Callback to zwykła funkcja, która czyta strumień źródłowy, pisze bajty PNG do strumienia wyjściowego i honoruje flagę orientacji. Rejestracja jest procesowa i chroniona blokadą, więc zrób ją raz przy starcie, a nie per dokument:
uses
Classes, PDFlibModernImage,
AppCodec; // twój własny moduł opakowujący kodek, który już wysyłasz
function MyModernDecoder(InStream, OutPNG: TStream;
ImageFormat: TPDFlibModernImageFormat;
ApplyOrientation: Boolean): Boolean;
begin
// InStream stoi na pozycji 0, OutPNG jest pusty
Result := (ImageFormat <> mifUnknown) and
AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;
initialization
RegisterModernImageDecoderBackend(MyModernDecoder);
finalization
ClearModernImageDecoderBackend; // powrót do backendu MagickWand
Gdy obraz jest dodawany do dokumentu, biblioteka zawsze żąda nałożenia orientacji. Kamery w telefonach rutynowo przechowują obraz z sensora na boku i zapisują zamierzony obrót jako metadane, więc callback ignorujący ApplyOrientation wyprodukuje zdjęcia portretowe leżące na boku. Domowy backend popełnia tę pomyłkę łatwo, a pomyłkę łatwo przeoczyć, gdy wszystkie obrazy testowe były kręcone poziomo
Dlaczego dekodować do PNG w pamięci?
Backend zamienia zdekodowany obraz na PNG w pamięci i podaje ten PNG istniejącej ścieżce osadzania PNG. Obok podania surowego bufora pikseli wygląda to na wędrówkę okrężną, a jednak jest tańszą poprawną opcją. PNG potrafi wyrazić wszystko, co musi przeżyć (alfa, typ koloru, 8 albo 16 bitów na próbkę i osadzony profil ICC), a PDF Library for Delphi ma już dojrzałą drogę z PNG do obiektu obrazu PDF z właściwymi filtrami, miękką maską i przestrzenią kolorów. Nowoczesne formaty dziedziczą tę pracę zamiast dostać równoległą implementację z własnymi błędami do odkrycia. Wyjście dekodera jest normalizowane do 16 bitów, gdy źródło ma więcej niż 8 bitów na kanał, i do 8 bitów w przeciwnym razie
Żadne pliki tymczasowe nie są zapisywane, więc nie ma czego sprzątać po awarii. Jedna haczylica potrzebowała jawnej obsługi. Podczas developmentu odkryliśmy, że kodek mógł upuścić profil ICC przy przełączaniu obrazu w pamięci na PNG, co przywróciłoby dokładnie tę zmianę kolorów, do zapobiegania której ta ścieżka istnieje. Backend czyta teraz profil źródłowy przed zmianą formatu, kompresuje go Flate'em, zapisuje do poprawnego chunka iCCP z przeliczonym CRC i usuwa każdy chunk sRGB, który by mu zaprzeczył. W uruchomieniu Win64 na prawdziwym AVIF-ie wyjście zachowało 16-bitowe RGBA z alfą 16-bitową, a profil wyciągnięty z PDF miał 60 960 bajtów i SHA-256 identyczny z profilem źródłowym
Sprawdzanie kodeka przy starcie
Przetestuj kodek, gdy aplikacja startuje, zanim dotrze pierwsza fotografia. ModernImageCodecAvailable zwraca 1, gdy obecny jest zarejestrowany callback albo wczytywalny moduł MagickWand, a SetModernImageCodecLibrary celuje wczytywanie w konkretny plik lub katalog:
procedure CheckModernImageSupport(Lib: TPDFlib);
var
CodecDir: string;
begin
CodecDir := ExtractFilePath(ParamStr(0)) + 'codecs';
// Zwraca 0, gdy moduł kodeku jest już wczytany w tym procesie
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;
Dwa zachowania warto znać, zanim wpniesz to w instalator albo usługę. Nieudane wczytanie jest pamiętane, więc biblioteka nie przeszukuje dysku od nowa przy każdym obrazie. Jeśli twoja usługa testuje kodek, zanim instalator skończy kopiować katalog kodeka, będzie nadal raportować kodek jako niedostępny, aż do ponownego wywołania SetModernImageCodecLibrary, które czyści zapamiętaną porażkę. Odwrotna zależność też obowiązuje: gdy moduł raz się wczytał, SetModernImageCodecLibrary zwraca 0, a ścieżka zostaje taka, jaka jest, na całe życie procesu, bo wyładowywanie natywnego kodeka w trakcie trwających konwersji to nie jest coś, czego chcielibyśmy dokonywać w ciszy
Patrz też na rozmiar wyjścia. Fotografia RGBA 16-bitowa z własnym profilem to duży obiekt obrazu i raport z czterdziestoma takimi szybko zgrubieje. Dla dokumentów czytanych tylko na ekranie właściwym targiem jest pomniejszanie przed osadzeniem, a ogólne dźwignie rozmiaru pokrywa artykuł optymalizacja rozmiaru PDF. Polityka kolorów też zasługuje na świadomą decyzję. Zachowywanie każdego profilu źródłowego jest poprawne dla pracy archiwizacyjnej i poligraficznej, podczas gdy konwersja wszystkiego do jednej przestrzeni całego dokumentu pasuje do zestawu zdjęć z różnych telefonów, które muszą wyglądać spójnie obok siebie; tę drogę opisuje artykuł przebarwianie dokumentu do innej przestrzeni kolorów. By potwierdzić, co faktycznie wylądowało w pliku, ścieżka inspekcji w artykule ekstrakcja tekstu, obrazów i fontów raportuje obiekty obrazów, które dokument wozi
Wejście AVIF, HEIF i JPEG XL siedzi obok wejścia PNG, JPEG, TIFF i WebP, konwersji przestrzeni kolorów i optymalizacji obrazów w tej samej bibliotece dla Delphi, C++Builder i Free Pascal. Licencjonowanie, wsparcie platform i pełna referencja API są na stronie produktu PDF Library for Delphi