Class Objdetect

Method Details

• findChessboardCorners

  public static boolean findChessboardCorners(Mat image, Size patternSize, MatOfPoint2f corners, int flags)

  Finds the positions of internal corners of the chessboard.

  Parameters:

  image - Source chessboard view. It must be an 8-bit grayscale or color image.

  patternSize - Number of inner corners per a chessboard row and column ( patternSize = cv::Size(points_per_row,points_per_column) = cv::Size(columns,rows) ).

  corners - Output array of detected corners.

  flags - Various operation flags that can be zero or a combination of the following values:

  • REF: CALIB_CB_ADAPTIVE_THRESH Use adaptive thresholding to convert the image to black and white, rather than a fixed threshold level (computed from the average image brightness).
  • REF: CALIB_CB_NORMALIZE_IMAGE Normalize the image gamma with equalizeHist before applying fixed or adaptive thresholding.
  • REF: CALIB_CB_FILTER_QUADS Use additional criteria (like contour area, perimeter, square-like shape) to filter out false quads extracted at the contour retrieval stage.
  • REF: CALIB_CB_FAST_CHECK Run a fast check on the image that looks for chessboard corners, and shortcut the call if none is found. This can drastically speed up the call in the degenerate condition when no chessboard is observed.
  • REF: CALIB_CB_PLAIN All other flags are ignored. The input image is taken as is. No image processing is done to improve to find the checkerboard. This has the effect of speeding up the execution of the function but could lead to not recognizing the checkerboard if the image is not previously binarized in the appropriate manner.

  Returns:

  True if all of the corners are found and placed in a certain order (row by row, left to right in every row). Otherwise, if the function fails to find all the corners or reorder them, it returns false. The function attempts to determine whether the input image is a view of the chessboard pattern and locate the internal chessboard corners. For example, a regular chessboard has 8 x 8 squares and 7 x 7 internal corners, that is, points where the black squares touch each other. The detected coordinates are approximate, and to determine their positions more accurately, the function calls #cornerSubPix. You also may use the function #cornerSubPix with different parameters if returned coordinates are not accurate enough. Sample usage of detecting and drawing chessboard corners: : Size patternsize(8,6); //interior number of corners Mat gray = ....; //source image vector<Point2f> corners; //this will be filled by the detected corners //CALIB_CB_FAST_CHECK saves a lot of time on images //that do not contain any chessboard corners bool patternfound = findChessboardCorners(gray, patternsize, corners, CALIB_CB_ADAPTIVE_THRESH + CALIB_CB_NORMALIZE_IMAGE + CALIB_CB_FAST_CHECK); if(patternfound) cornerSubPix(gray, corners, Size(11, 11), Size(-1, -1), TermCriteria(CV_TERMCRIT_EPS + CV_TERMCRIT_ITER, 30, 0.1)); drawChessboardCorners(img, patternsize, Mat(corners), patternfound); Note: The function requires white space (like a square-thick border, the wider the better) around the board to make the detection more robust in various environments. Otherwise, if there is no border and the background is dark, the outer black squares cannot be segmented properly and so the square grouping and ordering algorithm fails. Use the generate_pattern.py Python script (REF: tutorial_camera_calibration_pattern) to create the desired checkerboard pattern.

