Draws the found matches of keypoints from two images

out = cv.drawMatches(im1, keypoints1, im2, keypoints2, matches1to2)
out = cv.drawMatches(..., 'OptionName', optionValue, ...)

Input

• im1 First source image.
• keypoints1 Keypoints from the first source image. A 1-by-N structure array with the following fields:
  • pt coordinates of the keypoint [x,y]
  • size diameter of the meaningful keypoint neighborhood
  • angle computed orientation of the keypoint (-1 if not applicable). Its possible values are in a range [0,360) degrees. It is measured relative to image coordinate system (y-axis is directed downward), i.e in clockwise.
  • response the response by which the most strong keypoints have been selected. Can be used for further sorting or subsampling.
  • octave octave (pyramid layer) from which the keypoint has been extracted.
  • class_id object id that can be used to clustered keypoints by an object they belong to.
• im2 Second source image.
• keypoints2 Keypoints from the second source image. Same format as keypoints1.
• matches1to2 Matches from the first image to the second one, which means that keypoints1(i) has a corresponding point in keypoints2(matches(i)). A 1-by-M structure array with the following fields:
  • queryIdx query descriptor index (zero-based index)
  • trainIdx train descriptor index (zero-based index)
  • imgIdx train image index (zero-based index)
  • distance distance between descriptors (scalar)

Output

• out Output image. Its content depends on the option values defining what is drawn in the output image. See possible options below. By default, the two source images, matches, and single keypoints will be drawn. For each keypoint, only the center point will be drawn (without a circle around the keypoint with the keypoint size and orientation).

Options

• MatchColor Color of matches (lines and connected keypoints). If all -1, the color is generated randomly. default [-1,-1,-1,-1].
• SinglePointColor Color of single keypoints (circles), which means that keypoints do not have the matches. If all -1, the color is generated randomly. default [-1,-1,-1,-1].
• MatchesMask Mask determining which matches are drawn. If the mask is empty, all matches are drawn. default empty.
• NotDrawSinglePoints Single keypoints will not be drawn. default false
• DrawRichKeypoints For each keypoint, the circle around keypoint with keypoint size and orientation will be drawn. default false.
• OutImage If set, matches will be drawn on existing content of output image, otherwise source image is used instead. Default not set

This function draws matches of keypoints from two images in the output image. Match is a line connecting two keypoints (circles).

In pseudo-code, the function works as follows:

for m=1:numel(matches1to2)
    if ~MatchesMask(m), continue, end
    kp1 = keypoints1(matches1to2(m).queryIdx + 1);
    kp2 = keypoints2(matches1to2(m).trainIdx + 1);
    draw_match(kp1, kp2);
end