Faites pivoter le PDF et ajoutez un filigrane. Pourquoi le filigrane sort-il de la page ?

Si vous utilisez pypdf pour ajouter un filigrane à un PDF, vous avez peut-être rencontré cette situation : le filigrane est clairement défini pour être centré dans le code, mais après la fusion, il tombe de la page ou pivote de 90 degrés ou 180 degrés par rapport au texte. Ce type de problème réside généralement dans l'attribut /Rotate de la page, et non dans le fichier de filigrane lui-même.

Cet article est destiné aux développeurs qui doivent traiter des fichiers PDF par lots et qui sont confrontés à des pages pivotées lors des processus de traduction ou de filigrane de documents. Après avoir lu, vous comprendrez la relation entre /Rotate et le système de coordonnées du flux de contenu, comprendrez les limites applicables et les effets secondaires de transfer_rotation_to_content et obtiendrez un ensemble d'idées de vérification de la mémoire et de tableaux de décision d'acceptation.

L'exemple est démontré à l'aide d'échantillons synthétiques. Le code a été vérifié avec des exemples dans un environnement isolé, mais cela ne constitue pas une garantie de tous les fichiers réels ou des performances du produit. Avant de traiter des documents importants, veuillez conserver les originaux et les examiner en fonction des limites et des éléments d'acceptation du texte.

Pourquoi le filigrane superposé du PDF pivoté s'étend-il hors de la page ? Conclusion en une phrase

Transférez d'abord /Rotate dans le flux de contenu, puis fusionnez le filigrane ; s'il rencontre une rotation non standard ou si la MediaBox s'est adaptée à la page pivotée, le transfert sera ignoré et révisé manuellement.

votre situation	Pratiques recommandées	raison
Page MediaBox standard `/Rotate=90` portrait	Appelez d'abord `transfer_rotation_to_content()`, puis fusionnez le filigrane	Unifiée dans un système de coordonnées visuelles, la donnée géométrique du filigrane est cohérente avec la page
Le filigrane est dans la bonne position mais le texte est à l'envers	Essayez la compensation `Transformation().rotate(180)`	Le filigrane lui-même contient une rotation ou subit une rotation répétée lorsqu'il est combiné.
Le filigrane est rogné ou partiellement invisible	Vérifiez les dimensions MediaBox et CropBox transférées	La taille de la boîte n'est pas mise à jour simultanément
MediaBox a adapté la rotation, mais `/Rotate` existe toujours	Ignorer le transfert, utilisez `merge_transformed_page()` avec `Transformation` pour une correction manuelle	Eviter la double rotation
La valeur `/Rotate` n'est pas un multiple de 90	Ne pas appeler `transfer_rotation_to_content`, évaluation manuelle	La spécification PDF autorise uniquement les multiples de 90

La source du décalage de position du filigrane : le désalignement entre l'attribut /Rotate et le système de coordonnées

Lorsque vous utilisez pypdf pour ajouter des filigranes ou fusionner des pages dans un PDF, un échec courant est que le filigrane apparaît en dehors de la zone visible de la page ou est dévié de 90 degrés ou 180 degrés par rapport au texte principal. Il ne s'agit généralement pas d'un problème lié au fichier de filigrane, mais plutôt au fait que l'attribut /Rotate de la page cible n'est pas géré correctement. Dans la spécification PDF, /Rotate est simplement une directive d'affichage qui indique au lecteur de faire pivoter le canevas lors du rendu. L'origine du système de coordonnées (0,0) du flux de contenu de la page et la taille de la MediaBox ne changeront pas en conséquence.

Lors de l'appel de merge_page() pour fusionner le filigrane dans le flux de contenu, pypdf le superpose en fonction du système de coordonnées d'origine, plutôt que de la vue pivotée vue à l'œil nu de l'utilisateur. Par exemple, une page A4 visuellement paysagée peut toujours avoir son portrait MediaBox sous-jacent [0, 0, 595, 842] et /Rotate=90. À ce stade, si vous fusionnez directement un filigrane horizontal standard, la référence des coordonnées du filigrane ne correspondra pas au contenu de la page et le calcul de la position de superposition sera erroné. L'essentiel pour résoudre ce problème est de comprendre la différence entre la « rotation visuelle » et la « rotation physique » et d'unifier le système de coordonnées avant la fusion.

