{"id":46538240,"url":"https://github.com/jamestrichardson/recognize","last_synced_at":"2026-03-07T00:14:40.200Z","repository":{"id":321128748,"uuid":"1084543623","full_name":"jamestrichardson/recognize","owner":"jamestrichardson","description":"An application that will detect object, faces and recognition of people within images and videos","archived":false,"fork":false,"pushed_at":"2025-10-27T22:57:57.000Z","size":79,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-28T00:25:06.813Z","etag":null,"topics":["docker","face-detection","face-recognition","facial-recognition","flask","object-detection","opencv","python","yolo"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamestrichardson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-27T20:28:26.000Z","updated_at":"2025-10-27T22:10:00.000Z","dependencies_parsed_at":"2025-10-28T00:25:10.394Z","dependency_job_id":null,"html_url":"https://github.com/jamestrichardson/recognize","commit_stats":null,"previous_names":["jamestrichardson/recognize"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jamestrichardson/recognize","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamestrichardson%2Frecognize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamestrichardson%2Frecognize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamestrichardson%2Frecognize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamestrichardson%2Frecognize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamestrichardson","download_url":"https://codeload.github.com/jamestrichardson/recognize/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamestrichardson%2Frecognize/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30204114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","face-detection","face-recognition","facial-recognition","flask","object-detection","opencv","python","yolo"],"created_at":"2026-03-07T00:14:40.064Z","updated_at":"2026-03-07T00:14:40.174Z","avatar_url":"https://github.com/jamestrichardson.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Recognize - Object and Facial Recognition Application\n\nA Flask-based web application for performing object detection and facial recognition on images and videos using computer vision techniques.\n\n## Features\n\n- **Face Detection**: Detect and locate faces in images and videos\n- **Object Recognition**: Identify and classify objects using YOLO models\n- **Video Processing**: Process video files frame-by-frame for comprehensive analysis\n- **REST API**: Well-documented API endpoints for integration\n- **Web Interface**: User-friendly web interface for file uploads and results viewing\n- **Scalable Architecture**: Separate worker containers for distributed processing (optional)\n- **Async Task Queue**: Handle high load with Celery and Redis\n- **Automated Releases**: Semantic versioning with Release Please\n- **Code Quality**: Pre-commit hooks with conventional commits enforcement\n\n## Documentation\n\n- 📖 [Scalable Architecture Guide](docs/SCALABLE_ARCHITECTURE.md) - Detailed architecture documentation\n- 🚀 [Quick Start Guide](docs/QUICKSTART_SCALABLE.md) - Get up and running quickly\n- 🔧 [Pre-commit Setup](docs/PRE_COMMIT_GUIDE.md) - Code quality automation\n- 📝 [Conventional Commits](docs/CONVENTIONAL_COMMITS.md) - Commit message standards\n- 🎯 [Release Process](docs/RELEASE_SETUP.md) - Automated release workflow\n- 🔒 [Docker Security](docs/DOCKER_SECURITY.md) - Container security best practices\n\n## Architecture Modes\n\n### 1. Simple Mode (Default)\n\n- Single container deployment\n- Synchronous processing\n- Good for: Development, low traffic, quick setup\n\n### 2. Scalable Mode (Production)\n\n- Multiple service containers (web, redis, face workers, object workers)\n- Asynchronous task processing with Celery\n- Independent scaling of face/object detection workers\n- Good for: Production, high traffic, compute-intensive workloads\n\n📖 **See [docs/SCALABLE_ARCHITECTURE.md](docs/SCALABLE_ARCHITECTURE.md) for detailed architecture guide**\n\n🚀 **See [docs/QUICKSTART_SCALABLE.md](docs/QUICKSTART_SCALABLE.md) for quick setup instructions**\n\n## Project Structure\n\n```text\nrecognize/\n├── app/\n│   ├── __init__.py          # Application factory\n│   ├── config.py            # Configuration settings\n│   ├── routes.py            # API and web routes\n│   ├── services/            # Recognition services\n│   │   ├── facial_recognition.py\n│   │   └── object_detection.py\n│   ├── utils/               # Utility modules\n│   │   ├── file_handler.py\n│   │   └── response_handler.py\n│   ├── static/              # CSS and JavaScript\n│   └── templates/           # HTML templates\n├── models/                  # Model files directory\n├── uploads/                 # Uploaded files directory\n├── tests/                   # Test suite\n├── requirements.txt         # Python dependencies\n├── .env.example            # Example environment variables\n├── Dockerfile              # Docker configuration\n├── docker-compose.yml      # Docker Compose setup\n└── run.py                  # Application entry point\n```\n\n## Installation\n\n### Prerequisites\n\n- Python 3.8 or higher\n- pip package manager\n\n### Setup\n\n1. Clone the repository:\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd recognize\n   ```\n\n2. Create a virtual environment:\n\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. Install dependencies:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. Copy the example environment file:\n\n   ```bash\n   cp .env.example .env\n   ```\n\n5. Edit `.env` and configure your settings (especially `SECRET_KEY` for production)\n\n### Model Files\n\nPlace the following model files in the `models/` directory:\n\n- **For Face Detection**: `haarcascade_frontalface_default.xml` (included with OpenCV)\n- **For Object Detection** (optional):\n  - `yolov3.weights` - Download from [YOLO website](https://pjreddie.com/darknet/yolo/)\n  - `yolov3.cfg` - Download from [YOLO repository](https://github.com/pjreddie/darknet/blob/master/cfg/yolov3.cfg)\n  - `coco.names` - Download from [YOLO repository](https://github.com/pjreddie/darknet/blob/master/data/coco.names)\n\n## Usage\n\n### Running Locally\n\n```bash\npython run.py\n```\n\nThe application will be available at `http://localhost:5000`\n\n### Using Docker\n\nBuild and run with Docker Compose:\n\n```bash\ndocker-compose up --build\n```\n\n### API Endpoints\n\n#### Health Check\n\n```text\nGET /api/health\n```\n\n#### Face Detection - Image\n\n```text\nPOST /api/detect/face/image\nContent-Type: multipart/form-data\nBody: file (image file)\n```\n\n#### Face Detection - Video\n\n```text\nPOST /api/detect/face/video\nContent-Type: multipart/form-data\nBody:\n  - file (video file)\n  - frame_skip (optional, default: 5)\n```\n\n#### Object Detection - Image\n\n```text\nPOST /api/detect/object/image\nContent-Type: multipart/form-data\nBody: file (image file)\n```\n\n#### Object Detection - Video\n\n```text\nPOST /api/detect/object/video\nContent-Type: multipart/form-data\nBody:\n  - file (video file)\n  - frame_skip (optional, default: 5)\n```\n\n## Configuration\n\nKey configuration options in `.env`:\n\n- `SECRET_KEY`: Flask secret key (required for production)\n- `DEBUG`: Enable/disable debug mode\n- `MAX_CONTENT_LENGTH`: Maximum file upload size (bytes)\n- `FACE_DETECTION_CONFIDENCE`: Confidence threshold for face detection (0-1)\n- `OBJECT_DETECTION_CONFIDENCE`: Confidence threshold for object detection (0-1)\n- `VIDEO_FRAME_SKIP`: Process every Nth frame in videos\n\n## Testing\n\nRun the test suite:\n\n```bash\npytest\n```\n\nRun with coverage:\n\n```bash\npytest --cov=app tests/\n```\n\n## Development\n\n### Pre-commit Hooks\n\nThis project uses pre-commit hooks to ensure code quality. The hooks run automatically before each commit and check:\n\n- **Code Formatting**: Black, isort\n- **Linting**: Flake8, pylint\n- **Type Checking**: mypy\n- **Security**: Bandit\n- **Documentation**: Docstring coverage\n- **Commit Messages**: Conventional Commits validation\n- **Files**: Trailing whitespace, YAML/JSON validation, merge conflicts\n\n#### Quick Setup\n\nRun the automated setup script:\n\n```bash\n./setup-dev.sh\n```\n\nOr manually install hooks:\n\n```bash\npip install pre-commit\nmake install-hooks  # Installs both pre-commit and commit-msg hooks\n```\n\n### Conventional Commits\n\nAll commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.\nThis enables automated versioning and changelog generation.\n\n#### Commit Format\n\n```text\n\u003ctype\u003e[optional scope]: \u003cdescription\u003e\n\n[optional body]\n[optional footer(s)]\n```\n\n#### Common Types\n\n- `feat:` - New feature (minor version bump)\n- `fix:` - Bug fix (patch version bump)\n- `docs:` - Documentation changes\n- `refactor:` - Code refactoring\n- `test:` - Test additions or modifications\n- `chore:` - Maintenance tasks\n\n#### Examples\n\n```bash\ngit commit -m \"feat: add video thumbnail generation\"\ngit commit -m \"fix(api): correct rate limiting logic\"\ngit commit -m \"docs: update deployment instructions\"\n```\n\nFor breaking changes:\n\n```bash\ngit commit -m \"feat!: change API response format\"\n```\n\n📖 **See [docs/CONVENTIONAL_COMMITS.md](docs/CONVENTIONAL_COMMITS.md) for detailed guide**\n\n#### Running Checks Manually\n\n```bash\n# Run all hooks on all files\nmake lint\n\n# Run specific hooks\nmake format          # Format code with black and isort\nmake type-check      # Run mypy type checking\nmake security-check  # Run bandit security scan\n\n# Auto-fix all issues\nmake format-fix\n```\n\n#### Using Makefile Commands\n\nThe project includes a comprehensive Makefile for common development tasks:\n\n```bash\n# Setup and installation\nmake install         # Install dependencies\nmake install-dev     # Install dev dependencies\nmake install-hooks   # Install pre-commit hooks\n\n# Code quality\nmake lint           # Run all linters\nmake format         # Check code formatting\nmake format-fix     # Fix formatting issues\nmake type-check     # Type checking with mypy\nmake security-check # Security scanning\n\n# Testing\nmake test           # Run tests\nmake test-cov       # Run tests with coverage\nmake test-watch     # Run tests in watch mode\n\n# Docker operations\nmake docker-build   # Build docker images\nmake docker-up      # Start containers (simple mode)\nmake docker-scale   # Start scalable architecture\nmake docker-down    # Stop containers\n\n# Cleanup\nmake clean          # Remove cache files\nmake clean-all      # Deep clean including venv\n```\n\n📖 **See [docs/PRE_COMMIT_GUIDE.md](docs/PRE_COMMIT_GUIDE.md) for detailed pre-commit documentation**\n\n### Code Style\n\nThis project follows Python best practices:\n\n- **Line length**: 100 characters\n- **Import order**: Standard library → Third-party → Local (enforced by isort)\n- **Formatting**: Black (opinionated formatter)\n- **Docstrings**: Google-style docstrings required for public functions\n\n### Adding New Features\n\n1. Create feature branch from main\n1. Install pre-commit hooks (`make install-hooks`)\n1. Implement changes with conventional commits\n1. Write tests (pytest)\n1. Ensure all checks pass (`make ci`)\n1. Submit pull request\n\n## Release Process\n\nThis project uses automated releases with [Release Please](https://github.com/googleapis/release-please).\n\n### How It Works\n\n1. **Commit with conventional commits**: All commits to `main` branch\n1. **Automatic PR creation**: Release Please analyzes commits and creates/updates a release PR\n1. **Version bump**: Determined by commit types (feat = minor, fix = patch, BREAKING CHANGE = major)\n1. **Changelog generation**: Automatically generated from commit messages\n1. **GitHub release**: Created when release PR is merged\n\n### Release Types\n\n- `fix:` commits → Patch release (0.0.X)\n- `feat:` commits → Minor release (0.X.0)\n- `BREAKING CHANGE:` or `!` → Major release (X.0.0)\n\n### Triggering a Release\n\nSimply merge the auto-generated \"chore(main): release X.X.X\" pull request. The release workflow will:\n\n- Create a GitHub release with auto-generated notes\n- Tag the release with version number\n- Update version in `app/version.py`\n- Maintain CHANGELOG.md\n\nNo manual version bumping or changelog editing required!\n\n## Deployment\n\n### Production Considerations\n\n1. Set `DEBUG=False` in production\n1. Use a strong `SECRET_KEY`\n1. Configure proper file upload limits\n1. Use a production WSGI server (gunicorn is included)\n1. Set up reverse proxy (nginx recommended)\n1. Enable HTTPS\n1. Configure logging and monitoring\n\n### Environment Variables\n\nEnsure all required environment variables are set in your production environment.\n\n## Troubleshooting\n\n### Models not loading\n\n- Verify model files are in the `models/` directory\n- Check file paths in `.env` configuration\n- Ensure proper file permissions\n\n### Large file uploads failing\n\n- Increase `MAX_CONTENT_LENGTH` in configuration\n- Check web server upload limits\n\n### Video processing slow\n\n- Increase `VIDEO_FRAME_SKIP` to process fewer frames\n- Consider using GPU-accelerated OpenCV\n\n## License\n\nSee LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor issues and questions, please open an issue on the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamestrichardson%2Frecognize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamestrichardson%2Frecognize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamestrichardson%2Frecognize/lists"}