Introduction :

YOLOv3, short for “You Only Look Once version 3” , stands out as a powerful and efficient object detection algorithm, capable of identifying objects in images and videos swiftly and accurately. Leveraging the capabilities of YOLOv3 within a FastAPI framework opens up new possibilities for creating seamless and responsive object detection applications.

If you’re eager to harness the potential of YOLOv3 and FastAPI to deploy your own object detection solution, you’re in the right place!

In this comprehensive guide, we’ll take you through a step-by-step journey, breaking down the process of setting up and deploying YOLOv3 object detection using the FastAPI framework and offer insights into best practices that will enable you to create a robust and efficient object detection API.

So, let’s dive in and unlock the potential of YOLOv3 and FastAPI !

P.S : This tutorial offers an in-depth exploration of the subject matter, which may result in a comprehensive and potentially lengthy read. However, for those seeking a quicker glance at the code, you have the option to directly access the GitHub repository for a concise overview.

Prerequisites and Installation Setup

This tutorial assumes you have a foundational understanding of Python programming, object-oriented concepts, a basic grasp of OpenCV principles and basic understanding of Neural Networks.

For this tutorial, I opted for the PyCharm IDE due to its advantageous features. However, feel free to choose the IDE that aligns best with your preferences and familiarity.

I employed Python version 3.11.4 for this tutorial; nonetheless, other versions will suffice.

Libraries you need to install :

pip install numpy
pip install opencv-python
pip install fastapi
pip install uvicorn
pip install pydantic

Download YOLOv3 Weights and COCO labels

Download and place these files in your working directory:

• yolov3.cfg : Yolov3 config file that contains various hyperparameters and settings that define the architecture and behavior of the YOLOv3 model.
• yolov3.weights : file that contains the pre-trained weights of the YOLOv3 model.
• coco.names : a text file that contains the list of class names corresponding to the objects that the YOLOv3 model is trained to detect using the COCO (Common Objects in Context) dataset.

Implementing YOLOv3 Object Detection with OpenCV

In this section, we will discuss how to implement YOLOv3 object detection using the versatile capabilities of the OpenCV library and OOP concepts.

Why opt for an object-oriented approach, you might wonder, when a procedural approach could suffice? The answer lies in the elegance and efficiency of managing complexity. By structuring the code within a class, we unlock the ability to organize functionalities, maintain clear boundaries, and enhance reusability.

Let’s now delve into the inner workings of this module and discover how it brings YOLOv3 to life in a structured and organized manner.

Let’s start by creating a new python file named Yolov3_Detector.py . This file will be the module containing the Detector class, designed to streamline and configure the object detection process.

Let’s begin with some imports :

import cv2
import matplotlib.pyplot as plt 

• Detector class definition and constructor method :

class Detector:
    """
    Class for performing object detection using YOLOv3 model.
    """

    def __init__(self, config_path='./yolov3.cfg', weights_path='./yolov3.weights',
                 coco_names_path='./coco.names', score_threshold=0.5, NMS_threshold=0.5):
        """
        Initializes the Detector instance.

        Parameters:
            config_path (str): Path to YOLO model configuration file.
            weights_path (str): Path to YOLO model weights file.
            coco_names_path (str): Path to COCO class names file.
            score_threshold (float): Detection score threshold.
            NMS_threshold (float): Non-Maximum Suppression threshold.
        """
        self.load_model(config_path, weights_path)
        self.load_coco_labels(coco_names_path)
        self.set_detection_params(score_threshold, NMS_threshold)

This constructor method creates an instance of the `Detector` class, which is designed for object detection using the YOLOv3 model while allowing customization of various parameters that affect the behavior of the object detection process.

How it works:

During initialization, this constructor method loads the YOLO model configuration and weights using the specified paths, and it loads the COCO class names for label mapping. It also sets the detection parameters for later use in the object detection process. After successful initialization, the instance can be used to perform object detection.

This method internally uses several other methods, which are explained in the sections below.

Parameters:

• config_path (str, optional): The path to the YOLO model configuration file. Default is ./yolov3.cfg
• weights_path(str, optional): The path to the YOLO model weights file. Default is ./yolov3.weights.
• coco_names_path(str, optional): The path to the COCO class names file. Default is ./coco.names.
• score_threshold(float, optional): The threshold for detection scores. Objects with scores lower than this value will be filtered out. Default threshold is 0.5.
• NMS_threshold(float, optional): The Non-Maximum Suppression (NMS) threshold. It controls the suppression of overlapping bounding boxes during post-processing. Default is 0.5.

load_model method :

