omega-prime: Tutorial for using the python library¶

Create omega-prime files¶

To create files in accordance with the omega-prime specification, you need the map information as ASAM OpenDRIVE XML and the infomration on dynamic elements as ASAM OSI GroundTruth messages. Alternatively, the information on dynamic elements can be provided as a table.

Create from ASAM OSI¶

The following code creates a omega-prime file from an ASAM OSI trace file (e.g., created from esmini (see example_files/README.md)) and an ASAM OpenDRIVE map.

In [ ]:

import omega_prime

r = omega_prime.Recording.from_file(
    "../../example_files/pedestrian.osi", map_path="../../example_files/fabriksgatan.xodr", apply_proj=False
)
r.to_mcap("example.mcap")

import omega_prime r = omega_prime.Recording.from_file( "../../example_files/pedestrian.osi", map_path="../../example_files/fabriksgatan.xodr", apply_proj=False ) r.to_mcap("example.mcap")

If you have large amount of data (e.g., 32.000 objects over a whole day), we suggest using the Apache Parquet file format to store omega-prime data. To do so run the following

In [11]:

r.to_parquet("example.parquet")

r.to_parquet("example.parquet")

Parquet files created with the method can be loaded with the from_file function

In [12]:

r = omega_prime.Recording.from_file("example.parquet")

r = omega_prime.Recording.from_file("example.parquet")

Create from table¶

You can also directly create a recording from object data in table form (we use polars). Create a table df like the following:

total_nanos	idx	x	y	z	vel_x	vel_y	vel_z	acc_x	acc_y	acc_z	length	width	height	roll	pitch	yaw	type	role	subtype
0	0	42.6987	-69.8783	0.75	-2.04032	9.78964	0	0	0	0	5.04	2	1.5	0	0	1.77627	2	0	4
0	1	35.6784	-23.5705	0.923	0	0	0	0	0	0	0.6	0.5	1.8	0	0	1.7984	3	-1	-1
3.3e+07	0	42.6306	-69.5554	0.75	-2.04288	9.78896	0	-0.0774077	-0.020523	0	5.04	2	1.5	0	0	1.7768	2	0	4
3.3e+07	1	35.6784	-23.5705	0.923	0	0	0	0	0	0	0.6	0.5	1.8	0	0	1.7984	3	-1	-1
6.6e+07	0	42.5623	-69.2325	0.75	-2.04801	9.7879	0	-0.155563	-0.0323452	0	5.04	2	1.5	0	0	1.77732	2	0	4
6.6e+07	1	35.6784	-23.5705	0.923	0	0	0	0	0	0	0.6	0.5	1.8	0	0	1.7984	3	-1	-1

type, subtyp and role have to be integers and correspond to the enumerations betterosi.MovingObjectType, betterosi.MovingObjectVehicleClassificationType and betterosi.MovingObjectVehicleClassificationRole. The role and subtype have to be -1 when the type is not of TYPE_VEHICLE.

The enumartions are defined as shown below.

In [13]:

import betterosi

print(f"MovingObjectType: { ({o.name: o.value for o in betterosi.MovingObjectType}) }")
print(
    f"MovingObjectVehicleClassificationType: { ({o.name: o.value for o in betterosi.MovingObjectVehicleClassificationType}) }"
)
print(
    f"MovingObjectVehicleClassificationRole: { ({o.name: o.value for o in betterosi.MovingObjectVehicleClassificationRole}) }"
)

import betterosi print(f"MovingObjectType: { ({o.name: o.value for o in betterosi.MovingObjectType}) }") print( f"MovingObjectVehicleClassificationType: { ({o.name: o.value for o in betterosi.MovingObjectVehicleClassificationType}) }" ) print( f"MovingObjectVehicleClassificationRole: { ({o.name: o.value for o in betterosi.MovingObjectVehicleClassificationRole}) }" )

