기술 문서

Delphi에서 PDF에 AVIF, HEIF, JPEG XL 이미지 임베드하기

휴대폰의 HEIC 사진이 Delphi로 만든 리포트에 들어가고, PDF는 화면에서 멀쩡해 보이는데, 인쇄물은 붉은색이 밀려 있고 잘라낸 로고가 단색 상자 위에 앉아 있습니다. 사진이 들어오는 길에서 플랫폼 비트맵을 거쳐 디코딩된 것입니다. 대신 PDF Library for Delphi의 AddModernImageFromFile로 로드하면 AVIF, HEIF, JPEG XL 이미지는 알파와 ICC 프로파일, 16비트 채널을 기본으로 유지합니다

이 형식들은 주로 휴대폰을 통해 문서 워크플로에 들어왔습니다. iPhone은 오래전부터 HEIC를 기본으로 저장하고, Android 기기는 AVIF를 만들어 내며, JPEG XL은 아카이브와 사진 파이프라인에 모습을 드러내고 있습니다. JPEG와 PNG를 중심으로 설계된 리포트 생성기는 하나가 도착하면 두 가지 선택지가 있습니다. 파일을 거부하거나, 운영체제가 제공하는 디코더로 열어 납작해진 8비트 비트맵을 받아들이거나입니다. 이 글은 세 번째 길을 다룹니다. 라이브러리가 형식을 직접 인식하고, 여러분이 고른 코덱으로 디코딩하며, 깊이와 색 데이터를 온전히 지닌 채 결과를 임베드합니다

비트맵 왕복은 무엇을 잃는가?

플랫폼 비트맵 변환은 한 번에 세 가지를 잃습니다. 투명도, 내장 색 프로파일, 8비트를 넘는 모든 채널 깊이입니다. 각각에 의존하는 워크플로가 있습니다. 알파는 페이지 콘텐츠 위에 놓이는 로고와 제품 컷아웃에 필요합니다. ICC 프로파일은 인쇄되거나 기준 색에 맞춰 조정될 모든 것에 필요한데, 없으면 뷰어는 sRGB를 가정하고 넓은 색역의 카메라 이미지가 재해석됩니다. 16비트 채널은 의료, 과학, 검사 이미지에 필요합니다. 8비트로 양자화하면 이미지가 촬영된 목적인 계조가 정확히 지워집니다

이 중 무엇도 오류를 내지 않습니다. 페이지는 렌더링되고 사진은 알아볼 수 있으며, 문제는 누군가 인쇄물을 원본과 비교할 때까지 기다립니다. 그래서 우리는 보존을 호출자가 옵트인하는 기능이 아니라 기본값으로 취급합니다. AddModernImageFromFile, AddModernImageFromStream, AddModernImageFromString은 모두 기본값 8인 Options 매개변수를 받는데, 옵션 8이 알파와 ICC, 16비트 샘플을 함께 PDF 이미지 객체에 담아 나르는 설정입니다

PDF Library for Delphi 다이어그램: 알파와 ICC 프로파일, 16비트 채널을 버리는 플랫폼 비트맵 변환과, 세 가지를 모두 PDF 이미지 객체로 나르는 모던 이미지 경로의 비교
일반적인 비트맵 디코딩은 페이지가 렌더링되기도 전에 조용히 투명도를 평탄화하고 채널을 양자화합니다

16비트 이미지는 여러분이 만드는 파일도 바꿉니다. 이미지가 16비트 샘플을 지니면 PDF Library for Delphi는 문서를 최소 PDF 1.5로 올립니다. 컴포넌트당 16비트가 이미지 XObject에 유효해진 버전이기 때문입니다. 다운스트림 시스템이 PDF 1.4를 고집한다면 그 요구와 16비트 사진은 양립할 수 없고, 설계 시점에 알아내는 것이 낫습니다

페이지에 휴대폰 사진 추가하기

모던 이미지 호출은 성공 시 0보다 큰 이미지 ID를, 실패 시 0을 돌려주며, 그 ID는 DrawImageAndRelease나 익숙한 SelectImage / DrawImage 쌍으로 넘어갑니다. 아래 스케치에는 실제 휴대폰 업로드가 필요로 하는 단 하나의 폴백이 들어 있는데, 바로 뒤에서 설명합니다:

uses
  PDFlibrary;

