Shared types
************

Shared typing helpers for pyStrich encoders and renderers.

class BarcodeRenderOptions

   Bases: "TypedDict"

   Optional render-time tweaks for label-bearing 1D barcodes.

   Currently used by "pystrich.code128.Code128Encoder" and
   "pystrich.code39.Code39Encoder". All keys are optional; omitted
   keys fall back to library defaults.

   show_label: bool

      Whether to render the human-readable label underneath the bars.
      Defaults to "True"; set to "False" to suppress it.

   ttf_font: str

      Absolute path to a TrueType font file used for the label in PNG
      output. Defaults to a bundled bitmap font if unset. SVG and EPS
      output always render the label using the bundled Courier Prime
      glyph paths and ignore this option.

   ttf_fontsize: int

      Font size in points (PNG output only — SVG/EPS use the bundled
      Courier Prime glyph paths).

   height: int

      Total image height in pixels. Defaults to roughly a third of the
      image width for Code 128, and to "120" for Code 39.

   label_border: int

      Pixels of vertical space between the bars and the label.

   bottom_border: int

      Pixels of vertical space between the label and the bottom edge.

Matrix mark extraction shared by vector renderers (SVG, EPS, DXF).

class MatrixMark(x: int, y: int, width: int, height: int)

   Bases: "NamedTuple"

   A rectangular region of a matrix to be drawn as a single shape.

   x: int

      Alias for field number 0

   y: int

      Alias for field number 1

   width: int

      Alias for field number 2

   height: int

      Alias for field number 3

class MarkShape(*values)

   Bases: "Enum"

   How marked cells are grouped and drawn in vector output.

   Each value selects a grouping (one "MatrixMark" per cell, or one
   per horizontal run) and -- where the renderer supports it -- the
   drawing primitive used per mark.

   HORIZONTAL_RUNS = 1

      Maximal horizontal runs of matched cells, drawn as filled
      rectangles.

   SQUARE_CELLS = 2

      One 1x1 region per matched cell, drawn as a filled rectangle.

   CIRCULAR_CELLS = 3

      One 1x1 region per matched cell, drawn as a filled circle
      inscribed in the cell.

iter_horizontal_runs(matrix: Sequence[Sequence[int | None]], *, mark_values_when: bool) -> Iterator[MatrixMark]

   Yield each maximal horizontal run of cells whose truthiness equals
   "mark_values_when".

   "mark_values_when=True" marks the dark (truthy) cells; "False"
   marks the light cells ("0" or "None"). Each yielded mark has
   "height=1".

iter_cells(matrix: Sequence[Sequence[int | None]], *, mark_values_when: bool) -> Iterator[MatrixMark]

   Yield a 1x1 mark for every cell whose truthiness equals
   "mark_values_when".

iter_marks(matrix: Sequence[Sequence[int | None]], *, mark_values_when: bool, mark_shape: MarkShape) -> Iterator[MatrixMark]

   Yield "MatrixMark" regions for the chosen "mark_shape".

class TextLabel(text: str, x: float, y: float, font_size: int, anchor: str = 'start')

   Bases: "NamedTuple"

   A run of text to render below the bars in vector output.

   Coordinates are in pixels (= user units for SVG/EPS at default
   DPI), and "y" is the *top* edge of the text — matching the
   convention used by "PIL.ImageDraw.text(xy, ...)" for the
   corresponding raster path. "anchor" controls how "x" relates to the
   text run: ""start"" is the left edge, ""middle"" the centre,
   ""end"" the right edge.

   text: str

      Alias for field number 0

   x: float

      Alias for field number 1

   y: float

      Alias for field number 2

   font_size: int

      Alias for field number 3

   anchor: str

      Alias for field number 4

class BarLayout(heights: Sequence[int], bar_width: int, quiet_left: int = 0, quiet_right: int = 0, quiet_top: int = 0, quiet_bottom: int = 0, labels: Sequence[TextLabel] = ())

   Bases: "NamedTuple"

   Pixel-precise layout of a 1D barcode for any output format.

   All values are in pixels (= user units for SVG/EPS at default DPI).
   "heights[i]" is the bar's pixel height at column "i" ("0" is a
   gap). Each column is "bar_width" pixels wide. The four quiet zones
   frame the symbol; "quiet_left" and "quiet_top" shift the bars,
   while "quiet_right" and "quiet_bottom" only enlarge the canvas.
   "labels" carries the human-readable text drawn beneath the bars by
   SVG/EPS renderers; the PNG path renders text via PIL directly and
   ignores this field.

   heights: Sequence[int]

      Alias for field number 0

   bar_width: int

      Alias for field number 1

   quiet_left: int

      Alias for field number 2

   quiet_right: int

      Alias for field number 3

   quiet_top: int

      Alias for field number 4

   quiet_bottom: int

      Alias for field number 5

   labels: Sequence[TextLabel]

      Alias for field number 6

iter_bar_marks(heights: Sequence[int], bar_width: int, *, quiet_left: int = 0, quiet_top: int = 0) -> Iterator[MatrixMark]

   Yield a "MatrixMark" per maximal run of equal positive heights.

   Coordinates and dimensions are in pixels. "heights[i]" is the bar's
   pixel height at column "i" ("0" is a gap; positive values are bars
   sharing a top edge at "y = quiet_top"). Each column is "bar_width"
   pixels wide. Adjacent columns with the same positive height
   collapse into one mark.

   Only "quiet_left" and "quiet_top" are accepted because they are the
   only offsets that affect mark coordinates; the right and bottom
   quiet zones are a renderer concern (canvas / viewBox sizing).