技術記事

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を前提に設計されたレポート生成器は、1つ届くたびに2つの選択を迫られます。ファイルを拒否するか、OSが提供するどんなデコーダーでも開いて平坦化された8ビットビットマップを受け入れるかです。この記事が扱うのは3つ目の道で、ライブラリ自らがフォーマットを認識し、自分で選んだコーデックを通してデコードし、深度と色データを保ったまま結果を埋め込みます

ビットマップの往復では何が失われるのか

プラットフォームのビットマップ変換は、3つのものを1ステップで失います。透過情報、埋め込みカラープロファイル、そして8ビットを超えるチャンネル深度です。それぞれに、それを頼りにするワークフローがあります。アルファは、ページのコンテンツの上に置かれるロゴや製品の切り抜きに効きます。ICCプロファイルは、印刷されるもの、基準に対してカラーマッチされるものすべてに効きます。プロファイルがなければビューアはsRGBを仮定し、広色域のカメラ画像は読み替えられてしまうからです。そして16ビットチャンネルは、医療、科学、検査の画像に効きます。8ビットへの量子化は、その画像が撮影された理由そのものである階調を消し去るからです

このどれも、エラーを生みません。ページはレンダリングされ、写真は認識でき、問題は誰かが印刷物をオリジナルと突き合わせるまで待っています。だからこそ私たちは、保持を「呼び出し側が選ぶもの」ではなく「デフォルト」として扱っています。AddModernImageFromFile、AddModernImageFromStream、AddModernImageFromStringはいずれもデフォルトが8のOptionsパラメータを受け取り、オプション8こそが、アルファとICCと16ビットサンプルをまとめてPDF画像オブジェクトへ運ぶ設定です

PDF Library for Delphi の比較図。アルファ、ICC プロファイル、16 ビットチャンネルを落とすプラットフォームビットマップ変換と、3 要素すべてを PDF イメージオブジェクトに引き継ぐ新しい画像経路の対比
汎用のビットマップデコードでは、ページが描画される前に透過情報が黙って平坦化され、チャネルが量子化されます

16ビット画像は、生成されるファイル自体も変えます。PDF Library for Delphiは、画像が16ビットサンプルを運ぶとき、ドキュメントを少なくともPDF 1.5へ引き上げます。画像XObjectでコンポーネントあたり16ビットが有効になったのがこのバージョンだからです。下流のシステムがPDF 1.4を強要するなら、その要件と16ビット写真は両立せず、設計時に判明しているほうが良いのです

スマホ写真をページに追加する

モダン画像の呼び出しは、成功時に0より大きい画像IDを返し、失敗時に0を返します。そのIDはDrawImageAndReleaseへ、またはおなじみのSelectImage / DrawImageペアへ渡します。下のスケッチには、実際のスマホ写真のアップロードに必要な1つのフォールバックが含まれています。直後で説明します:

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の suffix を被ったJPEGはモダンの呼び出しには失敗し、同様に中身を嗅ぎ分ける汎用のAddImageFromFileでは成功します。後者はJPEG、PNG、TIFFほかクラシックなフォーマットを扱います

なぜ全部をAddImageFromFileへ通さないのか。モダンフォーマットの認識はそちらでも行われますが、モダンの呼び出しは意図を明示し、何も渡さなければオプション8を供給してくれます。入力がスマホ写真であると期待される箇所では、呼び出しサイトにモダンの呼び出しが見えているほうが良いのです

ライブラリはAVIFとHEICをどう見分けるのか

PDF Library for Delphiは、最大4096バイトの範囲限定ヘッダ読み取りでフォーマットを判断し、その後呼び出し側のストリーム位置を元の場所へ戻します。JPEG XLは簡単なケースです。生のコードストリームはFF 0Aで始まり、コンテナ形式は固定の12バイトシグネチャボックスで始まります。AVIFとHEIFは難しいです。どちらもISOベースメディアファイルフォーマット、つまり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を試します

実務上の帰結が2つあります。コーデックはQ16ビルドを同梱することです。8ビット量子のビルドは、どんなオプションを渡しても16ビットサンプルを引き渡せません。そしてコーデックディレクトリにmodules\codersサブフォルダがある場合、ライブラリはMAGICK_HOME、MAGICK_CONFIGURE_PATH、MAGICK_CODER_MODULE_PATHを補完しますが、対象はホストプロセスがまだ設定していない変数だけです。独自のランタイム構成を持つアプリケーションは、それを維持できます

私たちの推奨は、パスを明示的に設定し、システム検索パスに頼らないことです。PATH上にたまたま別のImageMagickがあるマシンは、レポート生成器がどのコーデックを使うかを勝手に決めてしまいます。そしてそれは、特定の顧客のサーバーでだけ顔を出す種類の違いです

すでにデコーダーを同梱しているアプリケーションや、外部モジュールをロードすることが許されないアプリケーションは、代わりにコールバックを登録します。コールバックは、ソースストリームを読み、出力ストリームへPNGバイト列を書き、方向フラグを尊重する、ただの関数です。登録はプロセス全体で、ロックによって保護されているため、ドキュメントごとではなく起動時に1回だけ行ってください:

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ビットへ正規化されます

一時ファイルは書き出されないため、クラッシュ後の掃除物もありません。明示的な対応が必要だった皺が1つあります。開発中に、フォーマットの切り替えの際にコーデックが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;

これをインストーラーやサービスへ組み込む前に知っておくべき挙動が2つあります。失敗したロードは記憶されるため、ライブラリは画像ごとにディスクを再検索しません。インストーラーがコーデックフォルダのコピーを終える前にサービスが検査すると、記憶された失敗がSetModernImageCodecLibraryの再呼び出しで消されるまで、コーデックは利用不可と報告され続けます。逆もまた然りです。一度モジュールがロードされると、SetModernImageCodecLibraryは0を返し、パスはプロセスの生存期間中そのままになります。変換の走行中にネイティブコーデックをアンロードするようなことを、暗黙にやるべきではないからです

出力のサイズにも目を配ってください。プロファイル付きの16ビットRGBA写真は大きな画像オブジェクトであり、それが40枚のレポートはあっという間に重くなります。画面でしか読まれないドキュメントなら、埋め込み前のダウンサンプリングが正しいトレードであり、サイズの一般的なレバーはPDFファイルサイズの最適化で扱います。色の方針も、意図的な決定に値します。各ソースプロファイルの保持はアーカイブや印刷の仕事に正しく、すべてを1つのドキュメント全体の空間へ変換するのは、並べて見たときに一貫していなければならない、異なるスマホ由来の写真の集合に合います。その道はドキュメントを別の色空間へ再着色するで説明されます。ファイルに実際に何が入ったかを確かめるには、テキスト・画像・フォントの抽出の検査経路が、ドキュメントの運ぶ画像オブジェクトを報告します

AVIF、HEIF、JPEG XLの入力は、PNG、JPEG、TIFF、WebPの入力や、色空間変換、画像最適化と並んで、Delphi、C++Builder、Free Pascal向けの同じライブラリの中に座っています。ライセンス、プラットフォーム対応、完全なAPIリファレンスは、PDF Library for Delphi製品ページにあります