Aztec Code ********** Aztec Code est une symbologie 2D utilisée sur les titres de transport, les cartes d'embarquement et les dossiers médicaux. Il ne nécessite pas de zone de silence, et son puissant motif de recherche central en cible (*bullseye*) se décode de façon fiable quelle que soit la rotation. Les symboles vont de 15x15 modules (compact) à 151x151 (full-range). Ajouté dans la version 0.14: La prise en charge d'Aztec Code a été ajoutée dans cette version. Voir aussi: Code Aztec sur Wikipédia pour des informations générales sur la symbologie elle-même. Aztec Code est défini dans la norme ISO/IEC 24778 (Technologies de l'information -- Techniques automatiques d'identification et de capture des données -- Spécification pour la symbologie de code à barres du code Aztec). Exemple ======= from pystrich.aztec import AztecEncoder encoder = AztecEncoder("https://github.com/mmulqueen/pyStrich") encoder.save_svg("aztec-example.svg") [image: Aztec Code encodant l'URL GitHub de pyStrich.][image] Dimensionnement =============== L'argument "cellsize" de "save()" et "get_imagedata()" définit la longueur de côté, en pixels, d'un module ("5" par défaut). Aztec Code ne nécessite pas de zone de silence, mais pyStrich ajoute par défaut une marge de 2 modules pour offrir aux lecteurs un fond stable. Passez "quiet_zone=" à "AztecEncoder" pour changer la largeur de la bordure (en modules) à chaque appel ; passez "0" pour supprimer entièrement la marge. AztecEncoder("Hello", quiet_zone=0).save("aztec-no-margin.png") Voir aussi: Impression des codes-barres pour des conseils sur le choix de "cellsize" pour une sortie imprimée. encoder = AztecEncoder("https://github.com/mmulqueen/pyStrich") encoder.save("aztec-large.png", cellsize=10) [image: Aztec Code encodant l'URL GitHub de pyStrich, 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). from pystrich.marks import MarkShape AztecEncoder("https://github.com/mmulqueen/pyStrich").save_svg("aztec.svg") AztecEncoder("https://github.com/mmulqueen/pyStrich").save_svg( "aztec-circles.svg", mark_shape=MarkShape.CIRCULAR_CELLS ) Le "viewBox" du SVG est exprimé en unités de module, tandis que "width" et "height" sont mis à l'échelle par "cellsize". Le mot-clé "mark_shape" choisit la façon dont les cellules marquées sont dessinées -- des suites horizontales de rectangles (par défaut) ou un cercle plein par cellule. Sortie PNG ---------- Pour une sortie matricielle, utilisez "save()" pour écrire un fichier PNG ou "get_imagedata()" pour récupérer les octets PNG bruts. AztecEncoder("https://github.com/mmulqueen/pyStrich").save("aztec.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). AztecEncoder("https://github.com/mmulqueen/pyStrich").save_eps("aztec.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 lisible par un lecteur de codes-barres à l'aide de demi-blocs Unicode. Chaque caractère représente deux lignes de la matrice et une colonne, de sorte que les cellules apparaissent à peu près carrées dans une police à chasse fixe classique de terminal. print(AztecEncoder("https://github.com/mmulqueen/pyStrich").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 = AztecEncoder("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. Type et taille du symbole ========================= Aztec Code existe en deux formats : * Les symboles **Compact** font de 15x15 à 27x27 modules (1 à 4 couches de données) et portent jusqu'à 76 mots de code. Utilisez-les pour les charges utiles courtes où l'espace est compté. * Les symboles **Full-range** font de 19x19 à 151x151 modules (1 à 32 couches de données) et portent jusqu'à 1664 mots de code. Une grille de référence (*reference grid*) parcourt les plus grands symboles pour maintenir l'alignement des lecteurs sur tout le symbole. Avec la valeur par défaut "symbol_kind="auto"", l'encodeur choisit le plus petit symbole qui contient la charge utile au pourcentage de correction d'erreurs demandé. À nombre de modules égal, le format compact est préféré au full-range. # Force a full-range symbol even for short input. AztecEncoder("Hello", symbol_kind="full").save("aztec-full.png") # Pin both kind and layer count for a fixed symbol size. AztecEncoder("WDBCA45D2HA327260", symbol_kind="full", layers=5).save( "aztec-full-l5.png" ) Fixer "layers" nécessite un "symbol_kind" explicite ; sinon, l'encodeur lève "PyStrichInvalidOption". Si la charge utile ne tient pas à la taille demandée, il lève "PyStrichInvalidPayloadLength". Correction d'erreurs ==================== Aztec Code intègre des données redondantes afin qu'un symbole partiellement endommagé reste lisible. Contrairement aux niveaux discrets du QR Code, la redondance se règle sous forme de pourcentage entier de 5 à 95 via l'argument "ecc" ; l'encodeur ajoute le pourcentage demandé de la capacité du symbole, plus 3 mots de code : # Default: 23% -- the spec's recommended minimum. AztecEncoder("WDBCA45D2HA327260").save("aztec-default.png") # 50% redundancy for harsher environments. AztecEncoder("WDBCA45D2HA327260", ecc=50).save("aztec-high.png") Des pourcentages plus élevés produisent un symbole plus dense pour une même charge utile (ou, de façon équivalente, exigent un symbole plus grand pour contenir la même charge utile). La valeur par défaut de 23 % est le minimum recommandé par la spécification pour un usage général ; choisissez des valeurs plus élevées pour les symboles susceptibles d'être partiellement masqués ou imprimés sur des surfaces susceptibles d'être rayées, salies ou déchirées. Texte non ASCII =============== "AztecEncoder" 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 "AztecData" 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. Déclare ECI 3 au début du symbole afin que les décodeurs | | | ne se rabattent pas sur des heuristiques ASCII pour les octets | | | supérieurs à 127. | +------------------+---------------------------------------------------------------------+ | ""utf-8"" | Déclare ECI 26 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. AztecEncoder("Ich dachte, Sie wären kräftiger").save("latin1.png") [image: Aztec Code encodant « Ich dachte, Sie wären kräftiger » en Latin-1.][image] # Plain str: UTF-8 picked automatically, ECI 26 emitted. AztecEncoder("€5 親切にしろ 🐻‍❄️").save("utf8.png") [image: Aztec Code 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.aztec import AztecData >>> AztecData("Ich dachte, Sie wären kräftiger", encoding="ascii") Traceback (most recent call last): ... pystrich.exceptions.PyStrichInvalidInput: AztecData encoding ASCII cannot encode the input; try AztecData('Ich dachte, Sie wären kräftiger', encoding='iso-8859-1') or pass auto_encoding=True to select an encoding automatically. Aztec Runes =========== Les Aztec Runes -- de minuscules symboles d'un seul octet, apparentés à l'Aztec -- ne sont pas pris en charge. Si vous en avez besoin, vous pouvez les construire à partir des primitives géométriques de "pystrich.aztec.placement". Merci d'ouvrir une issue sur GitHub décrivant votre besoin. Anatomie ======== Les symboles Aztec combinent quelques éléments structurels fixes avec une zone de données variable. Le schéma ci-dessous annote un symbole full-range à 5 couches (37x37 modules) ; les symboles compacts utilisent les mêmes éléments dans un cœur plus petit et se passent de la grille de référence. [image: Aztec Code annoté montrant le motif de recherche en cible, les marques d'orientation, le message de mode, la grille de référence, les couches de données et la zone de silence.][image] * **Motif de recherche en cible** (*bullseye finder*) -- des carrés concentriques au centre (9x9 dans les symboles compacts, 13x13 en full-range). Le motif emblématique de l'Aztec ; les lecteurs s'y verrouillent quelle que soit la rotation. * **Marques d'orientation** (*orientation marks*) -- des motifs de trois cellules en forme de L à chaque coin du cœur ; le nombre de cellules sombres décroît dans le sens horaire (3, 2, 1, 0), encodant la rotation du symbole. * **Message de mode** (*mode message*) -- l'anneau le plus externe du cœur (d'une cellule de large), encodant le nombre de couches du symbole et le nombre de *mots de code* pour que le décodeur sache quelle est la taille de la zone de données. * **Grille de référence** (*reference grid*) -- des bandes clairsemées de cellules alternativement sombres et claires qui parcourent les symboles full-range tous les 16 modules pour maintenir l'alignement des lecteurs. Les symboles compacts n'en ont pas besoin. * **Couches de données** (*data layers*) -- des anneaux concentriques de modules portant la charge utile plus la correction d'erreurs *Reed-Solomon*. Le nombre de couches détermine la taille du symbole. * **Zone de silence** (*quiet zone*) -- marge blanche autour du symbole ; non requise par la spécification. API === class AztecEncoder(text: str | AztecData, *, ecc: int = 23, symbol_kind: Literal['auto', 'compact', 'full'] = 'auto', layers: int | None = None, quiet_zone: int = 2) Bases : "Matrix2DEncoder"["int"] Encode du texte sous forme de code-barres 2D Aztec Code. Une simple "str" est encodée avec le jeu de caractères le plus restreint qui convient : ASCII, Latin-1 (ECI 3) ou UTF-8 (ECI 26). Passez un "AztecData" pour fixer l'encodage explicitement. Utilisation typique: encoder = AztecEncoder("https://github.com/mmulqueen/pyStrich") encoder.save("aztec.png") Variables: * **matrix** -- Liste 2D décrivant le symbole avant le rendu. * **quiet_zone** -- Largeur, en modules, de la bordure blanche appliquée au moment du rendu. * **width** -- Largeur en pixels de la dernière image rendue. * **height** -- Hauteur en pixels de la dernière image rendue. 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 init_renderer() -> AztecRenderer Construit un "AztecRenderer" pour la matrice encodée. 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". class AztecData(*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. "AztecEncoder" accepte une simple "str" et sélectionne l'encodage automatiquement. N'utilisez "AztecData" 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.