6. Database

Goals for using the Database with the Simulator:

Centralized storage of recorded datasets of executed scenarios
Centralized storage of scenarios
Centralized storage of vehicle configurations

6.1. Connection

For the database management system, MongoDB is utilized.

To configure a connection to MongoDB, navigate to the Settings → Common Settings menu:

Specify the connection URL to MongoDB and the name of the database:

Optionally, you can activate the “Record Dataset” feature. In this case, assuming a database connection is established, dataset recording will automatically initiate when a scenario is played. You can also activate the “Auto Connect” feature, which enables the simulator to automatically connect to MongoDB upon start-up.

These last two options are also mirrored in the Database menu:

In this menu, you can also manually establish or disconnect the MongoDB connection.

The Database menu displays the current connection status to the database:

connection not established
connection in progress
connection established
connection error

6.2. Saving/Loading Scenarios in the Database

To save or load a scenario in the database, select the appropriate Remote option in the “Level Save & Load” menu:

Scenarios are stored in the “scenarios” collection in MongoDB (see Collection “scenarios”).

6.3. Saving/Loading Vehicles in the Database

Similarly, to save vehicle configurations in the database, select the appropriate Remote option:

To place a saved vehicle from the database onto the scene, drag it from the Add New Actor → Remote Vehicles menu:

Vehicles are stored in the “vehicles” collection in MongoDB (see Collection “vehicles”).

6.4. Dataset Recording

To record a scenario dataset, ensure that a database connection is established and the “Record Dataset” feature is activated:

After launching the scenario (using the Play Scenario button), a notification should appear in the bottom right corner indicating the start of the dataset recording with its unique ID:

You can find the recorded dataset in MongoDB using this ID. It is recommended to use the Studio 3T client for this purpose, as it doesn’t freeze when querying large volumes of data.

Note that all scene actors for which a dataset can be recorded have a “Dataset” section in their settings. Typically, here you can enable/disable dataset recording for the actor and adjust additional dataset recording options:

Datasets are stored in the dataset collections (see Collections “datasets” & “dataset”).

6.5. MongoDB Structure

6.5.1. Collection “scenarios”

The “scenarios” collection stores various scenarios.

Document structure:

{
	_id (int64)
	timestamp (int64) // Document creation time [us]
	description (string) // Arbitrary scenario description (matches in UI)
	bin (binary) // Binarily serialized scenario data
}

6.5.2. Collection “vehicles”

The “vehicles” collection stores vehicle configurations (savings).

Document structure:

{
	_id (string) // Unique vehicle name (corresponds to the name in UI)
	timestemp (int64) // Document creation time [us]
	soda.sim {} // JSON format for serializing the Soda Vehicle (same as in the file)
}

6.5.3. Collections “datasets” & “dataset*”

The “datasets” collection contains comprehensive information about all datasets, including static data (i.e., data that doesn’t change over time), such as the start and end time of the dataset recording, a list of actors involved in the scenario along with their descriptions, etc. One document in the “datasets” collection corresponds to one recorded dataset. Meanwhile, “dataset” holds dynamic information about the actors on the scene. The _id of documents from the “datasets” collection matches the “*” in the name of the “dataset collection (for instance, a document in the collection with _id=123 will correspond to the collection named dataset123).

6.5.3.1. Collection Document Structure “dataset”

{
	_id (int64) // Dataset ID, corresponds to "***" in "dataset***" collection
	begin_ts (int64) // Recording start time [us]
	end_ts (int64) // Recording end time [us]
	unreal_soda_ver (string) // SODA.Sim plugin version
	end_reason (string) // Reason for ending the recording
	actors  // Array describing the actors in the dataset
	[
		{
			name (string) // Actor name
			type (string) // Actor type (ego, pedestrian, vehicle..., see all types in Actors Dataset Format)
			class (string) // Actor's UE class name
			description {...} // Actor description, format depends on the actor type (see Actors Dataset Format)
		},
		...
	]
}