MovingObjectType: {'UNKNOWN': 0, 'OTHER': 1, 'VEHICLE': 2, 'PEDESTRIAN': 3, 'ANIMAL': 4}
MovingObjectVehicleClassificationType: {'UNKNOWN': 0, 'OTHER': 1, 'SMALL_CAR': 2, 'COMPACT_CAR': 3, 'CAR': 4, 'LUXURY_CAR': 5, 'DELIVERY_VAN': 6, 'HEAVY_TRUCK': 7, 'SEMITRACTOR': 16, 'SEMITRAILER': 8, 'TRAILER': 9, 'MOTORBIKE': 10, 'BICYCLE': 11, 'BUS': 12, 'TRAM': 13, 'TRAIN': 14, 'WHEELCHAIR': 15, 'STANDUP_SCOOTER': 17}
MovingObjectVehicleClassificationRole: {'UNKNOWN': 0, 'OTHER': 1, 'CIVIL': 2, 'AMBULANCE': 3, 'FIRE': 4, 'POLICE': 5, 'PUBLIC_TRANSPORT': 6, 'ROAD_ASSISTANCE': 7, 'GARBAGE_COLLECTION': 8, 'ROAD_CONSTRUCTION': 9, 'MILITARY': 10}

In [14]:

import polars as pl

import omega_prime

df = pl.read_csv("../../example_files/example.csv")
r = omega_prime.Recording(df=df, map=omega_prime.MapOdr.from_file("../../example_files/fabriksgatan.xodr"))

import polars as pl import omega_prime df = pl.read_csv("../../example_files/example.csv") r = omega_prime.Recording(df=df, map=omega_prime.MapOdr.from_file("../../example_files/fabriksgatan.xodr"))

Read and plot omega-prime file¶

In [15]:

import omega_prime

import omega_prime

By default the map information is not parsed. For parsing the map we utilize pyxodr. To directly parse the map you have to set parse_map=True.

In [16]:

r = omega_prime.Recording.from_file("example.mcap", parse_map=True, apply_proj=False)
ax = r.plot()
ax.set_xlim(-20, 50)
ax.set_ylim(-75, 20)

r = omega_prime.Recording.from_file("example.mcap", parse_map=True, apply_proj=False) ax = r.plot() ax.set_xlim(-20, 50) ax.set_ylim(-75, 20)

Out[16]:

(-75.0, 20.0)

In [17]:

ax = r.plot_frame(10)
ax.set_xlim(-20, 50)
ax.set_ylim(-75, 20)

ax = r.plot_frame(10) ax.set_xlim(-20, 50) ax.set_ylim(-75, 20)

Out[17]:

(-75.0, 20.0)

Plot using Altair¶

You can create interactive plots with altair using plot_altair function of the recording. If using the the function in a non notebook environment use import altair as alt; alt.renderers.enable("browser") to enable blotting in a browser and call .show() on the resulting chart.

In [18]:

nbval-ignore-output

nbval-skip

r.plot_altair(start_frame=0, end_frame=400, metric_column="vel_y", idx=0)

r.plot_altair(start_frame=0, end_frame=400, metric_column="vel_y", idx=0)

Out[18]:

In [19]:

nbval-ignore-output

r.map

r.map

Out[19]:

<omega_prime.map_odr.MapOdr at 0x1a4592b8310>

In [20]:

nbval-ignore-output

r.moving_objects

r.moving_objects

Out[20]:

{0: <omega_prime.recording.MovingObject at 0x1a49e847450>,
 1: <omega_prime.recording.MovingObject at 0x1a4a021f110>}

File Validation¶

By default, data is validated on file reading which takes time. to skip validation read the file with omega_prime.Recording.from_file(..., validate=False)

Interpolation¶

A simple (angle aware) linear (nearest neighbour for classification type data) interpolation function is build in

In [21]:

r.interpolate(hz=10)
r.interpolate(new_nanos=[0, int(1e8), int(2e8), int(3e8)])

r.interpolate(hz=10) r.interpolate(new_nanos=[0, int(1e8), int(2e8), int(3e8)])

CLI usage¶

In [3]:

nbval-ignore-output

!omega-prime --help

