sim3d.World

Object used to define virtual world in Unreal Engine environment

Since R2022b

Description

Use the sim3d.World object to create and define virtual worlds and run the cosimulation using Unreal Engine^®.

• Add or remove custom actors to or from the world. Only the actors added to the world object are displayed.

• Store the virtual world scene, the root sim3d.Actor object, and the hierarchical structure of all actors in the scene.

• Optionally control the simulation logic by specifying custom functions. The output function passes data to the Unreal Engine to change actor properties in the engine.

• Control the cosimulation between MATLAB^® and the Unreal Engine.

• Define the virtual world global coordinate system.

• Control scene environment settings.

• Control virtual world timing.

Creation

Syntax

world = sim3d.World()

world = sim3d.World('Name',name)

world = sim3d.World('RenderOffScreen',true)

world = sim3d.World('Setup',@setupFcn)

world = sim3d.World('Update',@updateFcn)

world = sim3d.World('Output',@outputFcn)

world = sim3d.World('Release',@releaseFcn)

Description

world = sim3d.World() launches the default Unreal Engine executable in a new window with a default name.

world = sim3d.World('Name',name) launches the Unreal Engine executable in a new window with the name specified.

world = sim3d.World('RenderOffScreen',true) runs the cosimulation while running the Unreal Engine executable in the background.

world = sim3d.World('Setup',@setupFcn) modifies the cosimulation by executing @setupFcn before setup. This custom function can be used to import additional data which required during simulation runtime.

world = sim3d.World('Update',@updateFcn) modifies the cosimulation by executing @updateFcn at each simulation step. This custom function can be used to read data from the Unreal Engine.

world = sim3d.World('Output',@outputFcn) modifies the cosimulation by executing @outputFcn at each simulation step. This custom function can be used to send data about the specified sim3d.Actor object to the Unreal Engine.

world = sim3d.World('Release',@releaseFcn) modifies the cosimulation by executing @releaseFcn at each simulation step. This function can be used to delete additional data you may import during setup.

Input Arguments

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: World = sim3d.World('Name',world1)

Name — Name of world

string

Name of the world, specified as a string.

ExecutablePath — Path to executable file

string

Path to executable file that the world runs, specified as a string.

RenderOffScreen — Option to run simulation in background

0 (false) | 1 (true)

Option to run simulation in the background, specified as either 0(false) or 1(true).

Update — Custom update function

handle to user-defined function

Custom update function that reads data about specified actors from Unreal Engine, specified as the handle to the user-defined function.

Output — Custom output function

handle to user-defined function

Custom output function that returns information, such as transform and color, for the specified actors to the Unreal Engine, specified as the handle to the user-defined function. This allows Unreal^® to control the simulation.

Setup — Custom setup function

handle to user-defined function

Custom function that reads to run additional commands during setup, specified as the handle to the user defined function. This can be used to load data required for simulation.

Release — Custom release function

handle to user-defined function

Custom release function that runs additional commands after simulation ends, specified as the handle to the user-defined function. This setting can be used to delete additional data imported for the setup.

Properties

Name — Name of world

string

Name of the world, specified as a string.

Actors — All actors in world

structure

All actors in the world, specified as a structure whose fields are the names of the actors.

UserData — Data specified by user

structure

Data specified by user that may be required during simulation runtime, specified as a structure.

You can use UserData to store the data needed by the Update, Output, Setup, and Release custom functions. UserData ensures that the same data is accessible to all these functions.

Viewports — Perspective of main camera

empty structure (default) | structure

Perspective of the main camera, defined as a structure containing a single field, Main. Main contains a sim3d.sensors.MainCamera object with these properties:

• Parent — Parent of actor object

• Children — Children of actor object

• ParentWorld — Handle to parent world

• SensorIdentifier — Unique ID of the main camera, with data type uint32

• Translation — Translation of the main camera relative to the parent vehicle, in meters

• Rotation — Rotation of the sensor relative to the parent vehicle, in radians

HitActors — Event container

empty array (default) | array

Event container for the handles for actors hit at a time step, specified as an array. After each time step, the event container resets to empty.

BeginOverlappedActors — Event container

empty array (default) | array

Event container for the handles for actors that start overlapping at a time step, specified as an array. After each time step, the event container resets to empty.

EndOverlappedActors — Event container

empty array (default) | array

Event container for the handles for actors that end overlapping at a time step, specified as an array. After each time step, the event container resets to empty.

ClickedActors — Event container

empty array (default) | array

Event container for the handles for actors that are interactively clicked at a time step, specified as an array. After each time step, the event container resets to empty.

Object Functions

createViewport	Create viewport for world
add	Add actor to virtual world
run	Run cosimulation in virtual reality world
remove	Remove actor added to world or remove all actors in world

Examples

Create World and Actor

This example shows how to create an actor in a virtual world to display in the Simulation 3D Viewer window using Simulink® or MATLAB®.

This process does not build an appearance for the actor, so the Simulation 3D Viewer does not render a visualization of the actor. For an example that shows how to build an appearance for an actor, see Build Actor from 3D Graphic Primitives.

Create Virtual World with Actor Using Simulink

You can use the Simulation 3D Actor block and Simulation 3D Scene Configuration block to create an actor in a virtual world and view it in the Simulation 3D Viewer window.

Open Model

Open the Simulink model.

open_system("CreateWorld");

Explore Model Components

The model includes a Simulation 3D Scene Configuration block and a Simulation 3D Actor block. The Simulation 3D Scene Configuration block implements a 3D simulation environment. Double-click the Simulation 3D Scene Configuration block to open the Block Parameters dialog box. Set a view in the scene with the Scene view parameter. You can also set a custom viewpoint with this parameter. You must include the configuration block when building Simulink models with Simulation 3D Actor blocks.

The Simulation 3D Actor block adds an actor to the virtual world. Double-click the Simulation 3D Actor block to open the Block Parameters dialog box. To create an actor before simulation starts, on the Main tab, set the Operation parameter to Create at setup. The block first creates an empty actor with the name specified in the Actor name parameter. You can use any name for the actor. Then, the block loads the source file, if any is present, and runs the Initialization script to build an appearance for the actor. For more details, see Operating Modes. For this example, the block does not build an appearance for the actor in the virtual world.

Simulate Model

Simulate the model and view the virtual world in the Simulation 3D Viewer.

sim("CreateWorld");

Close Model

Close the Simulink model.

close_system("CreateWorld");

Create Virtual World with Actor Using MATLAB

You can use the sim3d.World and sim3d.Actor objects to create an actor in a virtual world and view it in the Simulation 3D Viewer window.

Create World

Create a world scene.

world = sim3d.World();

Create Actor

Add an actor to the world.

add(world,sim3d.Actor());

Run Simulation

Run a simulation set for 10 seconds with a sample time of 0.02 seconds.

run(world,0.02,10)

Delete World

Delete the world object.

delete(world);

Version History

Introduced in R2022b

R2023a: Event Attributes

Use sim3d.World object properties to read event information, including:

• HitActors: Actors hit at a time step.

• BeginOverlappedActors: Actors that starts overlapping at a time step.

• EndOverlappedActors: Actors that ends overlapping at a time step.

• ClickedActors: Actors that are interactively clicked at a time step.