Report Events Using Actor Callbacks

Open Live Script

This example shows how to report actor events in a virtual world and access actor Properties during simulation using MATLAB®. You use the Events and Collsions properties of the actor object to report events and actor callbacks to access properties, including Event Attributes.

First, you create a virtual world and build box actors and a plane actor with sim3d.World and sim3d.Actor objects and functions. Then, you set function handles for actor objects to execute event callback functions when an actor participates in an event. Then, you set the properties of actor objects to animate the actors and report events. Then, you add the actors to the world, set a view in the scene, and set up event callback functions. The event callback function passes the actor handle as the input argument to access the actor properties when an event occurs during simulation. Finally, view the animation in the Simulation 3D Viewer window and the actor properties corresponding to the actor event in the MATLAB® Command Window.

You can detect these actor events:

Hit event
Begin overlap event
End overlap event
Click event

Unreal Engine® uses the PhysX® engine to control actor motion and perform real-time physics calculations when the physics property of an actor is enabled.

Create World

Create a virtual world and set up communication with the Unreal Engine simulation environment using the update function UpdateImpl. The sim3d.World object can send and receive data about a sim3d.Actor object to and from the Unreal Engine at each simulation step using output and update functions, respectively. The Unreal Engine executes at each time step and sends data to MATLAB in the update function. For this example, the update function is used to increment the simulation step value after each simulation step and set actor properties so that the events occur one after the other.

world = sim3d.World('Update', @UpdateImpl);

Enable Hit Event

Instantiate an actor named box1. Set the position of the actor using the Translation property. To animate and report a hit event, set the Mobility and Physics properties of the actor. The Events and Collsions properties are true by default. The OnHit function handle represents the hit event callback function OnHitImpl. Use the OnHitImp function to access the properties of box1. Use the createShape function to build a box shape for the actor, set the size of the box, and set the color of the box. Add the actor to the world.

% Create actors for Hit event in scene
box1 = sim3d.Actor('ActorName','Box1', 'Translation', [8, -5, 6], ...
    'Mobility', sim3d.utils.MobilityTypes.Movable, 'OnHit', @OnHitImpl);
box1.createShape('box', [2, 2, 2]);
box1.Color = [1, 0, 0];
box1.Physics = true;
world.add(box1);

Instantiate an actor named box2. Set the Translation, Mobility, Physics, and Color properties of the actor. Use the createShape function to build a box shape for the actor and set the size of the box. Add the actor to the world.

box2 = sim3d.Actor('ActorName','Box2', 'Translation', [8, -5, 2], ...
    'Mobility', sim3d.utils.MobilityTypes.Movable);
box2.createShape('box', [2, 2, 2]);
box2.Color = [0, 0, 1]; 
box2.Physics = true;
world.add(box2);

For this example, the OnHitImpl function executes when box1 hits box2 in the scene.

Enable Overlap Event

Instantiate an actor named box3. Set the position of the actor using the Translation property. To animate and report an overlap event, set the Mobility, Physics, and Collsions properties of the actor. The OnBeginOverlap and OnEndOverlap function handles represent the overlap event callback functions OnBeginOverlapImpl and OnEndOverlapImpl, respectively. Use these functions to access the properties of box3 when the overlap event begins and ends. Use the createShape function to build box shape for the actor, set the size of the box, and set the color of the box. Add the actor to the world.

% Create actors for Overlap event in scene
box3 = sim3d.Actor('ActorName','Box3', 'Translation', [8, 0, 6], ...
    'Mobility', sim3d.utils.MobilityTypes.Movable, ...
    'OnBeginOverlap', @OnBeginOverlapImpl, 'OnEndOverlap', @OnEndOverlapImpl);
box3.createShape('box', [2, 2, 2]);
box3.Color = [1, 0, 0];
box3.Physics = true;
box3.Collisions = false;
world.add(box3);

Instantiate an actor named box4. Set the Translation, Collsions, and Color properties of the actor. Use the createShape function to build a box shape for the actor and set the size of the box. Add the actor to the world.

box4 = sim3d.Actor('ActorName','Box4', 'Translation', [8, 0, 2]);
box4.createShape('box', [2, 2, 2]);
box4.Color = [0, 0, 1]; 
box4.Collisions = false;
world.add(box4);

