ActorAttachmentPoint

R2026b

Attachment point in RoadRunner scenario

Since R2026b

expand all in page

    Description

    The ActorAttachmentPoint object represents the spatial relationship between a child actor and its parent in the RoadRunner scenario, such as the distance and orientation between a trailer and the truck to which it is attached. When you attach a child actor to a parent actor, RoadRunner Scenario relocates the child actor so that its new position is relative to the parent actor based on the connection attributes of the child actor. You can use the ActorAttachmentPoint object properties to programmatically modify the connection attributes of the corresponding child actor. For more information on connection attributes, see Connection Attributes (RoadRunner Scenario).

    Creation

    To return the ActorAttachmentPoint object for a child actor in your RoadRunner scenario, extract the InitialPoint property of an actor that you have attached to a parent actor using the setActorInitialParent function. For example, given the Scenario object scnro, and that you have specified setActorInitialParent(scnro,childActor,parentActor), you can create an ActorAttachmentPoint object, childAttach, by specifying childAttach = childActor.InitialPoint.

    Properties

    expand all

    Name of the attachment point, specified as a string scalar or character vector.

    Note

    You can specify the Name property of ActorAttachmentPoint in MATLAB®, but RoadRunner Scenario does not display the Name property of attachment points in the user interface.

    Offset between the parent actor and child actor contact points, specified as a three-element vector. Units are in meters.

    Heading angle of the child actor relative to the parent actor, specified as a numeric scalar in the range [–180, 180]. Units are in degrees.

    Slope angle of the child actor relative to the parent actor, specified as a numeric scalar in the range [–180, 180]. Units are in degrees.

    Attachment type of the child actor, specified as "trailer" or "fixed". This property determines the behavior of the child actor during simulation.

    • "trailer" — Specifies for the child actor to follow the parent actor as a trailer, using independent movement dynamics relative to the parent actor. RoadRunner Scenario supports this option for only vehicle actors.

    • "fixed" — Specifies for the child actor to be fixed to the parent actor, locking its rotation to the dynamics of the parent actor.

    Actor to which the child actor is attached, specified as one of these objects:

    • Vehicle object — Represents a vehicle actor in the RoadRunner scenario.

    • Character object — Represents a character actor in the RoadRunner scenario.

    • MovableObject object — Represents a movable object actor in the RoadRunner scenario.

    Source of the contact point for the attachment on the child actor, specified as one of these values:

    • "computed" — RoadRunner Scenario computes the contact point for the attachment using the bounding box geometry of the child actor.

    • "imported" — The FBX file associated with the child actor asset defines the contact point for the attachment.

    Name of the child contact point used for the attachment, specified as a string scalar or character vector. If you set ChildContactPointSource to "computed", this property must be one of these options:

    • "Front" — Specifies for the computed contact point to be at the front of the actor.

    • "Origin" — Specifies for the computed contact point to be at the origin of the actor.

    • "Rear" — Specifies for the computed contact point to be at the rear of the actor.

    If you set ChildContactPointSource to "imported" you must specify the user-defined name of the attachment point in the FBX file associated with the actor asset. The name of the imported attachment point must be "hitch" or begin with the word "attach", for example "attach_rear" or "attachCustom". If the specified name does not meet these requirements, RoadRunner Scenario displays an error in the Output pane.

    Source of the contact point for attachment on the parent actor, specified as one of these values:

    • "computed" — RoadRunner Scenario computes the contact point for the attachment using the bounding box geometry of the parent actor.

    • "imported" — The FBX file associated with the parent actor asset defines the contact point for the attachment.

    Name of the parent contact point used for the attachment, specified as a string scalar or character vector. If you set ParentContactPointSource to "computed", this property must be one of these options:

    • "Front" — Specifies for the computed contact point to be at the front of the actor.

    • "Origin" — Specifies for the computed contact point to be at the origin of the actor.

    • "Rear" — Specifies for the computed contact point to be at the rear of the actor.

    If you set ParentContactPointSource to "imported" you must specify the user-defined name of the attachment point in the FBX file associated with the actor asset. The name of the imported attachment point must be "hitch" or begin with the word "attach", for example "attach_rear" or "attachCustom". If the specified string does not meet these requirements, RoadRunner Scenario displays an error in the Output pane.

    Examples

    collapse all

    Use the setActorInitialParent function to attach a child actor to a parent actor, and extract the resulting ActorAttachmentPoint object. You can use the ActorAttachmentPoint object to modify the properties of the child actor connection attributes.

    This example assumes that you have prior knowledge of working with RoadRunner in MATLAB. Before proceeding, follow the steps outlined in Set Up MATLAB Environment for RoadRunner Authoring Functions to set up your scenario using MATLAB functions for scenario authoring.

    Add Two Actors to Scenario

    Add two actors to your scenario by specifying the assets to use for the actors and the locations in the scenario in which to place them. Use the getAsset function to extract VehicleAsset objects that represent the SemiTruck.fbx_rrx and SemiTruck_Trailer01.fbx_rrx assets from the project prj. Then, use the addActor function to add them to the scenario represented by the Scenario object scnro at the scenario origin.

    semitruckAsset = getAsset(prj,"Vehicles/SemiTruck.fbx_rrx","VehicleAsset");
trailerAsset = getAsset(prj,"Vehicles/SemiTruck_Trailer01.fbx_rrx","VehicleAsset");
semiTruck = addActor(scnro,semitruckAsset,[0 0 0]);
trailer = addActor(scnro,trailerAsset,[0 0 0]);

    Align the semiTruck actor to a road. Use the findSceneAnchor function to reference an existing anchor in the scene, and then use anchorToPoint to relocate the actor from the current location to the location specified by the referenced anchor. For more information, see findSceneAnchor and anchorToPoint.

    anchorPoint = findSceneAnchor(scnro,"ScenarioStart");
semiPoint = semiTruck.InitialPoint;
anchorToPoint(semiPoint,anchorPoint,PosePreservation="reset-pose")

    Use setActorInitialParent to Attach Two Actors

    To attach the actor trailer as a child to the actor semiTruck, use the setActorInitialParent function. This creates an ActorAttachmentPoint object that represents the connection attributes of the child actor trailer.

    setActorInitialParent(scnro,trailer,semiTruck)

    Extract the ActorAttachmentPoint object from the InitialPoint property of the child actor to modify the attachment properties. Change the Offset property to adjust the position of the child actor trailer relative the parent actor semiTruck.

    trailerAttachmentPoint = trailer.InitialPoint;
trailerAttachmentPoint.Offset = [0 5 0];

    Run the simulation.

    simulateScenario(rrApp)

    Version History

    Introduced in R2026b

    See Also

    | | | |