8000 GitHub - jubelAhmed/facial-contour-masking Β· GitHub
[go: up one dir, main page]

Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Facial Contour Masking API

A modern, enterprise-grade FastAPI application for processing facial images and generating SVG contour masks for specific facial regions.

πŸš€ Features

Core Functionality

  • Facial Image Processing: Accepts facial images with landmarks and segmentation maps
  • SVG Generation: Returns SVG contour masks for specific facial regions
  • Face Alignment: Handles autorotation and cropping of faces
  • Background Job Processing: Asynchronous image processing with job status tracking
  • Real-time Status Updates: Poll job status and retrieve results when ready

Enterprise Features

  • πŸ” JWT Authentication: Secure user authentication with access/refresh tokens
  • πŸ›‘οΈ Security Middleware: CORS, security headers, and request logging
  • ⚑ Rate Limiting: Redis-backed rate limiting with slowapi
  • πŸ“Š Monitoring: Prometheus metrics and Grafana dashboards
  • πŸ—„οΈ Database Management: SQLAlchemy ORM with Alembic migrations
  • πŸ’Ύ Perceptual Caching: Smart caching using image similarity hashing
  • 🎨 Rich Logging: Beautiful console output with structured logging

πŸ—οΈ Architecture

System Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ HTTP Client │────▢│ FastAPI       │────▢│ Background    β”‚
β”‚             │◀────│ API Endpoint  β”‚     β”‚ Job Worker    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚                      β”‚
                           β–Ό                      β–Ό
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚ Database      │◀────│ Image         β”‚
                    β”‚ (Job Queue)   β”‚     β”‚ Processor     β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β–²                      β”‚
                           β”‚                      β–Ό
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚ Perceptual    │◀────│ SVG Generator β”‚
                    β”‚ Hash Cache    β”‚     β”‚ & Output      β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Design Patterns

Clean Architecture

  • Routers: HTTP layer (controllers)
  • Services: Business logic layer
  • Repositories: Data access layer (DAO pattern)
  • Models: Data structures
  • Shared: Infrastructure layer

SOLID Principles

  • Single Responsibility: Each class has one purpose
  • Open/Closed: Open for extension, closed for modification
  • Liskov Substitution: Derived classes are substitutable
  • Interface Segregation: Small, focused interfaces
  • Dependency Inversion: Depend on abstractions, not concretions

Enterprise Patterns

  • Repository Pattern: Data access abstraction
  • Service Layer: Business logic encapsulation
  • Dependency Injection: Loose coupling
  • Factory Pattern: Object creation
  • Strategy Pattern: Algorithm selection

πŸ“ Project Structure

opnecv_image_processing/
β”œβ”€β”€ .venv/                    # uv virtual environment
β”œβ”€β”€ src/                      # Source code
β”‚   β”œβ”€β”€ auth/                 # Authentication module
β”‚   β”‚   β”œβ”€β”€ models.py         # User & token models
β”‚   β”‚   β”œβ”€β”€ schemas.py        # Pydantic schemas
β”‚   β”‚   β”œβ”€β”€ service.py        # Business logic
β”‚   β”‚   β”œβ”€β”€ repository.py     # Data access layer
β”‚   β”‚   β”œβ”€β”€ constants.py      # Enums & constants
β”‚   β”‚   β”œβ”€β”€ exceptions.py     # Custom exceptions
β”‚   β”‚   └── utils.py          # JWT & password utilities
β”‚   β”œβ”€β”€ facial/               # Facial processing module
β”‚   β”‚   β”œβ”€β”€ models.py         # Processing models
β”‚   β”‚   β”œβ”€β”€ schemas.py        # Request/response schemas
β”‚   β”‚   β”œβ”€β”€ service.py        # Processing logic
β”‚   β”‚   β”œβ”€β”€ repository.py     # Data access layer
β”‚   β”‚   β”œβ”€β”€ background_worker.py # Background job processing
β”‚   β”‚   β”œβ”€β”€ constants.py      # Enums & constants
β”‚   β”‚   β”œβ”€β”€ exceptions.py     # Custom exceptions
β”‚   β”‚   β”œβ”€β”€ generators/       # Output generators (SVG, PNG, JSON)
β”‚   β”‚   └── facial_processing/ # Core processing
β”‚   β”œβ”€β”€ shared/               # Shared infrastructure
β”‚   β”‚   β”œβ”€β”€ config.py         # Configuration management
β”‚   β”‚   β”œβ”€β”€ database.py       # Database connection
β”‚   β”‚   β”œβ”€β”€ models.py         # Base models
β”‚   β”‚   β”œβ”€β”€ exceptions.py     # Global exceptions
β”‚   β”‚   └── utils.py          # Common utilities
β”‚   β”œβ”€β”€ routers/              # HTTP layer
β”‚   β”‚   β”œβ”€β”€ auth.py           # Auth endpoints
β”‚   β”‚   └── facial.py         # Processing endpoints
β”‚   β”œβ”€β”€ internal/             # Internal operations
β”‚   β”‚   └── admin.py          # Admin endpoints
β”‚   β”œβ”€β”€ middleware/           # Custom middleware
β”‚   β”‚   β”œβ”€β”€ rate_limiting.py  # Rate limiting with slowapi
β”‚   β”‚   └── security.py       # Security headers
β”‚   β”œβ”€β”€ monitoring/           # Monitoring setup
β”‚   β”‚   └── prometheus.py     # Prometheus metrics
β”‚   β”œβ”€β”€ dependencies.py       # Centralized FastAPI dependencies
β”‚   └── main.py              # Application entry point
β”œβ”€β”€ pyproject.toml           # Modern Python project configuration
β”œβ”€β”€ alembic/                 # Database migrations
β”œβ”€β”€ docker/                  # Docker configurations
β”œβ”€β”€ .env.sample              # Environment configuration template
└── templates/               # Static files & dashboards