• findChessboardCorners

  public static boolean findChessboardCorners(Mat image, Size patternSize, MatOfPoint2f corners)

  Finds the positions of internal corners of the chessboard.

  Parameters:

  image - Source chessboard view. It must be an 8-bit grayscale or color image.

  patternSize - Number of inner corners per a chessboard row and column ( patternSize = cv::Size(points_per_row,points_per_column) = cv::Size(columns,rows) ).

  corners - Output array of detected corners.

  • REF: CALIB_CB_ADAPTIVE_THRESH Use adaptive thresholding to convert the image to black and white, rather than a fixed threshold level (computed from the average image brightness).
  • REF: CALIB_CB_NORMALIZE_IMAGE Normalize the image gamma with equalizeHist before applying fixed or adaptive thresholding.
  • REF: CALIB_CB_FILTER_QUADS Use additional criteria (like contour area, perimeter, square-like shape) to filter out false quads extracted at the contour retrieval stage.
  • REF: CALIB_CB_FAST_CHECK Run a fast check on the image that looks for chessboard corners, and shortcut the call if none is found. This can drastically speed up the call in the degenerate condition when no chessboard is observed.
  • REF: CALIB_CB_PLAIN All other flags are ignored. The input image is taken as is. No image processing is done to improve to find the checkerboard. This has the effect of speeding up the execution of the function but could lead to not recognizing the checkerboard if the image is not previously binarized in the appropriate manner.

  Returns:

  True if all of the corners are found and placed in a certain order (row by row, left to right in every row). Otherwise, if the function fails to find all the corners or reorder them, it returns false. The function attempts to determine whether the input image is a view of the chessboard pattern and locate the internal chessboard corners. For example, a regular chessboard has 8 x 8 squares and 7 x 7 internal corners, that is, points where the black squares touch each other. The detected coordinates are approximate, and to determine their positions more accurately, the function calls #cornerSubPix. You also may use the function #cornerSubPix with different parameters if returned coordinates are not accurate enough. Sample usage of detecting and drawing chessboard corners: : Size patternsize(8,6); //interior number of corners Mat gray = ....; //source image vector<Point2f> corners; //this will be filled by the detected corners //CALIB_CB_FAST_CHECK saves a lot of time on images //that do not contain any chessboard corners bool patternfound = findChessboardCorners(gray, patternsize, corners, CALIB_CB_ADAPTIVE_THRESH + CALIB_CB_NORMALIZE_IMAGE + CALIB_CB_FAST_CHECK); if(patternfound) cornerSubPix(gray, corners, Size(11, 11), Size(-1, -1), TermCriteria(CV_TERMCRIT_EPS + CV_TERMCRIT_ITER, 30, 0.1)); drawChessboardCorners(img, patternsize, Mat(corners), patternfound); Note: The function requires white space (like a square-thick border, the wider the better) around the board to make the detection more robust in various environments. Otherwise, if there is no border and the background is dark, the outer black squares cannot be segmented properly and so the square grouping and ordering algorithm fails. Use the generate_pattern.py Python script (REF: tutorial_camera_calibration_pattern) to create the desired checkerboard pattern.

• checkChessboard

  public static boolean checkChessboard(Mat img, Size size)

  Checks whether the image contains chessboard of the specific size or not.

  Parameters:

  img - Source chessboard view.

  size - Size of the chessboard.

  Returns:

  Whether a chessboard was found.

