Class MarkerDetector

• Defined in File markerdetector.h

Nested Relationships

Nested Types

• Struct MarkerDetector::Params

Class Documentation

class MarkerDetector

Main class for marker detection.

Public Types

enum ThresMethod

Values:

enumerator THRES_ADAPTIVE

enumerator THRES_AUTO_FIXED

Public Functions

MarkerDetector()

See

MarkerDetector(int dict_type, float error_correction_rate = 0)

Creates indicating the dictionary. See

See also

setDictionary for further details

See also

setDictionary for further details

Parameters:

• dict_type – Dictionary employed. See

• error_correction_rate – value indicating the correction error allowed. Is in range [0,1]. 0 means no correction at all. So an erroneous bit will result in discarding the marker. 1, mean full correction. The maximum number of bits that can be corrected depends on each ditionary. We recommend using values from 0 to 0.5. (in general, this will allow up to 3 bits or correction).

MarkerDetector(std::string dict_type, float error_correction_rate = 0)

void saveParamsToFile(const std::string &path) const

Saves the configuration of the detector to a file.

void loadParamsFromFile(const std::string &path)

Loads the configuration from a file.

~MarkerDetector()

void setDetectionMode(DetectionMode dm, float minMarkerSize = 0)

Specifies the detection mode. We have preset three types of detection modes. These are ways to configure the internal parameters for the most typical situations. The modes are:

• DM_NORMAL: In this mode, the full resolution image is employed for detection and slow threshold method. Use this method when you process individual images that are not part of a video sequence and you are not interested in speed.

• DM_FAST: In this mode, there are two main improvements. First, image is threshold using a faster method using a global threshold. Also, the full resolution image is employed for detection, but, you could speed up detection even more by indicating a minimum size of the markers you will accept. This is set by the variable minMarkerSize which shoud be in range [0,1]. When it is 0, means that you do not set a limit in the size of the accepted markers. However, if you set 0.1, it means that markers smaller than 10% of the total image area, will not be detected. Then, the detection can be accelated up to orders of magnitude compared to the normal mode.

• DM_VIDEO_FAST: This is similar to DM_FAST, but specially adapted to video processing. In that case, we assume that the observed markers when you call to detect() have a size similar to the ones observed in the previous frame. Then, the processing can be speeded up by employing smaller versions of the image automatically calculated.

DetectionMode getDetectionMode()

returns current detection mode

std::vector<aruco::Marker> detect(const cv::Mat &input)

Detects the markers in the image passed

If you provide information about the camera parameters and the size of the marker, then, the extrinsics of the markers are detected

Parameters:

• input – input color image

• camMatrix – intrinsic camera information.

• distCoeff – camera distorsion coefficient. If set Mat() if is assumed no camera distorion

• markerSizeMeters – size of the marker sides expressed in meters. If not specified this value, the extrinsics of the markers are not detected.

• setYPerperdicular – If set the Y axis will be perpendicular to the surface. Otherwise, it will be the Z axis

• correctFisheye – Correct fisheye distortion

Returns:

vector with the detected markers

std::vector<aruco::Marker> detect(const cv::Mat &input, const CameraParameters &camParams, float markerSizeMeters, bool setYPerperdicular = false, bool correctFisheye = false)

void detect(const cv::Mat &input, std::vector<Marker> &detectedMarkers, CameraParameters camParams, float markerSizeMeters = -1, bool setYPerperdicular = false, bool correctFisheye = false)

Detects the markers in the image passed

If you provide information about the camera parameters and the size of the marker, then, the extrinsics of the markers are detected

Parameters:

• input – input color image

• detectedMarkers – output vector with the markers detected

• camParams – Camera parameters

• markerSizeMeters – size of the marker sides expressed in meters

• setYPerperdicular – If set the Y axis will be perpendicular to the surface. Otherwise, it will be the Z axis

• correctFisheye – Correct fisheye distortion

void detect(const cv::Mat &input, std::vector<Marker> &detectedMarkers, cv::Mat camMatrix = cv::Mat(), cv::Mat distCoeff = cv::Mat(), cv::Mat extrinsics = cv::Mat(), float markerSizeMeters = -1, bool setYPerperdicular = false, bool correctFisheye = false)

Detects the markers in the image passed

If you provide information about the camera parameters and the size of the marker, then, the extrinsics of the markers are detected

NOTE: be sure that the camera matrix is for this image size. If you do not know what I am talking about, use functions above and not this one

Parameters:

• input – input color image

• detectedMarkers – output vector with the markers detected

• camMatrix – intrinsic camera information.

• distCoeff – camera distortion coefficient. If set Mat() if is assumed no camera distortion

• extrinsics – translation (tx,ty,tz) from right stereo camera to left. Empty if no stereo or left camera

• markerSizeMeters – size of the marker sides expressed in meters

• setYPerperdicular – If set the Y axis will be perpendicular to the surface. Otherwise, it will be the Z axis

• correctFisheye – Correct fisheye distortion

Params getParameters() const

Returns operating params

Params &getParameters()

Returns operating params

void setDictionary(std::string dict_type, float error_correction_rate = 0)

Sets the dictionary to be employed. You can choose:ARUCO,//original aruco dictionary. By default ARUCO_MIP_25h7, ARUCO_MIP_16h3, ARUCO_MIP_36h12, **** recommended ARTAG,// ARTOOLKITPLUS, ARTOOLKITPLUSBCH,// TAG16h5,TAG25h7,TAG25h9,TAG36h11,TAG36h10//APRIL TAGS DICIONARIES CHILITAGS,//chili tags dictionary . NOT RECOMMENDED. It has distance 0. Markers 806 and 682 should not be used!!!

