Motion detection & video recording software based on OpenCV, built for research on Bumblebees (hence the name).

Index

• Use case
• Examples
• Install
• Usage
• Configuration
• Changelog
• ToDo
• Chat Support
• License

Use case

This software was built to meet the need of tracking, and/or recording clips of marked Bumblebee individuals in a scientific research project. It has been used with a Raspberry Pi 4[^1] and a Raspberry Pi HQ Camera[^2] pointed at the entrance of a Bombus terrestris nest, in order to record clips of the entry/exit events, based on motion. This considerably reduced the storage space required for the recordings and completely removed the need of post processing work, since it was only recording clips in which individuals appeared in the video frame.

bombuscv-rs offers realtime motion detection & video recording[^3] using camera input and can be directly used on fieldwork. However, using the video option, live camera input can be replaced with a pre-recorded video file: this is useful to remove dead moments from videos and reduce/remove the need of manual video trimming.

[^1]: 4GB of RAM memory, powered by a 30000mAh battery power supply, which means this setup can be also reproduced in locations where no AC is available [^2]: 12.3 megapixel Sony IMX477 sensor [^3]: Based on hardware (RasberryPi 4 at the moment of writing can handle 640x480 resolution at 60fps)

Examples

Below a brief example of the produced video output:

More examples can be found on YouTube.

Install

For installation on RaspberryPi check Install on RaspberryPi 4.

Requirements

This program requires a working installation of OpenCV (>=4.5.5). Building OpenCV from source is recommended (if you're going to build OpenCV from source make sure to also install OpenCV dependencies), although it should work with precompiled packages in your distro's repositories (it has been tested with success on ArchLinux with the extra/opencv package).

Using Cargo

A package is available at crates.io. In order to install it run cargo install bombuscv-rs in your shell[^4].

[^4]: Assuming Rust installed

Install on RaspberryPi 4

It is strongly recommended to use a RaspberryPi 4 with at least 4GB of RAM. Also, before trying to install, please enable Legacy Camera support under Interface options running raspi-config and reboot. Since installation on a RaspberryPi may be a little bit tricky, an installation script is provided[^5]. It takes care of updating & preparing the system, compiling OpenCV and installing Rustup and finally BombusCV. You can run the instllation script using curl:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/marcoradocchia/bombuscv-rs/master/bombuscv-raspi.sh | sh

[^5]: RaspberryPi OS 64 bits required in order to install using the script

Usage

bombuscv-rs 0.3.0
Marco Radocchia <marco.radocchia@outlook.com>
OpenCV based motion detection/recording software built for research on bumblebees.

USAGE:
    bombuscv [OPTIONS]

OPTIONS:
    -d, --directory <DIRECTORY>    Output video directory
    -f, --framerate <FRAMERATE>    Video capture framerate
        --format <FORMAT>          Output video filename format (see
                                   <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
                                   for valid specifiers)
    -h, --help                     Print help information
    -H, --height <HEIGHT>          Video capture frame height
    -i, --index <INDEX>            /dev/video<INDEX> capture camera index
        --no-color                 Disable colored output
    -o, --overlay                  Date&Time video overlay
    -q, --quiet                    Mute standard output
    -v, --video <VIDEO>            Video file as input
    -V, --version                  Print version information
    -W, --width <WIDTH>            Video capture frame width

Specifying width, height & framerate will make bombuscv probe the capture device for the closest combination of values it can provide and select them. In other words: if you required valid options, they will be used, otherwhise bombuscv will adapt those to the closest available combination[^6].

Note that video option, which runs bombuscv with a pre-recorded video input, is incompatible with framerate, width, height and overlay. Also, if these options are specified in the configuration file, they are going to be ignored. This because the first two are auto-detected from the input file while the last makes no sense if used with a non-live video feed; same rules apply to CLI arguments.

[^6]: Same rules apply to configuration file

Configuration

All CLI options (except video and no-color) can be set in a optional configuration file stored at $XDG_CONFIG_HOME/bombuscv/config.toml by default or at any other location in the filesystem specified by setting BOMBUSCV_CONFIG environment variable. CLI options/arguments/flags override those defined in the configuration file. Below listed an example configuration file:

# be quiet (mute stdout)
quiet = false
# output video directory
directory = "~/output_directory/"
# output video filename format (see
# https://docs.rs/chrono/latest/chrono/format/strftime/index.html for valid specifiers)
format = "%Y-%m-%dT%H:%M:%S"

# The following options are ignored if bombuscv is run with `--video` option
# /dev/video<index> camera input
index = 0
# video capture frame width
width = 640
# video capture frame height
height = 480
# video capture framerate
framerate = 30
# date&time video overlay
overlay = true

Changelog

Complete CHANGELOG.

ToDo

• Provide build & install instructions in README, as well as the instructions to install OpenCV.
• Make install script for automated installation on RaspberryPi.
• Passing video or directory options in the configuration file using ~/<path> results in an error: in the Deserialize expanding ~ to absolute path is required.
• Using video, date&time overlay generated on frame grabbed makes no sense: disable video overlay while using video option.
• Add option to specify custom config path using env variables.
• Add option to specify (in config file or via CLI argument) a custom output video filename formatter (must be chrono DateTime syntax).
• Add thread signalling to interrupt grabber thread and gracefully terminate the execution.
• Move logic from main to newly defined run.

Chat Support

Join BombusCV's Discord server for installation or usage chat support:

License

GPLv3