• findChessboardCornersSBWithMeta

  public static boolean findChessboardCornersSBWithMeta(Mat image, Size patternSize, Mat corners, int flags, Mat meta)

  Finds the positions of internal corners of the chessboard using a sector based approach.

  Parameters:

  image - Source chessboard view. It must be an 8-bit grayscale or color image.

  patternSize - Number of inner corners per a chessboard row and column ( patternSize = cv::Size(points_per_row,points_per_column) = cv::Size(columns,rows) ).

  corners - Output array of detected corners.

  flags - Various operation flags that can be zero or a combination of the following values:

  • REF: CALIB_CB_NORMALIZE_IMAGE Normalize the image gamma with equalizeHist before detection.
  • REF: CALIB_CB_EXHAUSTIVE Run an exhaustive search to improve detection rate.
  • REF: CALIB_CB_ACCURACY Up sample input image to improve sub-pixel accuracy due to aliasing effects.
  • REF: CALIB_CB_LARGER The detected pattern is allowed to be larger than patternSize (see description).
  • REF: CALIB_CB_MARKER The detected pattern must have a marker (see description). This should be used if an accurate camera calibration is required.

  meta - Optional output array of detected corners (CV_8UC1 and size = cv::Size(columns,rows)). Each entry stands for one corner of the pattern and can have one of the following values:

  • 0 = no meta data attached
  • 1 = left-top corner of a black cell
  • 2 = left-top corner of a white cell
  • 3 = left-top corner of a black cell with a white marker dot
  • 4 = left-top corner of a white cell with a black marker dot (pattern origin in case of markers otherwise first corner)

  The function is analog to #findChessboardCorners but uses a localized radon transformation approximated by box filters being more robust to all sort of noise, faster on larger images and is able to directly return the sub-pixel position of the internal chessboard corners. The Method is based on the paper CITE: duda2018 "Accurate Detection and Localization of Checkerboard Corners for Calibration" demonstrating that the returned sub-pixel positions are more accurate than the one returned by cornerSubPix allowing a precise camera calibration for demanding applications. In the case, the flags REF: CALIB_CB_LARGER or REF: CALIB_CB_MARKER are given, the result can be recovered from the optional meta array. Both flags are helpful to use calibration patterns exceeding the field of view of the camera. These oversized patterns allow more accurate calibrations as corners can be utilized, which are as close as possible to the image borders. For a consistent coordinate system across all images, the optional marker (see image below) can be used to move the origin of the board to the location where the black circle is located. Note: The function requires a white boarder with roughly the same width as one of the checkerboard fields around the whole board to improve the detection in various environments. In addition, because of the localized radon transformation it is beneficial to use round corners for the field corners which are located on the outside of the board. The following figure illustrates a sample checkerboard optimized for the detection. However, any other checkerboard can be used as well. Use the generate_pattern.py Python script (REF: tutorial_camera_calibration_pattern) to create the corresponding checkerboard pattern: \image html pics/checkerboard_radon.png width=60%

  Returns:

  automatically generated

• findChessboardCornersSB

  public static boolean findChessboardCornersSB(Mat image, Size patternSize, Mat corners, int flags)

• findChessboardCornersSB

  public static boolean findChessboardCornersSB(Mat image, Size patternSize, Mat corners)

• estimateChessboardSharpness

  public static Scalar estimateChessboardSharpness(Mat image, Size patternSize, Mat corners, float rise_distance, boolean vertical, Mat sharpness)

  Estimates the sharpness of a detected chessboard. Image sharpness, as well as brightness, are a critical parameter for accuracte camera calibration. For accessing these parameters for filtering out problematic calibraiton images, this method calculates edge profiles by traveling from black to white chessboard cell centers. Based on this, the number of pixels is calculated required to transit from black to white. This width of the transition area is a good indication of how sharp the chessboard is imaged and should be below ~3.0 pixels.

  Parameters:

  image - Gray image used to find chessboard corners

  patternSize - Size of a found chessboard pattern

  corners - Corners found by #findChessboardCornersSB

  rise_distance - Rise distance 0.8 means 10% ... 90% of the final signal strength

  vertical - By default edge responses for horizontal lines are calculated

  sharpness - Optional output array with a sharpness value for calculated edge responses (see description) The optional sharpness array is of type CV_32FC1 and has for each calculated profile one row with the following five entries: 0 = x coordinate of the underlying edge in the image 1 = y coordinate of the underlying edge in the image 2 = width of the transition area (sharpness) 3 = signal strength in the black cell (min brightness) 4 = signal strength in the white cell (max brightness)

  Returns:

  Scalar(average sharpness, average min brightness, average max brightness,0)

