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.
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.
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
.
Input 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
— Name of world
autogenerated name (default) | string
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.
RenderOffScreen
— Option to run simulation in background
0
(false
) (default) | 1
(true
)
Option to run simulation in the background, specified as either
0
(false
) or 1
(true
).
Scene
— Name of prebuilt 3D scene
"Empty scene"
(default) | "Straight road"
| "Curved road"
Name of the prebuilt 3D scene in which to simulate, specified as one of these values:
Empty scene
— See Empty Scene.Straight road
— See Straight Road.Curved road
— See Curved Road.
Data Types: string
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.
Example: Update = @updateFcn
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.
Example: Output = @outputFcn
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.
Example: Setup = @setupFcn
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.
Example: Release = @releaseFcn
SampleTime
— Sample time of simulation
0.02
(default) | real positive scalar
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
StopTime
— Simulation stop time
10
(default) | scalar
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.
Properties
Name
— Name of world
autogenerated name (default) | string
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.
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
— Viewports in 3D environment
structure
Viewports in 3D environment, defined 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.
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.
SampleTime
— Sample time of simulation
0.02
(default) | real positive scalar
This property is read-only.
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.
StopTime
— Simulation stop time
10
(default) | real positive scalar
This property is read-only.
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.
SimulationTime
— Current simulation time
0
(default) | real positive scalar
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.
PauseTime
— Time until simulation pauses
inf
(default) | real positive scalar
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
EnablePacing
— Option to enable simulation pacing
0
or false
(default) | 1
or true
Option to enable simulation pacing, specified as 0
(false
) to disable pacing or 1
(true
) to enable pacing.
Data Types: logical
PacingRate
— Simulation pacing rate
1
(default) | real positive scalar
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
Object Functions
createViewport | Create custom view of 3D environment |
add | Add actor to 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 |
remove | Remove actor added to world or remove all actors in world |
load | Load 3D models or actors into world object |
save | Save world object to MAT file |
close | End simulation and close simulation window |
setView | Set view of 3D environment |
deleteViewport | Delete viewport from 3D environment |
view | View 3D environment in Simulation 3D Viewer window |
Examples
Create World and Actor Using MATLAB
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);
Version History
Introduced in R2022bR2024b: Simulation pacing
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.
R2024b: Save multiple custom viewports
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
.
R2024a: Control simulation with new name-value arguments and properties
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.
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.
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
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)