This article assumes you have Shinobi Installed in the Default location /home/Shinobi with a Camera Added and capable of recording.

You must also have an NVIDIA Graphic Processor to use YoloV3. YoloV3 can run on CPU but it is not recommended. You will just shorten the lifespan of your CPU greatly.

How to Install the YoloV3 Plugin for Shinobi

Skip to the next section if you already have it appearing as Connected in the interface.

1. Navigate to your plugin's directory, where you downloaded the Shinobi files to.

cd /home/Shinobi/plugins/yolo

2. Navigate to your Shinobi directory and install the node.js wrappers needed to run the plugin.

sh INSTALL.sh

You will be asked if you want to install Tiny weights. You should choose Yes if your GPU has less then 4GB RAM or if you just want fast detection and you know you have a clear view of objects.

3. Modify the conf.json key value to anything you want, make it random.

nano conf.json

Here is an example of what it looks like inside the Yolo plugin's conf.json. See the key option? Change that.

{
  "plug":"Yolo",
  "host":"localhost",
  "port":8080,
  "key":"Yolo123123",
  "mode":"client",
  "type":"detector"
}

4. Open your main conf.json. Located in the main directory of Shinobi.

nano /home/Shinobi/conf.json

5. Add the key you created to allow the plugin to authenticate. Yolo123123 is the default key provided in the conf.json for the yolo plugin. Here is a full conf.json with the Yolo plugin key added.

{
  "port": 8080,
  "subscriptionId":"sub_XXXXXXXXXXXXXX",
  "debugLog":false,
  "smtpServer": true,
  "discordBot":true,
  "passwordType": "sha256",
  "detectorMergePamRegionTriggers": true,
  "addStorage": [],
  "db": {
    "host": "127.0.0.1",
    "user": "majesticflame",
    "password": "",
    "database": "ccio",
    "port": 3306
  },
  "mail": {
    "service": "gmail",
    "auth": {
      "user": "[email protected]",
      "pass": "your_password_or_app_specific_password"
    }
  },
  "cron": {
    "key": "cats are cool123"
  },
  "pluginKeys": {
    "OpenALPR": "123",
    "Yolo": "Yolo123123"
  },
  "dropInEventServer": true,
  "ftpServer": true,
    "childNodes": {
      "enabled" : true,
      "mode" : "master",
      "port" : 8288,
      "key" : "aMatchingKey1234"
  }
}

6. Shinobi will need to be restarted after modifying connection keys.

pm2 restart camera

7. Start the plugin.

pm2 start shinobi-yolo.js

8. When complete you will see Object Detection : Yolo Connected in your Monitor Settings.

It says Connected, Now what?

First we'll talk about how to do only Object Detection. In the next section we'll talk about doing Motion Detection first.

1. Open your Monitor Settings and scroll down to Global Detector Settings and Enable it.

You may need to switch your Monitor Settings to Advanced in the bottom right corner to see this section.

2. Now since we are going to use Object Detection as the Primary Engine we can scroll down to Motion Detection and switch Built-In to No. Now the text in the Motion Detection header will have changed to Primary Engine : Yolo Connected.

3. Scroll Down to Object Detection. Enable it and enable Send Frames.

You may notice these options were disabled or not set. Since the primary engine is focused on the Object Detector Enabled will be defaulted to Yes regardless of the choice here. Send Frames will then be dictated by the Global Detector Settings section.

4. Scroll back up to Global Detector Settings and enable Send Frames and Save Events to SQL.

Saving Events to SQL will make the detection squares appear in the Power Video Viewer.

5. In the same section, raise Feed-In Image Width to 1280 and Height to 720.

Avoid going above this Width and Height unless you have the CPU power to spare.

6. Also in the same section, Set the Recording Timeout to 0.5 to see a quicker recording result after detection.

7. Hit Save and Watch her detect.

What about with Motion Detection first?

This is for if you want to Motion Detection as a preliminary check before turning on the Object Detection. Doing this will save a lot of CPU power because Motion Detection alone inherently uses a lot less CPU power than Object Detection, even with a GPU.

1. Open the Monitor Settings again and scroll to Motion Detection and enable Built-In.

Now the Primary Engine header tag will appear as Pixel Array.

2. Set Full Frame Detection to No and Open the Region Editor. Create a Region and set the Indifference.

Indifference in the Region Editor will use the value in the Motion Detection section if left blank.

Set the Indifference value to something like 10 as a test. This means 10% change of your region is required before beginning Object Detection.

For a Region in the Region Editor, detection occurs inside the points of your polygon.

3. Close the Region Editor and scroll up to Global Detector Settings and set the Feed-In Width and Height to 640 by 480.

4. Scroll down to the Object Detection section and set the Width and Height to 1280 by 720.

5. Save. Now you will see the Motion Meter become green when there is motion. This means is passing off to the detector. If it becomes red then that means something has been found.

... or the plugin disconnected. One of the two.

6. Enjoy!

What are Weights?

YoloV3 Weights are, for lack of better words, the memories of your neural net. Each set of weights are made for different things. The ones provided with the plugin's installer are general purpose. They were made to detect a variety of things, like Bears and Sheep as well as Cars and People.

How do I use different Weights?

In the Yolo plugin folder there will be a models folder after installation. You can swap out the four main files. Depending on where you source the files they can have different names. These are the names Shinobi's plugin uses.

  • data/coco.names
  • cfg/yolov3.cfg
  • cfg/coco.data
  • yolov3.weights

Here are a few different weight sets I made that you are free to use. If you wish to use them commercially please contact me first.

If you want to reset your weights to the original ones that the installer provides then just delete the models folder and run the installer again.

Why do my Weights keep crashing the plugin?

Try modifying the cfg/yolov3.cfg file. Set the batch and subdivison options to 1. Both of them. Then restart the plugin.

batch=1
subdivision=1

If that doesn't work try lowering the dimensions in the cfg. width and height. They need to be a multiple of 32. The higher the dimension the more accurate your detection but more RAM is then required and less frames per second can be done.

width=416
height=416

If that doesn't work then It may be that you don't have enough CPU or RAM to do the load you have set.

How do I make my own Weights?

There are lots of tutorials on the web. I suggest looking at all of AlexeyAB's readmes. He forked Darknet and it even more powerful, so he knows quite a bit.

A bit of warning though, it is very tedious. With that in mind I would like to mention that there is a Neural Net Trainer soon available for use to the public. If you are interested in testing it you can message me on discord for a trial, moeiscool#0001 is my username.

The sample weights I provided in How do I use different Weights were made by the tool. It can automatically download images from the Google Open Images data set and use those for training. They have the annotations for training already available and only need to be converted for use in Darknet/Yolo. My neural net trainer does the conversion for you. You can even add your own images and annotate them yourself.