JeVoisBase  1.0
JeVois Smart Embedded Machine Vision Toolkit Base Modules
ArUco.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 #pragma once
19 
21 #include <jevois/Types/Enum.H>
22 
23 #include <opencv2/aruco.hpp>
24 
25 namespace aruco
26 {
27  static jevois::ParameterCategory const ParamCateg("ArUco Options");
28 
29  //! Parameter \relates ArUco
30  JEVOIS_DECLARE_PARAMETER(camparams, std::string, "Filename of camera parameters, or empty", "", ParamCateg);
31 
32  //! Parameter \relates ArUco
33  JEVOIS_DECLARE_PARAMETER(detparams, std::string, "Filename of detector parameters, or empty", "", ParamCateg);
34 
35  //! Enum for parameter \relates ArUco
36  JEVOIS_DEFINE_ENUM_CLASS(Dict, (Original) (D4X4_50) (D4X4_100) (D4X4_250) (D4X4_1000) (D5X5_50) (D5X5_100)
37  (D5X5_250) (D5X5_1000) (D6X6_50) (D6X6_100) (D6X6_250) (D6X6_1000) (D7X7_50)
38  (D7X7_100) (D7X7_250) (D7X7_1000) );
39 
40  //! Parameter \relates ArUco
41  JEVOIS_DECLARE_PARAMETER(dictionary, Dict, "Symbol dictionary to use", Dict::D4X4_50, ParamCateg);
42 }
43 
44 //! Simple wrapper class over the opencv_contrib ArUco augmented reality markers
45 /*! ArUco markers are small 2D barcodes. Each ArUco marker corresponds to a number, encoded into a small grid of black
46  and white pixels. The ArUco decoding algorithm is capable of locating, decoding, and of estimating the pose
47  (location and orientation in space) of any ArUco markers in the camera's field of view.
48 
49  ArUcos are very useful as tags for many robotics and augmented reality applications. For example, one may place an
50  ArUco next to a robot's charging station, an elevator button, or an object that a robot should manipulate.
51 
52  For more information about ArUco, see https://www.uco.es/investiga/grupos/ava/node/26
53 
54  The implementation of ArUco used by JeVois is the one of OpenCV-Contrib, documented here:
55  http://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html
56 
57  ArUco markers can be created with several standard dictionaries. Different disctionaries give rise to different
58  numbers of pixels in the markers, and to different numbers of possible symbols that can be created using the
59  dictionary. The default dictionary used by JeVois is 4x4 with 50 symbols. Other dictionaries are also supported by
60  setting the appropriate parameter over serial port or in a config file, up to 7x7 with 1000 symbols.
61 
62  Creating and printing ArUco markers
63  -----------------------------------
64 
65  To create some markers, have a look at the samples here:
66  https://github.com/opencv/opencv_contrib/tree/master/modules/aruco
67 
68  To compile the sample program that can generate some ArUco markers (e.g., to be printed on paper):
69  \code
70  g++ -I/usr/local/include -L/usr/local/lib create_marker.cpp -o create_marker -lopencv_core \\
71  -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco
72  \endcode
73 
74  Then, to make images of the markers in dictionary 0 (4x4_50):
75  \code
76  for id in {0..49}; do ./create_marker -d=0 --id=${id} aruco${id}.png; done
77  \endcode
78 
79  You can then print them and later detect them using this Component. Make sure you select the same dictionary in the
80  component as you did when you generated the markers.
81 
82  Recovering 3D pose of markers
83  -----------------------------
84 
85  To enable recovery of the 3D pose of a marker, you need to calibrate your camera. Again using the sample code:
86 
87  \code
88  g++ -I/usr/local/include -L/usr/local/lib calibrate_camera.cpp -o calibrate_camera -lopencv_core \\
89  -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco -lopencv_imgproc -lopencv_videoio
90  \endcode
91 
92  To create a ChArUco board that can be printed, using dictionary 0, and then derive the camera parameters from it
93  (set the -l and -s parameters to what you measure on your printed board):
94 
95  \code
96  ./create_board_charuco -d=0 -h=5 -w=8 --ml=200 --sl=350 charuco.png
97  ./calibrate_camera -d=0 -h=5 -w=8 -l=.0175 -s=.00682 calibration.yaml
98  \endcode
99 
100  \ingroup components */
101 class ArUco : public jevois::Component,
102  public jevois::Parameter<aruco::camparams, aruco::detparams, aruco::dictionary>
103 {
104  public:
105  //! Constructor
107 
108  //! Destructor
109  virtual ~ArUco();
110 
111  //! Initialize, create the detector and read the config files
112  void postInit() override;
113 
114  //! Un-initialize, nuke allocated resources
115  void postUninit() override;
116 
117  //! Detect markers
118  void detectMarkers(cv::InputArray image, cv::OutputArray ids, cv::OutputArrayOfArrays corners);
119 
120  //! Estimate pose of individual markers
121  void estimatePoseSingleMarkers(cv::InputArrayOfArrays corners, float markerLength,
122  cv::OutputArray rvecs, cv::OutputArray tvecs);
123 
124  //! Our current camera matrix
125  cv::Mat itsCamMatrix;
126 
127  //! Our current distortion coefficients
128  cv::Mat itsDistCoeffs;
129 
130  protected:
131  cv::Ptr<cv::aruco::DetectorParameters> itsDetectorParams;
132  cv::Ptr<cv::aruco::Dictionary> itsDictionary;
133 };
134 
void detectMarkers(cv::InputArray image, cv::OutputArray ids, cv::OutputArrayOfArrays corners)
Detect markers.
Definition: ArUco.C:110
JEVOIS_DECLARE_PARAMETER(thresh1, double,"First threshold for hysteresis", 50.0, ParamCateg)
void estimatePoseSingleMarkers(cv::InputArrayOfArrays corners, float markerLength, cv::OutputArray rvecs, cv::OutputArray tvecs)
Estimate pose of individual markers.
Definition: ArUco.C:116
void postUninit() override
Un-initialize, nuke allocated resources.
Definition: ArUco.C:99
Simple wrapper class over the opencv_contrib ArUco augmented reality markers.
Definition: ArUco.H:101
virtual ~ArUco()
Destructor.
Definition: ArUco.C:21
Definition: ArUco.H:25
cv::Mat itsDistCoeffs
Our current distortion coefficients.
Definition: ArUco.H:128
cv::Mat itsCamMatrix
Our current camera matrix.
Definition: ArUco.H:125
friend friend class Component
cv::Ptr< cv::aruco::Dictionary > itsDictionary
Definition: ArUco.H:132
void postInit() override
Initialize, create the detector and read the config files.
Definition: ArUco.C:25
cv::Ptr< cv::aruco::DetectorParameters > itsDetectorParams
Definition: ArUco.H:131