PDF417 ****** PDF417 est une symbologie 2D empilée utilisée sur les permis de conduire, les cartes d'embarquement, les étiquettes d'expédition et d'autres documents nécessitant un code-barres à haute capacité (jusqu'à 925 mots de code de données). Ajouté dans la version 0.14: La prise en charge de PDF417 a été ajoutée dans cette version. Voir aussi: PDF417 sur Wikipédia pour des informations générales sur la symbologie elle-même. PDF417 est défini dans la norme ISO/IEC 15438 (Technologies de l'information -- Techniques automatiques d'identification et de capture des données -- Spécifications pour les symboles de codes à barres -- PDF 417). Exemple ======= from pystrich.pdf417 import PDF417Encoder encoder = PDF417Encoder("WDBCA45D2HA327260") encoder.save_svg("pdf417-example.svg") [image: PDF417 encodant « WDBCA45D2HA327260 ».][image] Dimensionnement et zone de silence ================================== L'argument "cellsize" de "save()" et "get_imagedata()" définit la longueur de côté, en pixels, d'un module ("5" par défaut). L'argument "quiet_zone" de "PDF417Encoder" définit la largeur (en modules) de la bordure blanche appliquée au moment du rendu. La spécification PDF417 exige au moins deux modules de chaque côté ; pyStrich utilise ce minimum par défaut. Les modules PDF417 ne sont pas carrés -- la spécification recommande une hauteur de rangée d'au moins trois fois la largeur de module ("Y >= 3X"). L'argument "row_height" exprime ce rapport ; la valeur par défaut "3" correspond à la recommandation de la spécification. La diminuer produit un symbole plus dense mais réduit la robustesse à la lecture. Voir aussi: Impression des codes-barres pour des conseils sur le choix de "cellsize" pour une sortie imprimée. encoder = PDF417Encoder("WDBCA45D2HA327260") encoder.save("pdf417-large.png", cellsize=10) [image: PDF417 encodant « WDBCA45D2HA327260 », rendu avec cellsize=10.][image] Formats de sortie ================= Sortie SVG ---------- Pour une intégration dans des pages web ou tout flux de travail tirant parti d'une sortie indépendante de la résolution, utilisez "save_svg()" (ou "get_svg()" pour récupérer le SVG sous forme de chaîne). PDF417Encoder("WDBCA45D2HA327260").save_svg("pdf417.svg") Le "viewBox" du SVG est exprimé en unités de module, tandis que "width" et "height" sont mis à l'échelle par "cellsize". Sortie PNG ---------- Pour une sortie matricielle, utilisez "save()" pour écrire un fichier PNG ou "get_imagedata()" pour récupérer les octets PNG bruts. PDF417Encoder("WDBCA45D2HA327260").save("pdf417.png") Sortie EPS ---------- Pour une intégration dans LaTeX ("\includegraphics") ou d'autres flux d'impression vectorielle, utilisez "save_eps()" (ou "get_eps()" pour récupérer l'EPS sous forme de chaîne). PDF417Encoder("WDBCA45D2HA327260").save_eps("pdf417.eps") L'argument "cellsize" est la longueur de côté d'un module en points PostScript (1 point = 1/72 de pouce). Sortie terminal --------------- Pour un affichage rapide à l'écran, "get_terminal_art()" renvoie un rendu à l'écran à l'aide de demi-blocs horizontaux ("▌"/"▐") : une rangée de mots de code par ligne, deux modules par caractère. Cela garde les limites des rangées de mots de code alignées sur les limites des caractères et donne un rapport d'aspect à l'écran proche du "Y >= 3X" de la spécification. print(PDF417Encoder("WDBCA45D2HA327260").get_terminal_art()) ████▐▐▐ ▐██▐▐▐██ █▌▌█▐█▌ ▐█ █▌▌ ▌█▐▐█▌▐██▐██▐▐▐██ ███▌▌ ▌▌▐ ████▐▐▐ ▐██▐▐ ▐▌ ██▐▐█▐█ ▐██▐ ▐ █ ██ ▐█▐█▐▐█▌▌▌▐ ███▌▌ ▌▌▐ ████▐▐▐ ▐▐▐ ██ ▌ ▐█ ▌█▐█▐██▌▐ ▌██▌▌█▌ ▌▐▌▌▌ ██▌ ███▌▌ ▌▌▐ ████▐▐▐ ▐▌▌██ ██▌▌▌ █ █ ▐▌▐ █ █▌ ██▐▌▌▐█ ▐▌▌██ ██▌███▌▌ ▌▌▐ ████▐▐▐ ▐▌▌█▌ ▐ ▌███▐▐▌ ▐█▐█ ██ ▌██▐ ▌▐ ▐█▌▌█▌▐█ ███▌▌ ▌▌▐ ████▐▐▐ ▐██▐▐█▌█ ▌█▌ ▌▐▌▐▐▌█ ██ █▐█▌ ▌▐▌▐█▌▌██ ▌███▌▌ ▌▌▐ ████▐▐▐ ▐█▐ █▌██▌▌█ █ ▐ ▐▐▐█▌▐█▌ ▌ ▌ ▌▌ ▐█▐ █▌██▌███▌▌ ▌▌▐ Par défaut, la sortie est encadrée par des codes d'échappement ANSI qui imposent un fond blanc et un premier plan noir, afin que le symbole se lise quel que soit le thème de couleurs du terminal. Passez "ansi_bg=False" pour une sortie simple (correcte uniquement sur un terminal à thème clair). Sortie DXF (CAO) ---------------- Pour les applications de marquage direct des pièces, "get_dxf()" renvoie une représentation DXF du symbole que les outils de CAO et de FAO peuvent lire directement. Le "cellsize" est exprimé dans vos "units" choisies (""mm"" par défaut) plutôt qu'en pixels. encoder = PDF417Encoder("WDBCA45D2HA327260") with open("part.dxf", "w") as f: f.write(encoder.get_dxf(cellsize=0.5, units="mm")) Par défaut, "inverse=True" émet la géométrie des modules clairs, y compris la zone de silence -- de sorte que la boîte englobante encadre le symbole. Passez "inverse=False" pour n'émettre que les modules sombres, ce qui correspond à l'apparence normale du symbole ; la boîte englobante épouse alors les cellules sombres et la zone de silence doit être réintroduite en aval. Forme du symbole ================ Les symboles PDF417 sont rectangulaires : "rows" (3 à 90) et "columns" (1 à 30, en comptant uniquement les colonnes de données -- les motifs de départ et d'arrêt ainsi que les indicateurs de rangée s'ajoutent par-dessus). pyStrich choisit les deux automatiquement pour minimiser l'aire du symbole tout en conservant l'aspect large qu'attendent les lecteurs à la valeur par défaut "row_height=3". Pour les applications qui exigent une largeur fixe -- par exemple une étiquette de taille connue --, fixez "columns" et laissez pyStrich choisir le nombre de rangées : PDF417Encoder("WDBCA45D2HA327260", columns=4).save("pdf417-4col.png") Augmenter "columns" rend le symbole plus large et plus court ; le diminuer, plus étroit et plus haut. L'encodeur lève "PyStrichInvalidPayloadLength" si les données ne tiennent pas au nombre de colonnes choisi. Niveau de correction d'erreurs ============================== PDF417 intègre des données redondantes afin qu'un symbole partiellement endommagé reste lisible. Le niveau de correction d'erreurs (ECL) est un entier de 0 à 8 ; chaque niveau double le nombre de mots de code de correction : +---------+--------------+-----------------------------------------------+ | ECL | Mots de code | Usage typique | | | de | | | | correction | | |=========|==============|===============================================| | "0" | 2 | Vérification uniquement, aucune récupération. | +---------+--------------+-----------------------------------------------+ | "1" | 4 | Symboles minuscules où l'espace est précieux. | +---------+--------------+-----------------------------------------------+ | "2" | 8 | **Par défaut** jusqu'à 40 mots de code de | | | | données. | +---------+--------------+-----------------------------------------------+ | "3" | 16 | Par défaut pour 41 à 160 mots de code de | | | | données. | +---------+--------------+-----------------------------------------------+ | "4" | 32 | Par défaut pour 161 à 320 mots de code de | | | | données. | +---------+--------------+-----------------------------------------------+ | "5" | 64 | Par défaut pour 321 à 863 mots de code de | | | | données. | +---------+--------------+-----------------------------------------------+ | "6" | 128 | Environnements hostiles (dommages probables | | | | sur l'étiquette). | +---------+--------------+-----------------------------------------------+ | "7" | 256 | Comme ci-dessus ; grands symboles uniquement. | +---------+--------------+-----------------------------------------------+ | "8" | 512 | Comme ci-dessus ; ne contient que jusqu'à 415 | | | | mots de code de données. | +---------+--------------+-----------------------------------------------+ Les valeurs par défaut suivent la recommandation de niveau minimal de la spécification. Choisissez un niveau plus élevé pour les symboles susceptibles d'être partiellement masqués -- rayés, salis ou déchirés --, et le symbole grandira pour accueillir la correction supplémentaire. PDF417Encoder("WDBCA45D2HA327260", ecl=5).save("pdf417-high.png") Texte non ASCII =============== "PDF417Encoder" accepte directement n'importe quelle chaîne Unicode et choisit le jeu de caractères le plus restreint qui convient. N'encapsulez l'entrée dans "PDF417Data" que si vous voulez restreindre ce choix -- par exemple, pour imposer ""ascii"" afin qu'un caractère non ASCII isolé lève une exception au lieu d'agrandir silencieusement le symbole : +------------------+---------------------------------------------------------------------+ | Encodage | Comportement | |==================|=====================================================================| | ""ascii"" | Lève "PyStrichInvalidInput" pour tout octet > 127. | +------------------+---------------------------------------------------------------------+ | ""iso-8859-1"" | Latin-1 -- l'interprétation de caractères par défaut de PDF417. | | | Émet le mot de code 927 + 3 (ECI 000003) une fois au début du | | | symbole, afin que les décodeurs qui devinent le jeu de caractères | | | ne se trompent pas sur les courtes charges utiles à octets hauts. | +------------------+---------------------------------------------------------------------+ | ""utf-8"" | Émet le mot de code 927 + 26 (ECI 000026) une fois au début du | | | symbole et encode l'entrée octet par octet. Les décodeurs conformes | | | détectent l'encodage automatiquement. | +------------------+---------------------------------------------------------------------+ Astuce: L'encodage sélectionné automatiquement est toujours le plus restreint qui convient ; passer une simple "str" vous donne donc déjà le plus petit symbole. Choisir un encodage à la main sert surtout à la validation des entrées -- par exemple, rejeter tout ce qui sort de l'ASCII dès l'entrée. # Plain str: Latin-1 picked automatically, ECI 3 emitted. PDF417Encoder("Ich dachte, Sie wären kräftiger").save("latin1.png") [image: PDF417 encodant « Ich dachte, Sie wären kräftiger » en Latin-1.][image] # Plain str: UTF-8 picked automatically, ECI 26 emitted. PDF417Encoder("€5 親切にしろ 🐻‍❄️").save("utf8.png") [image: PDF417 encodant « €5 親切にしろ 🐻‍❄️ » en UTF-8 (ECI 26).][image] Si vous fixez un encodage incompatible avec l'entrée, l'erreur levée suggère l'encodage qui *aurait* fonctionné : >>> from pystrich.pdf417 import PDF417Data >>> PDF417Data("Ich dachte, Sie wären kräftiger", encoding="ascii") Traceback (most recent call last): ... pystrich.exceptions.PyStrichInvalidInput: PDF417Data encoding ASCII cannot encode the input; try PDF417Data('Ich dachte, Sie wären kräftiger', encoding='iso-8859-1') or pass auto_encoding=True to select an encoding automatically. API === class PDF417Encoder(text: PDF417Data | str, *, ecl: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8] | None = None, columns: int | None = None, quiet_zone: int = 2, row_height: int = 3) Bases : "Matrix2DEncoder"["int"] Encode du texte sous forme de code-barres 2D PDF417. La forme de la matrice est déterminée par la longueur des données, le niveau de correction d'erreurs et un nombre de colonnes explicite facultatif. Lorsque "ecl" est omis, il est choisi pour correspondre à la recommandation de niveau minimal de la spécification pour la longueur de données donnée. Variables: * **matrix** -- Grille de modules 0/1 construite à partir du flux de mots de code. * **rows** -- Nombre de rangées de mots de code dans le symbole. * **columns** -- Nombre de colonnes de données (indicateurs de rangée exclus). * **ecl** -- Niveau de correction d'erreurs en vigueur. * **row_height** -- Rangées de matrice par rangée de mots de code (3 par défaut). * **quiet_zone** -- Bordure blanche appliquée par le moteur de rendu, en modules. get_ascii() -> str Renvoie un rendu en art ASCII du symbole. Type renvoyé: str get_dxf(cellsize: float = 1.0, inverse: bool = True, units: Literal['in', 'ft', 'mi', 'mm', 'cm', 'm'] | None = 'mm', *, mark_shape: MarkShape = MarkShape.SQUARE_CELLS) -> str Renvoie une représentation DXF (CAO) du symbole. Paramètres: * **cellsize** -- Longueur de côté d'un module en "units". * **inverse** -- Si "True" (par défaut), les modules clairs sont dessinés comme des cellules pleines. Si "False", ce sont les modules sombres qui sont dessinés, ce qui correspond à l'apparence normale du symbole. * **units** -- L'une des valeurs ""in"", ""ft"", ""mi"", ""mm"", ""cm"" ou ""m"", ou "None" pour « non spécifié » ("$INSUNITS=0"). * **mark_shape** -- Comment les cellules marquées sont groupées et dessinées. Type renvoyé: str get_eps(cellsize: int = 5, *, inverse: bool = False, mark_shape: MarkShape = MarkShape.HORIZONTAL_RUNS, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> str Génère le symbole et renvoie le balisage EPS. Paramètres: * **cellsize** -- Longueur de côté d'un module en points PostScript. * **inverse** -- Si "True", marque les cellules claires au lieu des sombres. * **mark_shape** -- Comment les cellules marquées sont groupées et dessinées. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA", opaque. Blanc par défaut. Type renvoyé: str Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". get_imagedata(cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> bytes Génère le symbole et renvoie les octets PNG. Paramètres: * **cellsize** -- Longueur de côté d'un module en pixels. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Blanc par défaut. Renvoie: Données d'image encodées en PNG. Type renvoyé: bytes Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". get_pilimage(cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> PILImage Génère le symbole et renvoie une image Pillow. Paramètres: * **cellsize** -- Longueur de côté d'un module en pixels. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Blanc par défaut. Renvoie: Le symbole rendu. Type renvoyé: PIL.Image.Image Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". get_rect_marks(*, inverse: bool = False, mark_shape: MarkShape = MarkShape.HORIZONTAL_RUNS) -> SymbolMarks Renvoie les cellules sombres du symbole sous forme de rectangles en unités de module. Paramètres: * **inverse** -- Si "True", marque les cellules claires au lieu des sombres. * **mark_shape** -- Comment les cellules marquées sont groupées et dessinées. Type renvoyé: pystrich.marks.SymbolMarks Ajouté dans la version 0.18. get_svg(cellsize: int = 5, *, inverse: bool = False, mark_shape: MarkShape = MarkShape.HORIZONTAL_RUNS, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> str Génère le symbole et renvoie le balisage SVG. Paramètres: * **cellsize** -- Longueur de côté d'un module en unités utilisateur. * **inverse** -- Si "True", marque les cellules claires au lieu des sombres. * **mark_shape** -- Comment les cellules marquées sont groupées et dessinées. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Blanc par défaut. Type renvoyé: str Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". get_terminal_art(*, ansi_bg: bool = True) -> str Génère le symbole à l'aide de demi-blocs Unicode pour les terminaux. Chaque caractère représente deux lignes de la matrice et une colonne, produisant des cellules à peu près carrées dans une police à chasse fixe classique et donnant un résultat lisible par un lecteur de codes-barres à l'écran. Paramètres: **ansi_bg** -- Si "True" (par défaut), encadre chaque ligne de codes d'échappement ANSI qui imposent un fond blanc et un premier plan noir, rendant le symbole lisible quel que soit le thème de couleurs du terminal. Mettez à "False" pour une sortie simple (correcte uniquement sur un terminal à thème clair). Type renvoyé: str png_dataurl(cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> str Génère le symbole et renvoie une chaîne d'URL "data:" PNG. Paramètres: * **cellsize** -- Longueur de côté d'un module en pixels. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Blanc par défaut. Type renvoyé: str Ajouté dans la version 0.15. Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". save(filename: str | os.PathLike[str], cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> None Enregistre le symbole en PNG. Passez un nom de fichier ".png". Paramètres: * **filename** -- Chemin de sortie PNG. * **cellsize** -- Longueur de côté d'un module en pixels. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Blanc par défaut. Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". save_eps(filename: str | os.PathLike[str], cellsize: int = 5, *, inverse: bool = False, mark_shape: MarkShape = MarkShape.HORIZONTAL_RUNS, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> None Enregistre le symbole dans un fichier EPS. Passez un nom de fichier ".eps". Paramètres: * **filename** -- Chemin de sortie EPS. * **cellsize** -- Longueur de côté d'un module en points PostScript. * **inverse** -- Si "True", marque les cellules claires au lieu des sombres. * **mark_shape** -- Comment les cellules marquées sont groupées et dessinées. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA", opaque. Blanc par défaut. Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". save_svg(filename: str | os.PathLike[str], cellsize: int = 5, *, inverse: bool = False, mark_shape: MarkShape = MarkShape.HORIZONTAL_RUNS, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> None Enregistre le symbole dans un fichier SVG. Passez un nom de fichier ".svg". Paramètres: * **filename** -- Chemin de sortie SVG. * **cellsize** -- Longueur de côté d'un module en unités utilisateur. * **inverse** -- Si "True", marque les cellules claires au lieu des sombres. * **mark_shape** -- Comment les cellules marquées sont groupées et dessinées. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Blanc par défaut. Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". svg_dataurl(cellsize: int = 5, *, inverse: bool = False, mark_shape: MarkShape = MarkShape.HORIZONTAL_RUNS, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) -> str Génère le symbole et renvoie une chaîne d'URL "data:" SVG. Paramètres: * **cellsize** -- Longueur de côté d'un module en unités utilisateur. * **inverse** -- Si "True", marque les cellules claires au lieu des sombres. * **mark_shape** -- Comment les cellules marquées sont groupées et dessinées. * **dark_hex** -- Couleur des modules sombres, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Noir par défaut. * **light_hex** -- Couleur de fond, sous forme de chaîne hexadécimale de 3, 6 ou 8 chiffres ou d'un "RGBA". Blanc par défaut. Type renvoyé: str Ajouté dans la version 0.15. Modifié dans la version 0.16: Ajout de "dark_hex" et "light_hex". init_renderer() -> PDF417Renderer Construit un "PDF417Renderer" pour la matrice encodée. Encapsule la matrice dans une zone de silence avant de la renvoyer et met à jour "width" et "height" avec les dimensions en modules du moteur de rendu. class PDF417Data(*segments: str | MarkerT, encoding: EncT | None = None, auto_encoding: bool = False) Bases : "EncodableData" Entrée d'encodeur avec un choix explicite de jeu de caractères. "PDF417Encoder" accepte une simple "str" et sélectionne l'encodage automatiquement. N'utilisez "PDF417Data" que pour fixer l'encodage -- par exemple, forcer ""ascii"" pour rejeter une entrée non ASCII. Passez soit "encoding=" (l'un de ""ascii"", ""iso-8859-1"", ""utf-8""), soit "auto_encoding=True". Avec "auto_encoding=True", le constructeur choisit l'encodage le plus restreint qui convient ; tout argument "encoding=" est alors ignoré. as_plain_text() -> tuple[str, EncT] Renvoie le texte concaténé et le codec permettant de l'encoder. Lève "_HasMarkers" si un segment est un marqueur brut plutôt qu'une chaîne. Pour les sous-classes sans marqueurs ("MarkerT == Never"), la vérification est sans effet.