bombuscv-rs
OpenCV based motion detection/recording software built for research on Bumblebees.
Science Score: 44.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
✓CITATION.cff file
Found CITATION.cff file -
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
○Academic publication links
-
○Committers with academic emails
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (12.7%) to scientific vocabulary
Keywords
Repository
OpenCV based motion detection/recording software built for research on Bumblebees.
Basic Info
Statistics
- Stars: 19
- Watchers: 2
- Forks: 1
- Open Issues: 2
- Releases: 3
Topics
Metadata Files
README.md
BombusCV
        Motion detection & video recording software based on OpenCV, built for research on Bumblebees (hence the name).
Index
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 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[^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:
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 marco.radocchia@outlook.com OpenCV based motion detection/recording software built for research on bumblebees.
USAGE: bombuscv [OPTIONS]
OPTIONS:
-d, --directory
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.
ToDo
- [x] Provide build & install instructions in README, as well as the instructions to install OpenCV.
- [x] Make install script for automated installation on RaspberryPi.
- [x] Passing
videoordirectoryoptions in the configuration file using~/<path>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 usingvideooption. - [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).
- [x] Add thread signalling to interrupt grabber thread and gracefully terminate the execution.
- [x] Move logic from
mainto newly definedrun.
Chat Support
Join BombusCV's Discord server for installation or usage chat support:
License
Owner
- Name: Marco Radocchia
- Login: marcoradocchia
- Kind: user
- Location: Italy
- Repositories: 47
- Profile: https://github.com/marcoradocchia
I'm a physics student with real enthusiasm in computers and free and open source software.
Citation (CITATION.cff)
cff-version: 1.2.0 message: "If you use this software, please cite it as below." authors: - family-names: "Radocchia" given-names: "Marco" - family-names: "Di Francescantonio" given-names: "Gaia" title: "BombusCV" version: 0.3.0 date-released: 2022-06-28 url: "https://github.com/marcoradocchia/bombuscv-rs"
GitHub Events
Total
- Watch event: 1
- Fork event: 1
Last Year
- Watch event: 1
- Fork event: 1
Committers
Last synced: 9 months ago
Top Committers
| Name | Commits | |
|---|---|---|
| Marco Radocchia | m****a@o****m | 92 |
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 4
- Total pull requests: 2
- Average time to close issues: 8 days
- Average time to close pull requests: 1 minute
- Total issue authors: 2
- Total pull request authors: 2
- Average comments per issue: 1.25
- Average comments per pull request: 0.0
- Merged pull requests: 1
- Bot issues: 0
- Bot pull requests: 1
Past Year
- Issues: 0
- Pull requests: 0
- Average time to close issues: N/A
- Average time to close pull requests: N/A
- Issue authors: 0
- Pull request authors: 0
- Average comments per issue: 0
- Average comments per pull request: 0
- Merged pull requests: 0
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
- gaiahah (2)
- marcoradocchia (2)
Pull Request Authors
- dependabot[bot] (1)
- marcoradocchia (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 1
-
Total downloads:
- cargo 5,442 total
- Total dependent packages: 0
- Total dependent repositories: 0
- Total versions: 4
- Total maintainers: 1
crates.io: bombuscv-rs
OpenCV based motion detection/recording software built for research on bumblebees.
- Documentation: https://docs.rs/bombuscv-rs/
- License: GPL-3.0-only
-
Latest release: 0.3.0
published over 3 years ago
Rankings
Maintainers (1)
Dependencies
- aho-corasick 0.7.18
- atty 0.2.14
- autocfg 1.1.0
- bitflags 1.3.2
- cc 1.0.73
- cfg-if 1.0.0
- chrono 0.4.19
- clang 1.0.3
- clang-sys 1.3.3
- clap 3.2.6
- clap_derive 3.2.6
- clap_lex 0.2.2
- directories 4.0.1
- dirs-sys 0.3.7
- dunce 1.0.2
- getrandom 0.2.7
- glob 0.3.0
- hashbrown 0.11.2
- heck 0.4.0
- hermit-abi 0.1.19
- indexmap 1.8.2
- jobserver 0.1.24
- libc 0.2.126
- maplit 1.0.2
- memchr 2.5.0
- num-integer 0.1.45
- num-traits 0.2.15
- once_cell 1.12.0
- opencv 0.65.0
- opencv-binding-generator 0.44.0
- os_str_bytes 6.1.0
- percent-encoding 2.1.0
- pkg-config 0.3.25
- proc-macro-error 1.0.4
- proc-macro-error-attr 1.0.4
- proc-macro2 1.0.39
- quote 1.0.18
- redox_syscall 0.2.13
- redox_users 0.4.3
- regex 1.5.6
- regex-syntax 0.6.26
- semver 1.0.10
- serde 1.0.137
- serde_derive 1.0.137
- shlex 1.1.0
- signal-hook 0.3.14
- signal-hook-registry 1.4.0
- strsim 0.10.0
- syn 1.0.96
- termcolor 1.1.3
- textwrap 0.15.0
- thiserror 1.0.31
- thiserror-impl 1.0.31
- time 0.1.44
- toml 0.5.9
- unicode-ident 1.0.1
- vcpkg 0.2.15
- version_check 0.9.4
- wasi 0.10.0+wasi-snapshot-preview1
- wasi 0.11.0+wasi-snapshot-preview1
- winapi 0.3.9
- winapi-i686-pc-windows-gnu 0.4.0
- winapi-util 0.1.5
- winapi-x86_64-pc-windows-gnu 0.4.0
- actions/checkout v3 composite