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 the co-simulation with Unreal Engine®.
Add or remove actors to or from the world. Only the actors added to the world object are displayed.
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.
Control the co-simulation between MATLAB® and the Unreal Engine.
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
— 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.
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
Object Functions
createViewport | Create viewport for world |
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 |
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
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 R2022bR2024a: 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 命令行窗口中直接输入以执行命令。Web 浏览器不支持 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)