Face Recognition System – User Guide

Complete documentation for end users.

What is This System?

This is a face recognition platform that allows you to:

• Store and manage face images
• Search for faces in your database
• Recognize faces automatically
• Track detection history
• Integrate face recognition into your applications via API

System Requirements

• Modern web browser (Chrome, Firefox, Safari, Edge)
• Internet connection
• Valid email address for registration

Registration and Login

1. Visit the Login Page

• Go to the system URL in your web browser
• Click "Register" or "Sign Up"

1. Fill in Your Details

• Email: Your email address (must be unique)
• Username: Choose a username
• Password: Create a strong password

1. Receive Your API Credentials

• After registration, you'll receive:
• API Key: A 32-character code (e.g., f1377d82a0e43f4a7682b1af582dea3e)
• API Secret: A 64-character code
• IMPORTANT: Save these credentials securely! You'll need them to use the API.

1. Automatic Subscription

• You're automatically enrolled in the Free Plan
• You can upgrade later if needed

Logging In

1. Go to the login page
2. Enter your email and password
3. Click "Login"
4. You'll be redirected to your dashboard

Important: Never expose API credentials publicly.

Dashboard Overview

When you log in, you'll see your main dashboard with:

Statistics Cards

• Total Faces: Total number of faces in your database
• Known Faces: Faces that have been identified/tagged
• Active Faces: Faces currently active for recognition
• Recent Detections: Detections made in the last 24 hours

Recent Faces Section

• Shows the 10 most recently added faces
• Click on any face to view details

Quick Actions

• Add Face: Upload a new face to your database
• Search Face: Search for a face in your database
• View All Images: Browse all stored faces
• View Detections: See detection history

Subscription Plans

Choose a plan based on your usage and scalability needs.

What is a “Request”?

A request is counted every time you:

• Search for a face
• Add a new face
• Recognize a face via API
• Update face information
• Delete a face

Understanding Rate Limits

• Hourly – Prevents burst overload (resets every hour)
• Daily – Controls daily usage (resets at midnight UTC)
• Monthly – Your main quota (resets every 30 days)

Checking Your Usage

Option 1: Via API

curl -X GET "http://164.52.200.227:8000/auth/rate-limit-status/" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example:

{
  "subscription_plan": "Free",
  "total_requests": 156,
  "limits": {
    "hourly": { "used": 12, "limit": 200, "remaining": 188 },
    "daily": { "used": 45, "limit": 200, "remaining": 155 },
    "monthly": { "used": 156, "limit": 2000, "remaining": 1844 }
  }
}

Option 2: Via Dashboard

• Open your dashboard
• Top-right shows: Requests: 156 / 2000 this month

Adding a Face

Via Web Interface

1. Go to Dashboard

• Click "Add Face" button

1. Upload Image

• Click "Choose File" or drag & drop
• Supported formats: JPG, PNG
• The image must contain a visible face

1. Enter Details

• Name: Person's name
• User ID: Unique identifier (optional)
• Active: Check if you want this face recognized immediately
• ✅ Active: Will be used for recognition
• ❌ Inactive: Stored but not used for matching

1. Save

• Click "Save Face"
• Face is processed and added to database
• You'll see a confirmation message

Via API

curl -X POST "http://164.52.200.227:8000/save/" \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_b64": "BASE64_ENCODED_IMAGE",
    "userId": "USER123",
    "user_name": "John Doe",
    "active": 1
  }'

Viewing All Faces

1. Navigate to Images Page

• Click "Images" in the menu

1. Filter Options

• All: Shows all faces
• Known: Shows identified faces
• Unknown: Shows unidentified faces
• Active: Shows only active faces

1. Search

• Use the search box to find by name or user ID
• Search is case-insensitive

1. Pagination

• 20 faces per page
• Use "Previous" and "Next" buttons to navigate

Viewing Face Details

1. Click on any face image
2. You'll see:

• Full-size image
• Name and User ID
• Status (Active/Inactive)
• Detection confidence score
• Date added
• Facial features data

