Face Detection and Cropping API

This project is a FastAPI-based API that accepts an image upload, detects a face using MediaPipe, crops the detected face, and returns the cropped face image in Base64 format.

Installation

Clone this repository:

git clone https://github.com/Samran-Elahi/facecrope-api.git
cd facecrope-api

Install Docker Desktop on Windows

If you haven't installed Docker Desktop on your Windows machine, follow these steps:

1. Download Docker Desktop: Visit the official Docker Desktop for Windows page and download the installer.
2. Install Docker: Run the installer and follow the on-screen instructions.
3. Start Docker: After installation, launch Docker Desktop from the Start menu. Ensure Docker is running (look for the Docker icon in your system tray).

Run Using Docker

1. Build the Docker Image:

Once Docker Desktop is installed and running, you can proceed with building the Docker image for this project. Open PowerShell or Command Prompt in the project directory and run the following command:

docker build -t face-detection-api .

This command will use the Dockerfile in the repository to build the Docker image and name it face-detection-api.

2. Run the Docker Container:

After the image is built, you can run the Docker container with this command:

docker run -d -p 8000:8000 face-detection-api

3. Check Running Containers:

To verify that your container is running, use the following command:

docker ps

This will list all the running containers. You should see the face-detection-api container in the list.

4. Stop the Docker Container:

When you're done, you can stop the container with the following command:

docker stop <container_id>

Replace <container_id> with the actual container ID (you can find it using docker ps).

Usage

Start the FastAPI server manually (if not using Docker):

If you prefer not to use Docker, you can manually start the FastAPI server on your machine using Uvicorn:

uvicorn face_detection:app --host 0.0.0.0 --port 8000 --reload

This will start the server locally at http://127.0.0.1:8000.

Upload an Image Using the /upload_image/ Endpoint:

• Method: POST
• URL: http://127.0.0.1:8000/upload_image/
• Form Data:
  • file: Upload an image file

Sample CURL Request:

curl -X 'POST' \
  'http://127.0.0.1:8000/upload_image/' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@sample_image.jpg'

Response:

If a face is detected, the API will return the cropped face image encoded in Base64 format:

{
  "cropped_face": "<base64_encoded_string>"
}

If no face is detected, the response will be:

{
  "error": "No face detected"
}

Folder Structure

project-folder/
│── face_detection.py           # FastAPI application
│── Dockerfile                  # Docker configuration
│── README.md                   # Documentation file

Dependencies

• FastAPI
• Uvicorn
• OpenCV
• NumPy
• MediaPipe
• Docker

API Endpoints

1. Upload Image and Detect Face

• Endpoint: /upload_image/
• Method: POST
• Request Parameters:
  • file: Image file
• Response:
  • Base64-encoded cropped face image if detected
  • JSON response if no face is found