PDF 주석을 Python에서 작업하는 방법

Aspose.PDF FOSS for Python은 페이지의 AnnotationCollection를 통해 페이지의 모든 주석을 실시간 Annotation 객체로 노출하므로, 마크업, 링크 및 3D 주석을 추가하고, 유형별 속성을 검사하며, PDF viewers가 렌더링에 필요한 appearance streams를 생성할 수 있습니다 — 모두 순수 Python에서 수행됩니다. 이 가이드는 라이브러리 설치, 주석 추가, 주석을 다시 읽고, appearance streams를 생성하는 방법을 보여줍니다.

단계별 가이드

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

import aspose_pdf
print("aspose_pdf OK")

from aspose_pdf import Document
from aspose_pdf.annotations import (
    Annotation,
    AnnotationType,
    AnnotationFlags,
    MarkupAnnotation,
    LinkAnnotation,
)

from aspose_pdf import Document

document = Document()
document.pages.add()
page = document.pages[0]

annotation = page.annotations.add(
    "Highlight",
    (100, 700, 300, 720),
    "Key clause",
)
print(type(annotation).__name__)   # MarkupAnnotation
print(annotation.contents)         # Key clause

from aspose_pdf import Document
from aspose_pdf.annotations import AnnotationType

document = Document()
document.pages.add()
page = document.pages[0]

annotation = page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)
print(annotation.subtype)                    # Polygon
print(annotation.get_property("Vertices"))   # [0, 0, 10, 0, 5, 10]

from aspose_pdf import Document

document = Document()
document.pages.add()
page = document.pages[0]
page.annotations.add("Text", (50, 50, 70, 70), "First note")
page.annotations.add("Text", (80, 80, 100, 100), "Second note")

for annotation in page.annotations:
    print(annotation.subtype, "-", annotation.contents)

from aspose_pdf import Document
from aspose_pdf.engine.cos import AnnotationName

document = Document()
document.pages.add()
page = document.pages[0]

stamp = page.annotations.add(
    "Stamp",
    (100, 100, 260, 150),
    "",
    properties={"Name": AnnotationName("Approved")},
)
if stamp.generate_appearance():
    print(f"Appearance stream: {len(stamp.appearance_normal)} byte(s)")

# Regenerate every missing appearance stream on the page in one call:
count = page.annotations.generate_appearances(force=True)
print(f"Regenerated {count} appearance stream(s)")

from aspose_pdf import Document
from aspose_pdf.annotations import LinkAnnotation, MarkupAnnotation

document = Document()
document.pages.add()
page = document.pages[0]

link = page.annotations.add("Link", (50, 750, 200, 770), "")
highlight = page.annotations.add("Highlight", (50, 700, 200, 720), "")

print(isinstance(link, LinkAnnotation))         # True
print(isinstance(highlight, MarkupAnnotation))  # True

일반적인 문제 및 해결 방법

get_property returns None 방금 설정한 속성에 대해

properties 키는 정확하고 대소문자를 구분하는 PDF 필드 이름("Vertices", "Name" 등)입니다 — 오타나 잘못된 대소문자는 오류를 발생시키지 않고 조용히 무시됩니다. get_property(name, default)에 default 인수를 전달하고 새로운 서브타입을 디버깅하는 동안 명시적으로 확인하십시오.

generate_appearance() returns False

모든 하위 유형 및 속성 조합이 내장 생성기에 의해 외관 스트림으로 합성될 수 있는 것은 아닙니다. 호출이 성공했다고 가정하기 전에 has_appearance을(를) 확인하고, 생성기가 지원하지 않는 하위 유형에 대해서는 add()에 직접 사전 렌더링된 appearance_normal (bytes)을(를) 제공하십시오.

예상치 못한 주석 하위 클래스 뒤에 add()

전달하는 하위 유형 문자열(또는 AnnotationType 멤버)이 반환되는 클래스를 결정합니다: 마크업 하위 유형은 MarkupAnnotation으로 반환되고, "Link"는 LinkAnnotation으로 반환되며, 기타 인식된 하위 유형은 기본 Annotation으로 반환됩니다. 특정 하위 유형 문자열을 가정하기보다 isinstance()를 MarkupAnnotation/LinkAnnotation에 사용하십시오.

AnnotationFlags 값이 렌더링을 변경하지 않는 것 같습니다

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY, 및 유사 항목)은 Python IntFlag 열거형으로, | 연산자를 사용해 주석의 동작 비트를 구성하고 해석하기 위한 표준입니다 — 값 타입이며, Annotation.add()이 자동으로 쓰는 속성이 아닙니다. 필요한 플래그를 결합하고 다른 하위 유형 전용 데이터에 사용되는 것과 동일한 타입별 properties 메커니즘을 통해 전달하십시오.

아직 주석이 없는 페이지 작업

page.annotations은 항상 유효한(비어 있을 수도 있는) AnnotationCollection이며 — add()을 호출하거나, 반복하거나, clear()을 호출하기 전에 None를 확인할 필요가 없습니다.

자주 묻는 질문

어떤 주석 하위 유형을 Aspose.PDF FOSS for Python가 지원합니까?

AnnotationType는 PDF 32000-1:2008 표 169에 정의된 25개의 표준 하위 유형을 모두 열거하며, TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT 등을 포함합니다.

이 라이브러리는 3D 주석을 지원합니까?

예. PDF3DAnnotation, 함께 PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, 그리고 PDF3DRenderMode, 사전 릴리스 PDF 3D 워크플로를 위한 최소 PDF 3D 주석 표면(직사각형, 삽입된 아트워크 및 명명된 뷰)을 모델링합니다. 자세히 보려면 PDF3DAnnotation 참조 전체 속성 집합에 대해.

페이지에서 주석을 어떻게 제거하나요?

위치별로 하나의 주석을 제거하려면 page.annotations.delete(index)를 호출하고, 페이지의 모든 주석을 제거하려면 page.annotations.clear()을 호출하십시오.

첨부하는 대신 특정 위치에 주석을 삽입할 수 있나요?

예 — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties)는 add()와 동일한 인수를 사용하며 추가로 대상 index를 받습니다.

주석의 colour는 어떻게 표현되나요?

Annotation에 있는 color 속성(및 그 하위 클래스)은 PDF /C 항목의 구성 요소 개수와 일치하는 tuple[float, ...]이며(색상이 설정되지 않으면 비어 있음) — 전용 colour 객체가 아닙니다.

참조

• 문서 관리 (개발자 가이드)
• Python에서 문서를 로드하는 방법
• 설치 가이드
• API Reference
• GitHub 저장소
• Aspose.PDF for Python — Enterprise Knowledge Base