sim3d.graphics.PathMarker

Display trajectory

Since R2025a

expand all in page

    Description

    Use the sim3d.graphics.PathMarker object to annotate and visualize a trajectory in the 3D environment. You can visualize an actor trajectory or a reference path in the 3D environment.

    Creation

    Syntax

    marker = sim3d.graphics.PathMarker(WayPoints=WayPoints)
    marker = sim3d.graphics.PathMarker(ControlActorName=ControlActorName)
    marker = sim3d.graphics.PathMarker(___,Name=Value)

    Description

    marker = sim3d.graphics.PathMarker(WayPoints=WayPoints) creates a default marker object to visualize the reference path with coordinates specified by WayPoints. After you create a sim3d.graphics.PathMarker object to visualize the reference path, the properties of the object become read-only.

    marker = sim3d.graphics.PathMarker(ControlActorName=ControlActorName) creates a default marker object to trace the trajectory of the actor specified by ControlActorName. After you create a sim3d.graphics.PathMarker object to trace the trajectory of ControlActorName, you can modify aspects of the object by setting property values.

    marker = sim3d.graphics.PathMarker(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input arguments in previous syntaxes. For example, to create a sphere-shaped marker, set MarkersShape to "Sphere".

    example

    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: marker = sim3d.graphics.PathMarker(WayPoints,MarkersShape="Box",MarkersColor=[0 1 0]) creates a marker object that creates green box markers at the coordinates specified in WayPoints to visualize the reference path coordinates in the 3D environment.

    Example: marker = sim3d.graphics.PathMarker(ControlActorName,MarkersShape="Box",MarkersColor=[0 1 0]) creates a marker object that traces the actor specified by ControlActorName with green box markers.

    Reference path coordinates that can guide the movement of an actor in the 3D environment, specified as an n-by-3-by-2 matrix that is a three-dimensional array. n is the number of waypoints. The first page of the three-dimensional array sets the relative translation (x,y,z), in m. The second page sets the relative rotation (roll, pitch, yaw), in rad.

    Example: WayPoints=cat(3,[0 -1 3; 0 0 3; 0 1 3],[-pi/4 0 0; 0 0 0; pi/4 0 0]);

    Data Types: double

    Name of control actor, specified as a character array or string. Specify the ActorName of the actor object to trace. To visualize the trajectory, the actor object must be added to the world.

    Example: ControlActorName="Actor1"

    Data Types: string

    Name of actor, specified as a character array or string. If you do not specify an actor name, then the software assigns the actor an autogenerated name. Use this argument to set the name of the sim3d.graphics.PathMarker object.

    Note

    If you specify the same name as an actor that already exists, then the software appends actor name you specify with a unique identifier.

    Shape of markers, specified as "Sphere", "Line", "Box", or "Cone".

    Example: MarkersShape="Line"

    Data Types: string

    Color of markers, specified as a real 1-by-3 vector of RGB triplet values. An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0, 1].

    Example: MarkersColor=[0 0 1]

    Data Types: double

    Size of markers, specified as real positive 1-by-3 vector. For a "Line" marker, only the first element of the vector affects the size of the marker, representing the thickness of the line.

    Example: MarkersSize=[0.5 0.5 1]

    Data Types: double

    Option to hide the actor from the 3D environment scene, specified as 0 (false) if the actor is visible in the scene or 1 (true) if the actor is hidden in the scene. When you hide the actor in the scene, all the markers are hidden.

    Example: MarkersHidden=1

    Data Types: logical

    Transparency of markers, specified as a real positive number in the range (0,1), where 0 indicates an opaque object and 1 indicates a completely transparent object.

    Example: MarkersTransparency = 0.8

    Data Types: double

    Output Arguments

    expand all

    Annotation actor, returned as a sim3d.graphics.PathMarker object.

    Properties

    expand all

    All the properties of the sim3d.graphics.PathMarker object are read-only after object creation with the WayPoints argument. If you create the sim3d.graphics.PathMarker object with the ControlActorName argument, the properties of the last drawn marker are run-time configurable.

    Parent of actor, specified as a handle to the parent actor object. After you add an actor to the sim3d.World object, the default parent actor is the Scene Origin at (0,0,0). Use this property to set any actor in the 3D environment as the parent actor of a sim3d.graphics.PathMarker object.

    This property is read-only.

    Children of actor, specified as a structure. Each field of the structure contains a handle to the child of a sim3d.graphics.PathMarker object.

    Parent world, specified as a handle to the parent sim3d.World object. You can use this property only if the sim3d.graphics.PathMarker object is added to the parent sim3d.World object.

    Relative translation (x,y,z) of the actor object to its parent actor, specified as a real 1-by-3 vector, in m. Use Translation to change the position of the sim3d.graphics.PathMarker object in the 3D environment along the X, Y, and Z axes of the coordinate system. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

    Example: marker.Translation = [1 2 1]

    Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real 1-by-3 vector, in rad. Use Rotation to rotate the sim3d.graphics.PathMarker object in the 3D environment.

    Example: marker.Rotation = [pi/4 pi/8 pi/2]

    This property is read-only.

    Reference path coordinates that can guide the movement of an actor in the 3D environment, specified as an n-by-3-by-2 matrix that is a three-dimensional array. n is the number of waypoints. The first page of the three-dimensional array sets the relative translation (x,y,z), in m. The second page sets the relative rotation (roll, pitch, yaw), in rad.

    Data Types: double

    Name of control actor, specified as a character array or string. Specify the ActorName of the actor object to trace. To visualize the trajectory, the actor object must be added to the world.

    Example: marker.ControlActorName = "Actor1"

    Data Types: string

    Color of markers, specified as a real 1-by-3 vector of RGB triplet values. An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0, 1].

    Example: marker.Color = [0.3 0.27 0.9]

    Shape of markers, specified as "Sphere", "Line", "Box", or "Cone".

    Example: marker.MarkersShape = "Line"

    Data Types: string

    Size of markers, specified as real positive 1-by-3 vector. For a "Line" marker, only the first element of the vector affects the size of the marker, representing the thickness of the line.

    Example: marker.MarkersSize = [0.5 0.5 1]

    Data Types: double

    Option to hide the actor from the 3D environment scene, specified as 0 (false) if the actor is visible in the scene or 1 (true) if the actor is hidden in the scene. When you hide the actor in the scene, all the markers are hidden.

    Example: marker.MarkersHidden = 1

    Data Types: logical

    Transparency of markers, specified as a real positive number in the range (0,1), where 0 indicates an opaque object and 1 indicates a completely transparent object.

    Example: MarkersTransparency = 0.8

    Data Types: double

    This property is read-only.

    Translation of last drawn marker, specified as real 1-by-3 vector, in m. Use this property to get the translation during simulation.

    Data Types: double

    This property is read-only.

    Rotation of last drawn marker (roll, pitch, yaw), specified as real 1-by-3 vector, in rad. Use this property to get the rotation during simulation.

    Data Types: double

    Examples

    collapse all

    Open Live Script

    Create a marker object to trace the actor path in the 3D environment using the sim3d.graphics.PathMarker object.

    Create a 3D environment and set up communication with the Unreal Engine® simulation environment using the output function OutputImpl. The sim3d.World object can send data about the 3D environment to the Unreal Engine at each simulation step using output function. Before the Unreal Engine simulates, MATLAB calls the output function and sends data to the Unreal Engine. Then, the Unreal Engine executes at each time step and sends data to MATLAB.

    world = sim3d.World(Output=@outputImpl);

    Create a box actor in the 3D environment using the sim3d.Actor object and add the box to the world.

    cube = sim3d.Actor( ...
        ActorName="Cube", ...
        Mobility=sim3d.utils.MobilityTypes.Movable);
