snowzach/doods repository overview

⁠DOODS

Dedicated Outside Object Detection Service - Yes, it's a backronym, so what...

DOODS is a GRPC service that detects objects in images. It's designed to be run as a container, optionally remotely.

⁠API

The API uses gRPC to communicate but it has a REST gateway built in for ease of use. It supports both a single call RPC and a streaming interface. It supports very basic pre-shared key authentication if you wish to protect it. It also supports TLS encryption but is disabled by default. It uses the content-type header to automatically determine if you are connecting in REST mode or GRPC mode. It listens on port 8080 by default.

⁠GRPC

The protobuf API definitations are in the odrpc directory. There are 3 endpoints.

• GetDetectors - Get the list of configured detectors.
• Detect - Detect objects in an image - Data should be passed as raw bytes
• DetectStream - Detect objects in a stream of images

⁠REST/JSON

• GET /detectors - Get the list of configured detectors
• POST /detect - Detect objects in an image

{
	"detector_name": "default",
	"data": "<base64 encoded image information>",
	"detect": {
		"*": 50
	}
}

The result is returned as:

{
    "id": "test",
    "detections": [
        {
            "top": 0,
            "left": 0.05,
            "bottom": .8552,
            "right": 0.9441,
            "label": "person",
            "confidence": 87.890625
        }
    ]
}

Perform a detection. Use the default detector. (If omitted, it will use the default) The data, when using the REST interface is base64 encoded image data. DOODS can decode png, bmp and jpg. The detect object allows you to specify the list of objects to detect as defined in the labels file. You can give a min percentage match. You can also use "*" which will match anything with a minimum percentage.

Example One Liner:

echo "{\"detector_name\":\"default\", \"detect\":{\"*\":60}, \"data\":\"`cat grace_hopper.png|base64 -w0`\"}" > /tmp/postdata.json && curl -d@/tmp/postdata.json -H "Content-Type: application/json" -X POST http://localhass.prozach.org:8080/detect

⁠Detectors

You should optimally pass image data in the requested size for the detector. If not, it will be automatically resized. It can read BMP, PNG and JPG as well as PPM.

⁠TFLite

If you pass PPM image data in the right dimensions, it can be fed directly into tensorflow. This skips a couple steps for speed. You can also specify hwAccel: true in the config and it will enable Coral EdgeTPU hardware acceleration. You must also provide it an appropriate EdgeTPU model file.

⁠Compiling

This is designed as a go module aware program and thus requires go 1.12 or better. It also relies heavily on CGO. The easiest way to compile it is to use the Dockerfile which will build a functioning docker image. It's a little large.

⁠Configuration

The configuration can be specified in a number of ways. By default you can create a json file and call it with the -c option you can also specify environment variables that align with the config file values.

Example:

{
	"logger": {
        "level": "debug"
	}
}

Can be set via an environment variable:

LOGGER_LEVEL=debug

⁠Options:

⁠TLS/HTTPS

You can enable https by setting the config option server.tls = true and pointing it to your keyfile and certfile. To create a self-signed cert: openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 -keyout server.key -out server.crt

⁠Detector Config

Detector config must be done with a configuration file. The default config includes one Tensorflow lite mobilenet detector.

doods:
  detectors:
    - name: default
      type: tflite
      modelFile: models/coco_ssd_mobilenet_v1_1.0_quant.tflite
      labelFile: models/coco_labels0.txt
      numThreads: 4
      numConcurrent: 4
      hwAccel: false

The default model is downloaded from google: coco_ssd_mobilenet_v1_1.0_quant_2018_06_29

⁠Detectors

• tflite - Tensorflow lite models - Supports Coral EdgeTPU
• tensorflow - Tensorflow

⁠Examples - Clients

See the examples directory for sample clients

⁠Docker

To run the container in docker you need to map port 8080. If you want to update the models, you need to map model files and a config to use them. docker run -it -p 8080:8080 snowzach/doods:latest

There is a script called fetch_models.sh that you can download and run to create a models directory and download several models and outputs an example.yaml config file. You could then run: docker run -it -v ./models:/opt/doods/models -v ./example.yaml:/opt/doods/config.yaml -p 8080:8080 snowzach/doods:latest

⁠Coral EdgeTPU

If you want to run it in docker using the Coral EdgeTPU, you need to pass the device to the container with: --device /dev/bus/usb Example: docker run -it --device /dev/bus/usb -p 8080:8080 snowzach/doods:latest

⁠Misc

Special thanks to https://github.com/mattn/go-tflite⁠ as I would have never been able to figure out all the CGO stuff. I really wanted to write this in Go but I'm not good enough at C++/CGO to do it. Most of the tflite code is taken from that repo and customized for this tool.