View Actor Orientation in MATLAB Coordinate System

This example shows how a box actor moves and rotates in the MATLAB coordinate system using MATLAB®. You can use sim3d.World object and functions to create and view a 3D environment and sim3d.Actor object and functions to build an actor in the world.

First, you create a world scene, then use the CoordinateSystem property of sim3d.Actor object to select a coordinate system to represent actor orientation in the 3D environment. You build a box actor, and add the actor to the 3D environment. You then set up a function to build the coordinate axes in the 3D environment, set up output function to display the actor orientation in the specified coordinate system, and set up update function to access and increment the simulation step. Finally, you set a view in the scene and view the animation in the Simulation 3D Viewer window.

This example uses the MATLAB coordinate system, but the software supports all of these:

• Default

• MATLAB

• ISO8855

• Aero

• Vrml

• SAE

Create 3D environment

Create a 3D environment and set up communication with Unreal Engine® using output and update functions. sim3d.World objects 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. Before the Unreal Engine simulates, MATLAB calls the output function. Then, the Unreal Engine executes at each time step and sends back data to MATLAB in the update function. You can use the update function to read this data or change values after each simulation step.

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

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, ...
    Translation=[-4 2 1],Rotation=[0 0 -pi/8]);

Create Coordinate System Axes

Assign a coordinate system value of MATLAB to coordSys.

coordSys = 'MATLAB';

Call the function createAxes to create the three-dimensional axes for the specified coordinate system in the 3D environment.

createAxes(world,coordSys);

Build Box Actor

Instantiate a box actor object named Box. Build the actor appearance from a box using the createShape function. Set the Color and Mobility of the actor. Set the CoordinateSystem property and add the actor to the 3D environment.

box = sim3d.Actor(ActorName='Box');
createShape(box,'box',[0.25 0.25 0.25]);
box.Color = [0.1 0.1 0.1];
box.Mobility = sim3d.utils.MobilityTypes.Movable;
box.CoordinateSystem = coordSys;
add(world,box);

Using the UserData property of 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 in the output function to set the animation time for the box along each axis.

world.UserData.Step = 1;

Run Animation

Run a simulation set for 35 seconds with a sample time of 0.02 seconds.

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

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 Box actor object to the Unreal Engine. For this example, the function animates the Box actor along the X, Y and Z axes to show the orientation in the coordinate system.

function outputImpl(world)
% Sets the actor outputs (e.g. an actor position to follow a path)
% Create actors in scene
    timePeriod = uint32(floor(world.UserData.Step/500));
    movementTime = world.UserData.Step - (timePeriod*500);
    deltaRotation = 60*(pi/180)/250;
    box = world.Actors.Box;
    switch timePeriod
        case 0
            box.Color = [1 0 0];
            if movementTime < 250
                box.Translation(1) = box.Translation(1) + 0.01;
            else
                box.Translation(1) = box.Translation(1) - 0.01;
            end
        case 1
            box.Color = [0 1 0];
            if movementTime < 250
                box.Translation(2) = box.Translation(2) + 0.01;
            else
                box.Translation(2) = box.Translation(2) - 0.01;
            end
        case 2
            box.Color = [0 0 1];
            if movementTime < 250
                box.Translation(3) = box.Translation(3) + 0.01;
            else
                box.Translation(3) = box.Translation(3) - 0.01;
            end
        case 3
            box.Color = [1 0 0];
            if movementTime < 250
                box.Rotation(1) = box.Rotation(1) + deltaRotation;
            else
                box.Rotation(1) = box.Rotation(1) - deltaRotation;
            end
        case 4 
            box.Color = [0 1 0];
            if movementTime < 250
                box.Rotation(2) = box.Rotation(2) + deltaRotation;
            else
                box.Rotation(2) = box.Rotation(2) - deltaRotation;
            end
        case 5
            box.Color = [0 0 1];
            if movementTime < 250
                box.Rotation(3) = box.Rotation(3) + deltaRotation;
            else
                box.Rotation(3) = box.Rotation(3) - deltaRotation;
            end
    end
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 ends.

function updateImpl(world)
    world.UserData.Step = world.UserData.Step + 1;
end

Set Up Function to Create Axes in 3D environment

The createAxes function creates X, Y and Z axes in the 3D environment based on the selected coordinate system. The function builds the axes using the createShape function. This function also sets the color of the axes and positions the axes to appear at the origin of the 3D environment.

function createAxes(world, csys)
    % Creates a triad to show the world axes
    % Axes X, Y, Z represented by colors R, G, B respectively
    xA = sim3d.Actor(ActorName='XAxis');
    yA = sim3d.Actor(ActorName='YAxis');
    zA = sim3d.Actor(ActorName='ZAxis');

    xA.CoordinateSystem = csys;
    yA.CoordinateSystem = csys;
    zA.CoordinateSystem = csys;

    createShape(xA,'box',[5 0.02 0.02]);
    createShape(yA,'box',[0.02 5 0.02]);
    createShape(zA,'box',[0.02 0.02 5]);

    % size/2 to create starting point at origin
    xA.Translation = [2.5 0.01 0.01];
    yA.Translation = [0.01 2.5 0.01];
    zA.Translation = [0.01 0.01 2.5];

    xA.Color = [1 0 0]; % Red
    yA.Color = [0 1 0]; % Green
    zA.Color = [0 0 1]; % Blue

    add(world,xA);
    add(world,yA);
    add(world,zA);
end