PDF एनोटेशन

PDF एनोटेशन

Page.annotations एक AnnotationCollection प्रकाशित करता है — पृष्ठ पर प्रत्येक एनोटेशन पर एक mutable, sequence-like view। प्रत्येक प्रविष्टि एक Annotation है (या MarkupAnnotation / LinkAnnotation उपवर्ग), और उपप्रकार-विशिष्ट डेटा जैसे क्वाड पॉइंट्स, इंक लिस्ट्स, या रंग get_property() / set_property() के माध्यम से पढ़ा और लिखा जाता है, न कि समर्पित गुणों के द्वारा।

एनोटेशन जोड़ना

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) एक नया एनोटेशन बनाता है और उसे पृष्ठ में जोड़ता है। subtype या तो एक साधारण स्ट्रिंग ("Text", "Square", "Highlight") या एक AnnotationType enum सदस्य को स्वीकार करता है।

import aspose_pdf
from aspose_pdf import Document, AnnotationType

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

# Plain string subtype
page.annotations.add("Text", (100, 100, 200, 200), "Hello")

# AnnotationType enum, with subtype-specific properties
page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)

गुणों को पढ़ना और अद्यतन करना

get_property(name, default) उपप्रकार-विशिष्ट मान पढ़ता है; set_property(name, value) इसे लिखता है, और किसी गुण को None पर सेट करने से वह एनोटेशन के properties शब्दकोश से हट जाता है।

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

ann = page.annotations.add(
    "Square", (0, 0, 50, 50), "x", properties={"C": [1, 0, 0]},
)
ann.set_property("IC", [0, 0, 1])
print(page.annotations[0].get_property("IC"))  # [0, 0, 1]

ann.set_property("C", None)  # removes the "C" entry entirely
print("C" in page.annotations[0].properties)  # False

एनोटेशन का नामकरण AnnotationName के साथ

PDF नामों (उदा. एक Stamp एनोटेशन का Name प्रविष्टि) को साधारण स्ट्रिंग्स से अलग पहचानने के लिए AnnotationName का उपयोग किया जाता है, जो aspose_pdf.engine.cos से str उपवर्ग है। इस तरह संग्रहीत मान अभी भी सामान्य स्ट्रिंग के बराबर तुलना करता है।

from aspose_pdf.engine.cos import AnnotationName

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

page.annotations.add(
    "Stamp", (10, 10, 110, 60), "",
    properties={"Name": AnnotationName("Approved")},
)

डालना, हटाना और साफ़ करना

insert(index, subtype, rect, contents, title, appearance_normal, properties) एक नई एनोटेशन को विशेष स्थिति पर रखता है; delete(index) इंडेक्स द्वारा एक को हटाता है (बाहरी सीमा के इंडेक्स के लिए IndexError उठाता है); clear() पृष्ठ से सभी एनोटेशन हटाता है।

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

page.annotations.add("Text", (0, 0, 100, 100), "A")
page.annotations.add("Text", (200, 200, 300, 300), "C")
page.annotations.insert(1, "Text", (100, 100, 200, 200), "B")
# order is now: A, B, C

page.annotations.delete(1)   # removes "B"
page.annotations.clear()     # removes everything remaining

एनोटेशन रूपांकन उत्पन्न करना

Annotation.generate_appearance(force) एक एनोटेशन के लिए /AP /N रूपांकन स्ट्रीम बनाता है और जब उस उपप्रकार के लिए एक रेंडरर मौजूद हो तो True लौटाता है; AnnotationCollection.generate_appearances(force) एक ही कॉल में पृष्ठ पर प्रत्येक एनोटेशन के लिये यही करता है और वास्तव में उत्पन्न हुए एनोटेशन की संख्या लौटाता है (असमर्थित उपप्रकारों को छोड़ दिया जाता है)।

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

page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

generated = page.annotations.generate_appearances()
print(generated)  # 2

एनोटेशन उपप्रकार और फ़्लैग्स

AnnotationType मानक PDF 32000-1:2008 (टेबल 169) के उपप्रकार नामों को सूचीबद्ध करता है: TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, POLY_LINE, HIGHLIGHT, UNDERLINE, SQUIGGLY, STRIKE_OUT, STAMP, CARET, INK, POPUP, FILE_ATTACHMENT, SOUND, MOVIE, WIDGET, SCREEN, PRINTER_MARK, TRAP_NET, WATERMARK, और REDACT।

AnnotationFlags एक IntFlag है जो एनोटेशन प्रदर्शन/इंटरेक्शन व्यवहार को कवर करता है: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED, और TOGGLE_NO_VIEW।