• estimateChessboardSharpness

  public static Scalar estimateChessboardSharpness(Mat image, Size patternSize, Mat corners, float rise_distance, boolean vertical)

  Estimates the sharpness of a detected chessboard. Image sharpness, as well as brightness, are a critical parameter for accuracte camera calibration. For accessing these parameters for filtering out problematic calibraiton images, this method calculates edge profiles by traveling from black to white chessboard cell centers. Based on this, the number of pixels is calculated required to transit from black to white. This width of the transition area is a good indication of how sharp the chessboard is imaged and should be below ~3.0 pixels.

  Parameters:

  image - Gray image used to find chessboard corners

  patternSize - Size of a found chessboard pattern

  corners - Corners found by #findChessboardCornersSB

  rise_distance - Rise distance 0.8 means 10% ... 90% of the final signal strength

  vertical - By default edge responses for horizontal lines are calculated The optional sharpness array is of type CV_32FC1 and has for each calculated profile one row with the following five entries: 0 = x coordinate of the underlying edge in the image 1 = y coordinate of the underlying edge in the image 2 = width of the transition area (sharpness) 3 = signal strength in the black cell (min brightness) 4 = signal strength in the white cell (max brightness)

  Returns:

  Scalar(average sharpness, average min brightness, average max brightness,0)

• estimateChessboardSharpness

  public static Scalar estimateChessboardSharpness(Mat image, Size patternSize, Mat corners, float rise_distance)

  Estimates the sharpness of a detected chessboard. Image sharpness, as well as brightness, are a critical parameter for accuracte camera calibration. For accessing these parameters for filtering out problematic calibraiton images, this method calculates edge profiles by traveling from black to white chessboard cell centers. Based on this, the number of pixels is calculated required to transit from black to white. This width of the transition area is a good indication of how sharp the chessboard is imaged and should be below ~3.0 pixels.

  Parameters:

  image - Gray image used to find chessboard corners

  patternSize - Size of a found chessboard pattern

  corners - Corners found by #findChessboardCornersSB

  rise_distance - Rise distance 0.8 means 10% ... 90% of the final signal strength The optional sharpness array is of type CV_32FC1 and has for each calculated profile one row with the following five entries: 0 = x coordinate of the underlying edge in the image 1 = y coordinate of the underlying edge in the image 2 = width of the transition area (sharpness) 3 = signal strength in the black cell (min brightness) 4 = signal strength in the white cell (max brightness)

  Returns:

  Scalar(average sharpness, average min brightness, average max brightness,0)

• estimateChessboardSharpness

  public static Scalar estimateChessboardSharpness(Mat image, Size patternSize, Mat corners)

  Estimates the sharpness of a detected chessboard. Image sharpness, as well as brightness, are a critical parameter for accuracte camera calibration. For accessing these parameters for filtering out problematic calibraiton images, this method calculates edge profiles by traveling from black to white chessboard cell centers. Based on this, the number of pixels is calculated required to transit from black to white. This width of the transition area is a good indication of how sharp the chessboard is imaged and should be below ~3.0 pixels.

  Parameters:

  image - Gray image used to find chessboard corners

  patternSize - Size of a found chessboard pattern

  corners - Corners found by #findChessboardCornersSB The optional sharpness array is of type CV_32FC1 and has for each calculated profile one row with the following five entries: 0 = x coordinate of the underlying edge in the image 1 = y coordinate of the underlying edge in the image 2 = width of the transition area (sharpness) 3 = signal strength in the black cell (min brightness) 4 = signal strength in the white cell (max brightness)

  Returns:

  Scalar(average sharpness, average min brightness, average max brightness,0)

• find4QuadCornerSubpix

  public static boolean find4QuadCornerSubpix(Mat img, Mat corners, Size region_size)

• drawChessboardCorners

  public static void drawChessboardCorners(Mat image, Size patternSize, MatOfPoint2f corners, boolean patternWasFound)

  Renders the detected chessboard corners.

  Parameters:

  image - Destination image. It must be an 8-bit color image.

  patternSize - Number of inner corners per a chessboard row and column (patternSize = cv::Size(points_per_row,points_per_column)).

  corners - Array of detected corners, the output of #findChessboardCorners.

  patternWasFound - Parameter indicating whether the complete board was found or not. The return value of #findChessboardCorners should be passed here. The function draws individual chessboard corners detected either as red circles if the board was not found, or as colored corners connected with lines if the board was found.