6.5.3.2. Collection Document Structure “dataset*”

{
	_id (ObjectId)
	name (string) // Actor name
	part (int) // Sequential batch index
	batch // Actor simulation data
	[
		{...}, // Data for one step of actor simulation, format depends on the actor type (see Actors Dataset Format)
		{...}, 
		... 
	]
} 

The data for each simulation step for each actor is grouped in batches of a fixed length (usually 10,000 elements). Each document from the “dataset*” collection contains one such batch. One simulation step for an actor corresponds to one element in the batch array, and the format of this array depends on the actor type (see Actors Dataset Format). This batch segmentation approach is utilized to adhere to MongoDB’s recommendation: “the document size should not exceed 16MB”.

6.5.4. Actors Dataset Format

By default, all measurement units and the coordinate system data in the database correspond to the default units of measurement and the UE coordinate system, unless stated otherwise in the parameter description:

Left-handed coordinate system

Centimeters are used in all measurement units (cm, cm/s, cm/s²,…)

In this section, data format descriptions for the actors recorded in the dataset are presented:

For the description field from the “datasets” collection in the actors[] field
For the batch field from the “dataset*” collection

6.5.4.1. Actor Types

The actor type is specified in the “datasets” collection in the actors[] → type field:

“ego” corresponds to the ASodaVehicle class.

{
	extents // Actor dimensions
	{
		forward (float)
		backward (float)
		left (float)
		right (float)
		up (float)
		down (float)
	}
	track_width (float) // Distance between wheels along the Y-axis
	wheel_base_width (float) // Distance between wheels along the X-axis
	mass (float) // Vehicle mass
	wheels // Wheel data
	[
		{
			4wd_ind (int) // Wheel index for 4WD vehicle (0-FL, 1-FR, 2-RL, 3-RR)
			radius (float) // Wheel radius
			location [x, y, z] // Wheel position
		},
		...
	]
}

{
	sim_ts (int64) // Simulation timestamp [us]
	render_ts (int64) // Rendering timestamp corresponding to the current simulation timestamp [us][us]
	step (int64) // Current simulation step
	loc [x, y, z] // Location
	ro* [pitch, yaw, roll] // Rotation
	vel [x, y, z] // Velocity
	acc [x, y, z] // Acceleration
	ang_vel [x, y, z] // Angular velocity [rad/s]
	input
	{
		break (float)
		steer (float)
		throttle (float)
		gear (int)
	}
	wheels
	[
		{
			4wd_ind (int)
			ang_vel (float)
			req_torq (float)
			req_brake_torq (float)
			steer (float)
			sus (float)
			long_slip (float)
			lat_slip (float)
		},
		...
	]
}

“pedestrian” corresponds to the APedestrian class.

{
	extents // Actor dimensions
	{
		forward (float)
		backward (float)
		left (float)
		right (float)
		up (float)
		down (float)
	}
}

{
	ts (int64) // Simulation timestamp [us]
	loc [x, y, z]
	rot [pitch, yaw, roll]
	vel [x, y, z]
	acc [x, y, z]
	route
	[
		name (string)
	]
}

“vehicle” corresponds to the AGhostVehicle class.

{
	extents // Actor dimensions
	{
		forward (float)
		backward (float)
		left (float)
		right (float)
		up (float)
		down (float)
	}
}

{
	ts (int64) // Simulation timestamp [us]
	loc [x, y, z]
	rot [pitch, yaw, roll]
	vel [x, y, z]
	acc [x, y, z]
	route
	[
		name (string)
	]
}

“opendrive” corresponds to the AOpenDriveTool class.

{
	xdor (string) // Original OpenDrive (.xdor) file
	road_lanes_marks
	[
		type (string) // Type of lane marking ("solid", "broken", "solid solid", "solid broken", "broken solid")
		points // Array with point coordinates
		[
			[x, y, z], [x, y, z], ...
		]
	]
}