PDOptionalContentGroup

PDOptionalContentGroupは、Apache PDFBox PDModel APIに含まれるクラスで、PDF文書内のオプショナルコンテンツグループ（OCG）を表現します。 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で定義されているオプショナルコンテンツは、ユーザー設定、アプリケーションの状態、または文書の構成に基づいて、PDFの一部を選択的に表示または非表示にすることを可能にします。このクラスは、Javaデベロッパーに対して、PDFファイル内のレイヤー表示設定をプログラムで作成、読み取り、変更するためのアクセス手段を提供します。

PDOptionalContentGroupは、Apache PDFBoxのPDModelパッケージ内の高レベルJavaクラスで、 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で規定されているオプショナルコンテンツグループの機能をカプセル化します。オプショナルコンテンツグループは、動的に表示または非表示にできるグラフィックオブジェクトの集合を定義するもので、PDFビューアアプリケーションでは一般的に「レイヤー」と呼ばれます。

このクラスは、PDFBoxの低レベルCOS（Carousel Object Structure）クラスとは異なり、PDFの基礎となる辞書構造を抽象化したオブジェクト指向インターフェースを提供します。COSクラスがPDFのプリミティブオブジェクトを直接操作するのに対し、PDOptionalContentGroupは型付きメソッドとプロパティを提供し、レイヤー構成の操作を簡素化することで、内部のPDF構文を理解する必要のないデベロッパーにも扱いやすくなっています。

このクラスは、グループ名、インテント、使用情報などのOCGプロパティを管理し、これらがコンテンツの表示方法とタイミングを決定します。常にレンダリングされるページレベルのコンテンツストリームとは異なり、オプショナルコンテンツグループは、基礎となるコンテンツ構造を変更することなく、オンまたはオフに切り替えることができます。

PDF処理アプリケーションを構築するデベロッパーにとって、PDOptionalContentGroupは、洗練されたマルチレイヤー文書を作成するための重要な機能を提供します。これは、技術文書、CAD図面、地図、多言語文書など、異なるコンテンツバージョンを単一ファイル内に共存させる必要がある場合に特に価値があります。

このクラスを理解して活用することで、デベロッパーはレイヤー管理パネル、印刷専用のコンテンツバリエーション、アクセシビリティの強化などの機能を実装できます。例えば、画面上では簡略化されたグラフィックを表示し、印刷時には高解像度版を出力するPDFや、特定の閲覧コンテキストでのみ透かしを表示するPDFを作成できます。

オプショナルコンテンツをプログラムで制御する機能は、 ( Citation: N.A., 2014 (N.A.). (2014). Document management applications — Electronic document file format enhancement for accessibility — Part 1: Use of ISO 32000-1 (PDF/UA-1) .  International Organization for Standardization Retrieved from https://www.iso.org/standard/64599.html ) で規定されているアクセシビリティ準拠においても重要です。装飾的な要素を支援技術からは非表示にしながら、視覚を持つユーザーには表示し続けるといった使い方が可能です。この選択的な可視性により、コンテンツを複製することなく、より包括的な文書を作成できます。

PDOptionalContentGroupは、PDF内のオプショナルコンテンツ構成内にOCG辞書エントリを作成および管理することで動作します。インスタンス化されると、このクラスは ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) のPDF仕様に従ってOCGのプロパティを含むCOSDictionaryオブジェクトをラップします。

基本的なワークフローは以下の通りです：

1. 作成：レイヤーを識別する名前（例：「背景レイヤー」や「技術注釈」）を指定して新しいPDOptionalContentGroupをインスタンス化

2. 構成：インテント（View、Design、またはカスタム目的）や、コンテンツを表示すべきタイミングを定義する使用辞書などのプロパティを設定

3. 割り当て：プロパティ辞書内でグループを参照することにより、OCGを特定のコンテンツストリーム、注釈、またはその他のPDFオブジェクトに関連付け

4. 登録：PDFビューアがOCGを認識して制御できるように、文書のオプショナルコンテンツプロパティ（PDOptionalContentProperties）にOCGを追加

このクラスは、グループの名前を取得・変更したり、可視性状態を確認したり、高度な操作のために基礎となるCOSオブジェクトにアクセスしたりするメソッドを提供します。PDFがレンダリングされる際、ビューアアプリケーションはオプショナルコンテンツ構成辞書内の各OCGの状態をチェックし、関連コンテンツを表示するかどうかを判断します。ON/OFF状態は文書内に保存することも、ズームレベル、印刷モード、ユーザー設定などの使用条件に基づいて動的に決定することもできます。

• PDOptionalContentProperties – すべてのオプショナルコンテンツグループとその構成を管理する文書レベルのコンテナ
• PDPage – オプショナルコンテンツグループを適用してコンテンツの可視性を制御できるPDF文書内の単一ページを表現
• PDResources – オプショナルコンテンツグループに関連付けられるフォントや画像などのリソースを管理
• PDAnnotation – 条件付き表示のためにオプショナルコンテンツグループに割り当て可能なPDF注釈
• COSDictionary – PDFファイルフォーマット内でオプショナルコンテンツグループのプロパティを格納する低レベルの辞書構造