Le mécanisme et l'exemple de synthèse de transfer_rotation_to_content

La méthode standard pour résoudre les désalignements du système de coordonnées consiste à appeler page.transfer_rotation_to_content(). Cette méthode « intègre » la valeur de /Rotate dans le flux de contenu, en faisant pivoter l'objet graphique en insérant une matrice de transformation, en réinitialisant /Rotate à 0 et en échangeant la largeur et la hauteur de MediaBox pour qu'elles correspondent à la nouvelle direction visuelle. Après l'exécution, le système de coordonnées logiques de la page est cohérent avec la représentation visuelle, et la fusion ultérieure des filigranes peut être basée sur la donnée géométrique correcte.

Pour démontrer cette approche, nous construisons un cas synthétique purement en mémoire. Remarque : le code suivant n'est qu'une démonstration logique et ne se connecte pas aux véritables fichiers IO et n'inclut pas les opérations réseau.

Paramètres d'entrée synthétique :

Page de destination : A4 portrait (595 x 842 points), /Rotate = 90. Visuellement, c'est un paysage, mais la MediaBox est toujours [0, 0, 595, 842].
Page de filigrane : les lecteurs doivent préparer un PDF standard A4 paysage (842 x 595 points) avec le texte « CONFIDENTIEL » imprimé au centre et sans attribut de rotation.
Sortie attendue : le filigrane est centré horizontalement au centre visuel de la page horizontale, avec le texte orienté parallèlement au bord long de la page.

Lorsque vous travaillez avec des fichiers réels, vous devez d'abord lire la page cible et vérifier son état de rotation. Dans des circonstances standard, transfer_rotation_to_content() est appelé en premier, puis le filigrane est fusionné. Pour les cas extrêmes, tels que MediaBox a une rotation adaptée mais /Rotate existe toujours, vous devez ignorer cette étape et utiliser directement merge_transformed_page() avec Transformation pour une correction manuelle ; ou vérifiez d'abord si le rapport hauteur/largeur de page.rotation correspond au rapport hauteur/largeur de MediaBox, puis décidez s'il faut transférer la rotation.

Cadre de code de vérification d'état exécutable

L'exemple Python suivant montre comment créer des cas de test en mémoire et affirmer les états clés. Veuillez d'abord installer pypdf>=3.0.0. La version spécifique doit être déterminée en fonction du fichier de verrouillage du projet. Ce code n'inclut pas la lecture et l'écriture de fichiers, les commandes Shell ou les opérations d'identification. Il vérifie uniquement la logique de changement d'état de l'objet et constitue une démonstration pédagogique.

from pypdf import PdfWriter

# 合成示例：模拟一个 /Rotate=90 但 MediaBox 未变的页面
writer = PdfWriter()
page = writer.add_blank_page(width=595, height=842)

# 使用标准属性设置旋转，而非直接操作底层字典
page.rotation = 90

# 记录原始状态
original_mediabox = page.mediabox
assert float(original_mediabox.width) == 595
assert float(original_mediabox.height) == 842

# 执行旋转转移：将 /Rotate 烘焙进内容流
page.transfer_rotation_to_content()

# 验证后置条件：/Rotate 归零，MediaBox 宽高交换
assert page.rotation == 0, "旋转属性应被清除"
new_mb = page.mediabox
assert float(new_mb.width) == 842, "MediaBox 宽度应随旋转调整"
assert float(new_mb.height) == 595, "MediaBox 高度应随旋转调整"

# 边界检查逻辑示意：若 MediaBox 已是横向，则不应盲目调用此方法
# 实际应用中需在调用前判断
is_already_adapted = (
    float(original_mediabox.width) > float(original_mediabox.height)
) and (page.rotation != 0)
assert not is_already_adapted, "MediaBox 已适配旋转时，应跳过 transfer_rotation_to_content"

