pose

R2026b

Position, orientation, and motion relative to reference frame

Since R2026b

Description

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

A pose object defines the position, orientation, and motion of an entity relative to a reference frame. Use pose objects to specify actor positions and orientations, and to transform between reference frames.

Creation

Syntax

p = pose(position)

p = pose(position,orientation)

p = pose(___,Name=Value)

Description

p = pose(position) creates a pose object with the specified position. By default, the orientation of the pose object is forward along the first axis of the reference frame.

p = pose(position,orientation) creates a pose object with the specified position and orientation.

p = pose(___,Name=Value) creates a pose object with options specified by one or more name-value arguments in addition to any combination of input arguments from previous syntaxes.

Input Arguments

position — Position coordinates

1-by-3 matrix | m-by-3 matrix

Position coordinates, specified as a 1-by-3 or m-by-3 matrix, where m is the number of pose objects you want to create. To specify one position for all m poses, specify this argument as a 1-by-3 vector.

The format and units of the coordinates depends on the reference frame.

• For geographic reference frames, the format is [lat lon h], where lat is latitude in degrees, lon is longitude in degrees, and h is height in meters.

• Otherwise, the format is [X Y Z], with units in meters.

This argument sets the Position property of each created pose object.

orientation — Orientation

m-by-3 matrix | 3-by-3-by-m array | m-by-1 vector of quaternion objects

Orientation, specified as one of these options:

• An m-by-3 matrix that specifies Euler angles in degrees. The axis rotation sequence for the angles must be "ZYX".

• A 3-by-3-by-m array that specifies a direction cosine matrix (DCM).

• An m-by-1 vector of quaternion objects. This option requires a product that includes the quaternion object.

m is the number of pose objects you want to create. If orientation specifies one pose and another argument specifies multiple poses, the orientation applies to all m poses.

The pose object uses this argument to set its Forward, Backward, Left, Right, Up, and Down properties. For more information, see Orientation and Motion Vectors.

Name-Value Arguments

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: pose(position,orientation,Velocity=[10 0 0]) creates a pose object with a velocity of 10 meters per second along the first axis.

ObjectOrientationBasis — Basis vectors for orientation

"auto" (default) | "flu" | "frd"

Basis vectors for the orientation argument, specified as "auto", "flu", or "frd". This value specifies whether the basis vectors for the orientation argument use a forward-left-up (FLU) or forward-right-down (FRD) convention.

The default, "auto", selects a convention based on the AxesConvention property of the reference frame. When the ReferenceFrame property is empty, the default convention is FLU.

Axes Convention	Corresponding Basis
"ned"	"frd"
"enu"	"flu"
"flu"	"flu"
"frd"	"frd"
"xyz"	"flu"

Velocity — Velocity vector, in meters per second

[0 0 0] (default) | 1-by-3 vector | m-by-3 vector

Velocity vector, in meters per second, specified as a 1-by-3 or m-by-3 vector, where m is the number of pose objects you want to create. To specify one velocity for all m poses, specify this argument as a 1-by-3 vector.

Specify this value with respect to the reference frame in ReferenceFrame. For more information, see Orientation and Motion Vectors.

This argument sets the Velocity property of each created pose object.

Acceleration — Acceleration vector, in meters per second squared

[0 0 0] (default) | 1-by-3 vector | m-by-3 vector

Acceleration vector, in meters per second squared, specified as a 1-by-3 or m-by-3 vector, where m is the number of pose objects you want to create. To specify one acceleration for all m poses, specify this argument as a 1-by-3 vector.

Specify this value with respect to the reference frame in ReferenceFrame. For more information, see Orientation and Motion Vectors.

This argument sets the Acceleration property of each created pose object.

AngularVelocity — Angular velocity vector, in radians per second

[0 0 0] (default) | 1-by-3 vector | m-by-3 vector

Angular velocity vector, in radians per second, specified as a 1-by-3 or m-by-3 vector, where m is the number of pose objects you want to create. To specify one angular velocity for all m poses, specify this argument as a 1-by-3 vector.

Specify this value with respect to the reference frame in ReferenceFrame. For more information, see Orientation and Motion Vectors.

This argument sets the AngularVelocity property of each created pose object.

AngularAcceleration — Angular acceleration vector, in radians per second squared