If dict_type is none of the above ones, it is assumed you mean a CUSTOM dicionary saved in a file

See also

Dictionary::loadFromFile Then, it tries to open it

void setDictionary(int dict_type, float error_correction_rate = 0)

setDictionary Specifies the dictionary you want to use for marker decoding

See also

Dictionary

Parameters:

• dict_type – dictionary employed for decoding markers

• error_correction_rate – value indicating the correction error allowed. Is in range [0,1]. 0 means no correction at all. So an erroneous bit will result in discarding the marker. 1, mean full correction. The maximum number of bits that can be corrected depends on each ditionary. We recommend using values from 0 to 0.5. (in general, this will allow up to 3 bits or correction).

cv::Mat getThresholdedImage(uint32_t idx = 0)

Returns a reference to the internal image thresholded. Since there can be generated many of them, specify which

void setMarkerLabeler(cv::Ptr<MarkerLabeler> detector)

setMakerLabeler sets the labeler employed to analyze the squares and extract the inner binary code

returns the number of thresholed images available

Methods you may not need

cv::Ptr<MarkerLabeler> getMarkerLabeler()

std::vector<MarkerCandidate> getCandidates() const

Returns a list candidates to be markers (rectangles), for which no valid id was found after calling detectRectangles

std::vector<cv::Mat> getImagePyramid()

void cornerUpsample(std::vector<std::vector<cv::Point2f>> &corners, cv::Size lowResImageSize)

void cornerUpsample(std::vector<Marker> &corners, cv::Size lowResImageSize)

bool warp(cv::Mat &in, cv::Mat &out, cv::Size size, std::vector<cv::Point2f> points)

Given the iput image with markers, creates an output image with it in the canonical position

Parameters:

• in – input image

• out – image with the marker

• size – of out

• points – 4 corners of the marker in the image in

Returns:

true if the operation succeed

void toStream(std::ostream &str) const

void fromStream(std::istream &str)

void setParameters(const Params &params)

struct Params

Operating params

Public Functions

void setDetectionMode(DetectionMode dm, float minMarkerSize)

Specifies the detection mode. We have preset three types of detection modes. These are ways to configure the internal parameters for the most typical situations. The modes are:

• DM_NORMAL: In this mode, the full resolution image is employed for detection and slow threshold method. Use this method when you process individual images that are not part of a video sequence and you are not interested in speed.

• DM_FAST: In this mode, there are two main improvements. First, image is threshold using a faster method using a global threshold. Also, the full resolution image is employed for detection, but, you could speed up detection even more by indicating a minimum size of the markers you will accept. This is set by the variable minMarkerSize which shoud be in range [0,1]. When it is 0, means that you do not set a limit in the size of the accepted markers. However, if you set 0.1, it means that markers smaller than 10% of the total image area, will not be detected. Then, the detection can be accelated up to orders of magnitude compared to the normal mode.

• DM_VIDEO_FAST: This is similar to DM_FAST, but specially adapted to video processing. In that case, we assume that the observed markers when you call to detect() have a size similar to the ones observed in the previous frame. Then, the processing can be speeded up by employing smaller versions of the image automatically calculated.

inline void detectEnclosedMarkers(bool do_)

Enables/Disbles the detection of enclosed markers. Enclosed markers are markers where corners are like opencv chessboard pattern

void setCornerRefinementMethod(CornerRefinementMethod method)

Sets the corner refinement method

• CORNER_SUBPIX: uses subpixel refinement implemented in opencv

• CORNER_LINES: uses all the pixels in the corner border to estimate the 4 lines of the square. Then estimate the point in which they intersect. In seems that it more robust to noise. However, it only works if input image is not resized. So, the value minMarkerSize will be set to 0.

• CORNER_NONE: Does no refinement of the corner. Again, it requires minMakerSize to be 0

void setThresholdMethod(ThresMethod method, int thresHold = -1, int wsize = -1, int wsize_range = 0)

Sets the thresholding method manually. Do no

inline void setAutoSizeSpeedUp(bool v, float Ts = 0.25)

inline bool getAutoSizeSpeedUp() const

void save(cv::FileStorage &fs) const

void load(cv::FileStorage &fs)

void toStream(std::ostream &str) const

void fromStream(std::istream &str)

Public Members

DetectionMode detectMode = DM_NORMAL

int maxThreads = 1

float borderDistThres = 0.015f

int lowResMarkerSize = 20

float minSize = -1

int minSize_pix = -1

bool enclosedMarker = false

float error_correction_rate = 0

std::string dictionary = "ALL_DICTS"

ThresMethod thresMethod = THRES_ADAPTIVE

int NAttemptsAutoThresFix = 3

int trackingMinDetections = 0

int AdaptiveThresWindowSize = -1

int ThresHold = 7

int AdaptiveThresWindowSize_range = 0

int markerWarpPixSize = 5

CornerRefinementMethod cornerRefinementM = CORNER_SUBPIX

bool autoSize = false

float ts = 0.25f

float pyrfactor = 2

Enables automatic image resize according to elements detected in previous frame

Param v:

Param ts:

is a factor in the range $(0,1]$ that accounts for the camera motion speed. For instance, when ts=0.1 , it means that in the next frame, $\tau_i$ is such that markers $10%$ smaller than the smallest marker in the current image will be seek. To avoid loosing track of the markers.

int closingSize = 0

Public Static Functions

static std::string toString(DetectionMode dm)

static DetectionMode getDetectionModeFromString(const std::string &str)

static std::string toString(CornerRefinementMethod dm)

static CornerRefinementMethod getCornerRefinementMethodFromString(const std::string &str)

static std::string toString(ThresMethod dm)

static ThresMethod getCornerThresMethodFromString(const std::string &str)