JeVoisBase  1.3
JeVois Smart Embedded Machine Vision Toolkit Base Modules
Share this page:
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, "File stem of camera parameters, or empty. Camera resolution "
31  "will be appended, as well as a .yaml extension. For example, specifying 'calibration' "
32  "here and running the camera sensor at 320x240 will attempt to load "
33  "calibration320x240.yaml from within the module's directory.",
34  "calibration", ParamCateg);
35 
36  //! Parameter \relates ArUco
37  JEVOIS_DECLARE_PARAMETER(detparams, std::string, "Filename of detector parameters, or empty", "", ParamCateg);
38 
39  //! Enum for parameter \relates ArUco
40  JEVOIS_DEFINE_ENUM_CLASS(Dict, (Original) (D4X4_50) (D4X4_100) (D4X4_250) (D4X4_1000) (D5X5_50) (D5X5_100)
41  (D5X5_250) (D5X5_1000) (D6X6_50) (D6X6_100) (D6X6_250) (D6X6_1000) (D7X7_50)
42  (D7X7_100) (D7X7_250) (D7X7_1000) );
43 
44  //! Parameter \relates ArUco
45  JEVOIS_DECLARE_PARAMETER(dictionary, Dict, "Symbol dictionary to use", Dict::D4X4_50, ParamCateg);
46 }
47 
48 //! Simple wrapper class over the opencv_contrib ArUco augmented reality markers
49 /*! ArUco markers are small 2D barcodes. Each ArUco marker corresponds to a number, encoded into a small grid of black
50  and white pixels. The ArUco decoding algorithm is capable of locating, decoding, and of estimating the pose
51  (location and orientation in space) of any ArUco markers in the camera's field of view.
52 
53  ArUcos are very useful as tags for many robotics and augmented reality applications. For example, one may place an
54  ArUco next to a robot's charging station, an elevator button, or an object that a robot should manipulate.
55 
56  For more information about ArUco, see https://www.uco.es/investiga/grupos/ava/node/26
57 
58  The implementation of ArUco used by JeVois is the one of OpenCV-Contrib, documented here:
59  http://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html
60 
61  ArUco markers can be created with several standard dictionaries. Different disctionaries give rise to different
62  numbers of pixels in the markers, and to different numbers of possible symbols that can be created using the
63  dictionary. The default dictionary used by JeVois is 4x4 with 50 symbols. Other dictionaries are also supported by
64  setting the appropriate parameter over serial port or in a config file, up to 7x7 with 1000 symbols.
65 
66  Creating and printing ArUco markers
67  -----------------------------------
68 
69  To create some markers, have a look at the samples here:
70  https://github.com/opencv/opencv_contrib/tree/master/modules/aruco
71 
72  To make sure that the files you compile are compatible with JeVois which uses OpenCV 3.2.0 release, get that exact
73  release from GitHub as opposed to just the latest version of those files:
74  \verbatim
75  wget wget https://github.com/opencv/opencv_contrib/archive/3.2.0.tar.gz
76  tar zxvf 3.2.0.tar.gz
77  # The files referenced below are in: opencv_contrib-3.2.0/modules/aruco/samples/
78  \endverbatim
79 
80  To compile the sample program that can generate some ArUco markers (e.g., to be printed on paper):
81  \code
82  g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib create_marker.cpp \\
83  -o create_marker -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco
84  \endcode
85 
86  Then, to make images of the markers in dictionary 0 (4x4_50):
87  \code
88  for id in {0..49}; do ./create_marker -d=0 --id=${id} aruco${id}.png; done
89  \endcode
90 
91  You can then print them and later detect them using this Component. Make sure you select the same dictionary in the
92  component as you did when you generated the markers.
93 
94  Recovering 3D pose of markers
95  -----------------------------
96 
97  To enable recovery of the 3D pose of a marker, you need to calibrate your camera. Again using the sample code:
98 
99  \code
100  g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib create_board_charuco.cpp \\
101  -o create_board_charuco -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco -lopencv_imgproc -lopencv_videoio
102 
103  g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib calibrate_camera_charuco.cpp \\
104  -o calibrate_camera_charuco -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco -lopencv_imgproc -lopencv_videoio
105  \endcode
106 
107  To create a ChArUco board that can be printed, using dictionary 0, and then derive the camera parameters from it
108  (set the `--ml` and `--sl` parameters to what you measure on your printed board; below are what we measured after
109  printing the 5x8 charuco board on US Letter paper with auto scaling/rotate to fit paper):
110 
111  \code
112  ./create_board_charuco -d=0 -h=5 -w=8 --ml=200 --sl=350 charuco.png
113  ./calibrate_camera_charuco -d=0 -h=5 -w=8 --ml=.0172 --sl=.0303 --rs --sc calibration.yaml
114  \endcode
115 
116  \ingroup components */
117 class ArUco : public jevois::Component,
118  public jevois::Parameter<aruco::camparams, aruco::detparams, aruco::dictionary>
119 {
120  public:
121  //! Constructor
123 
124  //! Destructor
125  virtual ~ArUco();
126 
127  //! Initialize, create the detector and read the config files
128  void postInit() override;
129 
130  //! Un-initialize, nuke allocated resources
131  void postUninit() override;
132 
133  //! Detect markers
134  void detectMarkers(cv::InputArray image, cv::OutputArray ids, cv::OutputArrayOfArrays corners);
135 
136  //! Estimate pose of individual markers
137  void estimatePoseSingleMarkers(cv::InputArrayOfArrays corners, float markerLength,
138  cv::OutputArray rvecs, cv::OutputArray tvecs);
139 
140  //! Our current camera matrix
141  cv::Mat itsCamMatrix;
142 
143  //! Our current distortion coefficients
144  cv::Mat itsDistCoeffs;
145 
146  protected:
147  cv::Ptr<cv::aruco::DetectorParameters> itsDetectorParams;
148  cv::Ptr<cv::aruco::Dictionary> itsDictionary;
149 };
150 
void detectMarkers(cv::InputArray image, cv::OutputArray ids, cv::OutputArrayOfArrays corners)
Detect markers.
Definition: ArUco.C:102
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:123
void postUninit() override
Un-initialize, nuke allocated resources.
Definition: ArUco.C:91
Simple wrapper class over the opencv_contrib ArUco augmented reality markers.
Definition: ArUco.H:117
virtual ~ArUco()
Destructor.
Definition: ArUco.C:22
Definition: ArUco.H:25
cv::Mat itsDistCoeffs
Our current distortion coefficients.
Definition: ArUco.H:144
cv::Mat itsCamMatrix
Our current camera matrix.
Definition: ArUco.H:141
friend friend class Component
cv::Ptr< cv::aruco::Dictionary > itsDictionary
Definition: ArUco.H:148
void postInit() override
Initialize, create the detector and read the config files.
Definition: ArUco.C:26
cv::Ptr< cv::aruco::DetectorParameters > itsDetectorParams
Definition: ArUco.H:147