Metadata-Version: 2.1
Name: pycasx
Version: 1.0.0
Summary: A Python implementation of ACAS XA and ACAS XU for Flightgear.
Author-email: Johann Christensen <johann.christensen@dlr.de>
License: MIT License
        
        Copyright (c) <year> <copyright holders>
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Documentation, https://pycasx.readthedocs.io/
Project-URL: Homepage, https://github.com/DLR-KI/pycasx.git
Project-URL: Source, https://github.com/DLR-KI/pycasx.git
Project-URL: Tracker, https://github.com/DLR-KI/pycasx/-/issues
Platform: macosx_13_x86_64
Platform: manylinux2014_x86_64
Platform: win_amd64
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Games/Entertainment :: Simulation
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.12,>=3.8
Description-Content-Type: text/markdown; charset=UTF-8
License-File: LICENSES/CC-BY-4.0.txt
License-File: LICENSES/MIT.txt
Requires-Dist: flightgear-python==1.6.0
Requires-Dist: fastapi[all]==0.105.0
Requires-Dist: hydra-core==1.3.2
Requires-Dist: loguru==0.7.2
Requires-Dist: lxml==5.1.0
Requires-Dist: numpy==1.24.4
Requires-Dist: onnx==1.14.1
Requires-Dist: onnx2torch==1.5.12
Requires-Dist: onnxruntime==1.16.1
Requires-Dist: pillow==10.1.0
Requires-Dist: pint==0.21.1
Requires-Dist: pyproj==3.5.0
Requires-Dist: libtmux==0.31.0.post0
Requires-Dist: scipy==1.10.1
Requires-Dist: torch==2.1.0
Requires-Dist: tqdm==4.66.2
Requires-Dist: rich==13.7.1
Provides-Extra: all
Requires-Dist: pycasx[dev,docs,tests]; extra == "all"
Provides-Extra: dev
Requires-Dist: lxml-stubs; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: reuse>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx==7.1.2; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints==1.25.2; extra == "docs"
Requires-Dist: sphinx-rtd-theme==2.0.0; extra == "docs"
Requires-Dist: sphinx-autoapi==3.0.0; extra == "docs"
Provides-Extra: full
Requires-Dist: pycasx[all]; extra == "full"
Provides-Extra: tests
Requires-Dist: coverage; extra == "tests"
Requires-Dist: flake8-bugbear; extra == "tests"
Requires-Dist: flake8-builtins; extra == "tests"
Requires-Dist: flake8-comprehensions; extra == "tests"
Requires-Dist: flake8-docstrings-complete; extra == "tests"
Requires-Dist: flake8-docstrings; extra == "tests"
Requires-Dist: flake8-pyproject; extra == "tests"
Requires-Dist: flake8-simplify; extra == "tests"
Requires-Dist: flake8; extra == "tests"
Requires-Dist: mypy; extra == "tests"
Requires-Dist: parameterized; extra == "tests"
Requires-Dist: pep8-naming; extra == "tests"
Requires-Dist: pycodestyle; extra == "tests"
Requires-Dist: pydoclint; extra == "tests"
Requires-Dist: pylint-per-file-ignores; extra == "tests"
Requires-Dist: pylint; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest>=7.4.0; extra == "tests"
Requires-Dist: shapely; extra == "tests"
Requires-Dist: types-requests; extra == "tests"

<!--
SPDX-FileCopyrightText: 2024 German Aerospace Center (DLR) <https://dlr.de>

SPDX-License-Identifier: CC-BY-4.0
-->

# `pyCASX` &ndash; A Python implementation of ACAS X<sub>A</sub> and ACAS X<sub>U</sub> for Flightgear

