add docs as github pages

Author: MichaelSchuldes

.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: docs 
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+            # Install a specific version of uv.
+            enable-cache: true
+            version: "0.6.12"
+            python-version: 3.12
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+      - run: mkdocs gh-deploy --force

.gitlab-ci.yml

@@ -50,9 +50,9 @@ create_doc:
     - apt-get update -q -y && apt-get install -y libgl1-mesa-dev
     - uv pip install --system -e .[test]
   script:
-    - pdoc ./omega_prime --html -o docs --force
+    - mkdocs build -d docs_build
   artifacts:
     when: always
     paths:
-     - "docs/**/*"
+     - "docs_build/**/*"
 

README.md

@@ -6,30 +6,30 @@
 [![](https://github.com/ika-rwth-aachen/omega-prime/workflows/CI/badge.svg)](https://github.com/ika-rwth-aachen/omega-prime/actions)
 [![](https://img.shields.io/pypi/pyversions/omega-prime.svg)](https://pypi.python.org/pypi/omega-prime/)
 [![](https://img.shields.io/github/issues-raw/ika-rwth-aachen/omega-prime.svg)](https://github.com/ika-rwth-aachen/omega-prime/issues)
-
+[![](https://img.shields.io/badge/Documentation-2e8b57)](https://ika-rwth-aachen.github.io/omega-prime)
 
 # Omega-Prime: Data Model, Data Format and Python Library for Handling Ground Truth Traffic Data 
 
 Data Model, Format and Python Library for ground truth data containing information on dynamic objects, map and environmental factors optimized for representing urban traffic. The repository contains:
 ### Data Model and Specification
-see [./docs/omega_prime_specification.md](https://github.com/ika-rwth-aachen/omega-prime/tree/main/docs/omega_prime_specification.md)
+see [Data Model & Specification](https://ika-rwth-aachen.github.io/omega-prime/omega_prime_specification/)
 
 - 🌍 **Data Model**: What signals exist and how these are defined.
 - 🧾 **Data Format Specification**: How to exchange and store those signals.
 
 ### Python Library
-  - 🔨 **Create** omega-prime files from many sources (see [./tutorial.ipynb](https://github.com/ika-rwth-aachen/omega-prime/blob/main/tutorial.ipynb)):
+  - 🔨 **Create** omega-prime files from many sources (see [./docs/notebooks/tutorial.ipynb](https://github.com/ika-rwth-aachen/omega-prime/blob/main/docs/notebooks/tutorial.ipynb)):
       - ASAM OSI GroundTruth trace (e.g., output of esmini)
       - Table of moving object data (e.g., csv data)
       - ASAM OpenDRIVE map
       - [LevelXData datasets](https://levelxdata.com/) through [lxd-io](https://github.com/lenvt/lxd-io)
       - Extend yourself by subclassing [DatasetConverter](omega_prime/converters/converter.py)
       - Use [omega-prime-trajdata](https://github.com/ika-rwth-aachen/omega-prime-trajdata) to convert motion prediction datasets into omega-prime 
-  - 🗺️ **Map Association**: Associate Object Location with Lanes from OpenDRIVE or OSI Maps (see [tutorial_locator.ipynb](https://github.com/ika-rwth-aachen/omega-prime/tree/main/tutorial_locatory.ipynb))
+  - 🗺️ **Map Association**: Associate Object Location with Lanes from OpenDRIVE or OSI Maps (see [./docs/notebooks/tutorial_locator.ipynb](https://github.com/ika-rwth-aachen/omega-prime/tree/main/docs/notebooks/tutorial_locatory.ipynb))
   - 📺 **Plotting** of data: interactive top view plots using [altair](https://altair-viz.github.io/)
   - ✅ **Validation** of data: check if your data conforms to the omega-prime specification (e.g., correct yaw) using [pandera](https://pandera.readthedocs.io/en/stable/)
   - 📐 **Interpolation** of data: bring your data into a fixed frequency
-  - 📈 **Metrics**: compute interaction metrics like PET, TTC, THW (see [tutorial_metrics.ipynb](https://github.com/ika-rwth-aachen/omega-prime/tree/main/tutorial_metrics.ipynb))
+  - 📈 **Metrics**: compute interaction metrics like PET, TTC, THW (see [./docs/notebooks/tutorial_metrics.ipynb](https://github.com/ika-rwth-aachen/omega-prime/tree/main/docs/notebooks/tutorial_metrics.ipynb))
     - Predicted and observed timegaps based on driving tubes (see [./omega_prime/metrics.py](https://github.com/ika-rwth-aachen/omega-prime/blob/main/omega_prime/metrics.py))
     - 2D-birds-eye-view visibility with [omega-prime-visibility](https://github.com/ika-rwth-aachen/omega-prime-visibility)
   - 🚀 **Fast Processing** directly on DataFrames using [polars](https://pola.rs/), [polars-st](https://oreilles.github.io/polars-st/)
@@ -48,7 +48,7 @@ To learn more about the example data read [example_files/README.md](https://gith
 `pip install omega-prime`
 
 ## Usage
-> A detailed introduction to the features and usage can be found in [tutorial.ipynb](https://github.com/ika-rwth-aachen/omega-prime/blob/main/tutorial.ipynb)
+> A detailed introduction to the features and usage can be found in [./docs/notebooks/tutorial.ipynb](https://github.com/ika-rwth-aachen/omega-prime/blob/main/docs/notebooks/tutorial.ipynb)
 
 Create an omega-prime file from an OSI GroundTruth message trace and an OpenDRIVE map:
 ```python

docs/README.md

@@ -0,0 +1,21 @@
+# Working with the documentation
+
+[mkdocs](https://www.mkdocs.org/) and [mkdocs-material](https://squidfunk.github.io/mkdocs-material) are used to create the documentation of this project.
+
+## Local
+
+1. Install dev dependencies (this install mkdocs and dependencies)
+`uv pip install -e .[test]`
+2. Create the documentation and start webserver serving them
+```
+mkdocs serve -a localhost:5555
+```
+or create the html pages with
+```
+mkdocs build -d docs_build
+```
+
+## Upload documentation to github-pages
+
+[Guide](https://www.mkdocs.org/user-guide/deploying-your-docs/)
+https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions

docs/api.md

@@ -0,0 +1,11 @@
+# API
+
+::: omega_prime.recording
+::: omega_prime.map
+::: omega_prime.map_odr
+
+::: omega_prime.locator
+
+::: omega_prime.converters.converter
+
+::: omega_prime.metrics

docs/cli.md

@@ -0,0 +1,4 @@
+::: mkdocs-typer2
+    :module: omega_prime.cli
+    :name: omega-prime
+    :pretty: true

docs/index.md

@@ -0,0 +1,49 @@
+
+# Omega-Prime: Data Model, Data Format and Python Library for Handling Ground Truth Traffic Data 
+
+Data Model, Format and Python Library for ground truth data containing information on dynamic objects, map and environmental factors optimized for representing urban traffic. The repository contains:
+## Data Model and Specification
+see [Data Model & Specification](omega_prime_specification.md)
+
+- 🌍 **Data Model**: What signals exist and how these are defined.
+- 🧾 **Data Format Specification**: How to exchange and store those signals.
+
+## Python Library
+  - 🔨 **Create** omega-prime files from many sources (see [Tutorials/Introduction](notebooks/tutorial.ipynb)):
+      - ASAM OSI GroundTruth trace (e.g., output of esmini),  Table of moving object data (e.g., csv data), ASAM OpenDRIVE map
+      - [LevelXData datasets](https://levelxdata.com/) through [lxd-io](https://github.com/lenvt/lxd-io)
+      - Extend yourself by subclassing [DatasetConverter](https://github.com/ika-rwth-aachen/omega-prime/blob/main/omega_prime/converters/converter.py#L52)
+      - Use [omega-prime-trajdata](https://github.com/ika-rwth-aachen/omega-prime-trajdata) to convert motion prediction datasets into omega-prime 
+  - 🗺️ **Map Association**: Associate Object Location with Lanes from OpenDRIVE or OSI Maps (see [Tutorials/Locator](notebooks/tutorial_locator.ipynb))
+  - 📺 **Plotting** of data: interactive top view plots using [altair](https://altair-viz.github.io/)
+  - ✅ **Validation** of data: check if your data conforms to the omega-prime specification (e.g., correct yaw) using [pandera](https://pandera.readthedocs.io/en/stable/)
+  - 📐 **Interpolation** of data: bring your data into a fixed frequency
+  - 📈 **Metrics**: compute interaction metrics like PET, TTC, THW (see [Tutorials/Metrics](notebooks/tutorial_metrics.ipynb))
+    - Predicted and observed timegaps based on driving tubes (see [./omega_prime/metrics.py](https://github.com/ika-rwth-aachen/omega-prime/blob/main/omega_prime/metrics.py))
+    - 2D-birds-eye-view visibility with [omega-prime-visibility](https://github.com/ika-rwth-aachen/omega-prime-visibility)
+  - 🚀 **Fast Processing** directly on DataFrames using [polars](https://pola.rs/), [polars-st](https://oreilles.github.io/polars-st/)
+
+
+## Installation
+`pip install omega-prime`
+
+
+## Acknowledgements
+
+This package is developed as part of the [SYNERGIES project](https://synergies-ccam.eu).
+
+<img src="https://raw.githubusercontent.com/ika-rwth-aachen/omega-prime/refs/heads/main/docs/synergies.svg"
+style="width:2in" />
+
+
+
+Funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or European Climate, Infrastructure and Environment Executive Agency (CINEA). Neither the European Union nor the granting authority can be held responsible for them. 
+
+<img src="https://raw.githubusercontent.com/ika-rwth-aachen/omega-prime/refs/heads/main/docs/funded_by_eu.svg"
+style="width:4in" />
+
+## Notice
+> The project is open-sourced and maintained by the [**Institute for Automotive Engineering (ika) at RWTH Aachen University**](https://www.ika.rwth-aachen.de/).
+> We cover a wide variety of research topics within our [*Vehicle Intelligence & Automated Driving*](https://www.ika.rwth-aachen.de/en/competences/fields-of-research/vehicle-intelligence-automated-driving.html) domain.
+> If you would like to learn more about how we can support your automated driving or robotics efforts, feel free to reach out to us!
+> ***opensource@ika.rwth-aachen.de***

docs/library.md

@@ -0,0 +1,93 @@
+## Recordings and Map Data
+
+The omega-prime library has two major components, the `Recording` and the `Map`.
+The `Recording` stores the dynamic object information and the map object.
+A recording is a continuous traffic observation and usually corresponds to an OSI trace or an MCAP recording.
+The dynamic object information is stored in the attribute `df` (for DataFrame) as a single polars DataFrame, where each row corresponds to the observation of a single moving object at a specific point in time.
+A convenience function to access this data in an object oriented manner are the `MovingObject` stored in `moving_objects` attribute of the `Recording`.
+For most operations, it is recommended to use the DataFrame stored in `df` directly, as polars provides a fast and flexible API for data manipulation.
+See the [Polars user guide](https://docs.pola.rs/) for more information on how to use polars DataFrames.
+The object polygons for each timestamp are accessible as shapely objects in the `polygon` column or as [`polars_st`](https://github.com/Oreilles/polars-st) geometries in the `geometry` column.
+It is recommended to make use of `polars_st` as much as possible instead of `shapely` since `polars_st` can utilize the benefits of using a DataFrame more effectively.
+
+
+```mermaid
+flowchart TB
+    
+    subgraph recording [Recording]
+        rec_map[map]@{ shape: doc }
+        df@{ shape: win-pane }
+        moving_objects@{ shape: docs } 
+    end
+    df -.- moving_objects
+
+    rec_map --> map
+    subgraph map [Map]
+        lane_boundaries@{ shape: docs }
+        lanes@{ shape: docs }
+    end
+
+    subgraph lane [Lane]
+        centerline
+        lane_polygon[polygon]
+        right_boundary_id@{ shape: doc }
+        left_boundary_id@{ shape: doc }
+    end
+
+    subgraph lane_boundary [LaneBoudary]
+        polyline
+    end
+    lanes --> lane
+    lane_boundaries --> lane_boundary
+    right_boundary_id --> lane_boundary
+    left_boundary_id --> lane_boundary
+    polyline -.- lane_polygon
+
+    subgraph moving_object [MovingObject]
+        
+    end
+    moving_objects --> moving_object
+```
+
+The `Map` stores the static map information, i.e., lanes and lane boundaries.
+Lanes and lane boundaries are derived form the ASAM OSI definition and are also corresponding to the concept of lanelets in Lanelet2.
+When working with the map data in python, the geometries of the map are represented through polygons or polylines (for boundaries and centerlines) using [shapely](https://shapely.readthedocs.io/en/stable/).
+
+`MovingObject`, `Lane` and `LaneBoundary` each have types and additional information corresponding to ASAM OSI definitions.
+The library uses [betterosi](https://github.com/ika-rwth-aachen/betterosi) as a python implementation of ASAM OSI.
+
+The omega-prime specification suggests the usage of ASAM OpenDRIVE maps as map data.
+This is supported through the `MapOdr` subclass of `Map`. 
+Additionally, this library provides subclasses for ASAM OSI maps through `MapOsi` and `MapOsiCenterline`, where the latter does not provide lane polygons and lane boundaries (which is needed for some datasets).
+In the future, `MapLanelet` will provide support for Lanelet2 maps.
+Thus, a key benefit of using this library is the unified interface to work with different map formats.
+
+See [Tutorials / Introduction](notebooks/tutorial) for examples of how to use omega-prime.
+
+## Converters
+
+The class `omega_prime.converters.DatasetConverter` aids in defining converters that transform existing data sources into the omega-prime format.
+For guidance on how to implement your own converter you can have a look at the `LxdConverter`, which translates the [LevelXData](https://levelxdata.com/) datasets into omega-prime.
+Additionally, you can have a look at [omega-prime-trajdata](https://github.com/ika-rwth-aachen/omega-prime-trajdata) to convert many motion prediction datasets into the omega-prime format.
+Examples of datasets that can be converted with `omega-prime-trajdata` into omega-prime are [NuPlan](https://www.nuscenes.org/nuplan), [NuScene](https://www.nuscenes.org/), [Argoverse2](https://www.argoverse.org/av2.html) and [Waymo Open Dataset - Motion](https://waymo.com/open/).
+Here, the class `TrajdataConverter` implements the `DatasetConverter`.
+
+Data that is available as ASAM OpenDRIVE and ASAM OSI traces does not need a conversion an can be directly used with `omega-prime`.
+Many simulation tools such as [esmini](https://github.com/esmini/esmini) or [CARLA](https://carla.org/) through [Carla-OSI-Service](https://github.com/DLR-TS/Carla-OSI-Service) support the logging of simulation data as OSI traces.
+These can be directly read in and analyzed with the omega-prime library.
+
+## Locator
+
+The `Locator` uses the `Map` object to locate `MovingObject`s or any polygon or coordinate onto the `Lane`s of the map.
+The `Locator` can assign lane occupancy to objects and derive s-t-coordinate (Frenet coordinates).
+
+See [Tutorials / Locator](notebooks/tutorial_locator) for examples of how to use the `Locator`.
+
+## Metrics
+
+The `MetricsManager` makes use of [Polars feature of lazy evaulation](https://docs.pola.rs/user-guide/concepts/lazy-api/#previewing-the-query-plan) to enable efficient computation of many, possible, dependent metrics.
+The metrics computation can be defined by subclassing `Metric` or, more easily by using the decorator `@omega_prime.metrics.metric` a function that computes your metric based on the `Recording.df`.
+Moreover, the `Metric` lets you define dependencies between metrics, e.g., `distance_traveled` needs to be computed to compute `timegaps`. 
+The `MetricsManager` then handles the dependencies automatically, and makes sure only the things you actually need are computed.
+
+See [Tutorials / Metrics](notebooks/tutorial_metrics) for examples of how to define and use the metric utilities.