Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/aitoair/multiangle_video_annotation

A PyQt-based multi-angle video annotation tool for bounding boxes, polygons, and collaborative labeling—featuring offline caching, real-time sync, and auto-updates. (Work in progress, some parts are not yet fully functional.)
https://github.com/aitoair/multiangle_video_annotation

annotation auto-update bounding-box collaboration dual-video multi-angle offline-caching pyqt6 python video-annotation

Last synced: about 1 year ago
JSON representation

A PyQt-based multi-angle video annotation tool for bounding boxes, polygons, and collaborative labeling—featuring offline caching, real-time sync, and auto-updates. (Work in progress, some parts are not yet fully functional.)

Awesome Lists containing this project

README 

          
# Multi-Angle Video Annotation Tool



An advanced **PyQt**-based desktop application tailored for multi-angle (dual-view) video annotation.  

If you need to analyze recordings from multiple perspectives—such as manufacturing lines, sports performances, security systems, or any scenario needing side-by-side footage—this tool is built to streamline collaborative labeling, commenting, and exporting.



> **Note**: This project is still **work in progress**, and some parts of the source code are **not yet fully functional or tested**. Expect ongoing changes and potential incomplete features.



## Table of Contents

- [Highlights \& Benefits](#highlights--benefits)

- [Features Overview](#features-overview)

- [Installation](#installation)

  - [Prerequisites](#prerequisites)

  - [Installation Steps](#installation-steps)

  - [Running the Application](#running-the-application)

- [When to Use This Tool](#when-to-use-this-tool)

- [Usage Workflow](#usage-workflow)

- [Auto-Update Mechanism](#auto-update-mechanism)

- [Dual-Licensing](#dual-licensing)

- [License Text](#license-text)

- [Support / Contributions](#support--contributions)

- [Disclaimer](#disclaimer)



---



## Highlights & Benefits



- **Side-by-Side Playback**: Compare videos from two camera angles in perfect frame sync.  

- **Streamlined Annotations**: Quickly create bounding boxes, polygons, and textual comments.  

- **Real-Time Collaboration**: Multiple annotators can work together, with changes synced to a central server or used offline for later sync.  

- **Offline Caching**: Local SQLite caching allows you to continue labeling even without a network connection—annotations are uploaded when reconnected.  

- **Auto-Update Ready**: The app can check a central server for updated builds, minimizing downtime and ensuring all collaborators are on the same version.  

- **Extensible & Cross-Platform**: Built in Python/PyQt, deployable on Windows, macOS, or Linux.  

- **Export for Downstream Tasks**: Save your annotations in JSON or CSV for easy integration with machine learning pipelines, report generation, or archival.



---



## Features Overview



1. **Video Upload & Management**  

   - Users can select from existing videos on the server or local object storage (S3, etc.).  

   - Upload new videos directly within the app, with progress tracking.  

   - Easily remove unneeded videos (if no comments exist).



2. **Annotation Tools**  

   - **Bounding Boxes**: Quickly draw rectangular bounds around subjects of interest.  

   - **Polygons**: Define irregular shapes.  

   - **Comments**: Attach textual notes to frames, referencing bounding boxes.  

   - **Frame-by-Frame Navigation**: Step through frames with configurable “comma-unit” increments for precise labeling.



3. **Collaboration**  

   - Multiple users can annotate the same project simultaneously.  

   - Real-time or asynchronous merges handle concurrency.  

   - Uses a central collaboration server for authentication and data sync.



4. **Dual-Video Playback**  

   - Watch two synchronized video angles side by side.  

   - Keep exact frame alignment for multiple camera feeds.



5. **Data Export**  

   - Export annotations (bounding box coordinates, polygons, comments) in JSON, CSV, or other formats.  

   - Seamless integration with external tasks (computer vision, QA, etc.).



6. **Offline Caching**  

   - Edits and new annotations can be saved locally in SQLite, syncing automatically when reconnected.



7. **Auto-Update**  

   - The application can poll a server for a new version and download installers for easy upgrades.



---



## Installation



### Prerequisites



- **Python 3.7+**  

- Recommended usage of a virtual environment (e.g., `venv`, `conda`)  

- **PyQt6** for the GUI (or PySide6 if you prefer a different license structure)  

- Common Python libraries (OpenCV, Requests, etc.) as listed in `requirements.txt`



### Installation Steps



1. **Clone or Download** this repository:

   ```bash

   git clone https://github.com/AItoAir/multiangle_video_annotation.git

   ```

   > Or download the ZIP and extract.



2. **Install Dependencies**:

   ```bash

   pip install -r requirements.txt

   ```

   This step installs all necessary Python libraries, including `PyQt6` (or PySide6).



### Running the Application



#### Local (Development) Mode



1. **Configure Environment** (optional):

   - `APP_MODE=local` or `APP_MODE=dev` to skip or simplify login flow.

2. **Launch**:

   ```bash

   python -m app.main

   ```

   By default, this runs with a local dev server or bypasses login entirely, depending on your environment settings.



#### Building an Executable



Use PyInstaller or similar tools:



```bash

pyinstaller --noconfirm --onefile app/main.py

```



- Adjust for your operating system (Windows, macOS, Linux).

- Distribute the resulting binary to end-users with minimal dependencies.



---



## When to Use This Tool



- **Manufacturing**: Check products from multiple production line camera angles.  

- **Sports Analysis**: Label player positions from multi-angle replays.  

- **Security & Surveillance**: Combine feeds for comprehensive incident reports.  

- **Entertainment & Film**: Annotate multi-camera shoots (behind the scenes, stunts, etc.).  

- **Robotics & Autonomous Driving**: Multi-camera sensor input for training datasets.



Whenever you have multi-angle footage and need consistent, frame-synchronized annotation, this tool delivers an intuitive interface plus a robust collaboration backend.



---



## Usage Workflow



1. **Login** (if not in local bypass mode)  

   - Provide your credentials to obtain a token from the central collaboration server.

2. **Select a Project**  

   - The app fetches an up-to-date project list; you choose where to store annotations.

3. **Upload or Choose Existing Videos**  

   - In the “Video Selector” dialog, either pick from server-stored videos or upload new files.

4. **Annotate**  

   - Switch to **Comment Mode** (`C` key or menu) to draw bounding boxes, polygons, or add text notes.  

   - Step through frames with arrow keys or custom hotkeys.  

   - Annotations auto-save to the server or your local cache (syncing later if offline).

5. **Dual-Angle Playback**  

   - The application keeps both videos in sync. You can pause, step forward/back, or jump to comments.

6. **Export**  

   - From the **File** menu, export your annotation data (JSON, CSV, etc.).  

   - Integrate these outputs into your machine learning pipeline or for compliance/reporting.



---



## Auto-Update Mechanism



- **Version Check**: On app startup (or periodically), it queries the server for the latest version tag.  

- **Download & Install**: If an update is found, the user is prompted to download a new installer.  

- **Bootstrapper**: (On Windows) you can run the downloaded `.exe` to replace the old version, or a silent update mechanism can be scripted for your environment.



This ensures teams always work on the same release—minimizing annotation discrepancies.



---



## Dual-Licensing



This software uses **PyQt** under the **GNU GPLv3**. Thus, you have:



1. **GPLv3 License**  

   - Freely use, modify, and distribute the tool under GPLv3 terms.  

   - If you distribute a modified binary, you must share the source code under the same license.

2. **Commercial License**  

   - If GPLv3 obligations conflict with your business, a commercial license is available.  

   - Contact us to discuss terms.



---



## License Text



All code in this repository is **dual-licensed**. You may use, redistribute, and/or modify it under:



1. The terms of the **GNU General Public License v3.0** as published by the Free Software Foundation  

2. The terms of a **custom commercial license agreement** with the copyright holder  



A copy of the GPLv3 is available in `LICENSE.txt`.



---



## Support / Contributions



- **Issues & Pull Requests**: Found a bug or have a feature request? We welcome your input.  

- **Commercial Support**: For enterprise help, integration, or SLA-based services, please get in touch as indicated in the repository or official site.



---



## Disclaimer



This tool is provided “as is,” without warranty of any kind. Performance depends on your environment, network conditions, and server configuration. Always test thoroughly before deploying to production or critical tasks.



**Note**: Because this project is under active development, some code paths and functionalities may be incomplete. Future updates may change APIs or behavior without backward compatibility.