initial commit
This commit is contained in:
301
README.md
Normal file
301
README.md
Normal file
@@ -0,0 +1,301 @@
|
||||
# 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+
|
||||
Reference in New Issue
Block a user