var
  Lib: TPDFlib;
  ImageID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.NewDocument;
    Lib.SetPageSize('A4');      // NewDocument는 이미 페이지 1을 생성했습니다
    Lib.SetOrigin(1);           // Top을 위쪽 가장자리부터 측정합니다

    // Options는 기본값 8: 알파, ICC 프로파일, 16비트 채널
    ImageID := Lib.AddModernImageFromFile('uploads\pump-housing.heic');

    // 확장자는 HEIC라 하지만 바이트는 평범한 JPEG일 수 있다
    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;

폴백이 존재하는 이유는 파일 이름이 거짓말을 하기 때문입니다. 공유 시트, 메신저 앱, 업로드 폼은 내보내는 길에 HEIC를 JPEG로 바꾸면서 원래 이름을 유지하거나, 받는 폼이 기대하는 무엇이든 이름을 바꿔 버립니다. AddModernImageFromFile은 확장자를 절대 보지 않습니다. 첫 바이트들을 살펴보고 AVIF, HEIF, JPEG XL이 아니면 디코더를 건드리지 않은 채 0을 돌려줍니다. 따라서 .heic 접미사를 쓰고 있는 JPEG는 모던 호출에서 실패하고, 같은 방식으로 내용을 후각하는 일반 AddImageFromFile에서 성공합니다. 이 함수는 JPEG, PNG, TIFF 등 고전 형식들을 처리합니다

전부 AddImageFromFile로 보내면 왜 안 될까? 이 함수도 모던 형식을 인식하기는 하지만, 모던 호출은 의도를 명시하고 아무것도 넘기지 않을 때 옵션 8을 공급합니다. 입력이 휴대폰 사진일 것으로 기대되는 호출 지점이라면 모던 호출을 보고 싶습니다

라이브러리는 AVIF와 HEIC를 어떻게 구분할까?

PDF Library for Delphi는 최대 4096바이트의 제한된 헤더 읽기로 형식을 판정한 다음 호출자의 스트림 위치를 제자리에 되돌려 놓습니다. JPEG XL이 쉬운 사례입니다. 원시 코덱스트림은 FF 0A로 시작하고, 컨테이너 형태는 고정된 12바이트 시그니처 박스로 시작합니다. AVIF와 HEIF는 더 어렵습니다. 둘 다 ISO base media file format, 즉 MP4와 같은 박스 구조 안에 살며, ftyp 박스 안에 나열된 브랜드에서만 갈립니다

함정은 브랜드 목록이 겹친다는 점입니다. AVIF 파일은 보통 호환 브랜드에 mif1을 나열합니다. AVIF는 HEIF와 같은 이미지 파일 프로파일 위에 세워졌기 때문입니다. mif1을 보는 순간 HEIF라고 답하는 탐지기는 실제 AVIF 파일의 상당수를 잘못 표시합니다. 그래서 라이브러리는 브랜드 목록 전체를 먼저 훑고 avif나 avis가 HEIF 계열(heic, heix, hevc, hevx, heim, heis, mif1, msf1)보다 우선하도록 합니다

제한된 매직 넘버 탐지 게이트 다이어그램. 명시적 경로, 환경 변수, 실행 파일 디렉터리 또는 등록된 Delphi 콜백에서 디코딩 백엔드를 고르기 전에 AVIF, HEIF, JPEG XL을 확인함
탐지는 제한된 헤더 읽기 위에서 돌아가므로, 이름을 바꾼 실행 파일이 코덱에 닿지 않습니다

디코딩 전에 탐지를 돌리는 것은 안전 성질이기도 합니다. 모르는 입력이나 위장한 입력은 외부 코덱에 닿지 않으므로, 이름을 바꾼 실행 파일이나 잘못된 업로드는 그것을 파싱해야 할 대형 이미지 디코더가 아니라 수십 번의 바이트 비교로 돌려보내집니다

디코딩이 일어나는 곳

