Main Content

sim3d.World

Create 3D environment in Unreal Engine

Since R2022b

expand all in page

    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

    Syntax

    world = sim3d.World()
    world = sim3d.World(Name=Value)

    Description

    world = sim3d.World() creates a world object that defines the 3D environment in the Unreal Engine with a default name.

    world = sim3d.World(Name=Value) specifies options using one or more optional name-value arguments. For example, for a sample time of 0.03 s, set SampleTime to 0.03.

    example

    Input Arguments

    expand all

    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 these values:

    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.

    Properties

    expand all

    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, 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.

    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.

    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.

    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.

    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

    Object Functions

    createViewportCreate custom view of 3D environment
    addAdd actor to 3D environment
    runRun co-simulation with the 3D simulation engine
    pausePause co-simulation with 3D simulation engine
    resumeResume co-simulation with 3D simulation engine
    removeRemove actor added to world or remove all actors in world
    loadLoad 3D models or actors into world object
    saveSave world object to MAT file
    closeEnd simulation and close simulation window
    setViewSet view of 3D environment
    deleteViewportDelete viewport from 3D environment
    viewView 3D environment in Simulation 3D Viewer window

    Examples

    collapse all

    Open Live Script

    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);

    Empty virtual world scene

    Delete World

    Delete the world object.

    delete(world);

    Version History

    Introduced in R2022b

    expand all

    See Also

    Classes

    Blocks

    Topics