πŸš€ Quick Start

Prerequisites

  • Python 3.12+
  • uv (recommended) or pip
  • Docker & Docker Compose (optional)

Installation

  1. Clone the repository

    git clone <repository-url>
    cd opnecv_image_processing
  2. Set up virtual environment with uv

    # Install uv if not already installed
    pip install uv
    
    # Create virtual environment
    uv venv
    
    # Activate virtual environment
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  3. Set up environment configuration

    # Copy environment template
    cp .env.sample .env
    
    # Edit configuration (optional for development)
    nano .env
  4. Install dependencies

    # Install in development mode
    uv pip install -e ".[dev]"
  5. Run the application

    # Development mode (uses SQLite by default)
    uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
    
    # Or with fastapi CLI
    fastapi run src.main:app --reload
  6. Access the application

🐳 Docker Deployment

Using Docker Compose

# Start all services
docker-compose up --build

# Run in background
docker-compose up -d

Services

πŸ”§ Configuration

Environment Variables

Copy .env.sample to .env and configure your settings:

Application Settings

  • APP_DEBUG: Enable debug mode (default: false)
  • APP_APP_NAME: Application name (default: "Facial Contour Masking API")
  • APP_VERSION: Application version (default: "1.0.0")

Database Settings

  • DB_USE_DATABASE: Enable/disable database (default: true)
  • DB_HOST: Database host (default: postgres)
  • DB_PORT: Database port (default: 5432)
  • DB_USERNAME: Database username (default: postgres)
  • DB_PASSWORD: Database password (default: postgres)
  • DB_DATABASE: Database name (default: facial_api)

Authentication Settings

  • AUTH_SECRET_KEY: JWT secret key (change in production!)
  • AUTH_ACCESS_TOKEN_EXPIRE_MINUTES: Access token expiration (default: 60)
  • AUTH_REFRESH_TOKEN_EXPIRE_DAYS: Refresh token expiration (default: 30)
  • AUTH_ALGORITHM: JWT algorithm (default: HS256)

Rate Limiting Settings

  • RATE_LIMIT_ENABLED: Enable rate limiting (default: true)
  • RATE_LIMIT_REQUESTS_PER_HOUR: Requests per hour (default: 100)
  • RATE_LIMIT_WINDOW_SECONDS: Rate limit window (default: 3600)
  • RATE_LIMIT_BURST_LIMIT: Burst limit (default: 10)
  • RATE_LIMIT_REDIS_URL: Redis URL for rate limiting (optional)

Monitoring Settings

  • PROMETHEUS_ENABLED: Enable Prometheus metrics (default: true)
  • PROMETHEUS_PORT: Prometheus port (default: 9090)

Security Settings

  • CORS_ALLOW_ORIGINS: CORS allowed origins (default: *)
  • TRUSTED_HOSTS: Trusted hosts (default: *)

πŸ“š API Documentation

Authentication Endpoints

POST /auth/register

Register a new user

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "secure_password123"
}

POST /auth/login

Login and get tokens

{
  "username": "johndoe",
  "password": "secure_password123"
}

POST /auth/refresh

Refresh access token

{
  "refresh_token": "your_refresh_token"
}

Processing Endpoints

POST /api/v1/process

Submit facial image for background processing

