# ViGi: A camera surveillance system
## Features
* Multiple camera support
* Motion detection
* Object recognition
* Web server to view the camera feed and recordings
* Notifications via SMS and email
## Requirements
- Python 3.8 or higher. Tested with Python 3.12
- OpenCV
- A USB camera that can be accessed via OpenCV
## Installation and usage
```bash
pip install vigi
vigi
```
## Configuration
A detailed configuration options are available in the [Configuration](docs/configuration.md) document.
The agent can be configured in two ways:
* Using the `vigi.ini` file. This method is recommended for production use and when configuration is
constant and does not change frequently.
* Using command line arguments. This method is recommended for development and testing purposes:
```txt
usage: vigi [-h] [--debug] [--no-monitor] [--data-dir DATA_DIR] [--camera-id CAMERA_ID] [--host HOST] [--port PORT] [--max-errors MAX_ERRORS]
[--sensitivity SENSITIVITY] [--detection-model-file DETECTION_MODEL_FILE] [--disable-detection] [--inference-device INFERENCE_DEVICE]
[--http-basic-username HTTP_BASIC_USERNAME] [--http-basic-password HTTP_BASIC_PASSWORD] [--http-basic-hash HTTP_BASIC_HASH]
optional arguments:
-h, --help show this help message and exit
--debug Enable debug mode
--no-monitor Disable the camera monitor
--data-dir DATA_DIR Directory to store the recordings
--camera-id CAMERA_ID
Camera ID to monitor
--host HOST Host to run the web server
--port PORT Port to run the web server
--max-errors MAX_ERRORS
Maximum number of consecutive errors when reading a frame from the camera
--sensitivity SENSITIVITY
Sensitivity of the motion detector, should be a float between 0 and 1
--detection-model-file DETECTION_MODEL_FILE
Path to the detection model file (YOLO's yolov8n.pt, by default)
--disable-detection Disable object detection
--inference-device INFERENCE_DEVICE
Inference device for object detection (cpu or cuda)
--http-basic-username HTTP_BASIC_USERNAME
Username for HTTP basic authentication. Disabled by default
--http-basic-password HTTP_BASIC_PASSWORD
Password for HTTP basic authentication
--http-basic-hash HTTP_BASIC_HASH
Hashed password for HTTP basic authentication
```
You can configure additional cameras by adding a [CAMERAn] section to the `vigi.ini` file, where n is the camera ID. The only required parameter is the `CameraID`:
```ini
[CAMERA0]
CameraID = 0
[CAMERA1]
CameraID = 1
MaxErrors=50
Sensitivity=0.5
```
You can specify `MaxErrors` and `Sensitivity` for each camera separately. If these parameters are not specified, the default values will be used.
## Installation on Raspberry Pi (Raspberry Pi OS)
64 bit OS is required for PyTorch to work. Tested with [Raspberry Pi OS (Legacy, 64-bit)](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy-64-bit).
Install the pip package:
```bash
pip install vigi
```
Run the agent:
```bash
./.local/bin/vigi --host 0.0.0.0
```
If the object detection is slow on your device, you can try to run the agent with the `--disable-detection` option to disable it.
# Notifications
Consult the [Notifications](docs/notifications.md) document for more information on how to configure notifications.
# Development
## Run from the sources
```bash
# Set up a virtual environment
python -m venv .venv
. .venv/bin/activate
# Install the required packages
pip install -r requirements.txt
# run the agent
python main.py
```
## Build a pip package
```bash
pip install build
python -m build
```
## Publish the package to PyPI
```bash
python -m pip install --upgrade twine
python -m twine upload dist/*
```
## Run unit tests
Download a samples dataset for the motion detection tests from [here](https://drive.google.com/file/d/16yQZuHf3xB-Z6zYG6lGxxMP1umbxlIYd/view?usp=sharing) and extract it to the `agent/tests` directory.
Then run the tests:
```bash
python -m unittest discover
```
## Test coverage
To generate a coverage report, run the following command:
```bash
pip install coverage
coverage run -m unittest discover
coverage html
```
## Run PyLint
```bash
pylint $(git ls-files '*.py')
```
Raw data
{
"_id": null,
"home_page": null,
"name": "vigi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Dzmitry Plashchynski <plashchynski@gmail.com>",
"keywords": "camera, home security, motion detection, object recognition, surveillance",
"author": null,
"author_email": "Dzmitry Plashchynski <plashchynski@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/61/cb/cae00ea99f296523778f566f0c1dd368ef140bae95d6205f5cbfb1b2fd63/vigi-0.9.2.tar.gz",
"platform": null,
"description": "# ViGi: A camera surveillance system\n\n## Features\n\n* Multiple camera support\n* Motion detection\n* Object recognition\n* Web server to view the camera feed and recordings\n* Notifications via SMS and email\n\n## Requirements\n\n- Python 3.8 or higher. Tested with Python 3.12\n- OpenCV\n- A USB camera that can be accessed via OpenCV\n\n## Installation and usage\n\n```bash\npip install vigi\nvigi\n```\n\n## Configuration\n\nA detailed configuration options are available in the [Configuration](docs/configuration.md) document.\n\nThe agent can be configured in two ways:\n* Using the `vigi.ini` file. This method is recommended for production use and when configuration is\nconstant and does not change frequently.\n* Using command line arguments. This method is recommended for development and testing purposes:\n\n```txt\nusage: vigi [-h] [--debug] [--no-monitor] [--data-dir DATA_DIR] [--camera-id CAMERA_ID] [--host HOST] [--port PORT] [--max-errors MAX_ERRORS]\n [--sensitivity SENSITIVITY] [--detection-model-file DETECTION_MODEL_FILE] [--disable-detection] [--inference-device INFERENCE_DEVICE]\n [--http-basic-username HTTP_BASIC_USERNAME] [--http-basic-password HTTP_BASIC_PASSWORD] [--http-basic-hash HTTP_BASIC_HASH]\n\noptional arguments:\n -h, --help show this help message and exit\n --debug Enable debug mode\n --no-monitor Disable the camera monitor\n --data-dir DATA_DIR Directory to store the recordings\n --camera-id CAMERA_ID\n Camera ID to monitor\n --host HOST Host to run the web server\n --port PORT Port to run the web server\n --max-errors MAX_ERRORS\n Maximum number of consecutive errors when reading a frame from the camera\n --sensitivity SENSITIVITY\n Sensitivity of the motion detector, should be a float between 0 and 1\n --detection-model-file DETECTION_MODEL_FILE\n Path to the detection model file (YOLO's yolov8n.pt, by default)\n --disable-detection Disable object detection\n --inference-device INFERENCE_DEVICE\n Inference device for object detection (cpu or cuda)\n --http-basic-username HTTP_BASIC_USERNAME\n Username for HTTP basic authentication. Disabled by default\n --http-basic-password HTTP_BASIC_PASSWORD\n Password for HTTP basic authentication\n --http-basic-hash HTTP_BASIC_HASH\n Hashed password for HTTP basic authentication\n```\n\nYou can configure additional cameras by adding a [CAMERAn] section to the `vigi.ini` file, where n is the camera ID. The only required parameter is the `CameraID`:\n\n```ini\n[CAMERA0]\nCameraID = 0\n\n[CAMERA1]\nCameraID = 1\n\nMaxErrors=50\nSensitivity=0.5\n\n```\n\nYou can specify `MaxErrors` and `Sensitivity` for each camera separately. If these parameters are not specified, the default values will be used.\n\n\n## Installation on Raspberry Pi (Raspberry Pi OS)\n\n64 bit OS is required for PyTorch to work. Tested with [Raspberry Pi OS (Legacy, 64-bit)](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy-64-bit).\n\nInstall the pip package:\n```bash\npip install vigi\n```\n\nRun the agent:\n```bash\n./.local/bin/vigi --host 0.0.0.0\n```\n\nIf the object detection is slow on your device, you can try to run the agent with the `--disable-detection` option to disable it.\n\n# Notifications\n\nConsult the [Notifications](docs/notifications.md) document for more information on how to configure notifications.\n\n# Development\n\n## Run from the sources\n\n```bash\n# Set up a virtual environment\npython -m venv .venv\n. .venv/bin/activate\n\n# Install the required packages\npip install -r requirements.txt\n\n# run the agent\npython main.py\n```\n\n## Build a pip package\n\n```bash\npip install build\npython -m build\n```\n\n## Publish the package to PyPI\n\n```bash\npython -m pip install --upgrade twine\npython -m twine upload dist/*\n```\n\n## Run unit tests\n\nDownload a samples dataset for the motion detection tests from [here](https://drive.google.com/file/d/16yQZuHf3xB-Z6zYG6lGxxMP1umbxlIYd/view?usp=sharing) and extract it to the `agent/tests` directory.\n\nThen run the tests:\n\n```bash\npython -m unittest discover\n```\n\n## Test coverage\n\nTo generate a coverage report, run the following command:\n\n```bash\npip install coverage\ncoverage run -m unittest discover\ncoverage html\n```\n\n## Run PyLint\n\n```bash\npylint $(git ls-files '*.py')\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Camera surveillance system with motion detection and object recognition for home security.",
"version": "0.9.2",
"project_urls": {
"Changelog": "https://github.com/plashchynski/vigi/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/plashchynski/vigi/blob/docs/",
"Homepage": "https://github.com/plashchynski/vigi",
"Issues": "https://github.com/plashchynski/vigi/issues",
"Repository": "https://github.com/plashchynski/vigi.git"
},
"split_keywords": [
"camera",
" home security",
" motion detection",
" object recognition",
" surveillance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "def67afc63d76c3f0cea26f969f1f02f2c080a1c221d3631d6324424bab7248b",
"md5": "5c4feb71fb6757007d7c5278ca2495de",
"sha256": "f5bb4921de46c353956d2d8139a17c38197b2393e255f993d288c4b4f3e7c486"
},
"downloads": -1,
"filename": "vigi-0.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c4feb71fb6757007d7c5278ca2495de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 152068,
"upload_time": "2024-03-25T10:18:52",
"upload_time_iso_8601": "2024-03-25T10:18:52.115244Z",
"url": "https://files.pythonhosted.org/packages/de/f6/7afc63d76c3f0cea26f969f1f02f2c080a1c221d3631d6324424bab7248b/vigi-0.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61cbcae00ea99f296523778f566f0c1dd368ef140bae95d6205f5cbfb1b2fd63",
"md5": "dd65dd56fcab6c3d61e64d8ef80b6aff",
"sha256": "c5956c79117d1921a6c822d9ae60be3ef4dca157294a2a4e7bb48289a71f1b7c"
},
"downloads": -1,
"filename": "vigi-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "dd65dd56fcab6c3d61e64d8ef80b6aff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 160725,
"upload_time": "2024-03-25T10:18:55",
"upload_time_iso_8601": "2024-03-25T10:18:55.599835Z",
"url": "https://files.pythonhosted.org/packages/61/cb/cae00ea99f296523778f566f0c1dd368ef140bae95d6205f5cbfb1b2fd63/vigi-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 10:18:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plashchynski",
"github_project": "vigi",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "opencv-python",
"specs": [
[
"==",
"4.9.0.80"
]
]
},
{
"name": "flask",
"specs": [
[
"==",
"3.0.2"
]
]
},
{
"name": "bootstrap-flask",
"specs": [
[
"==",
"2.3.3"
]
]
},
{
"name": "ultralytics",
"specs": [
[
"==",
"8.1.14"
]
]
},
{
"name": "flask-caching",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "humanize",
"specs": [
[
"==",
"4.9.0"
]
]
},
{
"name": "twilio",
"specs": [
[
"==",
"9.0.0"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.2.0"
]
]
},
{
"name": "Flask-HTTPAuth",
"specs": [
[
"==",
"4.8.0"
]
]
}
],
"lcname": "vigi"
}
JSON
