Simulate Actor Movement Using MATLAB

Open Live Script

This example shows how you can control an actor in the Unreal Engine® visualization environment through MATLAB®. The Unreal Engine and MATLAB communicate with each other during each simulation step through the co-simulation framework. To control an actor in the Unreal Engine® visualization environment through Simulink®, see Simulate Actor Movement Using Simulink.

You can use the sim3d.World object to set up a co-simulation framework between the Unreal Engine and MATLAB. The sim3d.World object can send and receive data about a sim3d.Actor object to the Unreal Engine at each simulation step using output and update functions. Before the Unreal Engine simulates, MATLAB calls the output function. Then, the Unreal Engine executes at each time step and sends data back to MATLAB in the update function. You can also capture the actor image from any viewpoint using a virtual camera.

Create 3D Environment

Create a world object and set up callback functions to communicate with the Unreal Engine.

world = sim3d.World('Output',@outputImpl,'Update',@updateImpl);

Create Actor

Instantiate a box actor object named Box1. You can use any name for the actor. Specify the size and color of the actor object and add the object to the 3D environment.

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

Add Camera to World Scene

Use the sim3d.sensors.IdealCamera object to capture an image in the Unreal Engine and return the image to MATLAB. To return the image, use the read function in the update function updateImpl.

camera1 = sim3d.sensors.IdealCamera( ...
    'ActorName',"Camera1", ...
    "ImageSize",[768, 1024], ...
    "HorizontalFieldOfView",60);
camera1.Translation = [-3 0 2];
add(world,camera1);

Set Viewer Window Point of View

If you do not create a viewport, then the default view is set and you can use the keyboard shortcuts and mouse controls to navigate in the Simulation 3D Viewer window.

For this example, use the createViewport function to create a viewport.

viewport = createViewport(world,Translation=[-5 0 1]);

Run Animation

Run the animation set for 2 seconds with a sample time of 0.01 seconds. The image from Camera1 displays in MATLAB.

sampletime = 0.01;
stoptime = 2;
run(world,sampletime,stoptime)

Figure contains an axes object. The axes object contains an object of type image.

Cube actor in the virtual world

Delete World

Delete the world object.

delete(world);

Set Up Output Function

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 properties during each simulation step. The changing values of the properties animates the actor in the Unreal Engine.

function outputImpl(world)
% Sets the actor outputs (e.g. actor position to follow a path)
world.Actors.Box1.Translation(3) = ...
    world.Actors.Box1.Translation(3) + 0.01;
world.Actors.Box1.Rotation(3) = world.Actors.Box1.Rotation(3) + 0.01;
world.Actors.Box1.Scale = world.Actors.Box1.Scale + [0.01 0.01 0.01];
world.Actors.Box1.Color = world.Actors.Box1.Color + [0.01 0 0];
end

Set Up Update Function

Use an update function to read data at each simulation step. The updateImpl function reads image data from Camera1 in the Unreal Engine using the read function of the sim3d.sensors.IdealCamera object.

function updateImpl(world)
% Implements a control algorithm and updates the actor states
%  (e.g. read a sensor and calculate new actor position)
sceneImage = read(world.Actors.Camera1);
image(sceneImage);
end