PDF417

PDF417 ist eine gestapelte 2D-Symbologie, die auf Führerscheinen, Bordkarten, Versandetiketten und anderen Dokumenten verwendet wird, die einen Barcode hoher Kapazität benötigen (bis zu 925 Daten-Codewörter).

Neu in Version 0.14: Die Unterstützung für PDF417 wurde in dieser Version hinzugefügt.

Siehe auch

PDF417 auf Wikipedia für Hintergründe zur Symbologie selbst.

PDF417 ist in ISO/IEC 15438 definiert (Informationstechnik – Verfahren der automatischen Identifikation und Datenerfassung – Spezifikation der Strichcodesymbologie PDF417).

Beispiel

from pystrich.pdf417 import PDF417Encoder

encoder = PDF417Encoder("WDBCA45D2HA327260")
encoder.save_svg("pdf417-example.svg")
PDF417, das "WDBCA45D2HA327260" codiert.

Größe und Ruhezone

Das Argument cellsize von save() und get_imagedata() legt die Kantenlänge eines Moduls in Pixeln fest (Vorgabe 5).

Das Argument quiet_zone von PDF417Encoder legt die Breite (in Modulen) des beim Rendern angewendeten weißen Rands fest. Die PDF417-Spezifikation verlangt mindestens zwei Module auf jeder Seite; pyStrich verwendet standardmäßig dieses Minimum.

PDF417-Module sind nicht quadratisch – die Spezifikation empfiehlt eine Zeilenhöhe von mindestens dem Dreifachen der Modulbreite (Y >= 3X). Das Argument row_height drückt dieses Verhältnis aus; die Vorgabe 3 entspricht der Empfehlung der Spezifikation. Ein Verringern erzeugt ein dichteres Symbol, verringert aber die Scanner-Robustheit.

Siehe auch

Barcodes drucken für Hinweise zur Wahl von cellsize bei gedruckter Ausgabe.

encoder = PDF417Encoder("WDBCA45D2HA327260")
encoder.save("pdf417-large.png", cellsize=10)
PDF417, das "WDBCA45D2HA327260" codiert, gerendert mit cellsize=10.

Ausgabeformate

SVG-Ausgabe

Zum Einbetten in Webseiten oder für jeden Arbeitsablauf, der von auflösungsunabhängiger Ausgabe profitiert, verwenden Sie save_svg() (oder get_svg(), um das SVG als Zeichenkette zu erhalten).

PDF417Encoder("WDBCA45D2HA327260").save_svg("pdf417.svg")

Die viewBox des SVG ist in Moduleinheiten angegeben, während width und height mit cellsize skalieren.

PNG-Ausgabe

Verwenden Sie für die Rasterausgabe save(), um eine PNG-Datei zu schreiben, oder get_imagedata(), um die rohen PNG-Bytes zu erhalten.

PDF417Encoder("WDBCA45D2HA327260").save("pdf417.png")

EPS-Ausgabe

Verwenden Sie zum Einbetten in LaTeX (\includegraphics) oder andere Vektor-Druck-Arbeitsabläufe save_eps() (oder get_eps(), um das EPS als Zeichenkette zu erhalten).

PDF417Encoder("WDBCA45D2HA327260").save_eps("pdf417.eps")

Das Argument cellsize ist die Kantenlänge eines Moduls in PostScript-Punkten (1 Punkt = 1/72 Zoll).

Terminal-Ausgabe

Für schnelle Anzeige auf dem Bildschirm liefert get_terminal_art() eine Bildschirmdarstellung mit horizontalen Halbblockzeichen (▌/▐): eine Codewort-Zeile pro Zeile, zwei Module pro Zeichen. Das hält die Grenzen der Codewort-Zeilen an den Zeichengrenzen ausgerichtet und ergibt ein Seitenverhältnis auf dem Bildschirm nahe dem Y >= 3X der Spezifikation.

print(PDF417Encoder("WDBCA45D2HA327260").get_terminal_art())

                                                              
 ████▐▐▐ ▐██▐▐▐██ █▌▌█▐█▌ ▐█ █▌▌  ▌█▐▐█▌▐██▐██▐▐▐██ ███▌▌ ▌▌▐ 
 ████▐▐▐ ▐██▐▐ ▐▌ ██▐▐█▐█ ▐██▐ ▐ █ ██ ▐█▐█▐▐█▌▌▌▐   ███▌▌ ▌▌▐ 
 ████▐▐▐ ▐▐▐ ██   ▌ ▐█  ▌█▐█▐██▌▐ ▌██▌▌█▌ ▌▐▌▌▌ ██▌ ███▌▌ ▌▌▐ 
 ████▐▐▐ ▐▌▌██ ██▌▌▌ █  █ ▐▌▐ █ █▌ ██▐▌▌▐█ ▐▌▌██ ██▌███▌▌ ▌▌▐ 
 ████▐▐▐ ▐▌▌█▌ ▐  ▌███▐▐▌ ▐█▐█ ██ ▌██▐ ▌▐  ▐█▌▌█▌▐█ ███▌▌ ▌▌▐ 
 ████▐▐▐ ▐██▐▐█▌█ ▌█▌  ▌▐▌▐▐▌█ ██  █▐█▌ ▌▐▌▐█▌▌██  ▌███▌▌ ▌▌▐ 
 ████▐▐▐ ▐█▐ █▌██▌▌█ █ ▐  ▐▐▐█▌▐█▌ ▌  ▌ ▌▌ ▐█▐ █▌██▌███▌▌ ▌▌▐

