yolov3

README

Go YOLO V3

This repository provides a plug and play implementation of the Yolo V3 object detection system in Go, leveraging gocv.

Prerequisites

Since this implementation builds on top of the gocv library, make sure you either use one of the provided docker images to run the example, or install the opencv dependencies on your system.

Furthermore, make sure you've got the yolov3 models downloaded before running the examples.

Simply run $ make models

Run the examples

Bird example

$ make bird-example

Output

Street example

$ make street-example

Output

Webcam example

$ make webcam-example

Note that this will not run smoothly on most machines, as the default net target type is set to NetTargetCPU. If you have cuda installed, adjust the net initialization to:

	conf := yolov3.DefaultConfig()
	// Adjust the backend and target type
	conf.NetBackendType = gocv.NetBackendCUDA
	conf.NetTargetType = gocv.NetTargetCUDA

	// Create the net with created config
	yolonet, err := yolov3.NewNetWithConfig(yolov3WeightsPath, yolov3ConfigPath, cocoNames, conf)
	if err != nil {
		log.WithError(err).Fatal("unable to create yolo net")
	}

Cuda example

Execute 50 fps test render with cuda, also see the CUDA section.

$ make cuda-example

CUDA

If you're interested in running yolo in Go with CUDA support, check the cmd/example_cuda to see a dummy example and test results of running object detection at 50 fps. The gocv cuda README provides detailed installation instructions.

Issues

If you have any issues, feel free to open a PR or create an issue!

Documentation

Overview

Package yolov3 provides a Go implementation of the YOLO V3 object detection system: https://pjreddie.com/darknet/yolo/.

The yolov3 package leverages gocv(https://github.com/hybridgroup/gocv) for a neural net able to detect object.

In order for the neural net to be able to detect objects, it needs the pre-trained network model consisting of a .cfg file and a .weights file. Using the Makefile provied by the library, these models can simply be downloaded by running 'make models'.

In order to use the package, make sure you've checked the prerequisites in the README: https://github.com/wimspaargaren/yolov3#prerequisites

Index

• Constants
• func DrawDetections(frame *gocv.Mat, detections []ObjectDetection)
• type Config
  • func DefaultConfig() Config
• type Net
  • func NewNet(weightsPath, configPath, cocoNamePath string) (Net, error)
  • func NewNetWithConfig(weightsPath, configPath, cocoNamePath string, config Config) (Net, error)
• type ObjectDetection

Examples

• NewNet
• NewNetWithConfig

Constants

const (
	DefaultInputWidth  = 416
	DefaultInputHeight = 416

	DefaultConfThreshold float32 = 0.5
	DefaultNMSThreshold  float32 = 0.4
)

Default constants for initialising the yolov3 net.

Functions

func DrawDetections

func DrawDetections(frame *gocv.Mat, detections []ObjectDetection)

DrawDetections draws a given list of object detections on a gocv Matrix.

Types

type Config

type Config struct {
	// InputWidth & InputHeight are used to determine the input size of the image for the network
	InputWidth  int
	InputHeight int
	// ConfidenceThreshold can be used to determine the minimum confidence before an object is considered to be "detected"
	ConfidenceThreshold float32
	// Non-maximum suppression threshold used for removing overlapping bounding boxes
	NMSThreshold float32

	// Type on which the network will be executed
	NetTargetType  gocv.NetTargetType
	NetBackendType gocv.NetBackendType

	// NewNet function can be used to inject a custom neural net
	NewNet func(weightsPath, configPath string) ml.NeuralNet
}

Config can be used to customise the settings of the neural network used for object detection.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig used to create a working yolov3 net out of the box.

type Net

type Net interface {
	Close() error
	GetDetections(gocv.Mat) ([]ObjectDetection, error)
	GetDetectionsWithFilter(gocv.Mat, map[string]bool) ([]ObjectDetection, error)
}

Net the yolov3 net.

func NewNet

func NewNet(weightsPath, configPath, cocoNamePath string) (Net, error)

NewNet creates new yolo net for given weight path, config and coconames list.

Example

yolov3WeightsPath := path.Join(os.Getenv("GOPATH"), "src/github.com/wimspaargaren/data/yolov3/yolov3.weights")
yolov3ConfigPath := path.Join(os.Getenv("GOPATH"), "src/github.com/wimspaargaren/data/yolov3/yolov3.cfg")
cocoNamesPath := path.Join(os.Getenv("GOPATH"), "src/github.com/wimspaargaren/data/yolov3/coco.names")

yolonet, err := NewNet(yolov3WeightsPath, yolov3ConfigPath, cocoNamesPath)
if err != nil {
	log.WithError(err).Fatal("unable to create yolo net")
}

// Gracefully close the net when the program is done
defer func() {
	err := yolonet.Close()
	if err != nil {
		log.WithError(err).Error("unable to gracefully close yolo net")
	}
}()

imagePath := path.Join(os.Getenv("GOPATH"), "src/github.com/wimspaargaren/yolov3/data/example_images/bird.jpg")
frame := gocv.IMRead(imagePath, gocv.IMReadColor)

detections, err := yolonet.GetDetections(frame)
if err != nil {
	log.WithError(err).Fatal("unable to retrieve predictions")
}

DrawDetections(&frame, detections)

window := gocv.NewWindow("Result Window")
defer func() {
	err := window.Close()
	if err != nil {
		log.WithError(err).Error("unable to close window")
	}
}()

window.IMShow(frame)
window.ResizeWindow(872, 585)

window.WaitKey(10000000000)

func NewNetWithConfig

func NewNetWithConfig(weightsPath, configPath, cocoNamePath string, config Config) (Net, error)

NewNetWithConfig creates new yolo net with given config.

Example

yolov3WeightsPath := path.Join(os.Getenv("GOPATH"), "src/github.com/wimspaargaren/data/yolov3/yolov3.weights")
yolov3ConfigPath := path.Join(os.Getenv("GOPATH"), "src/github.com/wimspaargaren/data/yolov3/yolov3.cfg")
cocoNamesPath := path.Join(os.Getenv("GOPATH"), "src/github.com/wimspaargaren/data/yolov3/coco.names")

conf := DefaultConfig()
// Set the neural net to use CUDA
conf.NetBackendType = gocv.NetBackendCUDA
conf.NetTargetType = gocv.NetTargetCUDA

yolonet, err := NewNetWithConfig(yolov3WeightsPath, yolov3ConfigPath, cocoNamesPath, conf)
if err != nil {
	log.WithError(err).Fatal("unable to create yolo net")
}

// Gracefully close the net when the program is done
defer func() {
	err := yolonet.Close()
	if err != nil {
		log.WithError(err).Error("unable to gracefully close yolo net")
	}
}()

// ...

type ObjectDetection

type ObjectDetection struct {
	ClassID     int
	ClassName   string
	BoundingBox image.Rectangle
	Confidence  float32
}

ObjectDetection represents information of an object detected by the neural net.