Custom QR Generator

Generate a styled QR code with optional text, icons, and frame options.

Requirements

• Python 3.10+
• Packages: qrcode[pil], pillow

Install:

pip install --upgrade qrcode[pil] pillow

Quick Start

python3 qr.py

The output image is written to custom_qr.png in the project directory.

Configure

Edit the values in the if __name__ == "__main__": block in qr.py:

• DATA: the QR payload (URL or text)
• LINES: three text lines displayed in the center
• FONT: optional path to a .ttf font
• out_path: output filename

Key options you can tweak:

• size_px: output size in pixels
• border: quiet zone size (larger improves scan reliability)
• center_box_ratio: size of the text layout area (smaller is safer to scan)
• text_fill_mode: "solid" or "split" for two-color text
• text_split_colors: text colors as RGB tuples
• auto_fit_text: set to False to make font_size take effect

Full Feature Guide

The main function is make_custom_qr(...) in qr.py. Below is a concise map of what each feature group does so you can tune output without reading the whole code.

Output and Canvas

• out_path: output PNG filename
• size_px: output image size (square)
• bg, fg: background and module colors
• border: quiet zone (increase for better scanning)
• use_styled_modules: True for rounded modules, False for crisp squares

Insets and Frame

• inset_px: reserves padding inside the canvas; QR is drawn smaller
• inset_corner_icon_paths: optional icons in the inset corners
• frame_px: adds an outer frame around the final image
• frame_color: fill color for the frame
• frame_corner_icon_paths: icons placed on the frame corners

Center Box (Text Layout Region)

• center_box_ratio: size of the text layout region relative to the canvas
• draw_center_box: toggle drawing the box (still used for layout if False)
• center_box_fill_color: fill color for the box
• center_box_outline_width, center_box_outline_color: optional outline

Text Rendering

• text_lines: three lines of text (tuple of 3 strings)
• font_path, font_size: font selection and base size
• auto_fit_text: auto scales text to fit the layout region
• text_fill_mode: "solid" or "split" for two-color text
• text_color or text_split_colors: fill color(s)
• text_split_angle_deg, text_split_position, text_split_invert: split gradient controls
• text_render_mode: "fill", "outline", or "fill_outline"
• text_outline_color_mode: "solid" or "split" for outline color
• text_stroke_width: explicit outline thickness (pixels)
• letter_spacing_px, word_spacing_px: manual spacing

Text Layout and Alignment

• text_horizontal_align: "left", "center", "right"
• text_vertical_align: "top" or "center"
• text_left_padding_ratio, text_top_padding_ratio: alignment padding
• text_margin_ratio: inner margin for text layout region
• line_spacing_ratio: vertical spacing between lines
• line_scales: per-line scale factors
• line_x_offsets_ratio: per-line horizontal offset
• line_horizontal_aligns: per-line alignment override
• line_height_mode: "bbox" (glyph-based) or "metrics" (consistent)
• text_vertical_offset_ratio: extra vertical shift

Knockout (Text Readability)

• knockout_text_bg: clears modules behind text
• knockout_padding_ratio: padding around each line
• knockout_mode: "lines" or "block"
• knockout_block_radius_ratio: roundness for block mode

Center Icons (Above Text)

• icon_path or icon_paths: add one icon or a row of icons
• icon_size_ratio: icon size relative to the text area
• icon_gap_ratio: vertical gap between icons and text
• icon_row_gap_ratio: horizontal gap between multiple icons
• icon_offset_ratio: (x, y) offset relative to the text area
• icon_white_to_transparent: remove white pixels from icons

Corner Finder Icons

Icons are drawn in the finder corners using corner_icon_paths.

Overlay modes:

• ring: icon is clipped into the white ring (scan-safe)
• tint / tint_invert: icon tints the finder pattern (uses corner_tint_dark and corner_tint_light)
• center_cutout: icon is cut out of the inner square (uses corner_center_icon_colors)
• overlay: icon is drawn over the full finder area (most visible, less scan-safe)

Related options:

• corner_icon_size_ratio: overall icon size
• corner_icon_overlay_alpha: opacity for "overlay"
• corner_icon_colors: per-corner recolor (used by "ring" and "overlay")
• corner_center_icon_colors: per-corner color for "center_cutout"
• corner_icon_white_to_transparent: remove white from icon assets

Text-Only Preview

Use this to preview text layout without rendering the QR:

• render_text_only=True
• text_only_size: custom size for the text-only image
• text_only_bg: background color for text-only mode

Corner Icons

Icons are drawn in the finder corners using corner_icon_paths.

Overlay modes:

• ring: icon is clipped into the white ring (scan-safe)
• tint / tint_invert: icon tints the finder pattern (uses corner_tint_dark and corner_tint_light)
• center_cutout: icon is cut out of the inner square (uses corner_center_icon_colors)
• overlay: icon is drawn over the full finder area (most visible, less scan-safe)

If you want the icon on top of the dots, use:

corner_icon_overlay_mode="overlay"

Adjust visibility:

• corner_icon_size_ratio: overall icon size (0.8 to 1.1 typical)
• corner_icon_overlay_alpha: icon opacity (0 to 255)

Notes on Scan Reliability

• Use border >= 6 for better scanning
• Keep center_box_ratio modest (0.26 to 0.32)
• Avoid large opaque overlays in the center

License

See LICENSE.