{"id":18695235,"url":"https://github.com/milosz275/uav-collision-avoidance","last_synced_at":"2025-04-12T07:30:26.044Z","repository":{"id":257823651,"uuid":"755010828","full_name":"milosz275/uav-collision-avoidance","owner":"milosz275","description":"Python project regarding implementation of two UAVs physics and collision detection/avoidance simulation.","archived":false,"fork":false,"pushed_at":"2024-07-03T08:21:18.000Z","size":10189,"stargazers_count":3,"open_issues_count":12,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-12T19:02:42.377Z","etag":null,"topics":["collision-avoidance","collision-detection","physics-simulation","pypi-package","pyqt6","uavsimulation"],"latest_commit_sha":null,"homepage":"https://milosz275.github.io/uav-collision-avoidance","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/milosz275.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mldxo","buy_me_a_coffee":"mldxo"}},"created_at":"2024-02-09T08:41:48.000Z","updated_at":"2024-10-09T23:10:25.000Z","dependencies_parsed_at":"2024-10-12T19:02:56.022Z","dependency_job_id":"79effa63-3f08-48be-b5c3-b2a9830af502","html_url":"https://github.com/milosz275/uav-collision-avoidance","commit_stats":null,"previous_names":["milosz275/uav-collision-avoidance"],"tags_count":7,"template":false,"template_full_name":"milosz275/python-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosz275%2Fuav-collision-avoidance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosz275%2Fuav-collision-avoidance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosz275%2Fuav-collision-avoidance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milosz275%2Fuav-collision-avoidance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/milosz275","download_url":"https://codeload.github.com/milosz275/uav-collision-avoidance/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223502234,"owners_count":17155938,"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":["collision-avoidance","collision-detection","physics-simulation","pypi-package","pyqt6","uavsimulation"],"created_at":"2024-11-07T11:14:21.589Z","updated_at":"2024-11-07T11:14:22.432Z","avatar_url":"https://github.com/milosz275.png","language":"Python","funding_links":["https://github.com/sponsors/mldxo","https://buymeacoffee.com/mldxo"],"categories":[],"sub_categories":[],"readme":"# UAV Collision Avoidance\n\n[![pl](https://img.shields.io/badge/lang-pl-blue.svg)](https://github.com/mldxo/uav-collision-avoidance/blob/master/README.pl.md)\n[![Qt6](https://img.shields.io/badge/Qt-6.7-41cd52.svg)](https://img.shields.io/badge/Qt-6.7-41cd52.svg)\n[![Build](https://github.com/mldxo/uav-collision-avoidance/actions/workflows/python-app.yml/badge.svg)](https://github.com/mldxo/uav-collision-avoidance/actions/workflows/python-app.yml)\n[![CodeQL](https://github.com/mldxo/uav-collision-avoidance/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/mldxo/uav-collision-avoidance/actions/workflows/github-code-scanning/codeql)\n[![PyPI version](https://badge.fury.io/py/uav-collision-avoidance.svg)](https://badge.fury.io/py/uav-collision-avoidance)\n\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/mldxo/uav-collision-avoidance)\n\nPython3 project regarding implementation of two UAVs simulation with collision avoidance system based on geometrical approach. Project links:\n\n- [Github](https://github.com/mldxo/uav-collision-avoidance)\n- [PyPI](https://pypi.org/project/uav-collision-avoidance)\n\n## Research work\n\n### Introduction\n\n`UAV Collision Avoidance` is my Bachelor's thesis project meeting problem of UAVs safe cooperation in the 3D space. Project implements functional physics calculations, scalable GUI, realistic ADS-B probable collision avoidance systems and on-board flight planning. Application offers multithreaded realtime simulation presenting simulated aircrafts as well as linearly pre-rendered simulation allowing for quick algorithm effectiveness testing.\n\n### Documentation\n\n- [Docs](/docs/en/README.md)\n- [Wiki](https://github.com/mldxo/uav-collision-avoidance/wiki)\n\n### Premises\n\n1. System Definition: The system is defined as a 3-dimensional (3D) space using an XYZ coordinate system. X and Y represent a flat horizontal plane, while Z represents height above sea level.\n2. Physics Simulation: Physics are simulated by differentiating parts of the second according to appropriate formulas. The physics of Unmanned Aerial Vehicles (UAVs) are considered relative to the Earth's frame, separated from the aircraft's frame and wind relative frame. 3D space is flat, and the Earth's curvature is not considered. Gaining or losing altitude preserves the aircraft's speed. RPY frame is considered.[^6]\n3. Aircraft Characteristics: The aircraft are considered Horizontal Take-off and Landing (HTOL) drones. They can only move in the direction of their speed vectors. The form of the aircraft is approximated to a simple solid sphere.\n4. Environment: The space is shared by two or three UAVs. There are no other objects or wind gusts assumed in this environment.\n5. Aerodynamics: No aerodynamic lift force is assumed at this moment. When turning, aircraft always take the maximum angle change that physics allow, respecting its mass inertia. Maximum pitch and roll angles are considered `-45°, 45°` and `-90°, 90°` respectively, where positive pitch angle means climbing and positive roll angle means banking right. Angles are not approximated for realism preservation.\n6. Units of Measurement: The default distance units are meters $m$, speed is measured in meters per second $m/s$, and frame times are represented in milliseconds $ms$.\n\n### Algorithms\n\nBoth collision detection and avoidance algorithms rely on geometrical approach. They were presented in referenced paper[^4]. Collision detection differentiates between collision and head-on collision. The second one applies when UAVs have no distance between their projected center of masses collision, and the first one when it is every other type of contact.\n\n### Results\n\nGeometrical approach proves useful in collision detection and avoidance. The system is capable of avoiding collisions in most cases. The system is not perfect and can fail in some scenarios, especially when the aircrafts are too close to each other when conflict is detected. The system is energy-efficient and can be used in real-life scenarios.\n\nProposed test cases generation and evaluation system is simple and effective. It allows for quick testing of the system's effectiveness in various scenarios. The system can be further developed to include more complex scenarios and additional parameters.\n\n## Python Project\n\n### Technologies\n\nPython3[^1] project is wrapped as a PyPI package[^2]. PySide6[^3] (Qt's Python Qt6 library) was used for GUI implementation.\n\n### Structures\n\nApplication is built based on two main object types, simulation and aircraft. Simulation is created up to initial settings, allowing for concurrent realtime variant and linear pre-rendering. Aircraft consists of two elements, physical representation of the UAV and Flight Control Computer, which is controlled by the ADS-B thread. Research among the UAV systems was drawn on from second cited paper[^5].\n\n### Data\n\nSimulation data is stored in CSV format. Each row in the file represents a single simulation conducted. The columns in the CSV file represent detailed information about the test case, including initial and final parameters of the aircrafts, collision detection results, and minimal relative distance between the aircrafts for both cases with and without avoidance.\n\nExample simulation data files are stored in the data directory [data](/data). Results of 200 simulation tests conducted with 10 `Hz` simulation frequency are stored in the file [simulation-2024-06-10-00-21-19.csv](/data/simulation-2024-06-10-00-21-19.csv).\n\n### File tree\n\nThe file structure was generated using `tree` command:\n\n```bash\ntree --gitignore -I \"__pycache__|.env|.github|.pytest_cache|.vscode|assets|build|logs|path-visual|uav_collision_avoidance.egg-info|venv|docs\"\n```\n\nView the file structure here: [File structure](docs/en/README.md#code-structure)\n\n### App arguments\n\nThere are eight possible arguments at the moment:\n- default (no arguments) - runs GUI simulation; avoiding collision can be achieved by pressing T, when aircrafts have their safe zones occupied\n- realtime `file_path` `test_index` `collision_avoidance` - runs GUI simulation; file name can be specified and defaults to latest simulation data found; test index can be specified and defaults to 0; collision avoidance can be specified and defaults to off\n- headless - runs physical simulation with ADS-B and collision avoidance algorithm\n- tests `test_number` - runs full tests comparing effectiveness of collision avoidance algorithm, test number defaults to 15\n- ongoing - runs default test number in parallel comparing effectiveness of collision avoidance algorithm continuously till Ctrl+C\n- load `file_path` `test_index` - loads and conducts headless simulation from file when specified, otherwise loads default example test case from data directory [data](/data); test index can be specified and defaults to 0\n- help `argument` - prints help message for the app argument; defaults to all arguments list\n- version - prints version of the app\n\n### Key shortcuts\n\nRealtime version of the app has several key shortcuts allowing user interaction with the environment.\n\n\u003e [!NOTE]\n\u003e Aircraft 0 is the first one, Aircraft 1 is the second one.\n\nThere are several key shortcuts for realtime version of the app that allow full-scale testing.\n\n- Left mouse click - appends click location to the top of destination list of Aircraft 0\n- Right mouse click - adds click location to the end of destination list of Aircraft 0\n- Middle mouse click (scroll click) - teleports Aircraft 0 to the click location\n- Mouse wheel - zooms in/out the simulation render smoothly\n- Plus/minus keys (+/-) - zooms in/out the simulation render quickly\n- Arrow keys (↑ ↓ → ←) - moves the view\n- F1 key - toggles ADS-B Aircraft 0 info reporting\n- F2/F3 keys - speed down/up target speed of Aircraft 0\n- N key - toggles Aircraft 0/1 view following (default off)\n- M key - switches between Aircraft 0/1 view following (default 0)\n- O key - toggles Aircraft 0 targeting Aircraft 1's speed vector (default off)\n- P key - toggles Aircraft 1 targeting Aircraft 0's speed vector (default off)\n- T key - toggles collision avoidance maneuvering (default off)\n- WSAD keys - sets course for Aircraft 0 - 0, 180, 270, 90 degrees respectively\n- R - resets simulation to start state\n- Slash key (/) - pauses physics simulation\n- Escape key (Esc) - closes and ends simulation\n\n### Install\n\nInstall the app by running the following command:\n\n```bash\npip install uav-collision-avoidance\n```\n\n#### Debian 12 Dependencies\n\nFor Debian 12, you need to install the following dependencies:\n\n```bash\nsudo apt-get install libgl1 libxcb-xinerama0\n```\n\nTo run the app headless, you need to run the following export:\n\n```bash\nexport QT_QPA_PLATFORM=offscreen\n```\n\n### Usage\n\nUse any of the following to run the app:\n\n```bash\nuav-collision-avoidance\n```\n\n```bash\nuav-collision-avoidance realtime [file_name] [test_index] [collision_avoidance]\n```\n\n```bash\nuav-collision-avoidance headless\n```\n\n```bash\nuav-collision-avoidance tests [test_number]\n```\n\n```bash\nuav-collision-avoidance ongoing\n```\n\n```bash\nuav-collision-avoidance load [file_name] [test_index]\n```\n\n```bash\nuav-collision-avoidance help [argument]\n```\n\n```bash\nuav-collision-avoidance version\n```\n\n### Build\n\nBuild it by cloning the repo and running the following commands:\n\n\u003cp align=\"left\"\u003e\n    \u003cimg width=\"30px\" alt=\"Bash\" style=\"padding-right:10px;\" src=\"https://skillicons.dev/icons?i=bash\" /\u003e\n\u003c/p\u003e\n\n```bash\n#!/bin/bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\npython main.py [argument]\n```\n\n\u003cp align=\"left\"\u003e\n    \u003cimg width=\"30px\" alt=\"Powershell\" style=\"padding-right:10px;\" src=\"https://skillicons.dev/icons?i=powershell\" /\u003e\n\u003c/p\u003e\n\n```powershell\npython -m venv venv\n.\\venv\\Scripts\\activate\npip install -r requirements.txt\npython main.py [argument]\n```\n\n### Remarks\n\n3-dimensional (3D) world is projected on 2D screen by flattening height (z coordinate). On the program start, the view is not centered on any of the aircrafts. The view can be moved with arrow keys or centered on the aircraft using `N` key.\n\nOne coding convention is not preserved in the scope of the project. Qt's methods are CamelCase formatted and the rest is default Python naming convention including snake_case for variable and member names.\n\n## Current Work / TODOs\n\n- [ ] ADS-B: FCC angle optimization\n- [ ] Rendering: Aircraft centered view optimization\n- [x] Wiki: Documentation\n\n## Authors\n\n[Miłosz Maculewicz](https://github.com/mldxo)\n\n## License\nCheck [LICENSE](/LICENSE)\n\n## References\n\n\u003cp align=\"left\"\u003e\n    \u003cimg width=\"30px\" alt=\"Aircraft icon\" style=\"padding-right:10px;\" src=\"/assets/aircraft.png\" /\u003e\n\u003c/p\u003e\n\nDrone by Anthony Lui from \u003ca href=\"https://thenounproject.com/browse/icons/term/drone/\" target=\"_blank\" title=\"Drone Icons\"\u003eNoun Project\u003c/a\u003e (CC BY 3.0)\n\nAll used references are listed below.\n\n[^1]: [Python3](https://www.python.org/)\n[^2]: [PyPI](https://pypi.org/)\n[^3]: [PyQt6](https://doc.qt.io/qtforpython-6/)\n[^4]: [UAV Collision Avoidance Based on Geometric Approach](https://ieeexplore.ieee.org/document/4655013/)\n[^5]: [Energy Efficient UAV Flight Control Method in an Environment with Obstacles and Gusts of Wind](https://www.mdpi.com/1638452/)\n[^6]: [Aircraft principal axes](https://en.wikipedia.org/wiki/Aircraft_principal_axes)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilosz275%2Fuav-collision-avoidance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmilosz275%2Fuav-collision-avoidance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilosz275%2Fuav-collision-avoidance/lists"}