sim3d.World
Description
Use the sim3d.World
object to create a world object that
defines the 3D environment. After you create a sim3d.World
object, you can
modify aspects of the world object by setting property values.
Run and control the co-simulation between MATLAB® and the Unreal Engine®.
Add or remove actors to or from the world. Only the actors added to the world object are displayed. The world uses the Unreal Engine coordinate system to transform objects.
Create a default view of the 3D environment.
Optionally define a control algorithm by specifying custom functions. For example, the output function passes data to the Unreal Engine to change actor properties in the engine during each time step.
Record the 3D animation data into a MAT file.
Creation
Description
creates a world object
that defines the 3D environment in the Unreal Engine with a default name.world
= sim3d.World()
specifies options using one or more optional name-value arguments. For example, for a
sample time of 0.03 s, set world
= sim3d.World(Name=Value
)SampleTime
to
0.03
.
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="World",Scene="Straight
road",SampleTime=0.03,StopTime=10,Output=@outputFcn)
creates a world object
with the specified name, scene, sample time, stop time, and custom callback function
handle to send information to Unreal Engine during each step.
Name of the world, specified as a string. If you do not specify a name, then the software assigns the world object an autogenerated name.
Option to run simulation in the background, specified as either
0
(false
) or 1
(true
).
Name of the prebuilt 3D scene in which to simulate, specified as one of the listed options. You can also install additional scenes on demand. For details about a scene, see its listed reference page.
These are the default scene options.
Empty scene
— See Empty Scene.Blank scene
— See Blank Scene.
These are the scenes that you can install. For more information about other scenes, see 3D Scenes for Simulation in Unreal Engine Environment.
Empty Grass
— See Empty Grass.Straight road
— See Straight Road.Curved road
— See Curved Road.
To install a scene, use the Install option in the
Simulation 3D Scene Configuration block as described in the
Scene
name parameter. After installation, you can set the
Scene
to the installed scene name.
Data Types: string
Custom update function that reads data about specified actors from Unreal Engine, specified as the handle to the user-defined function.
Example: Update=@updateFcn
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.
Example: Output=@outputFcn
Custom function that reads to run additional commands during setup, specified as the handle to the user defined function.
Example: Setup=@setupFcn
Custom release function that runs additional commands after simulation ends, specified as the handle to the user-defined function.
Example: Release=@releaseFcn
Sample time of simulation,
Ts, specified as a real positive scalar, in s.
Sample time refers to the time interval at which the output is updated during the simulation.
The simulation speed depends on the model complexity, computational speed, and the type of
prebuilt scene rendered. A smaller sample time allows frequent computations, which increases
computational load and reduces simulation speed. A larger sample time reduces the computational
load and increases the speed of the simulation. The graphics frame rate of the 3D simulation
engine is the inverse of the sample time. For example, if sample time is
1/50
, then the 3D simulation engine solver tries to achieve a frame
rate of 50 frames per second. However, the real-time graphics frame rate is often lower due to
factors such as graphics card performance and model complexity.
Example: SampleTime=0.01
Simulation stop time, specified as a real positive scalar, in
s. Stop time refers to the time at which the simulation is set to end. You can specify stop time
as inf
to run a simulation until you stop it by closing the game
window.
Example: StopTime=20
Note
The sample time and stop time values set using the run
function
overwrite the SampleTime
and StopTime
values
set using the sim3d.world
class.
Output Arguments
World object, returned as a sim3d.World
object.
Properties
Name of the world, specified as a string. If you do not specify a name, then the software assigns the world object an autogenerated name.
All actors in the world, specified as a structure whose fields are the names of the actors.
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 in 3D environment, specified as a structure that contains the default view
in the field Default
and incorporates any custom views of the 3D
environment as additional fields. You can create multiple custom views of the 3D
environment by using the createViewport
function and setting one as the view using the setView
function.
Since R2025a
Viewpoints in 3D environment, specified as a structure that contains the default
view in the field Default
and incorporates any custom views of the 3D
environment as additional fields. You can create multiple custom views of the 3D
environment by using the createViewpoint
function and setting one as the view using the setView
function.
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.
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.
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.
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.
Sample time of simulation,
Ts, specified as a real positive scalar, in s.
Sample time refers to the time interval at which the output is updated during the simulation.
The simulation speed depends on the model complexity, computational speed, and the type of
prebuilt scene rendered. A smaller sample time allows frequent computations, which increases
computational load and reduces simulation speed. A larger sample time reduces the computational
load and increases the speed of the simulation. The graphics frame rate of the 3D simulation
engine is the inverse of the sample time. For example, if sample time is
1/50
, then the 3D simulation engine solver tries to achieve a frame
rate of 50 frames per second. However, the real-time graphics frame rate is often lower due to
factors such as graphics card performance and model complexity.
Simulation stop time, specified as a real positive scalar, in
s. Stop time refers to the time at which the simulation is set to end. You can specify stop time
as inf
to run a simulation until you stop it by closing the game
window.
This property is read-only.
Current simulation time, specified as a real positive scalar in s. Simulation time
refers to the specific moment or a point within the StopTime
in a
simulation that is currently being executed. This property represents the virtual time
that has elapsed since the start of the simulation. You can use this property to make
decisions based on time-dependent conditions or analyze the behavior of the simulated
system at specific points in time during the simulation.
This property is read-only.
Time until simulation pauses, specified as a real positive scalar, in s. Pause time refers to the duration after which the simulation stops updating its state. You can set a value for pause time to pause the simulation. When the simulation is paused, you can analyze, debug, or troubleshoot your model performance.
You can set the pause time using the pause
function.
Data Types: single
Option to enable simulation pacing, specified as 0
(false
) to disable pacing or 1
(true
) to enable pacing.
Data Types: logical
Simulation pacing rate, specified as a real positive scalar. This property specifies
the approximate pacing rate as the ratio of simulation time to wall clock time. The
default value 1
specifies that the simulation runs at a rate equal to
the wall clock time. A value greater than 1
specifies that the
simulation runs faster than the wall clock time. A value less than 1
specifies that the simulation runs slower than the wall clock time.
Tip
The pacing period is the ratio of sample time to pacing rate and is limited to 1 millisecond precision. The property ignores pacing period with sub-millisecond precision.
Data Types: double
Option to enable recording simulation data, specified as 0
(false
) to disable recording or 1
(true
) to enable recording. For more information about the
limitations in recording 3D animation data, see Limitations.
Example: world.AnimationRecording = true
Data Types: logical
Recording time interval, specified as a real positive 1-by-2 vector, in seconds. The default value records the 3D simulation from the start time to the stop time.
Example: world.AnimationRecordingInterval = [0 10]
Data Types: double
Name of data file, specified as a character vector or string scalar. If you do not
specify a filename, then the software assigns the file an autogenerated name that
includes the world object name with the suffix anim
. The simulation
data is recorded into a MAT file within the same working folder.
Example: world.AnimationRecordingFileName =
"World_anim.mat"
Data Types: string
Object Functions
createViewport | Create view of 3D environment |
createViewpoint | Create custom view of 3D environment |
setView | Set view of 3D environment |
deleteViewport | Delete viewport from 3D environment |
deleteViewpoint | Delete viewpoint from 3D environment |
run | Run co-simulation with the 3D simulation engine |
pause | Pause co-simulation with 3D simulation engine |
resume | Resume co-simulation with 3D simulation engine |
close | End co-simulation and close simulation window |
view | View 3D environment in Simulation 3D Viewer window |
wait | Wait for co-simulation to complete |
play | Play recorded animation data |
Examples
This example shows how to create a 3D environment with an empty actor and view in the Simulation 3D Viewer window using MATLAB®. You can use the sim3d.World
to create a world object and sim3d.Actor
to create an empty actor object. You can then add the actor to the 3D environment and visualize the 3D environment in the Simulation 3D Viewer window. For an example that shows how to create a 3D environment with an actor using Simulink®, see Create World and Actor Using Simulink.
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 empty actor, see Build Actor from 3D Graphic Primitives Using MATLAB.
Create World
Create a world object.
world = sim3d.World();
Create Actor
Create an actor object. The sim3d.Actor
object creates an empty actor without any visual meshes.
actor = sim3d.Actor();
Add the actor to the world.
add(world,actor);
Run Simulation
Run a simulation set for 10
seconds with a sample time of 0.02
seconds.
sampletime = 0.02; stoptime = 10; run(world,sampletime,stoptime);
Delete World
Delete the world object.
delete(world);
Create a world object with an actor and record the 3D animation. To
play the recorded animation data, use the play
function.
Create a world object with callback function to communicate with the Unreal Engine.
world = sim3d.World(Output=@outputImpl);
To record the simulation data, set the AnimationRecording
property of the world
to true
.
world.AnimationRecording = true;
Create an actor and add it to the world
.
box1 = sim3d.Actor(ActorName='Box1', ... Mobility=sim3d.utils.MobilityTypes.Movable); createShape(box1,'box',[0.25 0.25 0.25]); box1.Color = [1 0 1]; add(world,box1);
Run the simulation. The simulation data is recorded into a MAT file with an
autogenerated name, such as "World2_anim.mat"
. The MAT file is saved
within the same working folder.
sampletime = 0.01; stoptime = 2; run(world,sampletime,stoptime)
Use an output function to send data at each simulation step. The
outputImpl
function sends data about the Box1
actor object to the Unreal Engine. This function controls the actor by varying the actor
transform properties during each simulation step.
function outputImpl(world) world.Actors.Box1.Translation(3) = ... world.Actors.Box1.Translation(3) + 0.01; world.Actors.Box1.Rotation(3) = world.Actors.Box1.Rotation(3) + 0.01; end
Limitations
When recording the 3D animation data into a MAT file, the software does not support:
Recording runtime-created or deleted actors.
Recording runtime reparenting of actors.
Recording viewpoints. Therefore you cannot change views during play back.
Recording scene data during simulation. You can select the scene using the
Scene
argument to play back the recorded data and reproduce the same behavior.Recording the
sim3d.World
object attributes.Recording weather configuration data.
Recording the actor coordinate system.
Version History
Introduced in R2022bUse these properties to record the 3D simulation data.
AnimationRecording
AnimationRecordingInterval
AnimationRecordingFileName
You can use the play
function to
play back the animation from the recorded data.
To record the simulation data, you can now edit the properties
SampleTime
and StopTime
. Previously, these
properties were read-only.
Use the Viewpoints
property of sim3d.World
object to store and access multiple custom viewpoints.
To create viewpoints use the
createViewpoint
function.To set the view, use the
setView
function.
The viewpoint structure includes fields for the default view of the 3D environment and any custom views.
In addition to the default scenes, you can download and install any prebuilt 3D scenes available in the Unreal Engine environment for 3D simulation.
To select and download a scene, use the Install option in the
Simulation 3D Scene Configuration block as described in the Scene name
parameter. MATLAB restarts after the scene is installed. You can now set the installed scene as
the Scene
.
The sim3d.World
object has these new properties to control simulation pacing:
EnablePacing
: Enable pacing for the simulation.PacingRate
: Set the pace of the simulation.
Use the Viewports
property of sim3d.World
object to access multiple custom viewports
created with the createViewport
function. The viewport structure
includes fields for the default view of the 3D environment and any custom views. Previously,
the viewport structure contained a single field, Main
.
The
sim3d.World
object has these new name-value arguments:SampleTime
: Set the sample time for the simulation.StopTime
: Set the stop time for the simulation.
The
sim3d.World
object has these new properties:SampleTime
: Read the sample time for the simulation.StopTime
: Read the stop time for the simulation.SimulationTime
: Read the current simulation time.
Use the new
sim3d.World
object propertyPauseTime
to set the duration after which the simulation pauses.
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.
See Also
Classes
Blocks
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)