def load_model(self, config_path, weights_path):
        """
        Loads the YOLO model using provided configuration and weights paths.

        Parameters:
            config_path (str): Path to YOLO model configuration file.
            weights_path (str): Path to YOLO model weights file.
        """
        net = cv2.dnn.readNet(config_path, weights_path)
        self.net = net
        print(f'* Model config loaded from {config_path}\n* Model weights loaded from {weights_path}')

The load_model method, used internally by the constructor, is responsible for loading the YOLO model using the provided configuration and weights paths.

It uses OpenCV's cv2.dnn.readNet function, assigns the loaded model to the instance variable self.net, and prints a message confirming the successful loading of the model's configuration and weights.

• load_coco_labels method :

    def load_coco_labels(self, coco_names_path):
        """
        Loads COCO class labels from the provided file.

        Parameters:
            coco_names_path (str): Path to COCO class names file.
        """
        labels = []
        with open(coco_names_path, 'rt') as coco_file:
            labels = coco_file.read().rstrip('\n').rsplit('\n')
        self.labels = labels
        print(f'* COCO labels loaded from {coco_names_path}')

The load_coco_labels method, used internally by the constructor, loads COCO class labels from the provided file, stores them in the instance variable self.labels, and prints a message to confirm the successful loading of the labels.

• preprocess_img method:

    def preprocess_img(self, img, size=(320, 320)):
        """
        Preprocesses the input image using OpenCV's blobFromImage.

        Parameters:
            img (np.ndarray): Input image.
            size (tuple): Desired image size after preprocessing.

        Returns:
            np.ndarray: Preprocessed image blob.
        """
        self.resize = size
        blob = cv2.dnn.blobFromImage(img, 1 / 255, size, [0, 0, 0], 1, crop=False)
        return blob

the preprocess_img method preprocesses an input image using OpenCV's blobFromImage function.

It resizes the image to the desired size specified in the size parameter, and it returns the preprocessed image blob suitable for input to the YOLOv3 model. The desired image size is also stored in the instance variable self.resize.

• set_detection_params method :

    def set_detection_params(self, score_threshold, NMS_threshold):
        """
        Sets detection parameters.

        Parameters:
            score_threshold (float): Detection score threshold.
            NMS_threshold (float): Non-Maximum Suppression threshold.
        """
        self.score_threshold = score_threshold
        self.NMS_threshold = NMS_threshold

The set_detection_params method ,used internally by the constructor, sets the detection parameters of the Detector instance.

It assigns the provided values for the detection score threshold and the Non-Maximum Suppression threshold to the corresponding instance variables (self.score_threshold and self.NMS_threshold)

• run_detection_on_img method:

The run_detection_on_img method is responsible for running object detection on an input image using the YOLOv3 model and returning the results in the form of a list of dictionaries. The dictionaries contain information about the detected objects, including their labels, confidence scores, and bounding box coordinates.

Let’s break it down :

First we start by pre-processing the input image and set the blob (the pre-processed image) as the input of the neural network model.

def run_detection_on_img(self, img):
    """
    Runs object detection on the provided image.

    Parameters:
        img (np.ndarray): Input image.

    Returns:
        list: List of dictionaries containing detection results.
    """
    # Preprocess the input image using the previously defined 'preprocess_img' method
    blob = self.preprocess_img(img)
    self.net.setInput(blob)

Then we perform a forward pass of the blob (pre-processed image) through the neural network model.

    # Perform forward pass through the DNN model
    layers_names = self.net.getLayerNames()
    output_layers_idx = self.net.getUnconnectedOutLayers()[0] - 1
    output_names = [(layers_names[idx - 1]) for idx in self.net.getUnconnectedOutLayers()]
    outputs = self.net.forward(output_names)

1. The method getLayerNames() retrieves the names of all the layers in the neural network model (self.net).
2. getUnconnectedOutLayers() returns the indices of the layers that are not connected to any subsequent layers. Since these indices are typically one-based, subtracting 1 gives us the zero-based index that can be used to access the layers. These unconnected layers are typically the output layers of the model. Why multiple output layers ? The backbone architecture (often based on Darknet-53) for the YOLOv3 model has multiple output layers in order to be able to detect objects at different scales.
3. Then we map the obtained indices of unconnected output layers to their corresponding names using the layers_names list.
4. Finally, we perform a forward pass through the neural network model (self.net) using the specified output_names list. It returns the outputs of the layers specified in output_names .

Now that we have our outputs let’s proceed to decoding them into useful information.

# Get the shape of the input image
        hT, wT, cT = img.shape

        # Create empty lists to store the bounding boxes, class IDs, and confidence scores for detected objects
        bbox = []
        class_ids = []
        confs = []

        # Loop over each output of the DNN model after the forward pass
        for output in outputs:
            # Loop over each detection in the output
            for det in output:
                # Extract the class ID, confidence score, and bounding box coordinates from the detection
                scores = det[5:]
                class_id = np.argmax(scores)
                confidence = scores[class_id]
                if confidence > self.score_threshold:
                    w, h = int(det[2] * wT), int(det[3] * hT)
                    x, y = int((det[0] * wT) - w / 2), int((det[1] * hT) - h / 2)
                    bbox.append([x, y, w, h])
                    class_ids.append(class_id)
                    confs.append(float(confidence))