PDF Library for Delphi는 AVIF, HEIF, JPEG XL 코덱을 자기 안에 컴파일하지 않습니다. 그 코덱들은 크고 자주 바뀌며, 휴대폰 사진을 한 번도 못 보는 애플리케이션이 그 비용을 치러야 할 이유가 없습니다. 기본 백엔드는 첫 사용 시 ImageMagick의 MagickWand 모듈을 프로세스 안에서 로드하며 고정된 순서로 찾습니다. SetModernImageCodecLibrary로 설정한 파일이나 디렉터리, 그다음 PDFLIB_MODERN_IMAGE_CODEC 환경 변수, 그다음 실행 파일의 디렉터리, 그다음 평범한 시스템 검색 경로입니다. Windows에서는 각 위치에서 CORE_RL_MagickWand_.dll, MagickWand-7.Q16HDRI-10.dll, MagickWand-7.Q16-10.dll을 시도합니다

실용적인 결과가 둘 따라옵니다. 코덱은 Q16 빌드를 배포하십시오. 8비트 퀀텀 빌드는 어떤 옵션을 넘기든 16비트 샘플을 넘겨줄 수 없습니다. 그리고 코덱 디렉터리에 modules\coders 하위 폴더가 있으면 라이브러리가 MAGICK_HOME, MAGICK_CONFIGURE_PATH, MAGICK_CODER_MODULE_PATH를 채워 줍니다. 다만 호스트 프로세스가 아직 설정하지 않은 변수만입니다. 자체 런타임 배치를 지닌 애플리케이션은 그것을 유지합니다

우리의 권고는 경로를 명시적으로 설정하고 시스템 검색 경로에 의존하지 않는 것입니다. 우연히 PATH에 다른 ImageMagick이 있는 기계가 여러분의 리포트 생성기가 쓸 코덱을 결정하게 되는데, 이런 종류의 차이는 고객 한 명의 서버에서만 드러나는 차이입니다

이미 디코더를 실어 나르는 애플리케이션이나 외부 모듈 로드가 허용되지 않는 애플리케이션은 대신 콜백을 등록합니다. 콜백은 소스 스트림을 읽고 출력 스트림에 PNG 바이트를 쓰며 방향 플래그를 존중하는 평범한 함수입니다. 등록은 프로세스 전역이며 락으로 보호되므로, 문서마다가 아니라 시작 시점에 한 번 하십시오:

uses
  Classes, PDFlibModernImage,
  AppCodec;  // 이미 배포하는 코덱을 감싸는 여러분 자신의 유닛

function MyModernDecoder(InStream, OutPNG: TStream;
  ImageFormat: TPDFlibModernImageFormat;
  ApplyOrientation: Boolean): Boolean;
begin
  // InStream은 위치 0에 있고, OutPNG는 비어 있다
  Result := (ImageFormat <> mifUnknown) and
    AppDecodeToPNG(InStream, OutPNG, ApplyOrientation);
end;

initialization
  RegisterModernImageDecoderBackend(MyModernDecoder);

finalization
  ClearModernImageDecoderBackend;  // MagickWand 백엔드로 되돌림

이미지가 문서에 추가될 때 라이브러리는 언제나 방향 적용을 요청합니다. 휴대폰 카메라는 센서 이미지를 옆으로 눕혀 저장하고 의도된 회전을 메타데이터로 기록하는 일이 흔하므로, ApplyOrientation을 무시하는 콜백은 옆으로 누운 세로 사진을 만들어 냅니다. 자작 백엔드는 이 부분을 쉽게 틀리고, 테스트 이미지가 모두 가로로 찍혔다면 실수는 놓치기도 쉽습니다

메모리에서 PNG로 디코딩하는 이유

백엔드는 디코딩된 이미지를 메모리 상의 PNG로 변환해 그 PNG를 기존 PNG 임베딩 경로에 먹입니다. 원시 픽셀 버퍼를 넘겨주는 것에 비해 우회처럼 보이지만, 이것이 더 저렴한 올바른 선택입니다. PNG는 살아남아야 할 모든 것(알파, 색 타입, 샘플당 8 또는 16비트, 내장 ICC 프로파일)을 표현할 수 있고, PDF Library for Delphi에는 이미 올바른 필터와 소프트 마스크, 색 공간을 지닌 PDF 이미지 객체로 가는 성숙한 PNG 경로가 있습니다. 모던 형식은 나중에 발견할 버그를 지닌 병렬 구현을 만드는 대신 그 작업을 물려받습니다. 디코더 출력은 소스가 채널당 8비트를 넘으면 16비트로, 그 외에는 8비트로 정규화됩니다