Ce code vérifie le contrat principal de transfer_rotation_to_content() : éliminez /Rotate et mettez à jour la MediaBox de manière synchrone. Si l'assertion échoue, cela signifie que le comportement de la version actuelle de pypdf a changé ou qu'il y a une interférence de champ non standard dans la structure de la page. Cet exemple n'inclut pas l'étape de fusion du filigrane car le fichier du filigrane doit être préparé par le lecteur. Ici, nous nous concentrons uniquement sur la vérification de la fiabilité de l’état de rotation pour garantir que les données géométriques des opérations de fusion ultérieures sont correctes.

Critères d'acceptation et conditions de déclenchement de l'examen manuel

Le fait que le code puisse s'exécuter ne signifie pas que les résultats sont utilisables. Le tableau suivant répertorie les indicateurs clés et les décisions correspondantes qui doivent être observées dans le traitement réel, et distingue les limites entre la vérification automatisée et l'intervention manuelle. Ces normes sont applicables aux scénarios de traitement par lots et permettent d'identifier les défauts cachés où « le programme ne signale aucune erreur mais présente des anomalies visuelles ».

Observer les phénomènes	Raisons possibles	Décisions de traitement automatisées	Conditions de déclenchement de l'examen manuel
Le filigrane est dans la bonne position et le sens du texte est normal.	Spin transféré avec succès	accepter	aucun
Le filigrane est dans la bonne position mais le texte est à l'envers	Le filigrane lui-même contient une rotation ou subit une rotation répétée lorsqu'il est combiné.	Essayez la rémunération `Transformation().rotate(180)`	C'est toujours anormal après compensation, ou le texte est également inversé.
Le filigrane est rogné ou partiellement invisible	MediaBox et CropBox ne sont pas mis à jour simultanément	Cochez la taille de la case après `transfer_rotation_to_content`	La taille de la boîte est raisonnable mais toujours recadrée, soupçonnée d'avoir imbriqué ClipPath
Les polices de texte sont floues ou les vecteurs sont déformés	Le transfert de rotation introduit une rastérisation de mauvaise qualité	Non applicable (pypdf conserve les vecteurs par défaut)	Il est confirmé que la rastérisation a eu lieu et que la chaîne d'outils doit être remplacée.
`/Rotate` existe mais la valeur n'est pas un multiple de 90	Angle de rotation non standard (la spécification PDF autorise uniquement les multiples de 90)	`transfer_rotation_to_content` n'est pas appelé	Toutes les pages pivotées de manière non orthogonale nécessitent une évaluation manuelle

Non applicable : PDF cryptés, pages comportant des champs de formulaire ou des couches d'annotations complexes et cas où la valeur /Rotate n'est pas 0, 90, 180, 270. Dans ces scénarios, le transfert de rotation peut interrompre des éléments interactifs ou produire des résultats de rendu imprévisibles. La démonstration de code ne couvre que la transformation géométrique de pages de contenu pur, et l'effet de bout en bout doit être vérifié avec des documents spécifiques. Si les processus automatisés déclenchent fréquemment des conditions de révision manuelle, il convient d'envisager l'introduction de capacités de traitement de documents plus complètes.

📊 Comparaison de base

Méthode de traitement	pratique	Scénarios applicables	Principaux risques
Fusionner directement les filigranes	Ne pas traiter `/Rotate`, superposer selon le système de coordonnées d'origine	La page n'a pas d'attribut de rotation	L'inadéquation de la référence du filigrane et l'écart de position sur la page pivotée
Transférer d'abord la rotation, puis fusionner	Appelez `transfer_rotation_to_content()` pour intégrer la rotation dans le flux de contenu et échanger la largeur et la hauteur de MediaBox	Page `/Rotate` standard	Il est nécessaire de vérifier si la taille de la Box est synchronisée et de faire attention à la qualité du vecteur.
Correction de transformation manuelle	Ajustez à l'aide de `merge_transformed_page()` et `Transformation`	MediaBox a adapté la rotation mais `/Rotate` existe toujours	Nécessite une confirmation manuelle de la direction et de l'emplacement

