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

    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.

    example

    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.

    Name-Value Arguments

    expand all

    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.

    These are the scenes that you can install. For more information about other scenes, see 3D Scenes for Simulation in Unreal Engine Environment.

    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

    expand all

    World object, returned as a sim3d.World object.

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

    expand all

    addAdd actor to 3D environment
    removeRemove actor added to world or remove all actors in world
    loadLoad 3D models or actors into 3D environment
    saveSave world object to MAT file

    expand all

    createViewportCreate view of 3D environment
    createViewpointCreate custom view of 3D environment
    setViewSet view of 3D environment
    deleteViewportDelete viewport from 3D environment
    deleteViewpointDelete viewpoint from 3D environment

    expand all

    runRun co-simulation with the 3D simulation engine
    pausePause co-simulation with 3D simulation engine
    resumeResume co-simulation with 3D simulation engine
    closeEnd co-simulation and close simulation window
    viewView 3D environment in Simulation 3D Viewer window
    waitWait for co-simulation to complete
    playPlay recorded animation data

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

    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 R2022b

    expand all

    See Also

    Classes

    Blocks

    Topics