Metadata-Version: 2.4
Name: OTAnalytics
Version: 0.6.7
Summary: OTAnalytics is a core module of the OpenTrafficCam framework to perform traffic analysis on trajectories of road users.
Project-URL: Homepage, https://opentrafficcam.org/
Project-URL: Documentation, https://opentrafficcam.org/overview/
Project-URL: Repository, https://github.com/OpenTrafficCam/OTAnalytics
Project-URL: Issues, https://github.com/OpenTrafficCam/OTAnalytics/issues
Project-URL: Changelog, https://github.com/OpenTrafficCam/OTAnalytics/releases
Author-email: OpenTrafficCam contributors <team@opentrafficcam.org>, platomo GmbH <info@platomo.de>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: OpenTrafficCam,Traffic Analysis,Traffic Counting,Trajectories
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: av==13.0.0
Requires-Dist: customtkinter==5.2.2
Requires-Dist: fastapi==0.115.5
Requires-Dist: ijson==3.3.0
Requires-Dist: matplotlib==3.10.0
Requires-Dist: more-itertools==10.5.0
Requires-Dist: nicegui==2.11.0
Requires-Dist: numpy==2.1.1
Requires-Dist: openpyxl==3.1.5
Requires-Dist: pandas==2.2.3
Requires-Dist: pillow==11.1.0
Requires-Dist: requests==2.32.3
Requires-Dist: seaborn==0.13.2
Requires-Dist: shapely==2.0.7
Requires-Dist: starlette==0.41.2
Requires-Dist: tqdm==4.67.1
Requires-Dist: ujson==5.10.0
Requires-Dist: uvicorn==0.32.1
Description-Content-Type: text/markdown

# OTAnalytics

[![PyPI version](https://img.shields.io/pypi/v/OTAnalytics.svg)](https://pypi.org/p/OTAnalytics/)
[![Tests](https://github.com/OpenTrafficCam/OTAnalytics/actions/workflows/test.yml/badge.svg?tag=latest)](https://github.com/OpenTrafficCam/OTAnalytics/actions/workflows/test.yml?query=tag%3Alatest)
[![Tests](https://github.com/OpenTrafficCam/OTAnalytics/actions/workflows/build-release.yml/badge.svg)](https://github.com/OpenTrafficCam/OTAnalytics/actions/workflows/build-release.yml)

OTAnalytics is a core module of the [OpenTrafficCam framework](https://github.com/OpenTrafficCam) designed to perform
traffic analysis on trajectories of road users tracked by [OTVision](https://github.com/OpenTrafficCam/OTVision) or
other tools in videos recorded by [OTCamera](https://github.com/OpenTrafficCam/OTCamera) or other camera systems.

## Overview

OTAnalytics provides tools for analyzing traffic data, including:

- Processing trajectory data of road users
- Defining and analyzing traffic flows
- Counting vehicles/road users assigned to flows
- Generating event lists and statistics
- Visualizing traffic data

The application offers multiple user interfaces:

- A graphical desktop interface (using CustomTkinter)
- A command-line interface for automation and batch processing

## Installation

### Requirements

- Python 3.12 or higher
- Dependencies listed in [requirements.txt](requirements.txt)

### Installation from GitHub Releases (Recommended)

The easiest way to install OTAnalytics is to download the latest release from
the [GitHub Releases page](https://github.com/OpenTrafficCam/OTAnalytics/releases).

1. Go to the [OTAnalytics Releases page](https://github.com/OpenTrafficCam/OTAnalytics/releases)
2. Download the latest release for your operating system
3. Extract the downloaded archive
4. Run the application using the instructions in the [Usage](#usage) section

### Installation from Source (Linux/macOS)

If you prefer to install from source:

1. Clone the repository:

   ```bash
   git clone https://github.com/OpenTrafficCam/OTAnalytics.git
   cd OTAnalytics
   ```

2. Run the installation script:
   ```bash
   ./install.sh
   ```

### Installation from Source (Windows)

If you prefer to install from source:

1. Clone the repository:

   ```cmd
   git clone https://github.com/OpenTrafficCam/OTAnalytics.git
   cd OTAnalytics
   ```

2. Run the installation script:
   ```cmd
   install.cmd
   ```

## Usage

### Starting the Application

#### Desktop GUI (Default)

On Linux/macOS:

```bash
./start_gui.sh
```

On Windows:

```cmd
start_gui.cmd
```

#### Command Line Interface

On Linux/macOS:

```bash
./start_gui.sh --cli
```

On Windows:

```cmd
start_gui.cmd --cli
```

### Configuration

OTAnalytics can be configured using:

1. Command-line arguments
2. Configuration files (YAML format)

Example configuration options:

- Specify track files for analysis
- Define flow and section configurations using otflow files
- Configure export formats and counting intervals
- Control parallelization with multiple processes
- Include or exclude specific road user classes

## Features

- **Track Analysis**: Process and analyze trajectory data from various sources
- **Flow Definition**: Define and analyze traffic flows between sections
- **Counting**: Count road users assgined to flows with configurable time intervals
- **Event Detection**: Generate event lists when road users cross defined sections
- **Visualization**: Visualize tracks, flows, and sections
- **Export**: Export analysis results in various formats
- **Filtering**: Filter tracks by road user class and time
- **Parallelization**: Process data using multiple CPU cores

## Documentation

For detailed instructions on how to install and use OTAnalytics, please refer to
the [official documentation](https://opentrafficcam.org/OTAnalytics).

- [Installation Guide](https://opentrafficcam.org/OTAnalytics/installation/)
- [User Interface Guide](https://opentrafficcam.org/OTAnalytics/usage-ui/)

## Contributing

We appreciate your support in the form of both code and comments. Please have a look at
the [contribute](https://opentrafficcam.org/contribute) section of the OpenTrafficCam documentation for guidelines on
how to contribute to this project.

## License

This software is licensed under the [GPL-3.0 License](LICENSE)

## Contact

- GitHub: [https://github.com/OpenTrafficCam](https://github.com/OpenTrafficCam)
- Email: [team@opentrafficcam.org](mailto:team@opentrafficcam.org)
