Module objdetect

Source

Expand description

§Object Detection

§Barcode detection and decoding

§QRCode detection and encoding

§DNN-based face detection and recognition

Check [tutorial_dnn_face] “the corresponding tutorial” for more details.

§Common functions and classes

§ArUco markers and boards detection for robust camera pose estimation

   ArUco Marker Detection
   Square fiducial markers (also known as Augmented Reality Markers) are useful for easy,
   fast and robust camera pose estimation.

   The main functionality of ArucoDetector class is detection of markers in an image. If the markers are grouped
   as a board, then you can try to recover the missing markers with ArucoDetector::refineDetectedMarkers().
   ArUco markers can also be used for advanced chessboard corner finding. To do this, group the markers in the
   CharucoBoard and find the corners of the chessboard with the CharucoDetector::detectBoard().

   The implementation is based on the ArUco Library by R. Muñoz-Salinas and S. Garrido-Jurado [Aruco2014](https://docs.opencv.org/5.0.0/d0/de3/citelist.html#CITEREF_Aruco2014).

   Markers can also be detected based on the AprilTag 2 [wang2016iros](https://docs.opencv.org/5.0.0/d0/de3/citelist.html#CITEREF_wang2016iros) fiducial marker detection method.

§See also

Aruco2014 This code has been originally developed by Sergio Garrido-Jurado as a project for Google Summer of Code 2015 (GSoC 15).

   <br>

   @warning In OpenCV, the order of the returned corners locations for the AprilTag family is not aligned with the ArUco one.

   Note that this order is also different from the convention adopted by the official [AprilTag library](https://github.com/AprilRobotics/apriltag/).
   ![](https://docs.opencv.org/5.0.0/AprilTag_corners_comparison_opencv_april.png) { width=80% }

   <br>

   An overview of the supported ArUco markers family is visible in the following image:
   ![](https://docs.opencv.org/5.0.0/ArUco_family.png) { width=80% }

   <br>

   An overview of the supported AprilTag markers family is visible in the following image:
   ![](https://docs.opencv.org/5.0.0/AprilTag_family.png) { width=80% }

Note: The generated images (in the above picture) using [aruco::generateImageMarker] for the AprilTag markers have been rotated by 180 degree in order to match the official AprilTag images. When using the [aruco::generateImageMarker] function, it will output by default a different image from the official AprilTag convention, see the AprilRobotics/apriltag-imgs repository. This is the reason why you see a different corners order between ArUco and AprilTag in the above image.

   <br>

   For the ArUco marker family, the recommended family is the DICT_ARUCO_MIP_36h12 one, [see](https://stackoverflow.com/a/51511558).
   In general, a smaller marker family (e.g. `4x4` vs `6x6`) should give you a better detection rate with respect to the camera distance,
   at the expense of having more probability to have issues with false detection or marker id decoding error.
   The number of marker ids in a family is also something to take into account with respect to the application use case and the ability
   to correct wrong bits during the marker id decoding process.

   You can download some pregenerated MIP_36h12 ArUco marker images from:
      - <https://sourceforge.net/projects/aruco/files/>
      - or use the `samples/cpp/tutorial_code/objectDetection/create_marker.cpp` sample to generate the marker image for your
      desired marker family (which uses the [aruco::generateImageMarker] function)

   For the AprilTag family, you can find some pregenerated marker images in the
   [AprilRobotics/apriltag-imgs](https://github.com/AprilRobotics/apriltag-imgs) repository.

Note: For accurate corners location extraction, a white border (to have a strong gradient between white and black transition) around the marker is important. This is necessary to precisely extract the marker contour in difficult conditions such as bad illumination, confusing color background, etc.

   <br>

   There are multiple parameters which can be tweaked to improve the marker detection rate or to be adapted to your use case (e.g. image resolution).
   Please refer to the:
      - [aruco::DetectorParameters]
      - "Detector Parameters" section in the [tutorial_aruco_detection] tutorial or in the [tutorial_aruco_faq] page
      - [ArUco Library Documentation](https://drive.google.com/file/d/1OiavRVYVJ-WH88sQg1LUsh8CuJZUQyrX) for additional information from the ArUco library

   The corner refinement method can be changed according to the [aruco::CornerRefineMethod] to improve the corners location accuracy
   at the expense of more computation time.

   <br>

   To estimate the marker pose with respect to the camera frame, we recommend you to look at the following sources of information:
      - [tutorial_aruco_detection] for a tutorial about ArUco markers detection
      - [_3d] for some theoretical background about the pinhole camera model and the [calib3d_solvePnP] page
      - [solvePnP], [solvePnPGeneric], [solveP3P] for the relevant pose estimation methods

Modules§

prelude

Structs§

ArucoDetector: The main functionality of ArucoDetector class is detection of markers in an image with detectMarkers() method.
BarcodeDetector
Board: Board of ArUco markers
CChecker: CChecker
CCheckerDetector: A class to find the positions of the ColorCharts in the image.
CharucoBoard: ChArUco board is a planar chessboard where the markers are placed inside the white squares of a chessboard.
CharucoDetector
CharucoParameters
CirclesGridFinderParameters
DetectorParameters: struct DetectorParameters is used by ArucoDetector
DetectorParametersMCC: struct DetectorParametersMCC is used by CCheckerDetector
Dictionary: Dictionary is a set of unique ArUco markers of the same size
FaceDetectorYN: DNN-based face detector
FaceRecognizerSF: DNN-based face recognizer
GraphicalCodeDetector
GridBoard: Planar board with grid arrangement of markers
QRCodeDetector: QR code detector.
QRCodeDetectorAruco: QR code detector based on Aruco markers detection code.
QRCodeDetectorAruco_Params
QRCodeEncoder: QR code encoder.
QRCodeEncoder_Params: QR code encoder parameters.
RefineParameters: struct RefineParameters is used by ArucoDetector

Enums§

CirclesGridFinderParameters_GridType
ColorChart: ColorChart
CornerRefineMethod
FaceRecognizerSF_DisType: Definition of distance used for calculating the distance between two face features
PredefinedDictionaryType: Predefined markers dictionaries/sets
QRCodeEncoder_CorrectionLevel
QRCodeEncoder_ECIEncodings
QRCodeEncoder_EncodeMode

Constants§

CALIB_CB_ACCURACY
CALIB_CB_ADAPTIVE_THRESH
CALIB_CB_ASYMMETRIC_GRID
CALIB_CB_CLUSTERING
CALIB_CB_EXHAUSTIVE
CALIB_CB_FAST_CHECK
CALIB_CB_FILTER_QUADS
CALIB_CB_LARGER
CALIB_CB_MARKER
CALIB_CB_NORMALIZE_IMAGE
CALIB_CB_PLAIN
CALIB_CB_SYMMETRIC_GRID
CORNER_REFINE_APRILTAG: Tag and corners detection based on the AprilTag 2 approach wang2016iros
CORNER_REFINE_CONTOUR: ArUco approach and refine the corners locations using the contour-points line fitting
CORNER_REFINE_NONE: Tag and corners detection based on the ArUco approach
CORNER_REFINE_SUBPIX: ArUco approach and refine the corners locations using corner subpixel accuracy
CirclesGridFinderParameters_ASYMMETRIC_GRID
CirclesGridFinderParameters_SYMMETRIC_GRID
DEFAULT_VALID_BIT_ID_THRESHOLD
DICT_4X4_50: 4x4 bits, minimum hamming distance between any two codes = 4, 50 codes
DICT_4X4_100: 4x4 bits, minimum hamming distance between any two codes = 3, 100 codes
DICT_4X4_250: 4x4 bits, minimum hamming distance between any two codes = 3, 250 codes
DICT_4X4_1000: 4x4 bits, minimum hamming distance between any two codes = 2, 1000 codes
DICT_5X5_50: 5x5 bits, minimum hamming distance between any two codes = 8, 50 codes
DICT_5X5_100: 5x5 bits, minimum hamming distance between any two codes = 7, 100 codes
DICT_5X5_250: 5x5 bits, minimum hamming distance between any two codes = 6, 250 codes
DICT_5X5_1000: 5x5 bits, minimum hamming distance between any two codes = 5, 1000 codes
DICT_6X6_50: 6x6 bits, minimum hamming distance between any two codes = 13, 50 codes
DICT_6X6_100: 6x6 bits, minimum hamming distance between any two codes = 12, 100 codes
DICT_6X6_250: 6x6 bits, minimum hamming distance between any two codes = 11, 250 codes
DICT_6X6_1000: 6x6 bits, minimum hamming distance between any two codes = 9, 1000 codes
DICT_7X7_50: 7x7 bits, minimum hamming distance between any two codes = 19, 50 codes
DICT_7X7_100: 7x7 bits, minimum hamming distance between any two codes = 18, 100 codes
DICT_7X7_250: 7x7 bits, minimum hamming distance between any two codes = 17, 250 codes
DICT_7X7_1000: 7x7 bits, minimum hamming distance between any two codes = 14, 1000 codes
DICT_APRILTAG_16h5: 4x4 bits, minimum hamming distance between any two codes = 5, 30 codes
DICT_APRILTAG_25h9: 5x5 bits, minimum hamming distance between any two codes = 9, 35 codes
DICT_APRILTAG_36h10: 6x6 bits, minimum hamming distance between any two codes = 10, 2320 codes
DICT_APRILTAG_36h11: 6x6 bits, minimum hamming distance between any two codes = 11, 587 codes
DICT_ARUCO_MIP_36h12: 6x6 bits, minimum hamming distance between any two codes = 12, 250 codes
DICT_ARUCO_ORIGINAL: 6x6 bits, minimum hamming distance between any two codes = 3, 1024 codes
FaceRecognizerSF_FR_COSINE
FaceRecognizerSF_FR_NORM_L2
MCC24: Standard Macbeth Chart with 24 squares
QRCodeEncoder_CORRECT_LEVEL_H
QRCodeEncoder_CORRECT_LEVEL_L
QRCodeEncoder_CORRECT_LEVEL_M
QRCodeEncoder_CORRECT_LEVEL_Q
QRCodeEncoder_ECI_SHIFT_JIS
QRCodeEncoder_ECI_UTF8
QRCodeEncoder_MODE_ALPHANUMERIC
QRCodeEncoder_MODE_AUTO
QRCodeEncoder_MODE_BYTE
QRCodeEncoder_MODE_ECI
QRCodeEncoder_MODE_KANJI
QRCodeEncoder_MODE_NUMERIC
QRCodeEncoder_MODE_STRUCTURED_APPEND
SG140: DigitalSG with 140 squares
VINYL18: DKK color chart with 12 squares and 6 rectangle

Traits§

ArucoDetectorTrait: Mutable methods for crate::objdetect::ArucoDetector
ArucoDetectorTraitConst: Constant methods for crate::objdetect::ArucoDetector
BarcodeDetectorTrait: Mutable methods for crate::objdetect::BarcodeDetector
BarcodeDetectorTraitConst: Constant methods for crate::objdetect::BarcodeDetector
BoardTrait: Mutable methods for crate::objdetect::Board
BoardTraitConst: Constant methods for crate::objdetect::Board
CCheckerDetectorTrait: Mutable methods for crate::objdetect::CCheckerDetector
CCheckerDetectorTraitConst: Constant methods for crate::objdetect::CCheckerDetector
CCheckerTrait: Mutable methods for crate::objdetect::CChecker
CCheckerTraitConst: Constant methods for crate::objdetect::CChecker
CharucoBoardTrait: Mutable methods for crate::objdetect::CharucoBoard
CharucoBoardTraitConst: Constant methods for crate::objdetect::CharucoBoard
CharucoDetectorTrait: Mutable methods for crate::objdetect::CharucoDetector
CharucoDetectorTraitConst: Constant methods for crate::objdetect::CharucoDetector
CharucoParametersTrait: Mutable methods for crate::objdetect::CharucoParameters
CharucoParametersTraitConst: Constant methods for crate::objdetect::CharucoParameters
DetectorParametersTrait: Mutable methods for crate::objdetect::DetectorParameters
DetectorParametersTraitConst: Constant methods for crate::objdetect::DetectorParameters
DictionaryTrait: Mutable methods for crate::objdetect::Dictionary
DictionaryTraitConst: Constant methods for crate::objdetect::Dictionary
FaceDetectorYNTrait: Mutable methods for crate::objdetect::FaceDetectorYN
FaceDetectorYNTraitConst: Constant methods for crate::objdetect::FaceDetectorYN
FaceRecognizerSFTrait: Mutable methods for crate::objdetect::FaceRecognizerSF
FaceRecognizerSFTraitConst: Constant methods for crate::objdetect::FaceRecognizerSF
GraphicalCodeDetectorTrait: Mutable methods for crate::objdetect::GraphicalCodeDetector
GraphicalCodeDetectorTraitConst: Constant methods for crate::objdetect::GraphicalCodeDetector
GridBoardTrait: Mutable methods for crate::objdetect::GridBoard
GridBoardTraitConst: Constant methods for crate::objdetect::GridBoard
QRCodeDetectorArucoTrait: Mutable methods for crate::objdetect::QRCodeDetectorAruco
QRCodeDetectorArucoTraitConst: Constant methods for crate::objdetect::QRCodeDetectorAruco
QRCodeDetectorTrait: Mutable methods for crate::objdetect::QRCodeDetector
QRCodeDetectorTraitConst: Constant methods for crate::objdetect::QRCodeDetector
QRCodeEncoderTrait: Mutable methods for crate::objdetect::QRCodeEncoder
QRCodeEncoderTraitConst: Constant methods for crate::objdetect::QRCodeEncoder

Functions§

check_chessboard: Checks whether the image contains chessboard of the specific size or not.
draw_chessboard_corners: Renders the detected chessboard corners.
draw_detected_corners_charuco: Draws a set of Charuco corners
draw_detected_corners_charuco_def: Draws a set of Charuco corners
draw_detected_diamonds: Draw a set of detected ChArUco Diamond markers
draw_detected_diamonds_def: Draw a set of detected ChArUco Diamond markers
draw_detected_markers: Draw detected markers in image
draw_detected_markers_def: Draw detected markers in image
estimate_chessboard_sharpness: Estimates the sharpness of a detected chessboard.
estimate_chessboard_sharpness_def: Estimates the sharpness of a detected chessboard.
extend_dictionary: Extend base dictionary by new nMarkers
extend_dictionary_def: Extend base dictionary by new nMarkers
find4_quad_corner_subpix: finds subpixel-accurate positions of the chessboard corners
find_chessboard_corners: Finds the positions of internal corners of the chessboard.
find_chessboard_corners_def: Finds the positions of internal corners of the chessboard.
find_chessboard_corners_sb: Finds the positions of internal corners of the chessboard using a sector based approach.
find_chessboard_corners_sb_def: Finds the positions of internal corners of the chessboard using a sector based approach.
find_chessboard_corners_sb_with_meta: Finds the positions of internal corners of the chessboard using a sector based approach.
find_circles_grid: Finds centers in the grid of circles.
find_circles_grid_def: Finds centers in the grid of circles.
find_circles_grid_with_params: Finds centers in the grid of circles.
generate_image_marker: Generate a canonical marker image
generate_image_marker_def: Generate a canonical marker image
get_predefined_dictionary: Returns one of the predefined dictionaries defined in PredefinedDictionaryType
get_predefined_dictionary_i32: Returns one of the predefined dictionaries referenced by DICT_*.