Standardmäßig wird die Ausgabe von ANSI-Escape-Codes umschlossen, die einen weißen Hintergrund und schwarzen Vordergrund erzwingen, sodass das Symbol unabhängig vom Farbschema des Terminals eingelesen werden kann. Übergeben Sie ansi_bg=False für eine einfache Ausgabe (nur auf einem hell gestalteten Terminal korrekt).

DXF-Ausgabe (CAD)

Für Anwendungen zur direkten Teilekennzeichnung (direct part marking) liefert get_dxf() eine DXF-Darstellung des Symbols, die CAD- und CAM-Werkzeuge direkt lesen können. Die cellsize ist in Ihrer gewählten Einheit units (Vorgabe "mm") statt in Pixeln angegeben.

encoder = PDF417Encoder("WDBCA45D2HA327260")
with open("part.dxf", "w") as f:
    f.write(encoder.get_dxf(cellsize=0.5, units="mm"))

Die Vorgabe inverse=True gibt Geometrie für die hellen Module aus, einschließlich der Ruhezone – sodass der Begrenzungsrahmen (bounding box) das Symbol einrahmt. Übergeben Sie inverse=False, um stattdessen nur die dunklen Module auszugeben, was dem normalen Erscheinungsbild des Symbols entspricht; der Begrenzungsrahmen schmiegt sich dann an die dunklen Zellen an und die Ruhezone muss in der nachgelagerten Verarbeitung wieder hinzugefügt werden.

Symbolform

PDF417-Symbole sind rechteckig: rows (3-90) und columns (1-30, wobei nur Datenspalten gezählt werden – die Start-/Stoppmuster und Zeilenindikatoren kommen zusätzlich hinzu). pyStrich wählt beide automatisch, um die Fläche des Symbols zu minimieren und dabei das breite Seitenverhältnis beizubehalten, das Scanner bei der Vorgabe row_height=3 erwarten.

Legen Sie für Anwendungen, die eine feste Breite benötigen – zum Beispiel ein Etikett bekannter Größe – columns fest und lassen Sie pyStrich die Zeilenanzahl wählen:

PDF417Encoder("WDBCA45D2HA327260", columns=4).save("pdf417-4col.png")

Ein Erhöhen von columns macht das Symbol breiter und niedriger; ein Verringern schmaler und höher. Der Encoder löst PyStrichInvalidInput aus, wenn die Daten bei der gewählten Spaltenanzahl nicht passen.

Fehlerkorrekturstufe

PDF417 bettet redundante Daten ein, sodass ein teilweise beschädigtes Symbol noch gelesen werden kann. Die Fehlerkorrekturstufe (ECL) ist eine Ganzzahl von 0-8; jede Stufe verdoppelt die Anzahl der Fehlerkorrektur-Codewörter:

ECL

EC-Codewörter

Typische Verwendung

0

2

Nur Verifikation, keine Wiederherstellung.

1

4

Winzige Symbole, bei denen Platz knapp ist.

2

8

Vorgabe für bis zu 40 Daten-Codewörter.

3

16

Vorgabe für 41-160 Daten-Codewörter.

4

32

Vorgabe für 161-320 Daten-Codewörter.

5

64

Vorgabe für 321-863 Daten-Codewörter.

6

128

Raue Umgebungen (Etikettenschäden wahrscheinlich).

7

256

Wie oben; nur große Symbole.

8

512

Wie oben; passt nur für bis zu 415 Daten-Codewörter.

Die Vorgaben folgen der Mindeststufen-Empfehlung der Spezifikation. Wählen Sie eine höhere Stufe für Symbole, die wahrscheinlich teilweise verdeckt werden – zerkratzt, verschmiert oder eingerissen –, und das Symbol wächst, um die zusätzliche Korrektur aufzunehmen.

PDF417Encoder("WDBCA45D2HA327260", ecl=5).save("pdf417-high.png")

Nicht-ASCII-Text

