PosePatch Properties

R2026b

Pose plot appearance and behavior

PosePatch properties control the appearance and behavior of a PosePatch object. By changing property values, you can modify certain aspects of the pose plot. Use dot notation to query and set properties. To create a PosePatch object, use the poseplot function.

p = poseplot;
c = p.FaceColor;
p.FaceColor = "red";

Position and Orientation

Orientation — Orientation of pose plot

quaternion(1,0,0,0) object (default) | rotation matrix

Orientation of the pose plot, specified as a quaternion object or a rotation matrix.

Position — Position of pose plot

[0 0 0] (default) | three-element real-valued vector

Position of the pose plot, specified as a three-element real-valued vector.

Color and Styling

ScaleFactor — Scale factor of pose plot

1 (default) | nonnegative scalar

Scale factor of the pose plot, specified as a nonnegative scalar. The scale factor controls the size of the orientation box. When you specify the MeshFileName argument, the scale factor also changes the scale of the mesh.

FaceColor — Face color of pose patch

RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Face color of pose patch, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

• 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]; for example, [0.4 0.6 0.7].

• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

The default value is an RGB triplet from the ColorOrder property of the axes. The SeriesIndex property of the PosePatch object determines which color from the ColorOrder the pose plot uses.

Here is a list of commonly used colors and their corresponding values.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

FaceAlpha — Face transparency of pose patch

0.1 (default) | scalar in range [0, 1]

Face transparency of pose patch, specified as a scalar in range [0, 1]. A value of 1 is fully opaque and 0 is completely transparent.

MeshFileName — Name of STL mesh file

string scalar | character vector

This property is read-only after object creation.

Name of Standard Triangle Language (STL) mesh file, specified as a string scalar or a character vector containing the name of the mesh file. When you specify this argument, the poseplot function plots the mesh instead of the orientation box.

EdgeDensity — Edge density of mesh

0.8 (default) | numeric scalar in range [0, 1]

Since R2026b

This property is read-only after object creation.

Edge density of mesh, specified as a numeric scalar in the range [0, 1]. This property controls the density of edges displayed on a mesh specified by MeshFileName.

A value of 0 hides all edges. A value of 1 displays all edges. Between 0 and 1, higher values display more edges.

Setting this property has no effect if you do not specify MeshFileName.

For more information about EdgeDensity, see the More About section.

Data Types: single | double

EdgeColor — Color of mesh edges

RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Since R2026b

Color of mesh edges, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

• 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]; for example, [0.4 0.6 0.7].

• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Setting this property has effect only when a mesh is specified using the MeshFileName property and EdgeDensity is greater than 0.

Here is a list of commonly used colors and their corresponding values.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

EdgeAlpha — Transparency of mesh edges

0.5 (default) | scalar in range [0, 1]

Since R2026b

Transparency of mesh edges, specified as a scalar in the range [0, 1]. A value of 1 means fully opaque and 0 means completely transparent (invisible).

Setting this property has effect only when a mesh is specified using the MeshFileName property and EdgeDensity is greater than 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

EdgeLineWidth — Width of mesh edges

0.5 (default) | positive numeric scalar

Since R2026b

Width of mesh edges, specified as a positive numeric scalar in point units. One point equals 1/72 inch.

Setting this property has effect only when a mesh is specified using the MeshFileName property and EdgeDensity is greater than 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Pose Display

PoseAxisLabels — Visibility of pose axis labels

"on" (default) | "off" | on/off logical value

Since R2026b

Visibility of pose axis labels, specified as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• "on" — Display the X, Y, and Z axis labels at the tips of the pose axes.

• "off" — Hide the axis labels. Use this option to improve plot visibility when displaying a large number of poses simultaneously.

OriginBox — Visibility of origin box

"on" (default) | "off" | on/off logical value

Since R2026b

Visibility of the origin box, specified as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• "on" — Display the box at the origin of the pose.

• "off" — Hide the origin box. Use this option to improve plot visibility when displaying a large number of poses simultaneously.

Setting this property has no effect when you specify a mesh using MeshFileName. Specifying MeshFileName hides the origin box.

Parent/Children

Parent — Parent axes

Axes object

Parent axes, specified as an Axes object.

Children — Children

empty GraphicsPlaceholder array | DataTip object array