[![The latest version of pycasx can be found on PyPI.](https://img.shields.io/pypi/v/pycasx.svg)](https://pypi.python.org/pypi/pycasx)
[![Information on what versions of Python pycasx supports can be found on PyPI.](https://img.shields.io/pypi/pyversions/pycasx.svg)](https://pypi.python.org/pypi/pycasx)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/DLR-KI/pycasx/main.svg)](https://results.pre-commit.ci/latest/github/DLR-KI/pycasx/main)
[![Docs status](https://readthedocs.org/projects/pycasx/badge/)](https://pycasx.readthedocs.io/)
[![REUSE status](https://api.reuse.software/badge/github.com/DLR-KI/pycasx)](https://api.reuse.software/info/github.com/DLR-KI/pycasx)

Implementation of ACAS X<sub>A</sub> and ACAS X<sub>U</sub> with neural networks for FlightGear.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [`pyCASX` – A Python implementation of ACAS XA and ACAS XU for Flightgear](#pycasx--a-python-implementation-of-acas-xa-and-acas-xu-for-flightgear)
  - [Description](#description)
  - [Installation](#installation)
    - [Requirements](#requirements)
    - [Users](#users)
      - [Installation via `pipx`](#installation-via-pipx)
      - [Installation via `pip`](#installation-via-pip)
    - [Development](#development)
    - [`pre-commit`](#pre-commit)
    - [VS Code](#vs-code)
  - [Usage](#usage)
    - [Launching ACAS X](#launching-acas-x)
    - [Other options](#other-options)
      - [`onnx` or `make_onnx`](#onnx-or-make_onnx)
      - [`launch`](#launch)
      - [`acasx`](#acasx)
    - [Overwriting parameters](#overwriting-parameters)
  - [Citation](#citation)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Description

Implementation of Horizontal- and VerticalCAS using neural networks for [FlightGear](https://www.flightgear.org/).
The HCAS and VCAS implementations are based upon Stanford Intelligent Systems Laboratory's [HorizontalCAS](https://github.com/sisl/HorizontalCAS) and [VerticalCAS](https://github.com/sisl/VerticalCAS).

## Installation

Please read the following sections carefully.
Please also see the documentation at <https://pycasx.readthedocs.io>.

### Requirements

- Python 3.8 or higher (3.12 is currently not supported)
- [FlightGear](https://www.flightgear.org/) 2020.3.18 or higher

### Users

If you only want to use `pycasx` as a command-line tool and not develop it, you can install it via `pip` or `pipx`.
However, `pipx` is recommended, as it will install the package in an isolated environment and thus not interfere with other packages.

#### Installation via `pipx`

Ensure you have [`pipx`](https://pipx.pypa.io/stable/) installed.
If not, install it via

```shell
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```

Afterwards, install `pycasx` via

```shell
pipx install git+https://https://github.com/DLR-KI/pycasx.git
```

#### Installation via `pip`

**This is not recommended! Proceed at your own risk! For just using the package, `pipx` is recommended**

First, clone the repository

```shell
git clone https://https://github.com/DLR-KI/pycasx.git
```

_Optional:_ create yourself a virtual environment and activate it.

```shell
pip install virtualenv
virtualenv .pycasx-venv
source .pycasx-venv/bin/activate
```

Now, install the package via

```shell
pip install -e .
```

for basic features.

**NOTE:** for some virtual environments, especially with Windows, you might need to use `python` instead of `python3`  and might also need to use `python -m pip` instead of `pip`.

### Development

First, clone the repository into a directory of your choice:

```shell
git clone https://https://github.com/DLR-KI/pycasx.git
```

Then, it is recommended to create a virtual environment for the software:

```shell
pip install virtualenv
virtualenv .pycasx-venv
source .pycasx-venv/bin/activate
```

Afterwards, install the software and its dependencies:

```shell
pip install -e '.[all]'
```

Next, install the provided pre-commit hooks:

```shell
pre-commit install
```

### `pre-commit`

Prior to any commit, the hooks defined in [`.pre-commit-config.yaml`](./.pre-commit-config.yaml) will be ran.
A failure in any hook will block the commit.
Although, most of the errors, like formatting, will correct themselves.
You just have to re-add all changed files and commit again.
Be also aware, that the pipeline can take a few seconds to complete.

Alternatively, you can run the pipeline at any time to invoke changes before they block commits with

```shell
pre-commit run --all-files
```

Running the pre-commit pipeline manually once before the first commit is recommended.
It will install all required tools and dependencies and you'll see what's going on.
Otherwise you might be surprised why committing takes so long.

### VS Code

For VS Code, we provide a set of recommended extensions.
Please install them to smooth the development process.
You'll find them in your extensions tab under the _Workspace Recommendations_ section.

## Usage

This package provides a command-line interface with the `pycasx` command.
General information is available via `pycasx [-h|--help]` and the current version via `pycasx [-v|--version]`.
All other commands are explained in the following.

### Launching ACAS X

You can launch FlightGear via

```shell
pycasx launch
```

Once FlightGear is up and running, just run:

```shell
pycasx acasx
```

This will start the ACAS X with the default settings.

### Other options

#### `onnx` or `make_onnx`

```shell
pycasx onnx
```

Convert the provided `.nnet` files into `.onnx` files.
This is required if one wants to use the ONNX or PyTorch backend.
**BE WARNED: BOTH THE ONNX AND PYTORCH BACKEND ARE EXPERIMENTAL AND NOT FULLY TESTED. THE RESULTING ADVISORIES ARE NOT VALID!**

#### `launch`

```shell
pycasx launch
```

Launch FlightGear with options defined in [`pycasx/cli/launch.py`](./pycasx/cli/launch.py).

#### `acasx`

```shell
pycasx acasx
```

Runs the ACAS X with the default settings.
This includes the API backend to fetch the advisories via REST calls.
Please see the official documentation for more information.

### Overwriting parameters

Every launch script has a set of default parameters.
Those are handled via [Hydra](https://hydra.cc/).
Accordingly, overwriting parameters can be achieved by following the [Hydra documentation](https://hydra.cc/docs/advanced/override_grammar/basic/).

Nevertheless, overwriting (or adding) new default properties for `pycasx launch` is not as straight forward as one might try.
The correct syntax to overwrite (or add) a default property is

```shell
pycasx launch ++prop='{/autopilot/settings/target-speed-kt: 123456789}'
```

## Citation

If you found our work useful, please cite our paper:

```text
@InProceedings{Christensen2024,
  author    = {Christensen, Johann Maximilian and Anilkumar Girija, Akshay and Stefani, Thomas and Durak, Umut and Hoemann, Elena and K{\"{o}}ster, Frank and Kr{\"{u}}ger, Thomas and Hallerbach, Sven},
  booktitle = {36th {IEEE} International Conference on Tools with Artificial Intelligence ({ICTAI})},
  date      = {2024-10},
  title     = {Advancing the AI-Based Realization of ACAS X Towards Real-World Application},
}
```