प्रारंभिक रिलीज़: 3D एनोटेशन

PDF3DAnnotation, PDF3DArtwork, PDF3DContent, और PDF3DView पेज से जुड़ी 3D कलाकृति का मॉडल बनाते हैं — एक PDF3DAnnotation में एक rect: Rectangle, एक artwork: PDF3DArtwork, और एक वैकल्पिक background_color: Color होता है। PDF3DArtwork.add_view() एक PDF3DView को पंजीकृत करता है, प्रत्येक के पास एक render_mode होता है (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) और एक lighting_scheme होता है (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM)। लाइब्रेरी की अपनी docstring PDF3DAnnotation को “prerelease imports के लिए न्यूनतम एनोटेशन रैपर” के रूप में चिह्नित करती है — इस सतह को प्रारंभिक चरण के रूप में मानें, न कि पूर्ण रूप से विकसित 3D लेखन API।

टिप्स और सर्वोत्तम प्रथाएँ

• जब मान को आपके कोड के अन्य भागों में तुलना या शाखा बनाने की भी आवश्यकता हो, तो कच्चे सबटाइप स्ट्रिंग्स के बजाय AnnotationType enum सदस्यों को प्राथमिकता दें।
• एक प्रॉपर्टी को पूरी तरह हटाने के लिए set_property(name, None) को कॉल करें, बजाय इसके कि पुराना मान जगह पर रह जाए — प्रविष्टि properties से पूरी तरह गायब हो जाती है।
• प्रत्येक एनोटेशन के लिए generate_appearance() को लूप करने के बजाय AnnotationCollection.generate_appearances के साथ बैच रूप में appearance जेनरेशन करें; यह उत्पन्न वास्तविक गिनती वापस करता है जिससे आप छोड़े गए/असमर्थित सबटाइप्स का पता लगा सकते हैं।
• delete() और page.annotations में इंडेक्सिंग दोनों 0-आधारित हैं; यदि इंडेक्स उपयोगकर्ता इनपुट से आया है तो delete() को कॉल करने से पहले उसे मान्य करें, क्योंकि सीमा से बाहर का इंडेक्स IndexError उत्पन्न करता है।
• PDF नाम मानों (जैसे Stamp के Name) को AnnotationName में लपेटें ताकि वे साधारण टेक्स्ट स्ट्रिंग्स के बजाय PDF नामों के रूप में राउंड-ट्रिप हों।

सामान्य समस्याएँ

FAQ

मैं साधारण टेक्स्ट टिप्पणी एनोटेशन कैसे जोड़ूँ?

कॉल page.annotations.add("Text", (x0, y0, x1, y1), "comment text")। चार-नंबर ट्यूपल पेज पर एनोटेशन के आयत को दर्शाता है।

Annotation, MarkupAnnotation और LinkAnnotation में क्या अंतर है?

Annotation पेज पर किसी भी एनोटेशन के लिए लौटाया गया लाइव व्यू है। MarkupAnnotation मार्कअप-शैली उपप्रकारों (हाइलाइट्स, टेक्स्ट नोट्स, आकार) के लिए आधार है और LinkAnnotation लिंक-शैली एनोटेशनों के लिए रखा गया है; दोनों वर्तमान में Annotation के समान मेथड/प्रॉपर्टी सतह को उजागर करते हैं।

क्या मैं पूरी एनोटेशन को हटाए बिना केवल एक प्रॉपर्टी हटा सकता हूँ?

हां — कॉल annotation.set_property(name, None); एनोटेशन स्वयं अप्रभावित रहता है, केवल वह एक प्रविष्टि properties से हटाई जाती है।

क्या AnnotationCollection.generate_appearances तब विफल हो जाता है जब कोई उपप्रकार समर्थित नहीं है?

नहीं। यह उन उपप्रकारों को छोड़ देता है जिनमें अंतर्निहित रूप रेंडरर नहीं है और उन एनोटेशन की गिनती लौटाता है जिनके लिए वास्तव में रूप उत्पन्न किया गया था।

क्या 3D एनोटेशन क्लासेस उत्पादन के लिए तैयार हैं?

PDF3DAnnotation और संबंधित प्रकारों को प्री-रिलीज़ इम्पोर्ट्स के लिए न्यूनतम रैपर के रूप में दस्तावेज़ित किया गया है — उत्पादन 3D सामग्री के लिए उन पर निर्भर करने से पहले अपने लक्षित PDF व्यूअर के विरुद्ध व्यवहार सत्यापित करें।

API Reference सारांश

यह भी देखें

• Aspose.PDF for Python — Enterprise Documentation