Utilisez cette liste de contrôle pour la traduction de documents

Le fractionnement, la fusion, le chiffrement ou le traitement des pièces jointes des fichiers sont des préparatifs avant la livraison et la traduction ne peut remplacer ces contrôles. Conservez le document original et la liste des opérations avant le traitement, et vérifiez l'ordre des pages, les liens et l'intégrité du contenu de la traduction une fois la traduction terminée.

OmniDoc fournit un portail pour la traduction de documents multiformats. Le site officiel présente des fonctions telles que l'OCR, le glossaire et la comparaison bilingue. Si l’équipe souhaite démarrer le traitement directement à partir du fichier, ce chemin peut être évalué avec des échantillons réels. Veuillez utiliser des fichiers désensibilisés que vous êtes autorisé à télécharger et examiner les résultats en fonction des éléments de vérification de cet article. Rien ne prétend qu'OmniDoc utilise les bibliothèques open source ou les algorithmes internes mentionnés dans cet article, et l'exemple ne remplace pas non plus les tests de performances du produit.

🎯 Quelle méthode vous convient ?

Si votre page est une MediaBox verticale `/Rotate=90` standard

Appelez d’abord transfer_rotation_to_content(), puis fusionnez le filigrane et vérifiez la taille de MediaBox.

Si le filigrane est dans la bonne position mais que le texte est à l'envers

Essayez la compensation Transformation().rotate(180) ; si l'erreur est toujours anormale après compensation, un examen manuel est requis.

Si la MediaBox a été adaptée à la rotation

Ignorez l'étape de transfert et utilisez plutôt merge_transformed_page() avec Transformation pour une correction manuelle.

Si la page est cryptée, contient des formulaires ou des commentaires, ou si `/Rotate` n'est pas un multiple de 90

Ne le traitez pas automatiquement, évaluez-le d’abord manuellement.

❓ Questions fréquemment posées (FAQ)

1. Pourquoi la page `/Rotate` est-elle mal alignée après la fusion des filigranes ?

Étant donné que /Rotate est une instruction d'affichage uniquement, le système de coordonnées du flux de contenu et de MediaBox ne sont pas modifiés. merge_page() est superposé selon le système de coordonnées d'origine et les données géométriques du filigrane ne correspondront pas à la page visuelle.

2. `transfer_rotation_to_content()` modifiera-t-il le contenu de la page ?

Il intègre la valeur de rotation dans le flux de contenu, réinitialise /Rotate à 0 et échange la largeur et la hauteur de la MediaBox. De cette façon, le système de coordonnées logiques de la page est cohérent avec la représentation visuelle.

3. Si le code peut s'exécuter, cela signifie-t-il que le résultat est utilisable ?

incertain. La transmission du code indique uniquement que l'état de l'objet change comme prévu. Les effets visuels doivent encore être vérifiés élément par élément selon le formulaire d'acceptation, en accordant une attention particulière au recadrage, à l'orientation du texte et à la qualité des vecteurs.

4. Cette méthode peut-elle être utilisée pour crypter directement un PDF ?

Le champ d’application de l’inapplicabilité est clairement indiqué dans l’article. Pour les PDF cryptés, les pages comportant des formulaires complexes ou des couches d'annotations, la rotation et le transfert peuvent détruire les éléments interactifs et doivent être vérifiés individuellement en conjonction avec le document spécifique.

📝Résumé

/Rotate n'est pas cohérent avec le système de coordonnées du flux de contenu, ce qui est la principale raison du mauvais alignement du filigrane sur la page pivotée. Les pages standard sont d'abord transférées et pivotées, puis les filigranes sont fusionnés. Dans les cas frontaliers, le transfert est ignoré et examiné manuellement.

Essayez-le maintenant : téléchargez le document pour lancer la traduction, en conservant la mise en page d'origine.

Références et prochaines étapes

Document officiel sur le filigrane et la rotation pypdf : https://pypdf.readthedocs.io/en/stable/user/add-watermark.html