• we start by iterating through the outputs of the YOLOv3 model and process each detected object.
• For each output and detection, we extract the confidence scores (scores), determine the class with the highest confidence (class_id), and check if the confidence is above the specified threshold.
• If the confidence is sufficient, it calculates the bounding box coordinates based on the detected object's information and image dimensions. These coordinates and associated information are added to the respective lists (bbox, class_ids, and confs).

  # Perform non-maximum suppression to eliminate overlapping bounding boxes
  indices = cv2.dnn.NMSBoxes(bbox, confs, self.score_threshold, self.NMS_threshold)

• Here, non-maximum suppression (NMS) is applied to the list of bounding boxes (bbox) and associated confidence scores (confs) to eliminate overlapping and redundant detections. The cv2.dnn.NMSBoxes function returns indices of the boxes that survive the NMS process. These indices correspond to the selected, non-overlapping detections.

 results_list = []
        # Loop over each index in the indices list
        for i in indices:
            result_dict = {}
            # Get the bounding box coordinates, class label, and confidence score for the current index
            box = bbox[i]
            class_id = class_ids[i]
            conf = int(confs[i] * 100)
            # Create a dictionary to store each detection of the detection results
            result_dict['label'] = self.labels[class_id]
            result_dict['confidence'] = str(conf) +'%'
            result_dict['bbox_xywh'] = box

            results_list.append(result_dict)

        # return the list of detections
        return results_list

finally the run_detection_on_img organizes the filtered detection information into a list of dictionaries results_list, Each dictionary provides information about the detected object’s label, confidence level, and bounding box coordinates, making it easy to access and analyze the results of the object detection process.

Model Deployment with FastAPI

In this section, we’ll explore how to seamlessly transform your trained YOLOv3 object detection model into a dynamic and accessible API using FastAPI.

First create a new python script named main.py

Import libraries and modules :

from fastapi import FastAPI, File, UploadFile
import uvicorn
from pydantic import BaseModel

from collections import Counter
import numpy as np
from io import BytesIO
import cv2

from Yolov3_Detector import Detector

Let’s define a function that reads a binary image file and transform it into a numpy.ndarray.

def read_image(file) -> np.ndarray:
    """Reads and decodes an image from an uploaded file."""
    # Create a BytesIO stream from the uploaded file
    image_stream = BytesIO(file)

    # Move the stream's position to the beginning
    image_stream.seek(0)

    # Read the bytes from the stream and decode them using OpenCV
    # This will decode the image data into a NumPy array
    image = cv2.imdecode(np.frombuffer(image_stream.read(), np.uint8), cv2.IMREAD_COLOR)

    # Return the decoded image as a NumPy array
    return image

the read_image function is useful for processing image uploads in a FastAPI application . It takes an uploaded image file, creates a stream from the file's binary data, decodes the image data using OpenCV, and returns the decoded image as a NumPy array.

class DetectionResults(BaseModel):
    """Model class to represent the results of object detection."""
    filename: str = None
    results_str: str = 'No detections'
    results_list: list = None

class DetectionParams(BaseModel):
    """Model class to represent detection parameters."""
    score_threshold: float = 0.5
    NMS_threshold: float = 0.5

These two model classes (DetectionResults and DetectionParams) are used to define the structure and default values for the results of object detection and the parameters used for the detection process. They both inherit from the BaseModelclass provided by pydanticwhich makes it easier to validate, serialize, and deserialize data related to object detection within the FastAPI application.

Create a FastAPI and Detector instances:

# Create a FastAPI and Detector instances
app = FastAPI()
detector = Detector()

Now let’s actually use FastAPI and create an endpoint that performs object detection on an uploaded image.:

@app.post("/detection/")
async def detect_on_img(file: UploadFile = File(...)):
    """Endpoint to perform object detection on an uploaded image."""

    # Create an instance of DetectionResults to store the detection results
    results = DetectionResults()

    # Read the uploaded image and decode it using OpenCV
    img = read_image(await file.read())

    # Perform object detection using the detector instance
    results.results_list = detector.run_detection_on_img(img)

    # Store the filename of the uploaded image in the results
    results.filename = file.filename

    # If objects are detected in the image, update the results string
    if len(results.results_list):
        detected_labels_counter = Counter([detected_object['label'] for detected_object in results.results_list])
        str2 = ", ".join(f"{value} x {key}" for key, value in detected_labels_counter.items())
        results.results_str = f'Found {len(results.results_list)} objects: ' + str2

    # Return the DetectionResults instance containing the detection results
    return results

