Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marcoradocchia/bombuscv-rs
OpenCV based motion detection/recording software built for research on Bumblebees.
https://github.com/marcoradocchia/bombuscv-rs
bee bee-detection bees bumblebee bumblebee-detection bumblebees insect-detection insects-detection motion-detection open-cv opencv raspberry-pi rust rust-lang video video-recording
Last synced: about 1 month ago
JSON representation
OpenCV based motion detection/recording software built for research on Bumblebees.
- Host: GitHub
- URL: https://github.com/marcoradocchia/bombuscv-rs
- Owner: marcoradocchia
- License: gpl-3.0
- Created: 2022-05-27T23:55:14.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-01-22T21:51:53.000Z (10 months ago)
- Last Synced: 2024-09-28T14:01:40.973Z (about 2 months ago)
- Topics: bee, bee-detection, bees, bumblebee, bumblebee-detection, bumblebees, insect-detection, insects-detection, motion-detection, open-cv, opencv, raspberry-pi, rust, rust-lang, video, video-recording
- Language: Rust
- Homepage:
- Size: 3.65 MB
- Stars: 18
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
BombusCV
Motion detection & video recording software based on OpenCV, built for research
on **Bumblebees** (hence the name).
## Index
- [Use case](#use-case)
- [Examples](#examples)
- [Install](#install)
- [Requirements](#requirements)
- [Cargo](#cargo)
- [Install on RaspberryPi 4](#install-on-raspberrypi-4)
- [Usage](#usage)
- [Configuration](#configuration)
- [Changelog](#changelog)
- [ToDo](#todo)
- [Chat Support](#chat-support)
- [License](#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](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/)[^1]
and a
[Raspberry Pi HQ Camera](https://www.raspberrypi.com/products/raspberry-pi-high-quality-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:
https://user-images.githubusercontent.com/74802223/171311278-c5caf303-832f-46f6-a4cc-a3e05f823349.mp4
More examples can be found at the [BombusCV YouTube
channel](https://www.youtube.com/channel/UCkSjz-EAjhEvtUcY-ruYkrA).
## Install
For installation on *RaspberryPi* check [Install on RaspberryPi
4](#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](https://crates.io/crates/bombuscv-rs). 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](bombuscv-raspi.sh) using `curl`:
```sh
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
OpenCV based motion detection/recording software built for research on bumblebees.
USAGE:
bombuscv [OPTIONS]
OPTIONS:
-d, --directory Output video directory
-f, --framerate Video capture framerate
--format Output video filename format (see
for valid specifiers)
-h, --help Print help information
-H, --height Video capture frame height
-i, --index /dev/video capture camera index
--no-color Disable colored output
-o, --overlay Date&Time video overlay
-q, --quiet Mute standard output
-v, --video Video file as input
-V, --version Print version information
-W, --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:
```toml
# 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 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](CHANGELOG.md).
## ToDo
- [x] Provide build & install instructions in [README](README.md), as well as
the instructions to install OpenCV.
- [x] Make install script for automated installation on RaspberryPi.
- [x] Passing `video` or `directory` options in the configuration file using
`~/` results in an error: in the Deserialize expanding `~` to
absolute path is required.
- [x] Using `video`, _date&time_ overlay generated on frame grabbed makes no
sense: disable video overlay while using `video` option.
- [x] Add option to specify custom config path using env variables.
- [x] Add option to specify (in config file or via CLI argument) a custom
output video filename formatter (must be [chrono DateTime
syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)).
- [x] Add thread signalling to interrupt grabber thread and gracefully
terminate the execution.
- [x] Move logic from `main` to newly defined `run`.
## Chat Support
Join *BombusCV's Discord server* for installation or usage chat support:
[](http://discord.gg/srNGQEs2QA)
## License
[GPLv3](LICENSE)