BombusCV

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¹ and a Raspberry Pi HQ Camera² 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³ 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.

Examples

Below a brief example of the produced video output:

example.mp4

More examples can be found at the BombusCV YouTube channel.

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).

Cargo

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

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⁵. 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

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⁶.

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.

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
# date&time video overlay border
overlay_border = 2

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

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 ↩
12.3 megapixel Sony IMX477 sensor ↩
Based on hardware (RasberryPi 4 at the moment of writing can handle 640x480 resolution at 60fps) ↩
Assuming Rust installed ↩
RaspberryPi OS 64 bits required in order to install using the script ↩
Same rules apply to configuration file ↩

marcoradocchia/bombuscv-rs