Editing a Face

1. Open face details page
2. Click "Edit" button
3. Update information:

• Change name
• Change user ID
• Toggle active status

1. Click "Save Changes"

Deleting a Face

1. Open face details page
2. Click "Delete" button
3. Confirm deletion
4. Note: This action cannot be undone!

How Face Search Works

When you upload an image:

1. System detects the face in the image
2. Extracts facial features
3. Compares against all faces in database
4. Returns matches sorted by similarity score

Using the Search Feature

1. Go to Search Page

• Click "Search" in the menu

1. Upload Search Image

• Click "Choose File" or drag & drop
• Image should clearly show the face

1. Click "Search"

• System processes the image
• Results appear within seconds

1. View Results

• Shows top 10 matches
• Each result shows:
• Match image
• Name and User ID
• Similarity score (0-100%)
• Status (Active/Inactive)

Understanding Similarity Scores

• 90-100%: Excellent match (very likely same person)
• 80-89%: Good match (probably same person)
• 70-79%: Moderate match (possibly same person)
• 60-69%: Low confidence match (might be same person)
• Below 60%: Not a reliable match

Search Tips

✅ Good Practices:

• Use clear, well-lit photos
• Face should be facing forward
• Avoid sunglasses or masks
• High resolution images work best

❌ Avoid:

• Blurry or dark images
• Extreme angles
• Multiple faces in one image (system uses first detected face)
• Very small face images

What is Detection History?

Every time the system recognizes (or attempts to recognize) a face, it creates a detection record.

Accessing Detection History

1. Click "Detections" in the menu
2. You'll see a list of all detection events

Understanding Detection Records

Each record shows:

• Input Image: The image that was searched
• Matched Face: The face that was found (if any)
• Similarity Score: How confident the match is
• Name & User ID: Who was recognized
• Timestamp: When the detection occurred

Filtering Detections

Filter Options:

• All: Show all detections
• Recognized: Only successful matches
• Unknown: Only unrecognized faces
• High Confidence: Matches with similarity > 80%
• Low Confidence: Matches with similarity < 50%

Date Range:

• Select "From" and "To" dates
• Click "Filter" to apply

Search:

• Search by name or user ID

Exporting Detection History

(Feature coming soon)

• Export to CSV
• Export to PDF report
• Email scheduled reports

What is the API?

The API (Application Programming Interface) allows you to integrate face recognition into your own applications, websites, or systems.

Your API Credentials

You received these when you registered:

• API Key: f1377d82a0e43f4a7682b1af582dea3e (example)
• API Secret: f0a48b922f4550aa857e787a92583f7712edbc364dccb3c21c7d6d5cb3e0e8b9 (example)

Security:

• Never share these credentials
• Never commit them to public code repositories
• If compromised, contact support immediately

Getting an Authentication Token

For web/mobile apps, get a token first:

curl -X POST "http://164.52.200.227:8000/auth/login/" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'

Response:

{
  "message": "Login successful",
  "token": "abc123def456...",
  "api_key": "f1377d82...",
  "api_secret": "f0a48b92...",
  "user": {
    "email": "your@email.com",
    "username": "yourname",
    "subscription_id": "..."
  }
}

Common API Operations

1. Recognize a Face

curl -X POST "http://164.52.200.227:8000/recognize/" \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_b64": "BASE64_ENCODED_IMAGE"
  }'

Response:

{
  "status": true,
  "message": "Face recognized",
  "responsePacket": {
    "name": "John Doe",
    "userId": "USER123",
    "similarity": 0.95,
    "Active": 1
  }
}

2. Add a Face

curl -X POST "http://164.52.200.227:8000/save/" \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_b64": "BASE64_ENCODED_IMAGE",
    "userId": "USER123",
    "user_name": "John Doe",
    "active": 1
  }'

3. Check Your Usage

curl -X GET "http://164.52.200.227:8000/auth/rate-limit-status/" \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Get User Info

curl -X GET "http://164.52.200.227:8000/user/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Encoding Images to Base64

Python:

