Simulation 3D Scene Configuration

Scene configuration for 3D simulation environment

Library:
Automated Driving Toolbox / Simulation 3D
Vehicle Dynamics Blockset / Vehicle Scenarios / Sim3D / Sim3D Core

Description

The Simulation 3D Scene Configuration block implements a 3D simulation environment that is rendered by using the Unreal Engine^® from Epic Games^®. Automated Driving Toolbox™ integrates the 3D simulation environment with Simulink^® so that you can query the world around the vehicle and virtually test perception, control, and planning algorithms.

You can simulate from a set of prebuilt scenes or from your own custom scenes. Scene customization requires the Automated Driving Toolbox Interface for Unreal Engine 4 Projects support package. For more details, see Customize Unreal Engine Scenes for Automated Driving.

Note

The Simulation 3D Scene Configuration block must execute after blocks that send data to the 3D environment and before blocks that receive data from the 3D environment. To verify the execution order of such blocks, right-click the blocks and select Properties. Then, on the General tab, confirm these Priority settings:

For blocks that send data to the 3D environment, such as Simulation 3D Vehicle with Ground Following blocks, Priority must be set to -1. That way, these blocks prepare their data before the 3D environment receives it.
For the Simulation 3D Scene Configuration block in your model, Priority must be set to 0.
For blocks that receive data from the 3D environment, such as Simulation 3D Camera blocks, Priority must be set to 1. That way, the 3D environment can prepare the data before these blocks receive it.

For more information about execution order, see How Unreal Engine Simulation for Automated Driving Works.

Parameters

expand all

Scene Selection

`Scene source` — Source of scene
`Default Scenes` (default) | `Unreal Executable` | `Unreal Editor`

Source of the scene in which to simulate, specified as one of the options in the table.

Option Description

Option	Description
`Default Scenes`	Simulate in one of the default, prebuilt scenes specified in the Scene name parameter.
`Unreal Executable`	Simulate in a scene that is part of an Unreal Engine executable file. Specify the executable file in the File name parameter. Specify the scene in the Scene parameter. Select this option to simulate in custom scenes that have been packaged into an executable for faster simulation.
`Unreal Editor`	Simulate in a scene that is part of an Unreal Engine project (`.uproject`) file and is open in the Unreal^® Editor. Specify the project file in the Project parameter. Select this option when developing custom scenes. By clicking Open Unreal Editor, you can co-simulate within Simulink and the Unreal Editor and modify your scenes based on the simulation results.

Default Scenes

Simulate in one of the default, prebuilt scenes specified in the Scene name parameter.

Unreal Executable

Simulate in a scene that is part of an Unreal Engine executable file. Specify the executable file in the File name parameter. Specify the scene in the Scene parameter.

Select this option to simulate in custom scenes that have been packaged into an executable for faster simulation.

Unreal Editor

Simulate in a scene that is part of an Unreal Engine project (.uproject) file and is open in the Unreal^® Editor. Specify the project file in the Project parameter.

Select this option when developing custom scenes. By clicking Open Unreal Editor, you can co-simulate within Simulink and the Unreal Editor and modify your scenes based on the simulation results.

`Scene name` — Name of prebuilt 3D scene
`Straight road` (default) | `Curved road` | `Parking lot` | `Double lane change` | `Open surface` | `US city block` | `US highway` | `Virtual Mcity` | `Large parking lot`

Name of the prebuilt 3D scene in which to simulate, specified as one of these options. For details about a scene, see its listed corresponding reference page.

Straight road — Straight Road
Curved road — Curved Road
Parking lot — Parking Lot
Double lane change — Double Lane Change
Open surface — Open Surface
US city block — US City Block
US highway — US Highway
Virtual Mcity — Virtual Mcity
Large parking lot — Large Parking Lot

The Automated Driving Toolbox Interface for Unreal Engine 4 Projects contains customizable versions of these scenes. For details about customizing scenes, see Customize Unreal Engine Scenes for Automated Driving.

Dependencies

To enable this parameter, set Scene source to Default Scenes.

`File name` — Name of Unreal Engine executable file
`VehicleSimulation.exe` (default) | valid executable file name

Name of the Unreal Engine executable file, specified as a valid executable file name. You can either browse for the file or specify the full path to the file, using backslashes. To specify a scene from this file to simulate in, use the Scene parameter.

By default, File name is set to VehicleSimulation.exe, which is on the MATLAB^® search path.

Example: C:\Local\WindowsNoEditor\AutoVrtlEnv.exe

Dependencies

To enable this parameter, set Scene source to Unreal Executable.

`Scene` — Name of scene from executable file
`/Game/Maps/HwStrght` (default) | path to valid scene name

Name of a scene from the executable file specified by the File name parameter, specified as a path to a valid scene name.

When you package scenes from an Unreal Engine project into an executable file, the Unreal Editor saves the scenes to an internal folder within the executable file. This folder is located at the path /Game/Maps. Therefore, you must prepend /Game/Maps to the scene name. You must specify this path using forward slashes. For the file name, do not specify the .umap extension. For example, if the scene from the executable in which you want to simulate is named myScene.umap, specify Scene as /Game/Maps/myScene.