For this example, the OnBeginOverlapImpl function executes when box3 begins to overlap box4. The OnEndOverlapImpl function executes when box3 stops overlapping box4.

Enable Click Event

Instantiate an actor named box5. Set the position of the actor using the Translation property. To report a click event, set the Events property of the actor. The default value is true. The OnClick function handle represents the click event callback function OnClickImpl. Use this function to access the properties of box5 when you click the actor during simulation. Use the createShape function to build a box shape for the actor, set the size of the box, and set the color of the box. Add the actor to the world.

% Create actors for Click event in scene
box5 = sim3d.Actor('ActorName','Box5', 'Translation', [8, 5, 6],'OnClick',@OnClickImpl);
box5.createShape('box', [2, 2, 2]);
box5.Color = [1, 0, 0];
world.add(box5);

For this example, the OnClickImpl function executes when you click box5.

Build Plane Actor

Instantiate an actor named plane1. Set the position of the actor using the Translation property. Set the Mobility and PreciseContacts properties of the actor. The PreciseContacts property precisely renders the collision of any actor with the plane actor. Use the createShape function to build a plane shape for the actor and set the size of the plane. Add the actor to the world.

plane1 = sim3d.Actor('ActorName','Plane1','Mobility', sim3d.utils.MobilityTypes.Stationary);
plane1.createShape('plane', [100, 100, 0.01]);
plane1.PreciseContacts = true;
plane1.Translation = [0,0,-3];
world.add(plane1);

Using the UserData property in the sim3d.World object, create a user data structure with a field named Step to store the simulation step during simulation. Initialize the user data structure to 1. You will use this structure in the update function to increment the UserData.Step value after each simulation step and to display the events one after the other.

world.UserData.Step = 1;

Set Viewer Window Point of View

If you do not create a viewport, then the point of view is set to 0, 0, 0, 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 with a single field, Main, that contains a sim3d.sensors.MainCamera object.

viewport = createViewport(world);
viewport.Translation = [-15 0 0];

Run Animation

Run a simulation set for 20 seconds with a sample time of 0.02 seconds. The Simulation 3D Viewer window displays five box actors and a plane actor. During simulation, box1 and box2 display the hit event. The color of the box1 changes when it hits box2, and the MATLAB Command Window displays the hit event attributes of box1. After the hit event, box3 starts to overlap box4. During the overlap, box3 changes color, and the MATLAB Command Window displays the overlap event attributes. After the overlap event, the MATLAB Command Window displays, the message Click on the Rightmost box actor to visualize the click event. Click on the rightmost box actor to display the click event attributes of box5 in the MATLAB Command Window. During each click, the color of box5 changes.

run(world,0.02,20)

HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [700,-600,303] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [890,-590,139] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [890,-590,52] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [890,-590,-95] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [890,-590,-86] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [890,-590,-87] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [891,-592,-90] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [892,-593,-92] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [895,-595,-96] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [895,-595,-97] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-597,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [900,-598,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [911,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [911,-594,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [907,-594,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [906,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [898,-595,-99] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [898,-594,-99] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [895,-595,-96] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [895,-595,-96] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
HIT DETECTED
Actor ID : 1 
Other Actor ID : 2 
Other Actor Name : Box2 
Hit Location : [899,-595,-100] 
 
 
OVERLAP BEGAN
Actor starts overlapping with Box4 
Self Actor ID : 3 
Other Actor ID : 4 
 
OVERLAP ENDS
Actor ends overlapping with Box4 
Self Actor ID : 3 
Other Actor ID : 4 
 
OVERLAP BEGAN
Actor starts overlapping with Plane1 
Self Actor ID : 3 
Other Actor ID : 6 
 
OVERLAP ENDS
Actor ends overlapping with Plane1 
Self Actor ID : 3 
Other Actor ID : 6 
 
Click on the Rightmost box actor to visualize the click event
CLICK DETECTED
Click Event occurred for Box1 
Clicked Actor ID : 5 
Clicked Actor Name : Box5

Virtual world with five box actors. Two box actors vertically aligned on the left side of the scene, next two box actors vertically aligned on the center of the scene and one box actor on the right side of the scene.

Two box actors colliding in the virtual world

Box actor overlapping another actor and changes color.

Box actor changes color after click event.

Delete World

Delete the world object.

world.delete();

Set Up Event Callback Function

Use an event callback function to access actor properties when an actor participates in a particular event. For this example, the event callback functions displays the actor properties described in the Event Attributes of the sim3d.Actor object.

Set Up Hit Event Callback Function

The OnHitImpl function passes the actor handle of box1 as the input argument. When box1 collides with box2, a hit event is reported, and the OnHitImpl function executes. This function changes the color of box1, and the MATLAB Command Window displays the properties of box1 during simulation.

function OnHitImpl(Actor)
% Sets the actor's OnHit callback
    disp('HIT DETECTED');
    fprintf ('Actor ID : %d \n', Actor.HitSelfID);
    fprintf ('Other Actor ID : %d \n', Actor.HitOtherID);
    fprintf ('Other Actor Name : %s \n', Actor.HitOtherActorName);
    fprintf ('Hit Location : [%s] \n \n \n', join(string(Actor.HitLocation), ','));
    Actor.Color = [randi([0 1],1,1), randi([0 1],1,1), randi([0 1],1,1)];
end

Set Up Overlap Event Callback Function

The OnBeginOverlapImpl and OnEndOverlapImpl functions pass the actor handle of box3 as the input argument. When box3 starts to overlap box4, the begin overlap event is reported, and the OnBeginOverlapImpl function executes. When box3 stops overlapping box4, the end overlap event is reported, and the OnEndOverlapImpl function executes.

When box3 starts to overlap box4, the OnBeginOverlapImpl function changes the color of box3, and the MATLAB Command Window displays the properties during simulation. To avoid an overlap event of box3 with plane1, the Collsions property of box3 is set to true in the update function after box3 stops overlapping box4.

% Sets the actor's OnBeginOverlap callback
function OnBeginOverlapImpl(Actor)
    disp('OVERLAP BEGAN');
    fprintf ('Actor starts overlapping with %s \n', Actor.BeginOverlapOtherActorName);
    fprintf ('Self Actor ID : %d \n',    Actor.BeginOverlapSelfID);
    fprintf ('Other Actor ID : %d \n \n',   Actor.BeginOverlapOtherID);
    Actor.Color = [0,1,0];
end

The OnEndOverlapImpl function changes the color of box3, and the MATLAB Command Window displays the properties of box3 during simulation when box3 stops overlapping box4.

% Sets the actor's OnEndOverlap callback
function OnEndOverlapImpl(Actor)
    disp('OVERLAP ENDS');
    fprintf ('Actor ends overlapping with %s \n', Actor.EndOverlapOtherActorName);
    fprintf ('Self Actor ID : %d \n',    Actor.EndOverlapSelfID);
    fprintf ('Other Actor ID : %d \n \n',   Actor.EndOverlapOtherID);    
    Actor.Color = [0,0,1];
end

Set Up Click Event Callback Function

The OnClickImpl function passes the actor handle of box5 as the input argument. This function changes the color of box5, and the MATLAB Command Window displays the properties of box5 during simulation. Each time you click on box5, a click event is reported, and the OnClickImpl function executes.

% Sets the actor's OnClick callback
function OnClickImpl(Actor)
    disp('CLICK DETECTED');
    fprintf ('Click Event occurred for Box1 \n');
    fprintf ('Clicked Actor ID : %d \n',    Actor.ClickActorID);
    fprintf ('Clicked Actor Name : %s \n \n', Actor.ClickActorName);
    Actor.Color = [randi([0 1]), randi([0 1]), randi([0 1])];
end

Set Up Update Function

Use an update function to read data after each simulation step. For this example, the updateImpl function increments the simulation step in the UserData structure after each simulation step. This function uses the simulation step value in UserData structure to set the properties of box1 and box3 so that the box actors animate and the events occur one after the other. The function also displays the instruction to click the rightmost box actor to visualize the click event.

function UpdateImpl(world)
    if world.UserData.Step == 100
        world.Actors.Box1.Gravity = true;
    end    

    if world.UserData.Step == 500
        world.Actors.Box3.Gravity = true;
    end

    if world.UserData.Step == 625
        world.Actors.Box3.Collisions = true;
    end

    if world.UserData.Step == 820
        disp('Click on the Rightmost box actor to visualize the click event');
    end

    world.UserData.Step = world.UserData.Step + 1;
end