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")

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)

PDF417 encodant « WDBCA45D2HA327260 », rendu avec cellsize=10.

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 de correction	Usage typique
`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")

PDF417 encodant « Ich dachte, Sie wären kräftiger » en Latin-1.

# Plain str: UTF-8 picked automatically, ECI 26 emitted.
PDF417Encoder("€5 親切にしろ 🐻‍❄️").save("utf8.png")

PDF417 encodant « €5 親切にしろ 🐻‍❄️ » en UTF-8 (ECI 26).

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)[source]¶

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.

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.

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.

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[source]¶

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.