{"id":24576112,"url":"https://github.com/edoardotosin/objecttracker","last_synced_at":"2026-05-09T09:12:55.934Z","repository":{"id":272914521,"uuid":"917095998","full_name":"EdoardoTosin/ObjectTracker","owner":"EdoardoTosin","description":"Lightweight, real-time object detection and video recording tool.","archived":false,"fork":false,"pushed_at":"2025-03-11T10:50:48.000Z","size":12070,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-11T11:37:10.031Z","etag":null,"topics":["object-detection","object-tracking","opencv","python","raspberry-pi","real-time","video-recording"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EdoardoTosin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-15T10:50:38.000Z","updated_at":"2025-03-11T10:50:56.000Z","dependencies_parsed_at":"2025-01-17T12:30:09.000Z","dependency_job_id":"c8974fdc-511d-4b6c-b0b1-b4edd02dc368","html_url":"https://github.com/EdoardoTosin/ObjectTracker","commit_stats":null,"previous_names":["edoardotosin/objecttracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/EdoardoTosin/ObjectTracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdoardoTosin%2FObjectTracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdoardoTosin%2FObjectTracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdoardoTosin%2FObjectTracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdoardoTosin%2FObjectTracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EdoardoTosin","download_url":"https://codeload.github.com/EdoardoTosin/ObjectTracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdoardoTosin%2FObjectTracker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261434235,"owners_count":23157210,"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":["object-detection","object-tracking","opencv","python","raspberry-pi","real-time","video-recording"],"created_at":"2025-01-23T22:21:29.032Z","updated_at":"2026-05-09T09:12:55.898Z","avatar_url":"https://github.com/EdoardoTosin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ObjectTracker\n\nObjectTracker is a lightweight, real-time object detection and video recording tool built for Raspberry Pi, Linux, and Windows. It uses OpenCV's DNN module with a pre-trained MobileNet SSD model to detect specified objects and automatically start recording when detections occur.\n\n## Features\n\n- **Real-time Object Detection**: Detect specified objects in real-time using OpenCV's DNN module and MobileNet SSD.\n \n- **Event-based Video Recording**: Automatically starts recording when objects are detected, with a configurable duration to continue recording after the last detection.\n\n- **Customizable Detection**: Supports detection of specific objects or all detectable classes via CLI arguments or configuration files.\n\n- **Automatic Camera Reconnection**: Automatically attempts to reconnect in case of camera disconnection during runtime.\n\n- **Organized Video Storage**: Videos are saved in a structured format under the `recordings/` folder, organized by date.\n\n- **Docker Support**: Deploy effortlessly using Docker with an optional `docker-compose.yml` setup.\n\n## Installation\n\n### Method 1: Using Python Directly\n\n1. **Clone the repository**\n   \n   First, clone the repository to your local machine by running:\n   \n   ```bash\n   git clone https://github.com/EdoardoTosin/ObjectTracker\n   cd ObjectTracker\n   ```\n\n2. **Install dependencies**\n   \n   Ensure you have Python 3.9+ installed. If not, you can download it from the official Python website. Once you have the correct version, install the necessary Python dependencies:\n   \n   ```bash\n   pip install --user -r requirements.txt\n   ```\n   \n   This command installs the required packages, including those needed for object detection.\n\n### Method 2: Using Docker (for containerized setup)\n\n1. **Install Docker**\n   \n   If you don’t have Docker installed, you can download and install it from [Docker's website](https://www.docker.com/get-started).\n\n2. **Clone the repository**\n   \n   As with the Python method, first clone the repository to your local machine:\n   \n   ```bash\n   git clone https://github.com/EdoardoTosin/ObjectTracker\n   cd ObjectTracker\n   ```\n\n3. **Build the Docker image**\n   \n   Build the Docker image for the project using the following command:\n   \n   ```bash\n   docker build -t object-tracker .\n   ```\n\n4. **Run the Docker container**\n   \n   Run the container, mapping the `recordings` folder to your local machine’s folder for easy access:\n   \n   ```bash\n   docker run --rm -v $(pwd)/recordings:/app/recordings object-tracker\n   ```\n   \n   This will start the application within the Docker container. You can modify the path to the `recordings` folder if needed.\n\n5. **Alternatively: Use Docker Compose**\n   \n   If you'd like an even easier setup with pre-configured environment settings, you can use Docker Compose. Run the following command:\n   \n   ```bash\n   docker-compose up --build\n   ```\n   \n   Docker Compose will handle the image build and container execution automatically.\n\n## Usage\n\n### 1. Running the object detection system\n\n- **Using Python directly**:\n   \n   To run the object detection system, execute the following command:\n   \n   ```bash\n   python src/main.py\n   ```\n\n- **Using Docker**:\n\n   After building and running the Docker container, it will automatically start the object detection system.\n\n### 2. Detect specific objects\n\nTo detect specific objects like a \"person\" or \"car,\" use the `--objects` flag followed by a comma-separated list of object names. Whitespace around names is automatically trimmed:\n\n```bash\npython src/main.py --objects person, car, traffic light\n```\n\n- **Note**: Both `person, car, traffic light` and `person , car , traffic light` are handled correctly.\n\n- **Using Docker**:\n   \n   If running via Docker, this step should be handled by passing the same arguments during container execution.\n\n### 3. Detect all objects\n\nTo detect all objects, use the `--objects` flag with the value `all`:\n\n```bash\npython src/main.py --objects all\n```\n\n- **Using Docker**:\n   \n   You can modify the Docker command to pass the desired arguments in the same way.\n\n### 4. View Available Command-Line Options\n\nTo get a full list of available options, run:\n\n```bash\npython src/main.py --help\n```\n\nThis will show you all available parameters, including those for specifying which objects to detect, input files, output formats, etc.\n\n- **Using Docker**:\n   \n   The same command applies in the Docker container as well for accessing available help options.\n\n## Configuration\n\nThe main configuration file is `config/config.yaml`. You can customize parameters like objects to detect, recording duration, and buffer size.\n\n### Key Configuration Parameters\n\n- **Objects to Detect**\n  Specify a comma-separated list of object names (whitespace is automatically trimmed) or use `\"all\"` to detect everything:\n  ```yaml\n  objects_to_detect: \"person, car, traffic light\"\n  ```\n\n  To detect all objects:\n  ```yaml\n  objects_to_detect: all\n  ```\n\n- **Recording Settings**\n  Control the recording behavior:\n  ```yaml\n  recording_duration: 30        # Duration in seconds to keep recording after the last detection\n  buffer_size: 50               # Number of frames to buffer before starting recording\n  reconnect_interval: 5         # Time in seconds to wait before attempting camera reconnection\n  ```\n\n- **Output Folder**\n  Specify a custom folder for recordings:\n  ```yaml\n  recordings_folder: \"path/to/custom/folder\"\n  ```\n\n## File Descriptions\n\n### `src/main.py`\n\nThe main script that initializes the detection system, manages camera input, and handles video recording.\n\n### `config/config.yaml`\n\nContains user-defined parameters like object detection list, recording duration, and buffer settings.\n\n### `detector/object_detector.py`\n\nImplements object detection logic using OpenCV's DNN module, processing frames and identifying specified objects.\n\n### `detector/recorder.py`\n\nHandles video recording, buffering frames, and saving videos to the `recordings/` folder.\n\n### `docker-compose.yml`\n\nSimplifies deployment in a Docker environment, managing volume mounting and build steps.\n\n## Customization\n\n### Changing Camera Index\n\nIf multiple cameras are available, use the `--camera-index` argument to specify which one to use:\n\n```bash\npython src/main.py --camera-index 1\n```\n\n### Specifying Objects to Detect\n\nYou can define the objects to detect either in `config.yaml` or directly via CLI arguments:\n\n```bash\npython src/main.py --objects \"person, car, traffic light\"\n```\n\n## Contributing\n\nContributions are welcome! Follow these steps to contribute:\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/your-feature`).\n3. Commit your changes (`git commit -am 'Add a new feature'`).\n4. Push the branch (`git push origin feature/your-feature`).\n5. Create a pull request.\n\nPlease read the [CONTRIBUTING.md](CONTRIBUTING.md) file for more details.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.\n\n## Acknowledgments\n\nThis project was built using:\n\n- [OpenCV](https://opencv.org/)\n- Pre-trained MobileNet SSD model\n- Python 3.9+\n- Docker\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedoardotosin%2Fobjecttracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedoardotosin%2Fobjecttracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedoardotosin%2Fobjecttracker/lists"}