python-detection

A motion detector. Currently two detectors, SimpleDetector and BlobDetector are implemented. The former performs simple frame differencing, and may not be useful for most purposes. The latter does a bit more and utilizes the OpenCV MOG2 background subtractor to get more realistic results. The detectors try to use OpenCL if it's available.

Using the BlobDetector:

import numpy as np
from detection.detectors.blob.detector import BlobDetector

detector = BlobDetector({"blur": 7, "learningrate": 0.001, "accelerate": True})
(_boundingboxes, _metadata) = detector.feed(
    np.reshape(np.frombuffer(frame, dtype=np.uint8), newshape=(height, width, 3))
)

The blur value, if specified, will be performed before feeding the frame to the detector. If no blur is given, the frame is fed as-is.

The learningrate parameter is described here. If no learningrate is specified, it will default to 0.001.

The accelerate parameter defaults to True, and the detector attempts to exploit any GPU resources available on the host.

The metadata contains details (in order) about the operations performed on the input image, and for how long each of those took:

{
    'start_timestamp': datetime.datetime(2020, 6, 16, 17, 7, 6, 443946),
    'took': [
        ('cv.UMat', 0.0007669925689697266),
        ('cv.GaussianBlur', 0.0014679431915283203),
        ('cv.BackgroundSubtractorMOG2.apply', 0.0003933906555175781),
        ('cv.findContours', 0.001050710678100586),
        ('cv.approxPolyDP', 1.7404556274414062e-05),
        ('cv.boundingRect', 2.384185791015625e-06),
        ('total', 0.005391)
    ],
    'end_timestamp': datetime.datetime(2020, 6, 16, 17, 7, 6, 449337)}
}

The bounding boxes contain any detected movement:

{
    (
        UUID('091c2620-ebb6-4cbe-b59d-42da156c3ba9'),
        datetime.datetime(2020, 6, 16, 16, 11, 35, 931755)
    ): (279, 324, 710, 755),
    (
        UUID('bcbf2e18-ed2b-4e68-b94c-abe021071e61'),
        datetime.datetime(2020, 6, 16, 16, 11, 35, 931755)
    ): (489, 324, 920, 755)
}

The UUIDs are here to provide forward compatibility with a hypothetical new detector that also tracks movement.

Development

TLDR:

Create and activate a Python 3.7 virtualenv:

$ python3.7 -m venv .venv && . .venv/bin/activate

Change to a branch:

git checkout -b my_branch

Install Poetry: https://python-poetry.org/docs/#installation

Install project deps and pre-commit hooks:

poetry install
pre-commit install
pre-commit run --all-files

Ready to go.

Remember to activate your virtualenv whenever working on the repo, this is needed because pylint and mypy pre-commit hooks use the "system" python for now (because reasons).