Al entregar documentos anotados, no entregue simplemente un PDF que parezca limpio.

Antes de entregar anotaciones en PDF, muchas personas utilizarán directamente page.get_text() para exportar un texto de aspecto limpio para traducirlo, archivarlo o entregárselo al siguiente revisor. Pero este texto no suele contener anotaciones. Algunos métodos de extracción también insertarán comentarios en medio del texto, interrumpiendo la semántica; Es posible que se pierdan los comentarios de modificación y los comentarios sensibles en la barra lateral.

Este artículo está escrito para desarrolladores y propietarios de documentos que necesitan trabajar con archivos PDF anotados. Después de leer, comprenderá por qué las anotaciones son capas de datos independientes, cómo extraer texto y anotaciones en capas, qué casos extremos deben manejarse de manera defensiva y qué puntos de aceptación deben confirmarse manualmente.

Todos los ejemplos de este artículo utilizan muestras sintéticas. El código ha sido verificado como muestra en un entorno aislado, pero esto no es una garantía de todos los archivos reales o del rendimiento del producto. Antes de procesar documentos importantes, conserve los originales y revíselos de acuerdo con los límites y elementos de aceptación del texto.

¿Cómo extraer el PDF anotado antes de la entrega? Conclusión de una frase

Trate el texto y las anotaciones como dos flujos de datos independientes, extráigalos por separado y realice una revisión de seguridad explícita del contenido de las anotaciones.

Por qué las anotaciones son independientes de la capa de datos del texto

En la especificación PDF, el flujo de contenido de la página (Content Stream) y el diccionario de anotaciones (Annots Array) están estructuralmente separados. El cuerpo consta de instrucciones de visualización de texto; las anotaciones son objetos independientes adjuntos a la página, con sus propias coordenadas, tipo y atributos de contenido. El método Page.annots() de PyMuPDF devuelve un generador que atraviesa esta lista de anotaciones independientes en lugar del flujo de texto de la página.

Esto significa que no puedes asumir que todo el texto que ves se puede extraer de la misma manera.

La diferencia entre anotaciones de clase de marca y de clase de contenido

• Las anotaciones de etiquetas (como resaltado y subrayado) no contienen texto en sí, sino que solo registran el área (Quads/Rects) correspondiente al texto original. El texto real solo se puede obtener buscando el texto mediante coordenadas.
• Las anotaciones de contenido (como notas, texto libre) tienen sus propias cadenas de contenido y se pueden leer directamente.
• Si lee annot.info["content"] directamente sin distinguir el tipo, perderá el contexto original al que apunta la anotación de clase de etiqueta o generará una excepción si el contenido está vacío.

Ejemplo de síntesis: extracción en capas e interceptación de información confidencial

Para demostrar la lógica de procesamiento correcta, construimos un escenario sintético que contiene tres anotaciones típicas en el código. Las siguientes entradas son ejemplos creados dentro del código, no de archivos reales de clientes, y tienen únicamente fines de demostración educativa.

El resultado esperado contiene tres campos estructurados:

1. Fragmento de texto: Contiene solo el texto original de la página, sin ningún contenido de anotación.
2. Lista de anotaciones: Cada registro incluye tipo, ubicación, autor, hora y contenido (si corresponde).
3. Marca de seguridad: si el contenido de la anotación coincide con las reglas confidenciales preestablecidas (como el número de identificación, el código interno), la entrada se marca como redacted=True y el contenido se reemplaza con un marcador de posición.

Tres tipos de límites que deben defenderse

• Anotación de contenido vacía: Ink (Tinta) o anotaciones gráficas creadas por algunos lectores no tienen atributos de texto. El acceso directo a .info["content"] puede dar como resultado una cadena vacía o Ninguna, el código debe realizar comprobaciones defensivas y no puede asumir que todas las anotaciones tengan texto legible.
• Coordenadas de la página girada: después de girar la página 90 grados, el rectángulo de anotación todavía se basa en la página sin girar. Si usa directamente estas coordenadas para recortar o posicionar el texto, la posición quedará completamente desordenada y primero se debe realizar la transformación de coordenadas.
• Objeto huérfano: si el documento se cierra o la página se vuelve a cargar durante el proceso transversal, el objeto de anotación actual dejará de ser válido inmediatamente. Todas las operaciones de lectura deben completarse dentro de una sola página.

Implementación de Python: verificación y recorrido seguro de anotaciones

El ejemplo utiliza PyMuPDF para crear un PDF de prueba en la memoria, lo que demuestra la extracción jerárquica y la lógica de enmascaramiento básica. La biblioteca dependiente es PyMuPDF (es decir, el paquete pymupdf). Ejecútelo en un entorno de dependencia bloqueado. La versión debe ser >=1.23.0 para acceder completamente al atributo annot. Este código no realiza operaciones de red ni escritura de archivos, solo se usa para demostrar lógica.

import fitz  # PyMuPDF
import re

# 合成示例：仅在内存中构造，无需外部文件
def create_sample_pdf():
    doc = fitz.open()
    page = doc.new_page()
    # 插入正文
    page.insert_text((72, 72), "Confidential Project Alpha Report", fontsize=12)
    # 添加便签批注（含敏感信息模拟）
    page.add_text_annot((200, 72), "Reviewer: SSN 123-45-6789 approved.")
    # 添加高亮批注（无自身文本，关联正文）
    highlight = page.add_highlight_annot(fitz.Rect(72, 60, 250, 80))
    # 必须调用update()使info变更生效
    highlight.set_info(title="Editor", content="Check this term")
    highlight.update()
    return doc

