データプリミティブとXMPメタデータ

データプリミティブとXMPメタデータ

Aspose.PDF FOSS for Python は、aspose_pdf.engine.dataで定義された小さなプリミティブデータ型の集合の上に、その上位レベルのAPI—Document、Page、およびアノテーションとフォームクラス—を構築します。これらの多くを直接構築することはほとんどありませんが、プロパティ型や戻り値として常に現れます。ページのリソース辞書はPdfName値をキーにし、色はColorインスタンスであり、Document.xmp_metadataはXmpPacketを返します。本ガイドでは、オブジェクトアイデンティティのプリミティブ、プリミティブ値ラッパー、Color、テキストエンコーディング列挙型、そしてXMPメタデータモデルを紹介します。

オブジェクトアイデンティティとオブジェクトレジストリ

PdfObjectIDは、PDFファイル内の間接オブジェクトをobject_numberとgeneration_numberで識別します。PdfObjectRegistryはオブジェクトがシリアライズされる際にこれらの識別子を割り当て、追跡し、PdfTrailerableはPDFトレーラに書き込まれる辞書を生成できるオブジェクトの共通インターフェースです。

import aspose_pdf
from aspose_pdf.engine.data import PdfObjectRegistry

registry = PdfObjectRegistry()

# register() assigns a PdfObjectID to a serializable object
object_id = registry.register(some_pdf_object)
print(object_id.object_number, object_id.generation_number)

# get() resolves an object back from its PdfObjectID
resolved = registry.get(object_id)

プリミティブ値ラッパー

PdfNumberとPdfNameは、生のPDF値を型付けされたPythonオブジェクトでラップします。PdfNumberは数値的なvalueをネイティブなPythonintまたはfloatとして保持します。PdfNameはname文字列を保持し、低レベルオブジェクトモデル全体で辞書キーに使用される型です――例えば、ページのリソース辞書のFontおよびResourcesキーです。PdfNullはPDFのnullオブジェクトを表します。

import aspose_pdf
from aspose_pdf.engine.data.number import PdfNumber
from aspose_pdf.engine.data.types import PdfName

number = PdfNumber(3.14)
raw_value = number.value  # already the native int/float you passed in

resources_key = PdfName("Resources")
font_key = PdfName("Font")

カラー値

Color は r、g、b、a の float プロパティを持つ RGBA カラーを表します。2 引数＋アルファのコンストラクタに加えて、完全な名前付きカラー工場セットを提供します — 小文字の (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) と PascalCase エイリアス (Aqua(), Blue(), Azure(), Red(), Green(), Yellow(), Black(), White(), Gray()) が用意されています。

import aspose_pdf
from aspose_pdf.engine.data.types import Color

custom = Color(r=0.2, g=0.4, b=0.8, a=1.0)

# Named factories return ready-made Color instances
highlight = Color.yellow()
border = Color.Black()

テキストエンコーディングとストリームフィルタ

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) はテキストエンコーディングを識別し、Encoding は一致するエンコーディング定数 (UTF8, UTF16, LATIN1, WIN_ANSI) と、エンコードされた bytes を返す encode(text, encoding_type) メソッドを提供します。FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) は圧縮された PDF コンテンツに適用されるストリームフィルタを識別します。

import aspose_pdf
from aspose_pdf.engine.data import Encoding, EncodingType, FilterType

encoded = Encoding.encode("Hello, world", EncodingType.WIN_ANSI)

# FilterType values identify how a content or image stream is compressed
current_filter = FilterType.FLATE_DECODE

XMP メタデータ

XmpPacket はドキュメントの XMP メタデータパケットのインメモリモデルです — Document.xmp_metadata が返す型です。fields の順序付きコレクション（各要素は XmpField、XmpArray、または XmpProperty）を保持し、XmpNamespaceProvider を通じて名前空間プレフィックスを解決します。型付き getter と setter（get_value スタイルのアクセサである get_bool、get_int、get_real、get_date、get_localized_text、get_array とそれらの set_* 対応物）は、名前空間プレフィックスまたは URI とプロパティ名で個別のプロパティを読み書きします。

import aspose_pdf

doc = aspose_pdf.Document()
doc.load_from("input.pdf")

xmp = doc.xmp_metadata  # XmpPacket

title = xmp.get_localized_text("dc", "title", lang="x-default")
xmp.set_value("dc", "creator", "Jane Doe")

serialized = xmp.serialize()

XmpStruct は独自の get(name) ルックアップを持つ構造化された (rdf:parseType="Resource") 値をモデル化し、XmpArray は add(item) と remove(item) を備えた順序付き配列をモデル化し、XmpProperty は独自の add_qualifier/remove_qualifier 修飾子を持つプロパティです。これら四つはすべて、個々の値のための同じ XmpField ビルディングブロックを共有します。

ヒントとベストプラクティス

• 最初から作成するのではなく、Document.xmp_metadata を読み取ってドキュメントの XmpPacket を取得してください — それはロードされたファイルからすでに設定されています。
• PdfNumber.value を直接読み取ります — コンストラクタに渡したネイティブな Python int または float がすでに保持されています; to_double() や to_int() の変換メソッドはありません。
• 一般的な色には、手作りの r/g/b/a タプルよりも、名前付きの Color ファクトリ（Color.red()、Color.Black() など）を使用する方が望ましいです — 呼び出し側での可読性が向上します。
• 渡す EncodingType を Encoding.encode() と、宛先（フォント、ストリーム、またはビューア）が実際に期待するエンコーディングと合わせてください; PDF のテキストエンコーディングの不一致は、文字化けの一般的な原因です。
• PdfObjectRegistry と PdfObjectID を低レベルのエンジン向け型として扱ってください — 多くのアプリケーションコードはオブジェクトを直接登録するのではなく、Document と Page を通じて文書内容を読み取ります。

一般的な問題

FAQ

自分で PdfObjectID または PdfObjectRegistry を構築する必要がありますか？

ほとんどの場合必要ありません。これらはエンジンのシリアライズ処理を裏で支えています; 低レベルのオブジェクトモデルを扱う場合を除き、ほとんどのアプリケーションコードは直接インスタンス化しません。

XmpField、XmpArray、XmpStruct、およびXmpPropertyの違いは何ですか？

XmpFieldは単一のスカラー値です。XmpArrayは値の順序付きリストで、XmpStructは構造化された（rdf:parseType="Resource"）フィールドのグループで、XmpPropertyは独自の修飾子も持つ値です。

ドキュメントのXMPメタデータはどうやって取得しますか？

ロードされたDocumentのxmp_metadataプロパティを読み取ります — それは、その場でクエリや更新が可能なXmpPacketを返します。

小文字とPascalCaseのColorファクトリは異なる色ですか？

いいえ — Color.red()とColor.Red()は同じ色を返すエイリアスであり、便宜上両方の表記が提供されています。

API Reference の概要

参照

• Aspose.PDF for Python — Enterprise Documentation