add new ut version and update links to latest version (#5)

Author: klit-la

.gitignore

@@ -5,6 +5,9 @@
 doc/build
 doc/source/user_guide/faq/index.rst
 doc/source/user_guide/data_visualization/index.rst
+doc/source/user_guide/data_analysis/index.rst
+doc/source/user_guide/data_loading_and_saving/index.rst
+
 *api
 
 # distribution

.gitlab-ci.yml

@@ -59,7 +59,7 @@ image_base:
             RUN mkdir /deps
             COPY dist/*.whl /deps/
             RUN pip install /deps/*.whl; rm -r /deps;
-            RUN dlr-downloader --name urban --version 1.1.0 --path /tmp;
+            RUN dlr-downloader --name urban --version 1.2.0 --path /tmp;
             RUN python -c 'import tilemapbase; tilemapbase.init(create=True)'" > dockerfile
 
         - |

doc/source/user_guide/data_loading_and_saving/dlr-ut-dataset.pct.py

@@ -1,24 +1,24 @@
 #%% [markdown]
 # # DLR Urban Traffic Dataset (DLR UT)
 #
-# This example should give a short overview on how to load the [Urban Traffic
-# Dataset](https://zenodo.org/records/11396372) which is hosted on Zenodo. 
+# This example should give a short overview on how to load the [DLR Urban Traffic
+# Dataset](https://doi.org/10.5281/zenodo.11396371) which is hosted on Zenodo.
 #
 # ## Download dataset
 #
 # At first, we need to download the dataset. For that purpose, helper classes
 # are available in `tasi` that we will utilize in the following. In particular,
 # since we want to download the DLR UT dataset, we use the. The class contains a
 # `tasi.dlr.dataset.DLRUTVersion` enumerator that may be used to
-# specify the version of the dataset to download. 
+# specify the version of the dataset to download.
 # %%
 import os
 from tasi.dlr.dataset import DLRUTDatasetManager, DLRUTVersion
 
-dataset = DLRUTDatasetManager(DLRUTVersion.v1_1_0)
+dataset = DLRUTDatasetManager(DLRUTVersion.v1_2_0)
 path = dataset.load(path='/tmp')
 path
-#%% [markdown] 
+#%% [markdown]
 # The dataset is now available in the `/tmp` directory. Let's have
 # a look into the dataset and list the available traffic information
 #%%
@@ -30,19 +30,19 @@
 # We can now utilize the `tasi.dlr.dataset.DLRTrajectoryDataset` class to load
 # the trajectory data from the directory. For demonstration purpose, let's load
 # the first batch of the dataset.
-#%% 
+#%%
 from tasi.dlr import DLRTrajectoryDataset
 
 ds = DLRTrajectoryDataset.from_csv(dataset.trajectory("/tmp")[0])
 ds
 #%% [markdown]
 # Note that the `Dataset` is represented as a `pandas.DataFrame` since it
 # inherits from it. The index of the `Dataset` contains the `timestamp` of a
-# traffic participant's state and its `id` as a unique identifier. 
+# traffic participant's state and its `id` as a unique identifier.
 #
 # The traffic participant's state include various information, including the
-# center position, the velocity, dimension and classification type.  
-#  
+# center position, the velocity, dimension and classification type.
+#
 # ## Load traffic light data
 #
 # The DLR UT dataset also contains information of the traffic lights. We utilize
@@ -58,7 +58,7 @@
 #
 # The DLR Research Intersection is equipped with a weather station stat collects
 # various information. We can utilize the `tasi.dataset.WeatherDataset` to load
-# some of this information. 
+# some of this information.
 #%%
 from tasi.dataset import WeatherDataset
 
@@ -83,5 +83,24 @@
 
 road_conditions = RoadConditionDataset.from_csv(dataset.road_condition("/tmp")[0])
 road_conditions
+# %% [markdown]
+# ## Load traffic volume data
+#
+# The DLR UT dataset contains meta information like traffic volume data that were extracted from the raw trajectory data.
+# %%
+from tasi.dataset import TrafficVolumeDataset
+
+traffic_volume = TrafficVolumeDataset.from_csv(dataset.traffic_volume("/tmp")[0])
+traffic_volume
+# %% [markdown]
+# ## Load OpenSCENARIO files
+#
+# The DLR UT dataset contains the trajectory data in OpenSCENARIO format.
+# %%
+from tasi.dataset import TrafficVolumeDataset
+
+openscenario_files = dataset.openscenario("/tmp")
+openscenario_files
+
 #%% [markdown]
-# That's it for now. We hope this page helps you get started 😎
+# That's it for now. We hope this page helps you get started 😎

doc/source/user_guide/data_visualization/trajectory.pct.py

@@ -2,17 +2,18 @@
 # # Visualization of trajectories
 # If we work with trajectory data, we often want to visualize them from a
 # so called `birds eye view`. The following example demonstrates how to achieve
-# this with `tasi` using the [Urban Traffic
-# Dataset](https://zenodo.org/records/11396372).
+# this with `tasi` using the [DLR Urban Traffic Dataset](https://doi.org/10.5281/zenodo.11396371).
 #
 # ## Load trajectories
 # At first, let's load trajectories from the DLR dataset.
 # %%
 from tasi.dlr.dataset import DLRUTDatasetManager, DLRUTVersion
 from tasi.dlr import DLRTrajectoryDataset
 
-dataset = DLRUTDatasetManager(DLRUTVersion.v1_1_0)
-ds = DLRTrajectoryDataset.from_csv(dataset.trajectory("/tmp")[0])
+dataset = DLRUTDatasetManager(DLRUTVersion.v1_2_0)
+# select a trajectory file from the middle of the dataset to include data from all object classes
+ut = DLRTrajectoryDataset.from_csv(dataset.trajectory("/tmp")[48])
+ut
 # %% [markdown]
 # ## Plot trajectories
 # We now utilize the `TrajectoryPlotter` to visualize the trajectories of the
@@ -24,28 +25,31 @@
 f, ax = plt.subplots()
 
 plotter = TrajectoryPlotter()
-plotter.plot(ds, ax=ax)
+plotter.plot(ut, ax=ax)
 # %% [markdown]
 # ### Change trajectory color
 # Note that the trajectories are colorized with the default color which we can
 # change so any arbitrary color, such as `lightgray`.
 # %%
 f, ax = plt.subplots()
-plotter.plot(ds, ax=ax, color="lightgray")
+plotter.plot(ut, ax=ax, color="lightgray")
 # %% [markdown]
 # ### Change color of a specific trajectory
 # You can also define the color of a specific trajectory.
 # %%
 f, ax = plt.subplots()
-plotter.plot(ds, ax=ax, color="black", trajectory_kwargs={ds.ids[-1]: {"color": "red"}})
+plotter.plot(ut, ax=ax, color="black", trajectory_kwargs={
+    ut.ids[-20]: {
+        "color": "red"
+    }
+})
 # %% [markdown]
 # ### Change trajectory opacity
 # or even change the opacity of each trajectory to quickly get an overview of
-# the traffic density. Let's change the opacity to 10% via the `alpha` argument
-# and set the color to `black`.
+# the traffic density. Let's change the opacity to 20% via the `alpha` argument.
 # %%
 f, ax = plt.subplots()
-plotter.plot(ds, ax=ax, color="black", alpha=0.1)
+plotter.plot(ut, ax=ax, alpha=0.2)
 # %% [markdown]
 # The plot already indicates the various traffic volumes on the different routes
 # at the intersection.
@@ -60,14 +64,12 @@
 f, ax = plt.subplots()
 
 # plot the orthophoto first
-roi = np.array([604675, 5792680, 604875, 5792870]).reshape(-1, 2)
-
-bbox_plotter = BoundingboxPlotter(roi, LowerSaxonyOrthophotoTile())
+bbox_plotter = BoundingboxPlotter(ut.roi, LowerSaxonyOrthophotoTile())
 bbox_plotter.plot(ax)
 
 # and the trajectories on top
 tj_plotter = TrajectoryPlotter()
-tj_plotter.plot(ds, ax=ax)
+tj_plotter.plot(ut, ax=ax)
 
 # hide the axis
 _ = ax.axis("off")
@@ -79,7 +81,7 @@
 f, ax = plt.subplots()
 
 bbox_plotter.plot(ax, alpha=0.5)
-tj_plotter.plot(ds, ax=ax, alpha=0.25)
+tj_plotter.plot(ut, ax=ax, alpha=0.25)
 
 _ = ax.axis("off")
 
@@ -96,28 +98,18 @@
 # load dataset
 dataset = DLRHTDatasetManager(DLRHTVersion.v1_0_0)
 path = dataset.load(path="/tmp")
-ds = DLRTrajectoryDataset.from_csv(
-    dataset.trajectory("/tmp")[3]
-)  # use 3 as it contains objects from all object classes
+# use 3 as it contains objects from all object classes
+ht = DLRTrajectoryDataset.from_csv(dataset.trajectory("/tmp")[3])
 
 f, ax = plt.subplots()
 
 # plot the orthophoto first
-roi = np.array(
-    [
-        ds.center.easting.min(),
-        ds.center.northing.min(),
-        ds.center.easting.max(),
-        ds.center.northing.max(),
-    ]
-).reshape(-1, 2)
-
-bbox_plotter = BoundingboxPlotter(roi, LowerSaxonyOrthophotoTile())
+bbox_plotter = BoundingboxPlotter(ht.roi, LowerSaxonyOrthophotoTile())
 bbox_plotter.plot(ax)
 
 # and the trajectories on top
 tj_plotter = DLRTrajectoryPlotter()
-tj_plotter.plot(ds, ax=ax)
+tj_plotter.plot(ht, ax=ax)
 
 # hide the axis
 _ = ax.axis("off")

tasi/dlr/dataset.py

@@ -6,6 +6,7 @@
 from pathlib import Path
 from typing import List
 
+import numpy as np
 import requests
 from tqdm import tqdm
 
@@ -98,9 +99,7 @@ def load(self, path: Path) -> str:
         # define final path
         export_path = path.joinpath(self.name)
 
-        logging.info(
-            "Checking if dataset already downloaded %s", export_path.absolute()
-        )
+        logging.info("Checking if dataset already downloaded %s", export_path.absolute())
         if not export_path.exists():
 
             logging.info(f"Downloading dataset from {self.url}")
@@ -176,6 +175,17 @@ def road_condition(self, path: Path) -> List[str]:
         """
         return self._dataset(path, "road_condition")
 
+    def traffic_volume(self, path: Path) -> List[str]:
+        """List of files with traffic volume data.
+
+        Args:
+            path (Path): The path of the dataset
+
+        Returns:
+            List[str]: The files with traffic volume data
+        """
+        return self._dataset(path, "traffic_volume")
+
 
 class DLRUTVersion(Enum):
     """The available version of the DLR UT dataset"""
@@ -191,6 +201,10 @@ class DLRUTVersion(Enum):
     """The road condition information was moved into a new sub dataset from the weather data.
     """
 
+    v1_2_0 = "v1.2.0"
+    """New folder structure to split raw and metadata. Add new metadata "traffic_volume" and "openscenario". Improve classification of pedestrians and bicycles.
+    """
+
 
 class DLRUTDatasetManager(DLRDatasetManager):
     """A manager to load the DLR UT dataset from zenodo"""
@@ -199,15 +213,18 @@ class DLRUTDatasetManager(DLRDatasetManager):
         DLRUTVersion.v1_0_0.value: 11396372,
         DLRUTVersion.v1_0_1.value: 13907201,
         DLRUTVersion.v1_1_0.value: 14025010,
+        DLRUTVersion.v1_2_0.value: 14773161,
     }
     """Dict[str, int]: An internal mapping between version and the zenodo id
     """
 
-    ARCHIVE = {
-        DLRUTVersion.v1_0_0.value: "DLR-UT",
-        DLRUTVersion.v1_0_1.value: "DLR-Urban-Traffic-dataset",
-        DLRUTVersion.v1_1_0.value: "DLR-Urban-Traffic-dataset",
-    }
+    ARCHIVE = dict({
+        DLRUTVersion.v1_0_0.value: "DLR-UT"
+    },
+                   **{
+                       v: "DLR-Urban-Traffic-dataset"
+                       for v in list(VERSION.keys())[1:]
+                   })
 
     @classmethod
     def area(cls):
@@ -265,6 +282,17 @@ def air_quality(self, path: Path) -> List[str]:
         """
         return self._dataset(path, "air_quality")
 
+    def openscenario(self, path: Path) -> List[str]:
+        """List of files with OpenSCENARIO data.
+
+        Args:
+            path (Path): The path of the dataset
+
+        Returns:
+            List[str]: The files with OpenSCENARIO data
+        """
+        return self._dataset(path, "openscenario")
+
 
 class ObjectClass(IntEnum):
     """
@@ -349,9 +377,7 @@ def mru(self):
         Returns:
             DLRTrajectoryDataset: Dataset of all motorized objects.
         """
-        return self.get_by_object_class(
-            [ObjectClass.motorbike, ObjectClass.car, ObjectClass.van, ObjectClass.truck]
-        )
+        return self.get_by_object_class([ObjectClass.motorbike, ObjectClass.car, ObjectClass.van, ObjectClass.truck])
 
     @property
     def vru(self):
@@ -363,6 +389,21 @@ def vru(self):
         """
         return self.get_by_object_class([ObjectClass.pedestrian, ObjectClass.bicycle])
 
+    @property
+    def roi(self):
+        """
+        Return the region of interest of the dataset.
+
+        Returns:
+            np.ndarray: The region of interest.
+        """
+        return np.array([
+            self.center.easting.min(),
+            self.center.northing.min(),
+            self.center.easting.max(),
+            self.center.northing.max(),
+        ]).reshape(-1, 2)
+
 
 class DLRUTTrafficLightDataset(TrafficLightDataset):
 
@@ -431,26 +472,11 @@ def _dataset(self, path: Path, variant: str) -> List[str]:
             path = Path(path)
 
         # join dataset path and name, type and variant
-        path = (
-            path.joinpath(self.name)
-            .joinpath(self.DATA_TYPES[variant])
-            .joinpath(variant)
-        )
+        path = (path.joinpath(self.name).joinpath(self.DATA_TYPES[variant]).joinpath(variant))
 
         # return file pathes of variant
         return [os.path.join(path, p) for p in sorted(os.listdir(path))]
 
-    def traffic_volume(self, path: Path) -> List[str]:
-        """List of files with air quality data.
-
-        Args:
-            path (Path): The path of the dataset
-
-        Returns:
-            List[str]: The files with air quality data
-        """
-        return self._dataset(path, "traffic_volume")
-
 
 def download():