# 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):
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Run the application:
```bash
streamlit run app.py
```

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

### Option 2: Podman Container

1. Build and run using the provided script:
```bash
./run-podman.sh
```

2. Or manually:
```bash
# 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:
```bash
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`:
```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

```bash
# 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](https://streamlit.io/)
- QR code generation by [qrcode](https://github.com/lincolnloop/python-qrcode) and [segno](https://github.com/heuer/segno)
- Image processing by [Pillow](https://python-pillow.org/)

## 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+