Main Content

insertObjectKeypoints

Insert object keypoints in image

Since R2023b

collapse all in page

Syntax

RGB = insertObjectKeypoints(I,keypoints)
RGB = insertObjectKeypoints(___,Name=Value)

Description

RGB = insertObjectKeypoints(I,keypoints) inserts a set of object keypoints, keypoints into the specified image, I and returns the result as a truecolor output image, RGB.

example

RGB = insertObjectKeypoints(___,Name=Value) specifies one or more name-value arguments, in addition to any combination of input arguments from the previous syntax, to configure the keypoints to be inserted in the image. For example, KeypointSize=3 inserts keypoints with the size of 3 pixels in the image.

example

Examples

collapse all

This example uses:

Open Live Script

Read an input image

I = imread("visionteam.jpg");

Run the detect method of YOLOv4 object detector to detect bounding boxes around persons in the image. Here, persons are considered as objects.

detector = yolov4ObjectDetector("csp-darknet53-coco");
[bboxes,scores,labels] = detect(detector,I,Threshold=0.4);
personIndices = labels=="person";
personBoxes = bboxes(personIndices,:);

Run the detect method of a pretrained HRNet object keypoint detector to detect keypoints of every person in the image.

keypointDetector = hrnetObjectKeypointDetector;
[keypoints,keypointScores,valid] = detect(keypointDetector,I,personBoxes);

Create an object skeleton from keypoint connections. Each row in the skeleton corresponds to categorical keypoint class indices of a keypoint connection. 

objectSkeleton = keypointDetector.KeypointConnections
objectSkeleton = 17×2

     2     4
     2     1
     3     5
     3     1
     1     6
     1     7
     6     8
     8    10
     7     9
     9    11
      ⋮

Insert the keypoints and skeleton on the respective person and display results.

detectedKeypoints = insertObjectKeypoints(I,keypoints,KeypointColor="yellow",KeypointSize=2,...
                                          Connections=objectSkeleton,ConnectionColor="c",LineWidth=1);
imshow(detectedKeypoints);

Figure contains an axes object. The hidden axes object contains an object of type image.

This example uses:

Open Live Script

Read an input image.

I = imread("visionPeople.jpg");

Specify a bounding box to detect the persons in the image.

bboxes = uint8([1.39,19.30,122.39,341.61;131.78,27.06,108.36,324.50]);

Detect keypoints of the person by using the detect method of pretrained HRNet object keypoint detector.

keypointDetector = hrnetObjectKeypointDetector("human-full-body-w32");
[keypoints,keypointScores,valid] = detect(keypointDetector,I,bboxes);

Read categorical class labels of keypoints from the keypoint detector object.

labels = keypointDetector.KeyPointClasses
labels = 17x1 categorical
     Nose 
     Left-eye 
     Right-eye 
     Left-ear 
     Right-ear 
     Left-shoulder 
     Right-shoulder 
     Left-elbow 
     Right-elbow 
     Left-wrist 
     Right-wrist 
     Left-hip 
     Right-hip 
     Left-knee 
     Right-knee 
     Left-ankle 
     Right-ankle

Insert and display detected keypoints along with the labels in the image.

detectedKeypoints = insertObjectKeypoints(I,keypoints,KeypointColor="yellow",KeypointSize=2,keypointLabel=labels,...
                                         TextBoxColor="white",TextBoxOpacity=0.8,FontSize=8);
imshow(detectedKeypoints);

Figure contains an axes object. The hidden axes object contains an object of type image.

Input Arguments

collapse all

Input image, specified as an X-by-Y matrix for a grayscale image, or an X-by-Y-by-3 array for a RGB color image.

Data Types: single | double | int16 | uint8 | uint16

Object keypoints, specified as an M-by-2-by-P array for P objects in the image. M is the number of keypoints corresponding to each object in the input image I. Each row of the M-by-2 matrix is a keypoint location in the format [x y].

Data Types: double

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: insertObjectKeypoints(__,KeypointColor=[255 0 0]) inserts all the keypoints in red color.

Keypoint indices of keypoint connections specified as an L-by-2 matrix. L is the number of keypoint connections in an object. Each row in the matrix has two indices of connected keypoints. These two keypoints are connected by a line segment.

Data Types: double

