137 lines
4.2 KiB
Markdown
137 lines
4.2 KiB
Markdown
# PunimTag - Intelligent Photo Management System
|
|
|
|
A Flask-based photo management system with automatic face recognition, tagging, and duplicate detection.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Run the application
|
|
python main.py
|
|
|
|
# Access the web interface
|
|
# http://localhost:5000
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
PunimTag/
|
|
├── src/ # Main application source code
|
|
│ ├── backend/ # Flask backend and API
|
|
│ │ ├── app.py # Main Flask application
|
|
│ │ ├── db_manager.py # Database operations
|
|
│ │ └── visual_identifier.py # Face recognition
|
|
│ ├── frontend/ # JavaScript and UI components
|
|
│ └── utils/ # Utility functions
|
|
│ └── tag_manager.py # Tag management
|
|
├── docs/ # Documentation and steering documents
|
|
│ ├── product.md # Product vision and goals
|
|
│ ├── structure.md # Project organization
|
|
│ ├── tech.md # Technical architecture
|
|
│ ├── api-standards.md # API design standards
|
|
│ ├── testing-standards.md # Testing guidelines
|
|
│ └── code-conventions.md # Coding standards
|
|
├── tests/ # Test files
|
|
│ ├── test_main.py # Main test suite
|
|
│ └── conftest.py # Test configuration
|
|
├── data/ # Database files and user data
|
|
├── config/ # Configuration files
|
|
│ ├── settings.py # Application settings
|
|
│ └── punimtag_config.json
|
|
├── scripts/ # Utility scripts
|
|
├── assets/ # Static assets
|
|
├── photos/ # User photo storage
|
|
└── main.py # Application entry point
|
|
```
|
|
|
|
## 🎯 Key Features
|
|
|
|
- **Automatic Face Recognition**: Identify and tag people in photos
|
|
- **Smart Organization**: Group photos by people, events, and locations
|
|
- **Duplicate Detection**: Find and manage duplicate photos automatically
|
|
- **Intuitive Interface**: Web-based GUI with progressive loading
|
|
- **Privacy-First**: Local processing, no cloud dependencies
|
|
|
|
## 📚 Documentation
|
|
|
|
### Steering Documents
|
|
|
|
- **[Product Vision](docs/product.md)**: Product goals, target users, and roadmap
|
|
- **[Project Structure](docs/structure.md)**: Architecture and organization principles
|
|
- **[Technical Architecture](docs/tech.md)**: Technology stack and implementation details
|
|
- **[API Standards](docs/api-standards.md)**: API design and development guidelines
|
|
- **[Testing Standards](docs/testing-standards.md)**: Testing strategy and best practices
|
|
- **[Code Conventions](docs/code-conventions.md)**: Coding standards and style guides
|
|
|
|
### Development Guidelines
|
|
|
|
1. **Follow the steering documents** for consistent development
|
|
2. **Use the organized structure** - place code in appropriate directories
|
|
3. **Write tests** following the testing standards
|
|
4. **Follow API standards** for all endpoints
|
|
5. **Adhere to code conventions** for maintainability
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Run the main test suite
|
|
python tests/test_main.py
|
|
|
|
# Run with pytest (if installed)
|
|
pytest tests/
|
|
```
|
|
|
|
## 🔧 Configuration
|
|
|
|
Configuration is centralized in `config/settings.py`:
|
|
|
|
- Database paths
|
|
- Face recognition settings
|
|
- File upload limits
|
|
- Thumbnail sizes
|
|
|
|
## 🚀 Deployment
|
|
|
|
### Development
|
|
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
### Production
|
|
|
|
```bash
|
|
# Use a WSGI server like Gunicorn
|
|
gunicorn -w 4 -b 0.0.0.0:5000 main:app
|
|
```
|
|
|
|
## 📦 Dependencies
|
|
|
|
- **Flask**: Web framework
|
|
- **SQLite**: Database
|
|
- **dlib**: Face recognition
|
|
- **Pillow**: Image processing
|
|
- **NumPy**: Numerical operations
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Read the steering documents in `docs/`
|
|
2. Follow the code conventions
|
|
3. Write tests for new features
|
|
4. Update documentation as needed
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License.
|
|
|
|
## 🆘 Support
|
|
|
|
For issues and questions:
|
|
|
|
1. Check the steering documents in `docs/`
|
|
2. Review existing tests in `tests/`
|
|
3. Check the API standards for endpoint usage
|