• findCirclesGrid

  public static boolean findCirclesGrid(Mat image, Size patternSize, Mat centers, int flags)

• findCirclesGrid

  public static boolean findCirclesGrid(Mat image, Size patternSize, Mat centers)

• drawDetectedCornersCharuco

  public static void drawDetectedCornersCharuco(Mat image, Mat charucoCorners, Mat charucoIds, Scalar cornerColor)

  Draws a set of Charuco corners

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  charucoCorners - vector of detected charuco corners

  charucoIds - list of identifiers for each corner in charucoCorners

  cornerColor - color of the square surrounding each corner This function draws a set of detected Charuco corners. If identifiers vector is provided, it also draws the id of each corner.

• drawDetectedCornersCharuco

  public static void drawDetectedCornersCharuco(Mat image, Mat charucoCorners, Mat charucoIds)

  Draws a set of Charuco corners

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  charucoCorners - vector of detected charuco corners

  charucoIds - list of identifiers for each corner in charucoCorners This function draws a set of detected Charuco corners. If identifiers vector is provided, it also draws the id of each corner.

• drawDetectedCornersCharuco

  public static void drawDetectedCornersCharuco(Mat image, Mat charucoCorners)

  Draws a set of Charuco corners

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  charucoCorners - vector of detected charuco corners This function draws a set of detected Charuco corners. If identifiers vector is provided, it also draws the id of each corner.

