Main Content

remove

Remove actor added to world or remove all actors in world

Since R2023a

    Description

    remove(world,actor) removes the actor specified by actor from the world specified by world.

    example

    remove(world) removes all actors from world.

    Examples

    collapse all

    This example shows how to delete an actor during a simulation using MATLAB®. You build two ball actors and choose one to destroy. To delete an actor during a simulation using Simulink®, see Delete Actor During Simulation Using Simulink.

    You can use the sim3d.World class and functions to create a world object, view a 3D environment, and delete an actor from the 3D environment during simulation. You can use the sim3d.Actor class and functions to build actor objects in the 3D environment.

    You can also modify actors at run time using the sim3d.World class.

    Create World

    Create a world scene and set up communication with the Unreal Engine® using the update function. The Unreal Engine executes at each time step and sends data to MATLAB in the update function.

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

    Build Ball Actors

    Instantiate two actors named Ball1 and Ball2. Build actor appearances from a sphere using the createShape function. Add actors to the world.

    ball1 = sim3d.Actor(ActorName='Ball1');
    createShape(ball1,'sphere',[0.5 0.5 0.5]);
    ball1.Color = [0 .149 .179];
    ball1.Translation = [0 0 4.5];
    add(world,ball1);
    
    ball2 = sim3d.Actor(ActorName='Ball2');
    createShape(ball2,'sphere',[0.5 0.5 0.5]);
    ball2.Color = [.255 .510 .850];
    ball2.Translation = [0 0 3];
    add(world,ball2);

    Use the UserData property in the sim3d.World object to create a user data structure with a field named Step to store the simulation step during simulation. Initialize the user data structure to 0. You will use this structure to insert a delay before removing an actor from the world in the update function.

    world.UserData.Step = 0;

    Set Viewer Window Point of View

    If you do not create a viewport, then the 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);

    Run Animation

    Run a simulation set for 10 seconds with a sample time of 0.01 seconds.

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

    Two ball actors in the virtual world.

    The Ball1 actor disappears from the 3D environment during simulation.

    One ball actor in the virtual world.

    Delete world

    Delete the world object.

    delete(world);

    Set Up Update Function

    Use an update function to read data at each simulation step. The updateImpl function reads image data from MainCamera1 in the Unreal Engine and removes a ball actor from the scene.

    function updateImpl(world)
        world.UserData.Step = world.UserData.Step + 1;
        actorFields = fields(world.Actors);
        actorPresent = strcmp(actorFields,'Ball1');
        if any(actorPresent) && (world.UserData.Step == 500)
            actorIndex = (find(actorPresent));
            actorToDelete = actorFields{actorIndex};
            remove(world,actorToDelete);
        end
    end

    Input Arguments

    collapse all

    World object from which the actor object is being removed, specified as a sim3d.World object.

    Actor object being removed from the 3D world, specified as a sim3d.Actor object.

    Version History

    Introduced in R2023a