!omega-prime --help

                                                                               
 Usage: omega-prime [OPTIONS] COMMAND [ARGS]...                                
                                                                               
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --install-completion          Install completion for the current shell.     │
│ --show-completion             Show completion for the current shell, to     │
│                               copy it or customize the installation.        │
│ --help                        Show this message and exit.                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ from-lxd     Convert datasets from LevelXData to omega-prime.               │
│ from-osi     Convert from ASAM OSI GroundTruth trace.                       │
│ from-csv     Convert from csv table according to schema                     │
│ validate     Check an omega-prime file for specification conformance.       │
│ to-odr       Extracts the ASAM OpenDRIVE file from the omega-prime file.    │
│ to-parquet   Converts MCAP or OSI omega-prime into a parquet file           │
│              (beneficial for faster loading of large data).                 │
│ visualize    Visualize an omega-prime recording using Altair. Opens         │
│              interactive plot in browser.                                   │
│ attach-odr   Attach an ASAM OpenDRIVE (.xodr) map to an existing            │
│              omega-prime recording and write a new file.                    │
└─────────────────────────────────────────────────────────────────────────────┘

Create Omega file from ASAM OSI and ASAM OpenDRIVE¶

In [4]:

nbval-ignore-output

!omega-prime from-osi --help

!omega-prime from-osi --help

                                                                               
 Usage: omega-prime from-osi [OPTIONS] INPUT OUTPUT                            
                                                                               
 Convert from ASAM OSI GroundTruth trace.                                      
                                                                               
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *    input       FILE  Path to ASAM OSI trace file (either `.osi` or        │
│                        `.mcap`)                                             │
│                        [required]                                           │
│ *    output      FILE  Desired filename of omega file [required]            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --map-path                     FILE  Path to ASAM OpenDRIVE xml to use as   │
│                                      map                                    │
│ --validate    --no-validate          [default: validate]                    │
│ --help                               Show this message and exit.            │
└─────────────────────────────────────────────────────────────────────────────┘

In [2]:

nbval-ignore-output

!omega-prime from-osi ./../../example_files/pedestrian.osi example.mcap --map-path ./../../example_files/fabriksgatan.xodr

!omega-prime from-osi ./../../example_files/pedestrian.osi example.mcap --map-path ./../../example_files/fabriksgatan.xodr

Create Omega file from CSV and ASAM OpenDRIVE¶

In [6]:

nbval-ignore-output

!omega-prime from-csv --help

!omega-prime from-csv --help

                                                                               
 Usage: omega-prime from-csv [OPTIONS] INPUT OUTPUT                            
                                                                               
 Convert from csv table according to schema                                    
                                                                               
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *    input       FILE  Path to csv according to omega moving object csv     │
│                        schema                                               │
│                        [required]                                           │
│ *    output      FILE  Desired filename of omega file [required]            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --odr                          FILE  Path to ASAM OpenDRIVE xml to use as   │
│                                      map                                    │
│ --validate    --no-validate          [default: validate]                    │
│ --help                               Show this message and exit.            │
└─────────────────────────────────────────────────────────────────────────────┘

In [7]:

nbval-ignore-output

!omega-prime from-csv ./../../example_files/example.csv example.mcap --odr ./../../example_files/fabriksgatan.xodr

!omega-prime from-csv ./../../example_files/example.csv example.mcap --odr ./../../example_files/fabriksgatan.xodr

Validation check of omega file¶

In [8]:

nbval-ignore-output

!omega-prime validate --help

!omega-prime validate --help

                                                                               
 Usage: omega-prime validate [OPTIONS] INPUT                                   
                                                                               
 Check an omega-prime file for specification conformance.                      
                                                                               
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *    input      FILE  Path to omega file to validate [required]             │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --help          Show this message and exit.                                 │
└─────────────────────────────────────────────────────────────────────────────┘

In [9]:

nbval-ignore-output

!omega-prime validate ./example.mcap

!omega-prime validate ./example.mcap

File example.mcap is valid.