def extract_with_safety(page, sensitive_pattern=r"\d{3}-\d{2}-\d{4}"):
    body_text = page.get_text("text")
    annotations = []

    # 显式遍历批注生成器
    for annot in page.annots():
        info = annot.info
        # 防御性获取内容，处理None或空字符串
        content = info.get("content", "") or ""

        # 边界处理：敏感词检测与脱敏
        is_sensitive = bool(re.search(sensitive_pattern, content))
        safe_content = "[REDACTED]" if is_sensitive else content

        annotations.append({
            "type": annot.type[1],
            "author": info.get("title", "Unknown"),
            "content": safe_content,
            "is_redacted": is_sensitive,
            # 注意：此为未旋转坐标系，若页面有旋转需配合rotation_matrix使用
            "rect": list(annot.rect)
        })
    return body_text, annotations

# 执行校验
doc = create_sample_pdf()
page = doc[0]
text, annots = extract_with_safety(page)

assert "SSN 123-45-6789" not in str(annots), "敏感信息未被拦截"
assert any(a["type"] == "Highlight" for a in annots), "标记类批注丢失"
assert len(text.strip()) > 0, "正文提取失败"
print(f"Extracted {len(annots)} annotations safely.")

En esencia, el código es programación defensiva: no se confía en la pureza del contenido de la anotación, ni se asume la integridad del tipo de anotación. La declaración assert se utiliza para verificar la lógica esperada, pero esto es sólo una demostración y no representa una garantía de rendimiento de un extremo a otro para todas las variantes de PDF.

Comparación de categorías de anotaciones

Criterios de aceptación y límites de revisión manual

La extracción automatizada no puede cubrir todos los casos extremos. La siguiente tabla enumera los puntos de aceptación a los que se debe prestar atención durante la transferencia, distinguiendo entre el alcance que el código puede manejar y los escenarios que requieren intervención manual.

No aplicable: esta solución no se aplica a archivos PDF cifrados sin proporcionar una contraseña, archivos PDF estructuralmente dañados y archivos que utilizan extensiones privadas no estándar para definir tipos de anotaciones. En estas situaciones, el script puede omitir o generar silenciosamente una excepción de C++ de bajo nivel, que debe confirmarse abriendo manualmente el archivo fuente utilizando herramientas profesionales.

Utilice listas de verificación para la traducción de documentos

Primero confirme el orden de las páginas, la ubicación de origen y la integridad del texto, y luego envíe la misma muestra insensibilizada al proceso de traducción. Después de la traducción, aún deberás comprobar si el título, el texto y las ilustraciones corresponden correctamente. No puedes simplemente comprobar si el texto es fluido.

OmniDoc proporciona un portal de traducción de documentos multiformato y el sitio web oficial presenta funciones de OCR, glosario y comparación bilingüe. Si el equipo quiere comenzar a procesar directamente desde el archivo, esta ruta se puede evaluar con muestras reales. Utilice archivos no sensibles que tenga permiso para cargar y revise los resultados de acuerdo con los elementos de verificación de este artículo. Aquí no se afirma que OmniDoc utilice las bibliotecas de código abierto o los algoritmos internos de este artículo, ni el ejemplo reemplaza las pruebas de rendimiento del producto.

Referencias y próximos pasos

• PyMuPDF Page.annots() documentación oficial

1. Seleccione un archivo de proyecto histórico que contenga tipos de anotaciones mixtas.
2. Ejecute el script de verificación anterior y cuente la proporción de entradas que requieren revisión manual.
3. Si la proporción supera las expectativas, agregue un paso de preprocesamiento al proceso de entrega en lugar de depender de herramientas posteriores para proporcionar la respuesta.

🎯 ¿Qué método es el adecuado para ti?

Si solo necesitas traducir el texto

Puede extraer el texto directamente, pero debe confirmar si faltan anotaciones en el contenido exportado.

Si desea entregar el documento a otra persona para que lo archive

Al mismo tiempo, conserve el texto principal y la lista de anotaciones, y marque el contenido confidencial como no sensible.

Si su PDF tiene páginas rotadas

Primero haga la transformación de coordenadas y luego use la posición de anotación para ubicar el texto.

Si el archivo está cifrado o estructuralmente dañado

Esta solución no es aplicable. Utilice manualmente herramientas profesionales para abrir el archivo fuente y confirmar.

❓ Preguntas frecuentes (FAQ)

1. ¿Por qué get_text() no contiene anotaciones?

La salida predeterminada normalmente solo contiene el cuerpo de la página. Las anotaciones son objetos independientes del flujo de texto de la página y deben recorrerse por separado a través de page.annots().

2. ¿Se puede leer directamente el texto de todos los comentarios?

no puedo. Las anotaciones de tipo marca, como resaltado y subrayado, no contienen texto en sí y solo registran áreas; Es posible que las anotaciones gráficas y en tinta tampoco tengan atributos de texto y requieran un juicio defensivo.

3. ¿Por qué la posición de la página está desordenada después de girarla?

El rectángulo de anotación se basa en una página sin rotar. Si se usa directamente para posicionar el texto, causará errores. Primero debe usar page.rotation_matrix o page.derotation_matrix para la transformación de coordenadas.

4. ¿Se perderán las respuestas anidadas?

PyMuPDF devuelve una lista plana y, si el árbol de diálogo no se reconstruye en función de ParentID, se perderá el contexto.

5. ¿Se puede procesar PDF cifrado con este script?

Los archivos PDF cifrados y que no proporcionan una contraseña no están dentro del alcance de esta solución y requieren confirmación manual.

📝 Resumen

Las anotaciones son una capa de datos independiente en PDF. Antes de la entrega, el texto y las anotaciones deben extraerse por separado, y las anotaciones deben revisarse para detectar contenido confidencial. Los scripts automatizados pueden cubrir casos comunes, pero los casos extremos y la aceptación final aún deben realizarse manualmente.

Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original