데이터 기본형 및 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를 기본 Python int 또는 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 부동소수점 속성을 가진 RGBA 색상을 나타냅니다. 두 인수 플러스 알파 생성자를 제외하고, 전체 명명된 색상 팩토리 세트를 제공하는데 — 소문자 형태(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 factories는 다른 색상인가요?

아니요 — Color.red()와 Color.Red()는 동일한 색상을 반환하는 별칭이며, 편의를 위해 두 가지 표기가 제공됩니다.

API Reference 요약

참조

• Aspose.PDF for Python — Enterprise Documentation