• drawDetectedDiamonds

  public static void drawDetectedDiamonds(Mat image, List<Mat> diamondCorners, Mat diamondIds, Scalar borderColor)

  Draw a set of detected ChArUco Diamond markers

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  diamondCorners - positions of diamond corners in the same format returned by detectCharucoDiamond(). (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.

  diamondIds - vector of identifiers for diamonds in diamondCorners, in the same format returned by detectCharucoDiamond() (e.g. std::vector<Vec4i>). Optional, if not provided, ids are not painted.

  borderColor - color of marker borders. Rest of colors (text color and first corner color) are calculated based on this one. Given an array of detected diamonds, this functions draws them in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

• drawDetectedDiamonds

  public static void drawDetectedDiamonds(Mat image, List<Mat> diamondCorners, Mat diamondIds)

  Draw a set of detected ChArUco Diamond markers

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  diamondCorners - positions of diamond corners in the same format returned by detectCharucoDiamond(). (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.

  diamondIds - vector of identifiers for diamonds in diamondCorners, in the same format returned by detectCharucoDiamond() (e.g. std::vector<Vec4i>). Optional, if not provided, ids are not painted. are calculated based on this one. Given an array of detected diamonds, this functions draws them in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

• drawDetectedDiamonds

  public static void drawDetectedDiamonds(Mat image, List<Mat> diamondCorners)

  Draw a set of detected ChArUco Diamond markers

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  diamondCorners - positions of diamond corners in the same format returned by detectCharucoDiamond(). (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise. returned by detectCharucoDiamond() (e.g. std::vector<Vec4i>). Optional, if not provided, ids are not painted. are calculated based on this one. Given an array of detected diamonds, this functions draws them in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

• getPredefinedDictionary

  public static Dictionary getPredefinedDictionary(int dict)

  Returns one of the predefined dictionaries referenced by DICT_*.

  Parameters:

  dict - automatically generated

  Returns:

  automatically generated

• extendDictionary

  public static Dictionary extendDictionary(int nMarkers, int markerSize, Dictionary baseDictionary, int randomSeed)

  Extend base dictionary by new nMarkers

  Parameters:

  nMarkers - number of markers in the dictionary

  markerSize - number of bits per dimension of each markers

  baseDictionary - Include the markers in this dictionary at the beginning (optional)

  randomSeed - a user supplied seed for theRNG() This function creates a new dictionary composed by nMarkers markers and each markers composed by markerSize x markerSize bits. If baseDictionary is provided, its markers are directly included and the rest are generated based on them. If the size of baseDictionary is higher than nMarkers, only the first nMarkers in baseDictionary are taken and no new marker is added.

  Returns:

  automatically generated

• extendDictionary

  public static Dictionary extendDictionary(int nMarkers, int markerSize, Dictionary baseDictionary)

  Extend base dictionary by new nMarkers

  Parameters:

  nMarkers - number of markers in the dictionary

  markerSize - number of bits per dimension of each markers

  baseDictionary - Include the markers in this dictionary at the beginning (optional) This function creates a new dictionary composed by nMarkers markers and each markers composed by markerSize x markerSize bits. If baseDictionary is provided, its markers are directly included and the rest are generated based on them. If the size of baseDictionary is higher than nMarkers, only the first nMarkers in baseDictionary are taken and no new marker is added.

  Returns:

  automatically generated

• extendDictionary

  public static Dictionary extendDictionary(int nMarkers, int markerSize)

  Extend base dictionary by new nMarkers

  Parameters:

  nMarkers - number of markers in the dictionary

  markerSize - number of bits per dimension of each markers This function creates a new dictionary composed by nMarkers markers and each markers composed by markerSize x markerSize bits. If baseDictionary is provided, its markers are directly included and the rest are generated based on them. If the size of baseDictionary is higher than nMarkers, only the first nMarkers in baseDictionary are taken and no new marker is added.

  Returns:

  automatically generated

• drawDetectedMarkers

  public static void drawDetectedMarkers(Mat image, List<Mat> corners, Mat ids, Scalar borderColor)

  Draw detected markers in image

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  corners - positions of marker corners on input image. (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.

  ids - vector of identifiers for markers in markersCorners . Optional, if not provided, ids are not painted.

  borderColor - color of marker borders. Rest of colors (text color and first corner color) are calculated based on this one to improve visualization. Given an array of detected marker corners and its corresponding ids, this functions draws the markers in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

• drawDetectedMarkers

  public static void drawDetectedMarkers(Mat image, List<Mat> corners, Mat ids)

  Draw detected markers in image

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  corners - positions of marker corners on input image. (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.

  ids - vector of identifiers for markers in markersCorners . Optional, if not provided, ids are not painted. are calculated based on this one to improve visualization. Given an array of detected marker corners and its corresponding ids, this functions draws the markers in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

• drawDetectedMarkers

  public static void drawDetectedMarkers(Mat image, List<Mat> corners)

  Draw detected markers in image

  Parameters:

  image - input/output image. It must have 1 or 3 channels. The number of channels is not altered.

  corners - positions of marker corners on input image. (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise. Optional, if not provided, ids are not painted. are calculated based on this one to improve visualization. Given an array of detected marker corners and its corresponding ids, this functions draws the markers in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

• generateImageMarker

  public static void generateImageMarker(Dictionary dictionary, int id, int sidePixels, Mat img, int borderBits)

  Generate a canonical marker image

  Parameters:

  dictionary - dictionary of markers indicating the type of markers

  id - identifier of the marker that will be returned. It has to be a valid id in the specified dictionary.

  sidePixels - size of the image in pixels

  img - output image with the marker

  borderBits - width of the marker border. This function returns a marker image in its canonical form (i.e. ready to be printed)

• generateImageMarker

  public static void generateImageMarker(Dictionary dictionary, int id, int sidePixels, Mat img)

  Generate a canonical marker image

  Parameters:

  dictionary - dictionary of markers indicating the type of markers

  id - identifier of the marker that will be returned. It has to be a valid id in the specified dictionary.

  sidePixels - size of the image in pixels

  img - output image with the marker This function returns a marker image in its canonical form (i.e. ready to be printed)