PDF417Encoder akzeptiert jede Unicode-Zeichenkette direkt und wählt den schmalsten passenden Zeichensatz. Kapseln Sie die Eingabe nur dann in PDF417Data, wenn Sie diese Wahl einschränken möchten – zum Beispiel, um "ascii" zu erzwingen, sodass ein versehentliches Nicht-ASCII-Zeichen einen Fehler auslöst, statt das Symbol stillschweigend zu vergrößern:

Codierung

Verhalten

"ascii"

Löst PyStrichInvalidInput bei jedem Byte > 127 aus.

"iso-8859-1"

Latin-1 – die Standard-Zeicheninterpretation von PDF417. Kein ECI-Bezeichner; konforme Decoder erkennen sie automatisch.

"utf-8"

Gibt einmal am Anfang des Symbols Codewort 927 + 26 (ECI 000026) aus und codiert die Eingabe byteweise. Konforme Decoder erkennen die Codierung automatisch.

Tipp

Die automatisch gewählte Codierung ist immer die schmalste passende, sodass die Übergabe eines einfachen str bereits das kleinste Symbol ergibt. Eine Codierung von Hand zu wählen ist vor allem für die Eingabevalidierung nützlich – z. B. um an der Grenze alles außerhalb von ASCII abzulehnen.

# Plain str: Latin-1 picked automatically, no ECI prefix.
PDF417Encoder("Ich dachte, Sie wären kräftiger").save("latin1.png")
PDF417, das "Ich dachte, Sie wären kräftiger" als Latin-1 codiert. 
# Plain str: UTF-8 picked automatically, ECI 26 emitted.
PDF417Encoder("€5 親切にしろ 🐻‍❄️").save("utf8.png")
PDF417, das "€5 親切にしろ 🐻‍❄️" als UTF-8 (ECI 26) codiert.

Wenn Sie eine Codierung festlegen, die nicht zur Eingabe passt, schlägt der ausgelöste Fehler die Codierung vor, die funktioniert hätte:

>>> 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)[Quellcode]

Bases: Matrix2DEncoder[int]

Codiert Text als PDF417-2D-Barcode.

Die Matrixform wird durch die Datenlänge, die Fehlerkorrekturstufe und eine optionale explizite Spaltenanzahl bestimmt. Wenn ecl weggelassen wird, wird sie so gewählt, dass sie der Mindeststufen-Empfehlung der Spezifikation für die gegebene Datenlänge entspricht.

Variablen:

  • matrix – 0/1-Modulraster, aus dem Codewort-Strom aufgebaut.

  • rows – Anzahl der Codewort-Zeilen im Symbol.

  • columns – Anzahl der Datenspalten (ohne Zeilenindikatoren).

  • ecl – Wirksame Fehlerkorrekturstufe.

  • row_height – Matrixzeilen pro Codewort-Zeile (Vorgabe 3).

  • quiet_zone – Vom Renderer angewendeter weißer Rand, in Modulen.

get_ascii() → str

Gibt eine ASCII-Art-Darstellung des Symbols zurück.

Rückgabetyp:

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

Gibt eine DXF-Darstellung (CAD) des Symbols zurück.

Parameter:

  • cellsize – Kantenlänge eines Moduls in units.

  • inverse – Wenn True (die Vorgabe), werden helle Module als gefüllte Zellen gezeichnet. Wenn False, werden dunkle Module gezeichnet, was dem normalen Erscheinungsbild des Symbols entspricht.

  • units – Eines von "in", "ft", "mi", "mm", "cm" oder "m" oder None für nicht angegeben ($INSUNITS=0).

  • mark_shape – Wie gesetzte Zellen gruppiert und gezeichnet werden.

Rückgabetyp:

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

Rendert das Symbol und gibt EPS-Markup zurück.

Parameter:

  • cellsize – Kantenlänge eines Moduls in PostScript-Punkten.

  • inverse – Wenn True, die hellen statt der dunklen Zellen markieren.

  • mark_shape – Wie gesetzte Zellen gruppiert und gezeichnet werden.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA, deckend. Standard ist Weiß.

Rückgabetyp:

str

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

get_imagedata(cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) → bytes

Rendert das Symbol und gibt PNG-Bytes zurück.

Parameter:

  • cellsize – Kantenlänge eines Moduls in Pixeln.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Weiß.

Rückgabe:

PNG-codierte Bilddaten.

Rückgabetyp:

bytes

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

get_pilimage(cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) → PILImage

Rendert das Symbol und gibt ein Pillow-Bild zurück.

Parameter:

  • cellsize – Kantenlänge eines Moduls in Pixeln.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Weiß.

Rückgabe:

Das gerenderte Symbol.

Rückgabetyp:

PIL.Image.Image

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

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

Rendert das Symbol und gibt SVG-Markup zurück.