{
  "image_data": "base64_encoded_image",
  "landmarks": [{"x": 0, "y": 0}, ...],
  "output_format": "svg",
  "style": "default"
}

Response:

{
  "job_id": "uuid",
  "status": "pending",
  "message": "Processing job created successfully"
}

GET /api/v1/status/{job_id}

Check background job status

{
  "job_id": "uuid",
  "status": "completed",
  "result": {
    "contours": [...],
    "style": "default",
    "regions": [...],
    "output_format": "svg",
    "processed_at": "2024-01-01T12:00:00Z"
  },
  "error": null,
  "created_at": "2024-01-01T12:00:00Z",
  "completed_at": "2024-01-01T12:00:05Z"
}

Job Status Values:

  • pending: Job queued for processing
  • processing: Currently being processed
  • completed: Successfully finished
  • failed: Processing failed

Background Job Processing

The API uses FastAPI's BackgroundTasks for asynchronous image processing:

  1. Submit Job: POST /api/v1/process returns immediately with job ID
  2. Background Processing: Image processing happens asynchronously
  3. Status Polling: GET /api/v1/status/{job_id} to check progress
  4. Result Retrieval: Download processed results when status is "completed"

Benefits:

  • Non-blocking API responses
  • Scalable concurrent processing
  • Smart caching prevents duplicate work
  • Real-time status updates

Admin Endpoints

GET /admin/users

List all users (superuser only)

[
  {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com",
    "is_active": true,
    "is_superuser": false
  }
]

πŸ—„οΈ Database Management

Using Alembic Migrations

# Create a new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1

Database Models

  • Users: User authentication and profiles
  • RefreshTokens: JWT refresh token management
  • ProcessingJobs: Background job status and results
  • PerceptualHash: Smart caching for processed images
  • ProcessingMetrics: Performance metrics

πŸ› οΈ Development

Adding Dependencies

# Install package
uv pip install package-name

# Add to pyproject.toml dependencies section
# Then reinstall to update
uv pip install -e ".[dev]"

Code Quality

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format and lint code (Ruff handles both)
ruff check src/ --fix
ruff format src/

# Type checking
mypy src/

πŸ§ͺ Testing

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Run specific test file
uv run pytest tests/test_auth.py

# Run with verbose output
uv run pytest -v

Test Structure

tests/
β”œβ”€β”€ conftest.py              # Test configuration
β”œβ”€β”€ test_main.py             # Main app tests
β”œβ”€β”€ test_auth.py             # Authentication tests
β”œβ”€β”€ test_facial.py           # Facial processing tests
β”œβ”€β”€ test_facial_generators.py # Generator tests
└── test_facial_service.py   # Service tests

πŸ”’ Security Features

  • JWT Authentication: Secure token-based authentication with refresh tokens
  • Password Hashing: Bcrypt password hashing with strength validation
  • Rate Limiting: Redis-backed rate limiting with slowapi
  • CORS Protection: Configurable CORS policies
  • Security Headers: XSS, CSRF, and content type protection
  • Request Size Limiting: Protection against large request attacks
  • Input Validation: Pydantic V2 schema validation
  • Dependency Injection: Secure dependency management

πŸ“Š Monitoring & Observability

Prometheus Metrics

  • API request counts and latency
  • Image processing time
  • Job status distribution
  • Authentication events
  • Rate limiting violations

Grafana Dashboards

  • Real-time API performance
  • Error rates and response times
  • User activity and authentication
  • System resource usage

πŸš€ Production Deployment

Environment Setup

  1. Copy .env.sample to .env and configure production values
  2. Set ENV=production in environment variables
  3. Use PostgreSQL for database (DB_USE_DATABASE=true)
  4. Configure Redis for rate limiting (RATE_LIMIT_REDIS_URL)
  5. Set secure JWT secret key (AUTH_SECRET_KEY)
  6. Configure CORS origins (CORS_ALLOW_ORIGINS)
  7. Set up proper logging and monitoring

Performance Optimization

  • Database: PostgreSQL with connection pooling
  • Background Jobs: Asynchronous image processing with FastAPI BackgroundTasks
  • Caching: Redis for rate limiting and perceptual hash caching
  • Async Processing: Non-blocking I/O operations
  • Monitoring: Prometheus metrics and Grafana dashboards
  • Rate Limiting: Distributed rate limiting with Redis
  • Security: Request size limiting and security headers

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

πŸ“„ License

This project is licensed under the MIT License.

πŸ†˜ Support

For support and questions:

  • Create an issue in the repository
  • Check the API documentation at /docs
  • Review the monitoring dashboards

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0