Explanation of each step:

1. @app.post(“/detection/”)
   This is a FastAPI decorator that defines a POST endpoint for the URL path `/detection/`. The endpoint will be used to handle HTTP POST requests.

2. async def detect_on_img(file:UploadFile = File(…))

• This is the function that will be executed when a POST request is made to the `/detection/` endpoint.
• The function takes an argument named `file` of type `UploadFile`. This argument represents the uploaded image file.

4. Creating a DetectionResults instance:

• An instance of the `DetectionResults` class is created to store the detection results.

5. Reading and decoding the uploaded image:

• The `read_image` function is used to read and decode the uploaded image file using OpenCV. The result is stored in the `img` variable.

6. Performing object detection:

• The `run_detection_on_img` method of the `detector` instance is called to perform object detection on the `img`. The detection results are stored in the `results_list` attribute of the `results` instance.

7. Storing the filename:

• The filename of the uploaded image is stored in the `filename` attribute of the `results` instance.

8. Updating the results string if objects are detected:

• If objects are detected in the image (i.e., `results_list` is not empty), a counter is created to count the occurrences of each detected label. The `results_str` attribute of the `results` instance is updated to provide information about the detected objects and their counts.

9. Returning the results:

• The `results` instance, which contains the detection results and related information, is returned as the response to the HTTP POST request.

In summary, this FastAPI endpoint processes an uploaded image, performs object detection using a `detector` instance, and returns the detection results along with relevant information, such as the filename and a summary of detected objects.

if __name__ == '__main__':
    uvicorn.run(app, host='127.0.0.1', port=8000)

Now we can start the FastAPI application using the uvicorn server when the script is run directly.

Now let’s put everything to the test :

Run the FastAPI Server:

• Method 1 : Run with uvicorn CLI: Activate your environment then run the following command:

uvicorn main:app --host 127.0.0.1 --port 8000

• Method 2 : Execute the main.py script using either the command-line interface (CLI) or your preferred code editor:

python main.py

Make API Requests:

• Method 1: Use tools like curl or API clients to make POST requests to the API endpoint for object detection. Here’s an example of how to make a simple API request using curl:

curl -X POST -F "file=@image.jpg" http://localhost:8000/detection

• Method 2: Access Swagger UI: Open your web browser and navigate to the following URL to interact with your API using Swagger UI:

http://localhost:8000/docs

Here, you’ll find an interactive interface that presents a list of all available API endpoints. You can explore each endpoint’s input parameters, send requests directly from the browser, and view the API’s responses. This greatly simplifies the process of testing and interacting with your FastAPI application.

Let’s try it out :

Uploaded image :

The response we get :

{
  "filename": "people walking.PNG",
  "results_str": "Found 3 objects : 2 x person, 1 x dog",
  "results_list": [
    {
      "label": "person",
      "confidence": "99%",
      "bbox_xywh": [
        97,
        30,
        81,
        226
      ]
    },
    {
      "label": "person",
      "confidence": "99%",
      "bbox_xywh": [
        174,
        50,
        78,
        201
      ]
    },
    {
      "label": "dog",
      "confidence": "99%",
      "bbox_xywh": [
        276,
        168,
        73,
        96
      ]
    }
  ]
}

The uploaded image :

The response :

{
  "filename": "blank.PNG",
  "results_str": "No detections",
  "results_list": []
}

And voilà ! we have successfully deployed and tested an object detection model based on YOLOv3, able to accurately predict objects in an image, using FastAPI.

Conclusion:

In summary, this article has provided a practical roadmap for seamlessly integrating YOLOv3’s powerful object detection capabilities into FastAPI, demonstrating the fusion of advanced AI and web development for effective potential real-world applications.

Key Takeaways:

• YOLOv3 is a powerful yet straightforward state-of-the-art algorithm for fast and accurate object detection.
• FastAPI is key to transforming a sophisticated machine learning model like YOLOv3 into a functional and accessible API.
• By utilizing Python’s modularization, and OOP concepts, you can make your codebase more readable, maintainable, and efficient. Using these principles is considered one of software engineering best practices.

Exploring Beyond: More Tutorials on Computer Vision, Deep Learning, and Object Detection

Feeling interested by the realms of computer vision, deep learning, and object detection? Then check out my compilation of tutorials and GitHub repositories for a comprehensive exploration.

• Object Detection, Tracking and Counting with YOLOv8.
• Object Detection With YOLOv5.
• Real-time Facial Recognition with Dlib and Python.
• Train your YOLOv8 model on a custom Dataset.
• Visualize what ConvNets learn.