createShape(cube,"box");
cube.Color = [1 0 1];
add(world,cube);

    To view the actor trajectory, create the sim3d.graphics.PathMarker object with ControlActorName, MarkersSize, and MarkersColor. Add the path to the world.

    path = sim3d.graphics.PathMarker(ControlActorName="Cube", ...
    MarkersSize=[0.05 0.05 0.05],MarkersColor=[1 0 0]);
add(world,path);

    Run the co-simulation.

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

    Cube actor with trajectory in the 3D environment.

    Output Function

    The output function sends data about the actor to the Unreal Engine environment at each simulation step. For this example, the function controls the actor by varying the actor transform properties during each simulation step. 

    function outputImpl(world)
    world.Actors.Cube.Translation(3) = ...
        world.Actors.Cube.Translation(3) + 0.01;
    world.Actors.Cube.Rotation(3) = ...
        world.Actors.Cube.Rotation(3) + 0.01; 
end
    Open Live Script

    Create a marker object to view a predefined path in the 3D environment using the sim3d.graphics.PathMarker object. You can create an actor object to control and observe its movement along the predefined path.

    Create a 3D environment and set up communication with the Unreal Engine® simulation environment using the output function OutputImpl. The sim3d.World object can send data about the 3D environment to the Unreal Engine at each simulation step using output function. Before the Unreal Engine simulates, MATLAB calls the output function and sends data to the Unreal Engine. Then, the Unreal Engine executes at each time step and sends data to MATLAB.

    world = sim3d.World(Output=@outputImpl);

    Create a box actor in the 3D environment using the sim3d.Actor object and add the box to the world.

    cube = sim3d.Actor( ...
        ActorName="Cube", ...
        Mobility=sim3d.utils.MobilityTypes.Movable);
createShape(cube,"box");
cube.Color = [1 0 1];
add(world,cube);

    To view a predefined path, set the WayPoints argument and create the sim3d.graphics.PathMarker object with MarkersSize and MarkersColor. Add the path to the world.

    waypoints = cat(3,[zeros(21,2) (0:0.1:2)'],zeros(21,3));
path = sim3d.graphics.PathMarker(WayPoints=waypoints, ...
    MarkersSize=[0.05 0.05 0.05],MarkersColor=[1 0 0]);
add(world,path);

    Run the co-simulation.

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

    Cube actor following the predifined path.

    Output Function

    The output function sends data about the actor to the Unreal Engine environment at each simulation step. For this example, the function controls the actor by varying the actor transform properties during each simulation step. 

    function outputImpl(world)
    world.Actors.Cube.Translation(3) = ...
        world.Actors.Cube.Translation(3) + 0.01;
    world.Actors.Cube.Rotation(3) = ...
        world.Actors.Cube.Rotation(3) + 0.01; 
end

    Version History

    Introduced in R2025a

    See Also

    | | | | |

    Topics