actor

R2026b

Create point actor in 3D scenario

Since R2026b

expand all in page

    Description

    Add-On Required: This feature requires the 3D Scenarios add-on.

    An Actor object represents a movable entity in a 3D scenario.

    Creation

    Create actors by using these functions:

    • Create a car actor by using the car function.

    • Create an aircraft actor by using the aircraft function.

    • Create a generic point actor by using the actor function (described here).

    Syntax

    actr = actor(scnro,p)
    actr = actor(scnro,p,Name=name)

    Description

    actr = actor(scnro,p) creates a generic point actor in the specified scenario using the specified position or trajectory. Generic point actors do not include a 3D model. If you specify multiple positions or trajectories, then the function creates multiple actors.

    By default, creating an actor automatically creates an actor visual in each open scenario viewer. To avoid the automatic creation of visuals in a viewer, set the AutoUpdate property of the corresponding GlobeViewer object to "off".

    actr = actor(scnro,p,Name=name) specifies the name of the actor.

    Input Arguments

    expand all

    3D scenario, specified as a Scenario object.

    When the scenario uses custom terrain, the actor must be within the bounds of the terrain.

    Actor position or trajectory, specified as one of these options:

    • A geospatial table containing geopointshape objects — Place the actors at the positions specified by the table. You can create a geospatial table from coordinates by using the pointtable function. Each row of the table corresponds to one actor.

      • If the geopointshape objects represent 2D points, then the function places the actors on the terrain or surface specified by the height reference of the points. If the points do not specify a height reference, then the function places the actors on the terrain.

      • If the geopointshape objects represent 3D points, then the function places the actors at the specified heights, relative to the height reference specified by the points.

    • A vector of pose objects — Place the actors using the positions and orientations specified by the pose objects. Each pose object corresponds to one actor.

      • The velocity, acceleration, angular velocity, and angular acceleration of the pose objects must be 0.

      • If the ReferenceFrame property of the pose object is empty, then the function interprets the pose using the ReferenceFrame property of the scene.

    • A vector of groundTrajectory or airTrajectory objects — Place the actors using the initial positions and orientations specified by the trajectory objects. Each trajectory object corresponds to one actor. The function converts the trajectory objects to FixedTrajectoryBehavior objects and stores them in the Behavior property.

    When you use 2D points or a groundTrajectory object as input to the actor function, the function places the actor 1 cm above the terrain surface.

    Actor name, specified as a string scalar, character vector, string array, or cell array of character vectors. Actor names do not need to be unique.

    This argument sets the Name property of each actor object.

    Data Types: char | string | cell

    Output Arguments

    expand all

    Point actor, returned as an m-by-1 vector of Actor objects, where m is the number of actors.

    Properties

    expand all

    This property is read-only while the simulation is running.

    Actor name, specified as a string scalar or character vector. Actor names do not need to be unique.

    By default, the scenario generates a name by combining the name of the creation function with an integer, such as "car1", "aircraft2", and "actor3".

    Data Types: char | string

    This property is read-only.

    Actor identifier, represented as a positive integer. The scenario generates unique identifiers for the actors, starting with 1 and incrementing by 1 each time you add an actor to the scenario.

    Data Types: uint64

    This property is read-only.

    Actor asset, represented as an Asset object. The asset specifies information about the actor, such as the 3D model and the reference points.

    When you create an actor by using the actor function, the Asset property is empty. When you create an actor using the car or aircraft function, the Asset property contains a 3D model and reference points for a car or aircraft, respectively.

    This property is read-only while the simulation is running.

    Actor behavior, specified as a FixedTrajectoryBehavior object.

    The initial value of this property depends on whether you specify a position, pose, or trajectory as input to the creation function:

    • When you specify a position or pose as input, the property is empty.

    • When you specify a trajectory as input, the scenario converts the trajectory to a FixedTrajectoryBehavior object. Create actor trajectories by using the groundTrajectory and airTrajectory functions.

    Visuals associated with the actor, represented as a vector of ActorVisual objects. By default, when you add an actor to a scenario with open viewers, the scenario creates an ActorVisual object for each viewer and stores the objects in this property.

    Adjust the properties of an ActorVisual object by using dot notation. For example, change the marker fill color for the visual associated with actor act by using act.Visual.MarkerFaceColor = "green". To edit or query the properties of multiple actor visuals at once, use the set or get function. To get the visual for a specific viewer, use the getvisual function.

    Adding or removing objects using this property is not supported.

    Object Functions

    expand all

    positionSet or get actor position
    translateTranslate actor
    rotateRotate actor
    poseSet or get actor pose
    getvisualGet visual for actor, behavior, or analysis
    zoomtoFocus camera on actor, behavior, or analysis
    followMove camera to follow actor
    losAnalysisAdd line-of-sight analysis to 3D scenario
    rayTraceAnalysisAdd ray trace analysis to 3D scenario
    materialsGet materials of scene or actor
    removeRemove actor or analysis from 3D scenario

    Version History

    Introduced in R2026b

    See Also

    Functions

    Objects

    Topics