PySSD

A Tensorflow Single-Shot-Detector implementation

[Tensorflow] [Acknowledgements] [Issues]


           

Overview

PySSD is an example implementation of a Single-Shot-Detector (SSD) in Tensorflow encapsulated as bare-bones library.

It is meant to be used as either a standalone program to experiment with, or included as part of a larger workflow. All the supporting functions required to implement it into any project with relative ease are found within the library file, such as labelmap parsing and modularized output access methods that clearly depict the way the results are being handled.

Aditionally, it can be tweaked to work with other network types such as Region-based Convolutional Neural Network (RCNN) or You-Only-Look-Once (YOLO).

Requirements

Model & Configuration Files

To use this library, it is required that you utilize a trained SSD model.
(e.g. https://tfhub.dev/tensorflow/ssd_mobilenet_v2/2)

This library utilizes the savedModel format, but depending on the model you choose, other things such as how certain values of the output are accessed may change as well. By default, you are able to alter how the values are parsed in the returned output from a forward pass using the aforementioned model simply by specifying in the arguments:

Option	Type	Description
net_format_numdet	string	Defines the index for number of detections in model output
net_format_boxes	string	Defines the index for detection ROI boxes in model output
net_format_classes	string	Defines the index for detection classes in model output
net_format_scores	string	Defines the index for detection confidence scores in model output

Additionally, the model will likely also require a labelmap that can be parsed with the tools included in the module.
For the aforementioned model (which is trained on COCO images), you can use the COCO labelmap available in many repositories online.

Finally, to specify the label map file, set the argument --lmf_path specified in PySSD.arguments.

Dependencies

Tensorflow (2.6.0-3)

pacman -S python-tensorflow

Please see dependencies listed here.

NumPy (1.20.3-1)

pacman -S python-numpy

Please see dependencies listed here.

Pillow (8.3.1-1)

pacman -S python-pillow

Please see dependencies listed here.

Usage

Arguments

Option	Type	Description
conf_threshold	float	Defines the threshold for confidence of detected objects
img_path	string	Defines the path to load an input image from
net_path	string	Defines the path to load a saved network model from
lmf_path	string	Defines the path to load a label map from
net_format_numdet	string	Defines the index for number of detections in model output
net_format_boxes	string	Defines the index for detection ROI boxes in model output
net_format_classes	string	Defines the index for detection classes in model output
net_format_scores	string	Defines the index for detection confidence scores in model output
lmf_format_id	string	Defines the index for unique identifier in label map file
lmf_format_class	string	Defines the index for class label in label map file
lmf_format_misc	string	Defines the index for misc. info in label map file

Example

python3 SSD.py --lmf_path mscoco_label_map.pbtxt --img_path Images/DogPark3.jpg
Generating label map from "mscoco_label_map.pbtxt"
Loading model at "./"
Running input "./Images/DogPark3.jpg" through the model

Detection Class: 1 -- "person"
Detection Score: 85.793%
       Location: (2212, 354) -- (3073, 1922)

Detection Class: 18 -- "dog"
Detection Score: 82.915%
       Location: (24, 1169) -- (1216, 2039)

Detection Class: 18 -- "dog"
Detection Score: 74.295%
       Location: (1543, 958) -- (2222, 2370)

Finished with input "./Images/DogPark3.jpg"

Acknowledgements

'PySSD' is my attempt at creating a simple implementation of a portable Single-Shot-Detector library based on the model(s) found on the official Tensorflow repository. Additionally, it it also meant to serve as a learning tool for SSD's and what a typical implementation might look like. Many if not most of the commenting in the library is meant to be informative, and is liable to be overly explicit.