Alternatively, you can browse for the scene in the corresponding Unreal Engine project. These scenes are typically saved to the Content/Maps subfolder of the project. This subfolder contains all the scenes in your project. The scenes have the extension .umap. Select one of the scenes that you packaged into the executable file specified by the File name parameter. Use backward slashes and specify the .umap extension for the scene.

By default, Scene is set to /Game/Maps/HwStrght, which is a scene from the default VehicleSimulation.exe executable file specified by the File name parameter. This scene corresponds to the prebuilt Straight Road scene.

Example: /Game/Maps/scene1

Example: C:\Local\myProject\Content\Maps\scene1.umap

Dependencies

To enable this parameter, set Scene source to Unreal Executable.

`Project` — Name of Unreal Engine project file
valid project file name

Name of the Unreal Engine project file, specified as a valid project file name. You can either browse for the file or specify the full path to the file, using backslashes. The file must contain no spaces. To simulate scenes from this project in the Unreal Editor, click Open Unreal Editor. If you have an Unreal Editor session open already, then this button is disabled.

To run the simulation, in Simulink, click Run. Before you click Play in the Unreal Editor, wait until the Diagnostic Viewer window displays this confirmation message:

In the Simulation 3D Scene Configuration block, you set the scene source to 'Unreal Editor'.
In Unreal Editor, select 'Play' to view the scene.

This message confirms that Simulink has instantiated the scene actors, including the vehicles and cameras, in the Unreal Engine 3D environment. If you click Play before the Diagnostic Viewer window displays this confirmation message, Simulink might not instantiate the actors in the Unreal Editor.

Dependencies

To enable this parameter, set Scene source to Unreal Editor.

Scene Parameters

`Scene view` — Configure placement of virtual camera that displays scene
`Scene Origin` (default) | vehicle name

Configure the placement of the virtual camera that displays the scene during simulation.

If your model contains no Simulation 3D Vehicle with Ground Following blocks, then during simulation, you view the scene from a camera positioned at the scene origin.
If your model contains at least one vehicle block, then by default, you view the scene from behind the first vehicle that was placed in your model. To change the view to a different vehicle, set Scene view to the name of that vehicle. The Scene view parameter list is populated with all the Name parameter values of the vehicle blocks contained in your model.

If you add a Simulation 3D Scene Configuration block to your model before adding any vehicle blocks, the virtual camera remains positioned at the scene. To reposition the camera to follow a vehicle, update this parameter.

When Scene view is set to a vehicle name, during simulation, you can change the location of the camera around the vehicle.

To smoothly change the camera views, use these key commands.

Key	Camera View
1	Back left	View Animated GIF
2	Back
3	Back right
4	Left
5	Internal
6	Right
7	Front left
8	Front
9	Front right
0	Overhead

For additional camera controls, use these key commands.

Key	Camera Control
Tab	Cycle the view between all vehicles in the scene. View Animated GIF
Mouse scroll wheel	Control the camera distance from the vehicle. View Animated GIF
L	Toggle a camera lag effect on or off. When you enable the lag effect, the camera view includes: Position lag, based on the vehicle translational acceleration Rotation lag, based on the vehicle rotational velocity This lag enables improved visualization of overall vehicle acceleration and rotation. View Animated GIF
F	Toggle the free camera mode on or off. When you enable the free camera mode, you can use the mouse to change the pitch and yaw of the camera. This mode enables you to orbit the camera around the vehicle. View Animated GIF

`Sample time` — Sample time of visualization engine
`1/60` (default) | scalar greater than or equal to 0.01

Sample time, T_s, of the visualization engine, specified as a scalar greater than or equal to 0.01. Units are in seconds.

The graphics frame rate of the visualization engine is the inverse of the sample time. For example, if Sample time is 1/60, then the visualization engine solver tries to achieve a frame rate of 60 frames per second. However, the real-time graphics frame rate is often lower due to factors such as graphics card performance and model complexity.

By default, blocks that receive data from the visualization engine, such as Simulation 3D Camera blocks, inherit this sample rate.

`Display 3D simulation window` — Unreal Engine visualization
`on` (default) | `off`

Select whether to run simulations in the 3D visualization environment without visualizing the results, that is, in headless mode.

Consider running in headless mode in these cases:

You want to run multiple 3D simulations in parallel to test models in different Unreal Engine scenarios.
You want to capture sensor data to analyze in MATLAB but do not need to watch the visualization.

Dependencies

To enable this parameter, set Scene source to Default Scenes or Unreal Executable.

Model Examples

Simulate Simple Driving Scenario and Sensor in Unreal Engine Environment

Learn the basics of configuring and simulating scenes, vehicles, and sensors in a virtual environment rendered using the Unreal Engine from Epic Games.

Select Waypoints for Unreal Engine Simulation

Select waypoints from a scene and visualize the path of a vehicle following these waypoints in the Unreal Engine simulation environment.

Visualize Sensor Data from Unreal Engine Simulation Environment

Visualize sensor coverage areas and detections obtained from high-fidelity radar and lidar sensors in the Unreal Engine simulation environment.

Design Lane Marker Detector Using Unreal Engine Simulation Environment

Use the Unreal Engine simulation environment to record synthetic sensor data and develop and test a lane marker detection system.

Highway Lane Following

Simulate a lane-following controller and monocular camera-based perception algorithm in the Unreal Engine simulation environment.

Documentation

Simulation 3D Scene Configuration

Description