qr-code-generator/README.md

QR Code Generator

A professional web application for generating QR codes with optional logo overlay and export capabilities in multiple formats and resolutions.

Features

• Dual QR Code Types:
  • URL QR Codes: Convert any URL into a scannable QR code
  • WiFi QR Codes: Generate QR codes for WiFi network credentials (WPA/WPA2, WEP, or Open networks)
• Logo Overlay: Add your company logo or custom image to the center of the QR code
• Multiple Export Formats:
  • PNG (Portable Network Graphics)
  • JPEG (Joint Photographic Experts Group)
  • SVG (Scalable Vector Graphics - perfect for print)
• Flexible Resolution Options: Export in various resolutions from 500px to 4000px
• Customizable Appearance: Choose QR code and background colors
• Error Correction Levels: Support for L, M, Q, and H error correction levels
• WiFi Network Support: Supports WPA/WPA2, WEP, and open networks with hidden network option
• Responsive UI: Clean, intuitive interface built with Streamlit
• Containerized Deployment: Ready-to-use Podman/Docker configuration

Tech Stack

• Python 3.11: Core programming language
• Streamlit: Web application framework
• qrcode: QR code generation library
• segno: Advanced QR code library with SVG support
• Pillow (PIL): Image processing
• CairoSVG: SVG rendering
• Podman/Docker: Containerization

Prerequisites

Local Installation

• Python 3.11 or higher
• pip (Python package manager)

Container Installation

• Podman or Docker installed on your system

Installation

Option 1: Local Development

1. Clone the repository or download the files

2. Create a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Run the application:

streamlit run app.py

5. Open your browser to http://localhost:8501

Option 2: Podman Container

1. Build and run using the provided script:

./run-podman.sh

2. Or manually:

# Build the image
podman build -t qr-code-generator .

# Run the container
podman run -d --name qr-app -p 8501:8501 qr-code-generator

3. Access the application at http://localhost:8501

Option 3: Docker Container

Replace podman with docker in the commands above:

docker build -t qr-code-generator .
docker run -d --name qr-app -p 8501:8501 qr-code-generator

Usage Guide

URL QR Code Generation

1. Select Mode: Choose "URL" from the QR Code Type options
2. Enter URL: Type or paste the URL you want to encode
3. Configure Settings (optional):
   • Adjust error correction level (use H for logos)
   • Customize colors
   • Select export format and resolution
4. Generate: Click the "Generate QR Code" button
5. Download: Use the download button to save your QR code

WiFi QR Code Generation

1. Select Mode: Choose "WiFi" from the QR Code Type options
2. Enter Network Details:
   • Network Name (SSID): Your WiFi network name
   • Password: Your WiFi password (leave empty for open networks)
   • Security Type: Select WPA/WPA2, WEP, or None (Open)
   • Hidden Network: Check if your network is hidden
3. Configure Settings (optional):
   • Adjust error correction level
   • Customize colors
   • Select export format and resolution
4. Generate: Click the "Generate QR Code" button
5. Share: Users can scan the QR code to automatically connect to your WiFi network

Note: WiFi QR codes work on most modern smartphones (iOS 11+, Android 10+). The device will automatically detect the QR code contains WiFi credentials and prompt to connect.

Adding a Logo

1. Follow steps 1-2 from basic generation
2. Upload Logo: Click "Upload logo image" and select your image file
3. Adjust Size: Use the slider to set the logo size ratio (0.1 - 0.4)
4. Generate: Click "Generate QR Code"
5. Download: Save your branded QR code

Error Correction Levels

• L (7%): Suitable for clean environments, smallest QR code
• M (15%): Default level, balanced
• Q (25%): Better damage resistance
• H (30%): Recommended for QR codes with logos, highest damage resistance

Format Selection

• PNG: Best for web use, supports transparency
• JPEG: Smaller file size, good for photos, no transparency
• SVG: Vector format, infinitely scalable, perfect for print

Project Structure

qr-code-generator/
├── app.py                 # Main Streamlit application
├── utils/
│   ├── __init__.py       # Package initializer
│   ├── qr_generator.py   # QR code generation utilities
│   └── wifi_qr.py        # WiFi QR code utilities
├── requirements.txt       # Python dependencies
├── Dockerfile            # Container definition
├── .dockerignore         # Docker ignore rules
├── run-podman.sh         # Podman run script
├── .gitignore           # Git ignore rules
└── README.md            # This file

Configuration Options

Streamlit Configuration

The application uses default Streamlit settings. To customize:

Create .streamlit/config.toml:

[server]
port = 8501
headless = true

[theme]
primaryColor = "#FF4B4B"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F0F2F6"
textColor = "#262730"
font = "sans serif"

Environment Variables

For containerized deployment, you can customize:

• STREAMLIT_SERVER_PORT: Change the port (default: 8501)
• STREAMLIT_BROWSER_GATHER_USAGE_STATS: Disable telemetry

Development

Code Style

This project follows Python best practices:

• PEP 8 style guide
• Type hints for function parameters
• Comprehensive docstrings
• Modular, reusable code structure

Adding New Features

1. New Export Format: Update utils/qr_generator.py and add format handler
2. UI Enhancements: Modify app.py Streamlit components
3. New QR Styles: Extend QRCodeGenerator class methods

Testing

Run manual tests by generating QR codes with various configurations:

• Different URLs (short, long, special characters)
• With and without logos
• All export formats
• Various resolutions
• Different error correction levels

Container Management

Podman Commands

# View logs
podman logs qr-app

# Stop container
podman stop qr-app

# Start container
podman start qr-app

# Remove container
podman rm qr-app

# Remove image
podman rmi qr-code-generator

Docker Commands

Replace podman with docker in the commands above.

Troubleshooting

Issue: QR Code Won't Scan

• Solution: Increase error correction level to H
• Reduce logo size ratio
• Ensure sufficient contrast between QR code and background colors

Issue: Logo Appears Distorted

• Solution: Use square or nearly square logos
• Try a smaller logo size ratio
• Ensure logo has sufficient resolution

Issue: Container Won't Start

• Solution: Check if port 8501 is already in use
• Verify Podman/Docker is running
• Check container logs: podman logs qr-app

Issue: Dependencies Install Failure

• Solution: Update pip: pip install --upgrade pip
• Install system dependencies (for Pillow): apt-get install libjpeg-dev zlib1g-dev
• Use Python 3.11 or higher

Performance Considerations

• High-Resolution Exports: May take a few seconds to generate
• SVG Format: Fastest generation, smallest file size, infinite scalability
• Logo Processing: Larger logos require more processing time

Security Notes

• This application runs locally by default
• When deploying publicly, consider:
  • Adding authentication
  • Implementing rate limiting
  • Validating URL inputs
  • Setting up HTTPS

Contributing

To contribute to this project:

1. Follow the existing code style and structure
2. Add appropriate documentation
3. Test thoroughly before submitting
4. Keep commits focused and descriptive

License

This project is provided as-is for educational and commercial use.

Acknowledgments

• Built with Streamlit
• QR code generation by qrcode and segno
• Image processing by Pillow

Support

For issues, questions, or suggestions:

• Check the troubleshooting section
• Review the usage guide
• Examine the code documentation in utils/qr_generator.py

---

Version: 1.0 Last Updated: 2025-11 Python Version: 3.11+