임시 파일은 기록되지 않으므로 크래시 뒤에 청소할 것도 없습니다. 한 가지 주름은 명시적 처리가 필요했습니다. 개발 중 우리는 코덱이 메모리 이미지를 PNG로 바꾸는 과정에서 ICC 프로파일을 떨어뜨릴 수 있다는 것을 발견했는데, 그대로라면 이 경로가 존재하는 이유인 바로 그 색 밀림을 되살리는 셈이었습니다. 백엔드는 이제 형식 전환 전에 소스 프로파일을 읽고, Flate로 압축해 재계산한 CRC와 함께 유효한 iCCP 청크로 기록하며, 모순되는 sRGB 청크는 제거합니다. 실제 AVIF로 돌린 Win64 실행에서 출력은 16비트 알파를 지닌 16비트 RGBA를 유지했고, PDF에서 추출한 프로파일은 60,960바이트로 소스 프로파일과 SHA-256이 일치했습니다

PDF Library for Delphi 다이어그램: 형식 전환 전에 소스 ICC 프로파일을 붙잡아 압축된 iCCP 청크로 재건하고 모순되는 sRGB 청크를 버리며 검증된 PNG-PDF 임베딩 경로를 재사용하는 메모리 PNG 브리지
형식이 바뀌기 전에 ICC 프로파일을 스냅샷하면 임베드된 사본이 소스와 바이트 단위로 동일하게 유지됩니다

시작 시점에 코덱 점검하기

첫 사진이 도착하기 전, 애플리케이션이 시작할 때 코덱을 살펴두십시오. ModernImageCodecAvailable은 등록된 콜백이나 로드 가능한 MagickWand 모듈이 있으면 1을 돌려주고, SetModernImageCodecLibrary는 로더를 특정 파일이나 디렉터리로 향하게 합니다:

procedure CheckModernImageSupport(Lib: TPDFlib);
var
  CodecDir: string;
begin
  CodecDir := ExtractFilePath(ParamStr(0)) + 'codecs';

  // 이 프로세스에서 코덱 모듈이 이미 로드되어 있으면 0을 돌려준다
  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;

이것을 인스톨러나 서비스에 붙이기 전에 알아 둘 만한 동작이 둘 있습니다. 실패한 로드는 기억됩니다. 라이브러리는 이미지마다 디스크를 다시 뒤지지 않습니다. 인스톨러가 코덱 폴더 복사를 끝내기 전에 서비스가 살펴보면, 기억된 실패를 지우는 SetModernImageCodecLibrary가 다시 호출되기 전까지 코덱을 계속 사용 불가로 보고합니다. 반대도 성립합니다. 모듈이 한 번 로드되면 SetModernImageCodecLibrary는 0을 돌려주고 경로는 프로세스가 사는 동안 그대로입니다. 변환 도중에 네이티브 코덱을 언로드하는 것을 암묵적으로 하고 싶지 않기 때문입니다

출력 크기도 살펴보십시오. 프로파일을 지닌 16비트 RGBA 사진은 큰 이미지 객체이며, 그런 사진 마흔 장이 들어간 리포트는 빠르게 무거워집니다. 화면에서만 읽을 문서라면 임베드 전에 다운샘플링이 맞는 트레이드이고, 일반적인 크기 레버는 PDF 파일 크기 최적화에서 다룹니다. 색 정책도 의식적인 결정이 필요합니다. 각 소스 프로파일을 유지하는 것은 아카이브와 인쇄 작업에 맞고, 모든 것을 문서 전역의 한 공간으로 변환하는 것은 나란히 놓였을 때 일관되게 보여야 하는, 서로 다른 휴대폰의 사진 묶음에 어울립니다. 그 경로는 문서를 다른 색 공간으로 재채색하기에서 기술합니다. 실제로 파일에 무엇이 떨어졌는지 확인하려면 텍스트, 이미지, 폰트 추출의 검사 경로가 문서가 지닌 이미지 객체들을 보고합니다

AVIF, HEIF, JPEG XL 입력은 Delphi, C++Builder, Free Pascal을 위한 같은 라이브러리 안에서 PNG, JPEG, TIFF, WebP 입력과 색 공간 변환, 이미지 최적화와 나란히 있습니다. 라이선스, 플랫폼 지원, 전체 API 레퍼런스는 PDF Library for Delphi 제품 페이지에 있습니다