302 lines
8.4 KiB
Markdown
302 lines
8.4 KiB
Markdown
# 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+
|