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")
Aztec Code encodant l'URL GitHub de pyStrich.

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)
Aztec Code encodant l'URL GitHub de pyStrich, 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).

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")
Aztec Code encodant « Ich dachte, Sie wären kräftiger » en Latin-1. 
# Plain str: UTF-8 picked automatically, ECI 26 emitted.
AztecEncoder("€5 親切にしろ 🐻‍❄️").save("utf8.png")
Aztec Code 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.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.

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.

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

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

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.