[0 0 0] (default) | 1-by-3 vector | m-by-3 vector

Angular acceleration vector, in radians per second squared, specified as a 1-by-3 or m-by-3 vector, where m is the number of pose objects you want to create. To specify one angular acceleration for all m poses, specify this argument as a 1-by-3 vector.

Specify this value with respect to the reference frame in ReferenceFrame. For more information, see Orientation and Motion Vectors.

This argument sets the AngularAcceleration property of each created pose object.

ReferenceFrame — Reference frame

empty ReferenceFrame object (default) | ReferenceFrame object

Reference frame, specified as a ReferenceFrame object. The position, orientation vector, and motion vector properties report values with respect to this reference frame. For more information, see Orientation and Motion Vectors.

This argument sets the ReferenceFrame property of the created pose objects.

Output Arguments

p — Pose

m-by-1 vector of pose objects

Pose, returned as a m-by-1 vector of pose objects.

Properties

Position — Position coordinates

1-by-3 vector

This property is read-only after object creation.

Position coordinates, specified as a 1-by-3 vector. The format of Position depends on the value of the ReferenceFrame property.

• When ReferenceFrame specifies a geographic reference frame, the format is [lat lon h], where lat is latitude in degrees, lon is longitude in degrees, and h is height in meters.

• When ReferenceFrame specifies any other type of reference frame, the format is [X Y Z], which specifies xyz-coordinates in meters.

Forward — Forward orientation vector

[1 0 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Forward orientation vector, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

Backward — Backward orientation vector

[-1 0 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Backward orientation vector, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

Left — Left orientation vector

[0 1 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Left orientation vector, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

Right — Right orientation vector

[0 -1 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Right orientation vector, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

Up — Up orientation vector

[0 0 1] (default) | 1-by-3 vector

This property is read-only after object creation.

Up orientation vector, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

Down — Down orientation vector

[0 0 -1] (default) | 1-by-3 vector

This property is read-only after object creation.

Down orientation vector, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

Velocity — Velocity vector, in meters per second

[0 0 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Velocity vector, in meters per second, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

Acceleration — Acceleration vector, in meters per second squared

[0 0 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Acceleration vector, in meters per second squared, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

AngularVelocity — Angular velocity vector, in radians per second

[0 0 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Angular velocity vector, in radians per second, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

AngularAcceleration — Angular acceleration vector, in radians per second squared

[0 0 0] (default) | 1-by-3 vector

This property is read-only after object creation.

Angular acceleration vector, in radians per second squared, specified as a 1-by-3 vector. For more information, see Orientation and Motion Vectors.

ReferenceFrame — Reference frame

empty ReferenceFrame object (default) | ReferenceFrame object

This property is read-only after you set it.

Reference frame, specified as a ReferenceFrame object. The position, orientation vector, and motion vector properties report values with respect to this reference frame. For more information, see Orientation and Motion Vectors.

Object Functions

transform	Transform pose object between reference frames
euler	Orientation of pose object as Euler angles
dcm	Orientation of pose object as direction cosine matrix
quaternion	Orientation of pose object as quaternion

More About

Orientation and Motion Vectors

The pose object stores the orientation and motion of an actor using vectors. The object reports the vectors with respect to the reference frame stored in its ReferenceFrame property. For more information about reference frames, see Specify Coordinate Conventions for 3D Scenarios.

• The Forward, Backward, Left, Right, Up, and Down properties are unit vectors that describe the body-frame orientation of the actor. The vectors form an orthonormal set.

  • When an actor has no rotation, the Forward property aligns with the first axis of the reference frame. For example, when ReferenceFrame specifies a local reference frame that uses the east-north-up (ENU) axes convention, the Forward property points east.

  • When you rotate an actor, the orientation vectors also rotate. For example, when you specify a yaw angle of 90 degrees and ReferenceFrame specifies a local reference frame that uses the ENU axes convention, Forward points north instead of east.

  • Orientation vectors are not rotation angles. To convert the orientation vectors to Euler angles, a DCM, or a quaternion object, use the euler, dcm, or quaternion function, respectively.

• The Velocity, Acceleration, AngularVelocity, and AngularAcceleration properties are vectors that describe the body-frame motion of the actor.

Version History

Introduced in R2026b