Keypoint visibility value, specified as an M-by-P logical matrix. M is the number of keypoints in an object. P is the total number of objects in the image.

  • Keypoints with the keypoint visibility value set to true or 1 in the matrix are inserted in the image.

  • Keypoints with the keypoint visibility value set to false or 0 in the matrix are not inserted in the image.

By default, all keypoints have a keypoint visibility value set to true or 1.

Data Types: logical

Keypoint color, specified as a character vector, cell array of character vectors, M- element vector, or M-by-3 matrix of RGB 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.

You can specify a different color for each keypoint or one color for all keypoints. To specify one color for all keypoints, set KeypointColor to a color string or an [R G B] vector.

SpecificationFormatExample
One color for all keypoints

String or character color name

"r"

"red"

1-by-3 vector (RGB triplet)

[1 0 0]1-by-3 grid, with columns labeled r,g,b respectively.

Different color for each keypointM-element vector

["red","yellow","blue"]

M-by-3 matrix, as a list of RGB values

[1 0 0
 0 1 1
 1 0 1]
M-by-3 grid, with columns labeled r,g,b respectively.

Supported colors are listed in the table.

Color NameShort NameRGB TripletAppearance
"red""r"[1 0 0]

Sample of the color red

"green""g"[0 1 0]

Sample of the color green

"blue""b"[0 0 1]

Sample of the color blue

"cyan" "c"[0 1 1]

Sample of the color cyan

"magenta""m"[1 0 1]

Sample of the color magenta

"yellow""y"[1 1 0]

Sample of the color yellow

"black""k"[0 0 0]

Sample of the color black

"white""w"[1 1 1]

Sample of the color white

Data Types: logical | uint8 | uint16 | int16 | double | single

Keypoint labels, specified as an M-element categorical vector. M is the number of keypoints in an object.

Data Types: categorical

Keypoint size, specified as a positive integer in pixels.

Data Types: categorical

Opacity of keypoints and connections, specified as a scalar value in the range [0 1]. The value 1 makes the keypoints and connections completely opaque and the value 0 makes them completely transparent.

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

Color of line segment connecting keypoints, specified as a character vector, cell array of character vectors, M- element vector, or M-by-3 matrix of RGB 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.

You can specify a different color for each keypoint connection or one color for all connections. To specify one color for all keypoint connections, set ConnectionColor to a color string or an [R G B] vector.

For a description of RGB color and how to specify it, see KeypointColor.

Data Types: logical | uint8 | uint16 | int16 | double | single

Line width of keypoint connection, specified as a positive integer. The unit is pixels.

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

Text box color of keypoint label, specified as a character vector, cell array of character vectors, M- element vector, or M-by-3 matrix of RGB values. M is the number of keypoints in an object.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color.

You can specify a different color for each text box or one color for all text boxes. To specify one color for all text boxes, set TextBoxColor to a color string or an [R G B] vector.

For a description of RGB color and how to specify it, see KeypointColor.

Data Types: logical | uint8 | uint16 | int16 | double | single

Text box background opacity of keypoint label, specified as a scalar. Specify the opacity value in the range [0 1].

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

Font color of keypoint label, specified as a character vector, cell array of character vectors, vector, or M-by-3 matrix of RGB values. M is the number of keypoints in an object.

You can specify a different font color for each keypoint label or one font color for all keypoint labels. To specify one color for all keypoint labels, set FontColor to a color string or an [R G B] vector. For a description of RGB color and how to specify it, see KeypointColor.

Data Types: logical | uint8 | uint16 | int16 | double | single

Font face of text, specified as a character vector. The font face must be one of the available truetype fonts installed on your system. To get a list of available fonts on your system, type listTrueTypeFonts at the MATLAB® command prompt.

Data Types: char | string

Font size of keypoint label text, specified as an integer that corresponds to points in the range [8 72].

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

Output Arguments

collapse all

Output image, returned as a RGB color image of same datatype as the input image, with the same X-by-Y-by-3 dimensions as I.

Limitations

Value to the LineWidth, TextBoxColor, TextBoxOpacity, Font, FontColor, FontSize arguments should be specified only when the KeypointLabel argument is non-empty.

Extended Capabilities

Version History

Introduced in R2023b

See Also

| | |

Topics