Parameter:

  • cellsize – Kantenlänge eines Moduls in Benutzereinheiten.

  • inverse – Wenn True, die hellen statt der dunklen Zellen markieren.

  • mark_shape – Wie gesetzte Zellen gruppiert und gezeichnet werden.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Weiß.

Rückgabetyp:

str

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

get_terminal_art(*, ansi_bg: bool = True) → str

Rendert das Symbol mit Unicode-Halbblockzeichen für Terminals.

Jedes Zeichen steht für zwei Matrixzeilen und eine Spalte, erzeugt näherungsweise quadratische Zellen in einer typischen Schrift mit fester Breite und liefert ein Ergebnis, das auf dem Bildschirm vom Scanner lesbar ist.

Parameter:

ansi_bg – Wenn True (die Vorgabe), jede Zeile in ANSI-Escape-Codes einschließen, die einen weißen Hintergrund und schwarzen Vordergrund erzwingen, sodass das Symbol unabhängig vom Farbschema des Terminals vom Scanner lesbar ist. Setzen Sie ihn auf False für eine einfache Ausgabe (nur auf einem hell gestalteten Terminal korrekt).

Rückgabetyp:

str

png_dataurl(cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) → str

Rendert das Symbol und gibt einen PNG-data:-URL-String zurück.

Parameter:

  • cellsize – Kantenlänge eines Moduls in Pixeln.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Weiß.

Rückgabetyp:

str

Neu in Version 0.15.

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

save(filename: str | os.PathLike[str], cellsize: int = 5, *, dark_hex: str | RGBA | None = None, light_hex: str | RGBA | None = None) → None

Speichert das Symbol als PNG. Übergeben Sie einen .png-Dateinamen.

Parameter:

  • filename – PNG-Ausgabepfad.

  • cellsize – Kantenlänge eines Moduls in Pixeln.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Weiß.

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

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

Speichert das Symbol als EPS-Datei. Übergeben Sie einen .eps-Dateinamen.

Parameter:

  • filename – EPS-Ausgabepfad.

  • cellsize – Kantenlänge eines Moduls in PostScript-Punkten.

  • inverse – Wenn True, die hellen statt der dunklen Zellen markieren.

  • mark_shape – Wie gesetzte Zellen gruppiert und gezeichnet werden.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA, deckend. Standard ist Weiß.

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

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

Speichert das Symbol als SVG-Datei. Übergeben Sie einen .svg-Dateinamen.

Parameter:

  • filename – SVG-Ausgabepfad.

  • cellsize – Kantenlänge eines Moduls in Benutzereinheiten.

  • inverse – Wenn True, die hellen statt der dunklen Zellen markieren.

  • mark_shape – Wie gesetzte Zellen gruppiert und gezeichnet werden.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Weiß.

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

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

Rendert das Symbol und gibt einen SVG-data:-URL-String zurück.

Parameter:

  • cellsize – Kantenlänge eines Moduls in Benutzereinheiten.

  • inverse – Wenn True, die hellen statt der dunklen Zellen markieren.

  • mark_shape – Wie gesetzte Zellen gruppiert und gezeichnet werden.

  • dark_hex – Farbe der dunklen Module als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Schwarz.

  • light_hex – Hintergrundfarbe als 3-, 6- oder 8-stelliger Hex-String oder RGBA. Standard ist Weiß.

Rückgabetyp:

str

Neu in Version 0.15.

Geändert in Version 0.16: dark_hex und light_hex hinzugefügt.

init_renderer() → PDF417Renderer[Quellcode]

Konstruiert einen PDF417Renderer für die codierte Matrix.

Wickelt die Matrix vor der Rückgabe in eine Ruhezone und aktualisiert width und height auf die Modulmaße des Renderers.

class PDF417Data(*segments: str | MarkerT, encoding: EncT | None = None, auto_encoding: bool = False)

Bases: EncodableData

Encoder-Eingabe mit expliziter Zeichensatz-Wahl.

PDF417Encoder akzeptiert einen einfachen str und wählt die Codierung automatisch. Verwenden Sie PDF417Data nur, um die Codierung festzulegen – erzwingen Sie zum Beispiel "ascii", um Nicht-ASCII-Eingaben abzulehnen.

Übergeben Sie entweder encoding= (eines von "ascii", "iso-8859-1", "utf-8") oder auto_encoding=True. Mit auto_encoding=True wählt der Konstruktor die schmalste passende Codierung; ein etwaiges encoding=-Argument wird dann ignoriert.

as_plain_text() → tuple[str, EncT]

Gibt den verketteten Text und den Codec zum Codieren zurück.

Löst _HasMarkers aus, wenn ein Segment ein Roh-Marker statt einer Zeichenkette ist. Für Unterklassen ohne Marker (MarkerT == Never) ist die Prüfung ein No-op.