import base64

with open("image.jpg", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode('utf-8')

JavaScript:

const fs = require('fs');
const imageBuffer = fs.readFileSync('image.jpg');
const base64Image = imageBuffer.toString('base64');

Command Line (Linux/Mac):

base64 image.jpg

Why Rate Limits Exist

Rate limits prevent:

• System overload
• Abuse
• Excessive costs
• Performance degradation

What Happens When You Hit a Limit?

You'll receive an error:

{
  "detail": "Hourly API limit exceeded. Limit: 200/hour. Resets in 45 minutes."
}

HTTP Status Code: 429 (Too Many Requests)

Best Practices

1. Monitor Your Usage

• Check rate limit status regularly
• Set up alerts when approaching limits

1. Implement Retry Logic

   import time
   
   def api_call_with_retry():
       try:
           return make_api_call()
       except RateLimitError:
           time.sleep(3600)  # Wait 1 hour
           return make_api_call()

1. Batch Operations

• Process multiple faces in one session
• Avoid making calls one at a time

1. Cache Results

• Store recognition results locally
• Don't re-recognize the same face repeatedly

1. Upgrade if Needed

• If consistently hitting limits, consider upgrading

Troubleshooting

Common Issues

1. "Invalid API credentials"

Problem: API key or secret is incorrect

Solutions:

• Check for typos in your credentials
• Ensure no extra spaces
• Get new credentials by logging into dashboard
• Check if you're using the right credentials for the right account

2. "No face detected in the uploaded image"

Problem: System cannot find a face in the image

Solutions:

• Ensure face is clearly visible
• Check image quality (not too dark/blurry)
• Make sure face is not too small in the image
• Avoid extreme angles
• Remove sunglasses or face coverings

3. "Rate limit exceeded"

Problem: You've hit your hourly/daily/monthly limit

Solutions:

• Wait for the limit to reset
• Check when limit resets: /auth/rate-limit-status/
• Upgrade your subscription plan
• Optimize your application to make fewer calls

4. "Invalid token"

Problem: Your authentication token has expired or is invalid

Solutions:

• Log in again to get a new token
• Implement automatic token refresh in your application
• Check if token was copied correctly

5. Low recognition accuracy

Problem: System returns incorrect matches

Solutions:

• Add more images of each person (different angles/lighting)
• Use high-quality images
• Ensure database faces are properly tagged
• Check similarity threshold settings

6. Slow performance

Problem: Recognition takes too long

Solutions:

• Check your internet connection
• Reduce image size before uploading
• Use compressed image formats (JPEG instead of PNG)
• Contact support if system-wide slowdown

Getting Help

Need Assistance?

1. Check Documentation: Review this guide thoroughly
2. Check API Status: Visit status page for system outages
3. Contact Support:

• Email: support@yoursystem.com
• Include:
• Your username/email
• Description of the problem
• Steps to reproduce
• Screenshots if applicable
• Error messages

Appendix

API Endpoints Quick Reference

| Endpoint | Method | Purpose | Auth Required | |----------|--------|---------|---------------| | /auth/register/ | POST | Create account | No | | /auth/login/ | POST | Get token | No | | /auth/rate-limit-status/ | GET | Check usage | Token | | /user/ | GET | Get user info | Token | | /save/ | POST | Add face | API Key | | /recognize/ | POST | Recognize face | API Key | | /remove/ | DELETE | Delete face | API Key | | /search-face/ | POST | Search for face | Token |

HTTP Status Codes

• 200: Success
• 400: Bad request (check your data)
• 401: Unauthorized (check credentials)
• 404: Not found
• 422: Validation error (check required fields)
• 429: Rate limit exceeded
• 500: Server error (contact support)

Glossary

• Base64: A way to encode binary image data as text
• Similarity Score: Number between 0-1 indicating how similar two faces are
• Active Face: A face that's currently used for recognition
• Known Face: A face that has been identified/tagged
• Detection: An instance of the system trying to recognize a face
• Feature Vector: Mathematical representation of a face used for comparison