You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
288 lines
10 KiB
288 lines
10 KiB
# Face Recognition Service - Sequence Diagrams
|
|
|
|
## 1. Face Registration Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant GradioUI as Gradio Interface
|
|
participant RegisterUC as RegisterFaceUseCase
|
|
participant UserRepo as MongoDBUserRepository
|
|
participant FaceService as FaceRecognitionService
|
|
participant Detector as RetinaFaceDetector
|
|
participant Recognizer as SFaceRecognizer
|
|
participant FaceRepo as MongoDBFaceRepository
|
|
participant VectorStore as ChromaDBVectorStore
|
|
participant FileStorage as FileSystemStorage
|
|
participant MongoDB as MongoDB Database
|
|
participant ChromaDB as ChromaDB Vector DB
|
|
|
|
User->>GradioUI: Upload images + username
|
|
GradioUI->>RegisterUC: execute(username, images)
|
|
|
|
RegisterUC->>UserRepo: get_user_by_name(username)
|
|
UserRepo->>MongoDB: Query user by name
|
|
MongoDB-->>UserRepo: User data or null
|
|
UserRepo-->>RegisterUC: User entity or null
|
|
|
|
alt User doesn't exist
|
|
RegisterUC->>UserRepo: save(new_user)
|
|
UserRepo->>MongoDB: Insert new user
|
|
MongoDB-->>UserRepo: User ID
|
|
UserRepo-->>RegisterUC: User ID
|
|
end
|
|
|
|
loop For each image
|
|
RegisterUC->>FaceService: register_face(user_id, image)
|
|
|
|
FaceService->>Detector: detect_faces(image)
|
|
Detector-->>FaceService: List of detected faces
|
|
|
|
alt No faces detected
|
|
FaceService-->>RegisterUC: null
|
|
else Face detected
|
|
FaceService->>Detector: calculate_quality_score(best_face)
|
|
Detector-->>FaceService: Quality score
|
|
|
|
alt Quality too low
|
|
FaceService-->>RegisterUC: null
|
|
else Quality acceptable
|
|
FaceService->>Detector: align_face(image, landmarks)
|
|
Detector-->>FaceService: Aligned face image
|
|
|
|
FaceService->>Recognizer: extract_embedding(aligned_face)
|
|
Recognizer-->>FaceService: Face embedding
|
|
|
|
FaceService->>FileStorage: save_image(aligned_face, user_id)
|
|
FileStorage-->>FaceService: Image path
|
|
|
|
FaceService->>FaceRepo: save(face_entity)
|
|
FaceRepo->>MongoDB: Insert face record
|
|
MongoDB-->>FaceRepo: Success
|
|
FaceRepo-->>FaceService: Success
|
|
|
|
FaceService->>VectorStore: add(face_id, embedding, metadata)
|
|
VectorStore->>ChromaDB: Store embedding vector
|
|
ChromaDB-->>VectorStore: Success
|
|
VectorStore-->>FaceService: Success
|
|
|
|
FaceService-->>RegisterUC: Face ID
|
|
end
|
|
end
|
|
end
|
|
|
|
RegisterUC->>FaceService: update_user_mean_embedding(user_id)
|
|
FaceService->>FaceRepo: get_by_user_id(user_id)
|
|
FaceRepo->>MongoDB: Query faces by user_id
|
|
MongoDB-->>FaceRepo: Face records
|
|
FaceRepo-->>FaceService: Face entities
|
|
FaceService-->>RegisterUC: Mean embedding
|
|
|
|
RegisterUC->>UserRepo: update_user(user)
|
|
UserRepo->>MongoDB: Update user record
|
|
MongoDB-->>UserRepo: Success
|
|
UserRepo-->>RegisterUC: Success
|
|
|
|
RegisterUC-->>GradioUI: Success message
|
|
GradioUI-->>User: Registration result
|
|
```
|
|
|
|
## 2. Face Verification Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant GradioUI as Gradio Interface
|
|
participant VerifyUC as VerifyFaceUseCase
|
|
participant UserRepo as MongoDBUserRepository
|
|
participant FaceService as FaceRecognitionService
|
|
participant Detector as RetinaFaceDetector
|
|
participant Recognizer as SFaceRecognizer
|
|
participant FaceRepo as MongoDBFaceRepository
|
|
participant MongoDB as MongoDB Database
|
|
|
|
User->>GradioUI: Upload image + username
|
|
GradioUI->>VerifyUC: execute(username, image)
|
|
|
|
VerifyUC->>UserRepo: get_user_by_name(username)
|
|
UserRepo->>MongoDB: Query user by name
|
|
MongoDB-->>UserRepo: User data or null
|
|
UserRepo-->>VerifyUC: User entity or null
|
|
|
|
alt User not found
|
|
VerifyUC-->>GradioUI: VerificationResult(false, 0.0)
|
|
else User found
|
|
VerifyUC->>FaceService: verify_face(user_id, image)
|
|
|
|
FaceService->>Detector: detect_faces(image)
|
|
Detector-->>FaceService: List of detected faces
|
|
|
|
alt No faces detected
|
|
FaceService-->>VerifyUC: (false, 0.0)
|
|
else Face detected
|
|
FaceService->>Detector: align_face(image, landmarks)
|
|
Detector-->>FaceService: Aligned face image
|
|
|
|
FaceService->>Recognizer: extract_embedding(aligned_face)
|
|
Recognizer-->>FaceService: Query embedding
|
|
|
|
FaceService->>FaceRepo: get_by_user_id(user_id)
|
|
FaceRepo->>MongoDB: Query registered faces
|
|
MongoDB-->>FaceRepo: Face records
|
|
FaceRepo-->>FaceService: User's face entities
|
|
|
|
alt No registered faces
|
|
FaceService-->>VerifyUC: (false, 0.0)
|
|
else Compare with registered faces
|
|
loop For each registered face
|
|
FaceService->>Recognizer: calculate_similarity(query_embedding, face_embedding)
|
|
Recognizer-->>FaceService: Similarity score
|
|
end
|
|
|
|
FaceService-->>VerifyUC: (is_verified, max_similarity)
|
|
end
|
|
end
|
|
|
|
VerifyUC-->>GradioUI: VerificationResult
|
|
end
|
|
|
|
GradioUI-->>User: Verification result
|
|
```
|
|
|
|
## 3. Face Identification Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant GradioUI as Gradio Interface
|
|
participant IdentifyUC as IdentifyFaceUseCase
|
|
participant UserRepo as MongoDBUserRepository
|
|
participant FaceService as FaceRecognitionService
|
|
participant Detector as RetinaFaceDetector
|
|
participant Recognizer as SFaceRecognizer
|
|
participant VectorStore as ChromaDBVectorStore
|
|
participant ChromaDB as ChromaDB Vector DB
|
|
participant MongoDB as MongoDB Database
|
|
|
|
User->>GradioUI: Upload image
|
|
GradioUI->>IdentifyUC: execute(image)
|
|
|
|
IdentifyUC->>FaceService: identify_face(image)
|
|
|
|
FaceService->>Detector: detect_faces(image)
|
|
Detector-->>FaceService: List of detected faces
|
|
|
|
alt No faces detected
|
|
FaceService-->>IdentifyUC: (null, 0.0, [])
|
|
else Face detected
|
|
FaceService->>Detector: align_face(image, landmarks)
|
|
Detector-->>FaceService: Aligned face image
|
|
|
|
FaceService->>Recognizer: extract_embedding(aligned_face)
|
|
Recognizer-->>FaceService: Query embedding
|
|
|
|
FaceService->>VectorStore: search_similar(query_embedding, top_k=10)
|
|
VectorStore->>ChromaDB: Vector similarity search
|
|
ChromaDB-->>VectorStore: Similar face vectors
|
|
VectorStore-->>FaceService: Similar faces with metadata
|
|
|
|
alt No similar faces above threshold
|
|
FaceService-->>IdentifyUC: (null, 0.0, [])
|
|
else Similar faces found
|
|
note over FaceService: Group by user_id and calculate best scores
|
|
FaceService-->>IdentifyUC: (best_user_id, confidence, candidates)
|
|
end
|
|
end
|
|
|
|
loop For each candidate user_id
|
|
IdentifyUC->>UserRepo: get_by_id(user_id)
|
|
UserRepo->>MongoDB: Query user by ID
|
|
MongoDB-->>UserRepo: User data
|
|
UserRepo-->>IdentifyUC: User entity
|
|
end
|
|
|
|
alt User identified
|
|
IdentifyUC->>UserRepo: get_by_id(best_user_id)
|
|
UserRepo->>MongoDB: Query identified user
|
|
MongoDB-->>UserRepo: User data
|
|
UserRepo-->>IdentifyUC: User entity
|
|
end
|
|
|
|
IdentifyUC-->>GradioUI: IdentificationResult
|
|
GradioUI-->>User: Identification result
|
|
```
|
|
|
|
## 4. System Initialization Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Main as main.py
|
|
participant Config as Settings
|
|
participant MongoDB as MongoDBFaceRepository
|
|
participant ChromaDB as ChromaDBVectorStore
|
|
participant FileStorage as FileSystemStorage
|
|
participant Detector as RetinaFaceDetector
|
|
participant Recognizer as SFaceRecognizer
|
|
participant FaceService as FaceRecognitionService
|
|
participant UseCases as Use Cases
|
|
participant GradioApp as Gradio Interface
|
|
|
|
Main->>Config: Load configuration
|
|
Config-->>Main: Settings object
|
|
|
|
Main->>MongoDB: Initialize with MongoDB URL
|
|
MongoDB-->>Main: Repository instance
|
|
|
|
Main->>ChromaDB: Initialize with Chroma host/port
|
|
ChromaDB-->>Main: Vector store instance
|
|
|
|
Main->>FileStorage: Initialize with upload directory
|
|
FileStorage-->>Main: File storage instance
|
|
|
|
Main->>Detector: Initialize RetinaFace
|
|
note over Detector: Load ONNX models, prepare ctx
|
|
Detector-->>Main: Detector instance
|
|
|
|
Main->>Recognizer: Initialize SFace
|
|
note over Recognizer: Download/load SFace ONNX model
|
|
Recognizer-->>Main: Recognizer instance
|
|
|
|
Main->>FaceService: Initialize with dependencies
|
|
FaceService-->>Main: Service instance
|
|
|
|
Main->>UseCases: Initialize use cases with service
|
|
UseCases-->>Main: Use case instances
|
|
|
|
Main->>GradioApp: create_gradio_interface(use_cases)
|
|
GradioApp-->>Main: Gradio app instance
|
|
|
|
Main->>GradioApp: launch(server_name, server_port)
|
|
note over GradioApp: Start web server on port 7860
|
|
GradioApp-->>Main: Server running
|
|
```
|
|
|
|
## Flow Descriptions
|
|
|
|
### Registration Flow
|
|
1. User uploads multiple images with username
|
|
2. System checks if user exists, creates if needed
|
|
3. For each image: detects faces, validates quality, extracts embeddings
|
|
4. Stores face metadata in MongoDB, embeddings in ChromaDB, images in filesystem
|
|
5. Updates user with mean embedding for faster verification
|
|
|
|
### Verification Flow (1:1)
|
|
1. User provides image and username to verify against
|
|
2. System detects face in query image and extracts embedding
|
|
3. Retrieves all registered faces for the specified user
|
|
4. Compares query embedding with user's registered face embeddings
|
|
5. Returns verification result based on similarity threshold
|
|
|
|
### Identification Flow (1:N)
|
|
1. User provides image without specifying identity
|
|
2. System detects face and extracts embedding
|
|
3. Performs vector similarity search across all registered faces
|
|
4. Groups results by user and calculates confidence scores
|
|
5. Returns best match if confidence exceeds threshold
|
|
|
|
### Initialization Flow
|
|
System startup involves initializing all dependencies in correct order, loading ML models, and starting the web interface. |