Children, returned as an empty GraphicsPlaceholder array or a DataTip object array. Currently, this property is not used and is reserved for future use.

Interactivity

Visible — Pose plot visibility

"on" (default) | "off" | on/off logical value

Pose plot visibility, specified as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• "on" — Display the object.

• "off" — Hide the object without deleting it. You still can access the properties of an invisible object.

HandleVisibility — Visibility of pose patch object handle

"on" (default) | "off" | "callback"

Visibility of the pose patch object handle in the Children property of the parent, specified as one of these values:

• "on" — Object handle is always visible.

• "off" — Object handle is invisible at all times. This option is useful for preventing unintended changes by another function. Set HandleVisibility to "off" to temporarily hide the handle during the execution of that function. Hidden object handles are still valid.

• "callback" — Object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command line, but permits callback functions to access it.

Standard Chart Properties

DisplayName — Pose plot name to display in legend

string scalar | character vector

Pose plot name to display in the legend, specified as a string scalar or character vector. The legend does not display until you call the legend command. If you do not specify the display name, then legend sets the label using the format "dataN", where N is the order of pose plots shown in the axes. You can also directly specify the legend. For example: legend("Pose1","Pose2").

Type — Type of pose plot object

Read-only: 'PosePatch' (default)

This property is read-only.

Type of pose plot object, returned as 'PosePatch'. Use this property to find all objects of a given type within a plotting hierarchy, for example, searching for the type using the findobj function.

Annotation — Control for including or excluding object from legend

Read-only: Annotation object

This property is read-only.

Control for including or excluding the object from a legend, returned as an Annotation object. Set the underlying IconDisplayStyle property to one of these values:

• "on" — Include the object in the legend (default).

• "off" — Do not include the object in the legend.

For example, to exclude a graphics object, go, from the legend, set the IconDisplayStyle property to "off".

go.Annotation.LegendInformation.IconDisplayStyle = "off";

Alternatively, you can control the items in a legend using the legend function.

SeriesIndex — Pose plot series index

nonnegative integer | "none"

Pose plot series index, specified as a nonnegative integer or "none". Use this property to reassign the marker colors of several PosePatch objects so that they match each other. By default, the SeriesIndex property of a PosePatch object is a number that corresponds to the order of creation of the object, starting at 1.

MATLAB uses the number to calculate indices for assigning colors when you call plotting functions if you do not specify the color directly. The indices refer to the rows of the arrays stored in the ColorOrder property of the axes.

A SeriesIndex value of "none" corresponds to a neutral color that does not participate in the indexing scheme.

More About

EdgeDensity

The EdgeDensity value determines the filter angle used to identify the edges to be displayed. The filter angle in radians is (1 - EdgeDensity) × π. An edge is displayed when the dihedral angle between its two adjacent triangular faces deviates from π radians by more than the filter angle. For more information on filter angle, see the featureEdges documentation.

Version History

Introduced in R2021b

R2026b: Control visibility of origin box and pose axis labels

You can now control the visibility of origin box and pose axis labels of a pose using the new OriginBox and PoseAxisLabels properties, respectively. You can use this option to improve plot visibility when displaying a large number of poses simultaneously.

R2026b: Control display of mesh edges

You can now control the visibility of origin box and pose axis labels of a pose using the new OriginBox and PoseAxisLabels properties, respectively. You can use this option to improve plot visibility when displaying a large number of poses simultaneously.

R2026b: Default display of mesh edges changed

Starting in R2026b, when you specify an STL mesh using the MeshFileName argument, the pose plot displays only edges whose adjacent faces meet at a dihedral angle that deviates from 180 degrees by more than (1 - EdgeDensity) × 180 degrees. With the default EdgeDensity of 0.8, only edges sharper than 36 degrees are shown by default. In previous releases, all mesh edges were displayed by default.

To use the previous default behavior, set EdgeDensity to 1:

poseplot(MeshFileName="groundvehicle.stl",EdgeDensity=1)

R2026b: PatchFaceColor and PatchFaceAlpha properties renamed

The PatchFaceColor and PatchFaceAlpha properties are now called FaceColor and FaceAlpha, respectively. The behavior of both properties remains the same. There are no plans to remove support for existing references to PatchFaceColor and PatchFaceAlpha.