{"id":14971097,"url":"https://github.com/marcoradocchia/bombuscv-rs","last_synced_at":"2025-10-26T14:31:05.139Z","repository":{"id":41111383,"uuid":"497168203","full_name":"marcoradocchia/bombuscv-rs","owner":"marcoradocchia","description":"OpenCV based motion detection/recording software built for research on Bumblebees.","archived":false,"fork":false,"pushed_at":"2024-01-22T21:51:53.000Z","size":3831,"stargazers_count":18,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-28T14:01:40.973Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcoradocchia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"marcoradocchia","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-05-27T23:55:14.000Z","updated_at":"2024-06-16T15:18:31.000Z","dependencies_parsed_at":"2022-07-21T04:48:51.298Z","dependency_job_id":null,"html_url":"https://github.com/marcoradocchia/bombuscv-rs","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fbombuscv-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fbombuscv-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fbombuscv-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fbombuscv-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcoradocchia","download_url":"https://codeload.github.com/marcoradocchia/bombuscv-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219862782,"owners_count":16555951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-09-24T13:44:42.707Z","updated_at":"2025-10-26T14:31:04.841Z","avatar_url":"https://github.com/marcoradocchia.png","language":"Rust","funding_links":["https://github.com/sponsors/marcoradocchia"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eBombusCV\u003c/h1\u003e\n\n  ![GitHub releases](https://img.shields.io/github/downloads/marcoradocchia/bombuscv-rs/total?color=%23a9b665\u0026logo=github)\n  ![GitHub source size](https://img.shields.io/github/languages/code-size/marcoradocchia/bombuscv-rs?color=ea6962\u0026logo=github)\n  ![GitHub open issues](https://img.shields.io/github/issues-raw/marcoradocchia/bombuscv-rs?color=%23d8a657\u0026logo=github)\n  ![GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/marcoradocchia/bombuscv-rs?color=%2389b482\u0026logo=github)\n  ![GitHub sponsors](https://img.shields.io/github/sponsors/marcoradocchia?color=%23d3869b\u0026logo=github)\n  ![Crates.io downloads](https://img.shields.io/crates/d/bombuscv-rs?label=crates.io%20downloads\u0026color=%23a9b665\u0026logo=rust)\n  ![Crates.io version](https://img.shields.io/crates/v/bombuscv-rs?logo=rust\u0026color=%23d8a657)\n  ![Discord](https://img.shields.io/discord/985154521946816595?label=chat%20support\u0026logo=discord\u0026logoColor=%23ffff\u0026color=%2389b482)\n  ![GitHub license](https://img.shields.io/github/license/marcoradocchia/bombuscv-rs?color=%23e78a4e)\n\u003c/div\u003e\n\nMotion detection \u0026 video recording software based on OpenCV, built for research\non **Bumblebees** (hence the name).\n\n## Index\n\n- [Use case](#use-case)\n- [Examples](#examples)\n- [Install](#install)\n  - [Requirements](#requirements)\n  - [Cargo](#cargo)\n  - [Install on RaspberryPi 4](#install-on-raspberrypi-4)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Changelog](#changelog)\n- [ToDo](#todo)\n- [Chat Support](#chat-support)\n- [License](#license)\n\n## Use case\n\nThis software was built to meet the need of tracking, and/or recording clips of\nmarked Bumblebee individuals in a scientific research project. It has been used\nwith a\n[Raspberry Pi 4](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/)[^1]\nand a\n[Raspberry Pi HQ Camera](https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/)[^2]\npointed at the entrance of a _Bombus terrestris_ nest, in order to record clips\nof the entry/exit events, based on motion. This considerably reduced the\nstorage space required for the recordings and completely removed the need of\npost processing work, since it was only recording clips in which individuals\nappeared in the video frame.\n\n`bombuscv-rs` offers realtime motion detection \u0026 video recording[^3] using\ncamera input and can be directly used on fieldwork. However, using the `video`\noption, live camera input can be replaced with a pre-recorded video file: this\nis useful to _remove dead moments_ from videos and reduce/remove the need of\nmanual video trimming.\n\n[^1]: 4GB of RAM memory, powered by a 30000mAh battery power supply, which\n  means this setup can be also reproduced in locations where no AC is available\n[^2]: 12.3 megapixel _Sony IMX477_ sensor\n[^3]: Based on hardware (RasberryPi 4 at the moment of writing can handle\n  640x480 resolution at 60fps)\n\n## Examples\n\nBelow a brief example of the produced video output:\n\n\u003cdiv align=\"center\"\u003e\n\nhttps://user-images.githubusercontent.com/74802223/171311278-c5caf303-832f-46f6-a4cc-a3e05f823349.mp4\n\n\u003c/div\u003e\n\nMore examples can be found at the [BombusCV YouTube\nchannel](https://www.youtube.com/channel/UCkSjz-EAjhEvtUcY-ruYkrA).\n\n## Install\n\nFor installation on *RaspberryPi* check [Install on RaspberryPi\n4](#install-on-raspberrypi-4).\n\n### Requirements\n\nThis program requires a working installation of **OpenCV** (`\u003e=4.5.5`).\nBuilding OpenCV from source is recommended (if you're going to build OpenCV\nfrom source make sure to also install OpenCV dependencies), although it should\nwork with precompiled packages in your distro's repositories (it has been\ntested with success on *ArchLinux* with the `extra/opencv` package).\n\n### Cargo\n\nA package is available at [crates.io](https://crates.io/crates/bombuscv-rs). In\norder to install it run `cargo install bombuscv-rs` in your shell[^4].\n\n[^4]: Assuming Rust installed\n\n### Install on RaspberryPi 4\n\nIt is strongly recommended to use a RaspberryPi 4 with at least 4GB of RAM.\nAlso, before trying to install, please enable *Legacy Camera* support under\n*Interface options*  running `raspi-config` and reboot. Since installation on a\nRaspberryPi may be a little bit *tricky*, an installation script is\nprovided[^5]. It takes care of updating \u0026 preparing the system, compiling\n*OpenCV* and installing *Rustup* and finally **BombusCV**. You can run the\n[instllation script](bombuscv-raspi.sh) using `curl`:\n```sh\ncurl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/marcoradocchia/bombuscv-rs/master/bombuscv-raspi.sh | sh\n```\n\n[^5]: RaspberryPi OS 64 bits required in order to install using the script\n\n## Usage\n\n```\nbombuscv-rs 0.3.0\nMarco Radocchia \u003cmarco.radocchia@outlook.com\u003e\nOpenCV based motion detection/recording software built for research on bumblebees.\n\nUSAGE:\n    bombuscv [OPTIONS]\n\nOPTIONS:\n    -d, --directory \u003cDIRECTORY\u003e    Output video directory\n    -f, --framerate \u003cFRAMERATE\u003e    Video capture framerate\n        --format \u003cFORMAT\u003e          Output video filename format (see\n                                   \u003chttps://docs.rs/chrono/latest/chrono/format/strftime/index.html\u003e\n                                   for valid specifiers)\n    -h, --help                     Print help information\n    -H, --height \u003cHEIGHT\u003e          Video capture frame height\n    -i, --index \u003cINDEX\u003e            /dev/video\u003cINDEX\u003e capture camera index\n        --no-color                 Disable colored output\n    -o, --overlay                  Date\u0026Time video overlay\n    -q, --quiet                    Mute standard output\n    -v, --video \u003cVIDEO\u003e            Video file as input\n    -V, --version                  Print version information\n    -W, --width \u003cWIDTH\u003e            Video capture frame width\n```\n\nSpecifying `width`, `height` \u0026 `framerate` will make `bombuscv` probe the\ncapture device for the closest combination of values it can provide and select\nthem. In other words: if you required valid options, they will be used,\notherwhise `bombuscv` will adapt those to the closest available combination[^6].\n\nNote that `video` option, which runs `bombuscv` with a pre-recorded video\ninput, is incompatible with `framerate`, `width`, `height` and `overlay`. Also,\nif these options are specified in the configuration file, they are going to be\nignored. This because the first two are auto-detected from the input file while\nthe last makes no sense if used with a non-live video feed; same rules apply to\nCLI arguments.\n\n[^6]: Same rules apply to configuration file\n\n## Configuration\n\nAll CLI options (except `video` and `no-color`) can be set in a *optional* configuration file\nstored at `$XDG_CONFIG_HOME/bombuscv/config.toml` by default or at any other\nlocation in the filesystem specified by setting `BOMBUSCV_CONFIG` environment\nvariable. CLI options/arguments/flags override those defined in the\nconfiguration file. Below listed an example configuration file:\n```toml\n# be quiet (mute stdout)\nquiet = false\n# output video directory\ndirectory = \"~/output_directory/\"\n# output video filename format (see\n# https://docs.rs/chrono/latest/chrono/format/strftime/index.html for valid specifiers)\nformat = \"%Y-%m-%dT%H:%M:%S\"\n\n# The following options are ignored if bombuscv is run with `--video` option\n# /dev/video\u003cindex\u003e camera input\nindex = 0\n# video capture frame width\nwidth = 640\n# video capture frame height\nheight = 480\n# video capture framerate\nframerate = 30\n# date\u0026time video overlay\noverlay = true\n# date\u0026time video overlay border\noverlay_border = 2\n```\n\n## Changelog\n\nComplete [CHANGELOG](CHANGELOG.md).\n\n## ToDo\n\n- [x] Provide build \u0026 install instructions in [README](README.md), as well as\n  the instructions to install OpenCV.\n- [x] Make install script for automated installation on RaspberryPi.\n- [x] Passing `video` or `directory` options in the configuration file using\n  `~/\u003cpath\u003e` results in an error: in the Deserialize expanding `~` to\n  absolute path is required.\n- [x] Using `video`, _date\u0026time_ overlay generated on frame grabbed makes no\n  sense: disable video overlay while using `video` option.\n- [x] Add option to specify custom config path using env variables.\n- [x] Add option to specify (in config file or via CLI argument) a custom\n  output video filename formatter (must be [chrono DateTime\n  syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)).\n- [x] Add thread signalling to interrupt grabber thread and gracefully\n  terminate the execution.\n- [x] Move logic from `main` to newly defined `run`.\n\n## Chat Support\n\nJoin *BombusCV's Discord server* for installation or usage chat support:\n\n\u003cdiv align=\"center\"\u003e\n\n[![Join our Discord server!](https://invidget.switchblade.xyz/srNGQEs2QA?language=en)](http://discord.gg/srNGQEs2QA)\n\n\u003c/div\u003e\n\n## License\n\n[GPLv3](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoradocchia%2Fbombuscv-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcoradocchia%2Fbombuscv-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoradocchia%2Fbombuscv-rs/lists"}