オプションコンテンツのサポート#
この文書では、PyMuPDFにおけるPDFコンセプト 「オプションコンテンツ」 のサポートについて説明します。
はじめに：オプションコンテンツのコンセプト#
PDFのオプションコンテンツは、特定の条件に基づいてドキュメントの一部を表示または非表示にする方法です。これは、サポートするPDFコンシューマ（ビューア）を使用する際にONまたはOFFに設定できるパラメータ、またはプログラムを使用して行います。
この機能は、CAD図面、レイヤー化されたアートワーク、地図、多言語ドキュメントなどのアイテムで有用です。一般的な用途には、地理的な地図、技術デバイス、建築設計などの複雑なベクトルグラフィックの詳細の表示または非表示、異なるズームレベル間の自動切り替えなどが含まれます。他の用途としては、画面上でドキュメントを表示する際と印刷する際で自動的に異なる詳細レベルを表示することが考えられます。
特別なPDFオブジェクトである「オプションコンテンツグループ（OCG）」を使用して、これらの異なるコンテンツのレイヤーを定義します。
「通常の」PDFオブジェクト（テキストや画像など）にOCGを割り当てると、そのオブジェクトは割り当てられたOCGの現在の状態に応じて表示または非表示になります。
PDFのオプションコンテンツの全体的な構成を簡単に定義するために、OCGは高レベルのグループ化である「OC構成」に組織化できます。各構成は、OCGの望ましい初期表示状態とともに、OCGのコレクションです。これらの構成のいずれかを選択する（PDFビューアまたはプログラムを介して）と、ドキュメント全体で影響を受けるすべてのPDFオブジェクトの表示状態が対応するように変更されます。
デフォルト以外のOC構成はオプションです。
詳細な説明や追加の背景情報については、PDF仕様マニュアルを参照してください。
PDFオプショナルコンテンツのPyMuPDFサポート#
PyMuPDFは、オプショナルコンテンツグループや構成の表示、定義、変更、削除、OCGのPDFオブジェクトへの割り当ての維持、OC構成間のプログラムによる切り替えや各単一OCGの可視性状態のサポートを完全に提供します。
オプショナルコンテンツの追加方法#
これは、PDFにオプショナルコンテンツグループ（OCG）を追加するだけの簡単な手順です：Document.add_ocg()。
以前にPDFがまったくOCサポートを持っていなかった場合、必要なセットアップ（デフォルトのOC構成の定義など）は自動的に行われます。
このメソッドは、作成されたOCGの xref を返します。このxrefを使用して、このOCGの状態に依存するようにする任意のPDFオブジェクトを関連付け（マーク）します。例えば、ページに画像を挿入し、次のようにxrefを参照できます:
img_xref = page.insert_image(rect, filename="image.file", oc=xref)
既存の画像をOCGの制御下に配置したい場合、まず画像のxref番号（ここでは img_xref と呼びます）を調べ、その後 doc.set_oc(img_xref, xref) を行う必要があります。これにより、OCGの状態が「ON」または「OFF」の場合、画像はドキュメント全体で（非）表示になります。また、このメソッドで異なるOCGを割り当てることもできます。
画像からOCGを削除するには、 doc.set_oc(img_xref, 0) を行います。
1つのOCGは複数のPDFオブジェクトに割り当てて、それらの可視性を制御することができます。
複雑なオプショナルコンテンツ条件の定義方法#
複雑な可視性のニーズに対応するために、洗練された論理条件を設定することができます。
例えば、ユーザーが必要に応じて言語を切り替えることができるような多言語ドキュメントを作成したいかもしれません。
この Jupyter Notebook をご覧いただき、必要に応じて実行してみてください。
もちろん、あなたの要件はさらに複雑で、論理的な関係で接続された複数のON/OFF状態を持つ複数のOCGが関与する可能性がありますが、これは可能なことと次のステップを計画する方法を示すものとなるでしょう。
