JeVoisBase  1.21
JeVois Smart Embedded Machine Vision Toolkit Base Modules
Share this page:
Loading...
Searching...
No Matches
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>
24
25#include <opencv2/aruco.hpp>
26
27namespace jevois { class StdModule; }
28
29namespace aruco
30{
31 static jevois::ParameterCategory const ParamCateg("ArUco Options");
32
33 //! Parameter \relates ArUco
34 JEVOIS_DECLARE_PARAMETER(detparams, std::string, "Filename of detector parameters, or empty - Note that "
35 "this parameter cannot be changed at runtime (must be set in the module's params.cfg).",
36 "", ParamCateg);
37
38 //! Enum for parameter \relates ArUco
39 JEVOIS_DEFINE_ENUM_CLASS(Dict, (Original) (D4X4_50) (D4X4_100) (D4X4_250) (D4X4_1000) (D5X5_50) (D5X5_100)
40 (D5X5_250) (D5X5_1000) (D6X6_50) (D6X6_100) (D6X6_250) (D6X6_1000) (D7X7_50)
41 (D7X7_100) (D7X7_250) (D7X7_1000) (ATAG_16h5) (ATAG_25h9) (ATAG_36h10) (ATAG_36h11) );
42
43 //! Parameter \relates ArUco
44 JEVOIS_DECLARE_PARAMETER(dictionary, Dict, "Symbol dictionary to use - Note that "
45 "this parameter cannot be changed at runtime (must be set in the module's params.cfg).",
46 Dict::D4X4_50, Dict_Values, ParamCateg);
47
48 //! Parameter \relates ArUco
49 JEVOIS_DECLARE_PARAMETER(dopose, bool, "Compute (and show) pose vectors, requires a valid camera calibration",
50 false, ParamCateg);
51
52 //! Parameter \relates ArUco
53 JEVOIS_DECLARE_PARAMETER(markerlen, float, "Marker side length (millimeters), used only for pose estimation",
54 100.0F, ParamCateg);
55
56 //! Parameter \relates ArUco
57 JEVOIS_DECLARE_PARAMETER(showcube, bool, "Show a 3D cube on top of each detected marker, when dopose is also true",
58 false, aruco::ParamCateg);
59}
60
61//! Simple wrapper class over the opencv_contrib ArUco augmented reality markers
62/*! ArUco markers are small 2D barcodes. Each ArUco marker corresponds to a number, encoded into a small grid of black
63 and white pixels. The ArUco decoding algorithm is capable of locating, decoding, and of estimating the pose
64 (location and orientation in space) of any ArUco markers in the camera's field of view.
65
66 ArUcos are very useful as tags for many robotics and augmented reality applications. For example, one may place an
67 ArUco next to a robot's charging station, an elevator button, or an object that a robot should manipulate.
68
69 For more information about ArUco, see https://www.uco.es/investiga/grupos/ava/node/26
70
71 The implementation of ArUco used by JeVois is the one of OpenCV-Contrib, documented here:
72 http://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html
73
74 ArUco markers can be created with several standard dictionaries. Different disctionaries give rise to different
75 numbers of pixels in the markers, and to different numbers of possible symbols that can be created using the
76 dictionary. The default dictionary used by JeVois is 4x4 with 50 symbols. Other dictionaries are also supported by
77 setting the appropriate parameter over serial port or in a config file, up to 7x7 with 1000 symbols.
78
79 Creating and printing ArUco markers
80 -----------------------------------
81
82 To create some markers, have a look at the samples here:
83 https://github.com/opencv/opencv_contrib/tree/master/modules/aruco
84
85 To make sure that the files you compile are compatible with JeVois which uses OpenCV 3.2.0 release, get that exact
86 release from GitHub as opposed to just the latest version of those files:
87 \verbatim
88 wget wget https://github.com/opencv/opencv_contrib/archive/3.2.0.tar.gz
89 tar zxvf 3.2.0.tar.gz
90 # The files referenced below are in: opencv_contrib-3.2.0/modules/aruco/samples/
91 \endverbatim
92
93 To compile the sample program that can generate some ArUco markers (e.g., to be printed on paper):
94 \code
95 g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib create_marker.cpp \\
96 -o create_marker -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco
97 \endcode
98
99 Then, to make images of the markers in dictionary 0 (4x4_50):
100 \code
101 for id in {0..49}; do ./create_marker -d=0 --id=${id} aruco${id}.png; done
102 \endcode
103
104 You can then print them and later detect them using this Component. Make sure you select the same dictionary in the
105 component as you did when you generated the markers.
106
107 Recovering 3D pose of markers
108 -----------------------------
109
110 To enable recovery of the 3D pose of a marker, you need to calibrate your camera. Again using the sample code:
111
112 \code
113 g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib create_board_charuco.cpp \\
114 -o create_board_charuco -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco -lopencv_imgproc -lopencv_videoio
115
116 g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib calibrate_camera_charuco.cpp \\
117 -o calibrate_camera_charuco -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco -lopencv_imgproc -lopencv_videoio
118 \endcode
119
120 To create a ChArUco board that can be printed, using dictionary 0, and then derive the camera parameters from it
121 (set the `--ml` and `--sl` parameters to what you measure on your printed board; below are what we measured after
122 printing the 5x8 charuco board on US Letter paper with auto scaling/rotate to fit paper):
123
124 \code
125 ./create_board_charuco -d=0 -h=5 -w=8 --ml=200 --sl=350 charuco.png
126 ./calibrate_camera_charuco -d=0 -h=5 -w=8 --ml=.0172 --sl=.0303 --rs --sc calibration.yaml
127 \endcode
128
129 \ingroup components */
131 public jevois::Parameter<aruco::detparams, aruco::dictionary,
132 aruco::dopose, aruco::markerlen, aruco::showcube>
133{
134 public:
135 //! Static method to allow anyone to get the ArUco dictionary for a given value of our dictionary parameter
136 static cv::aruco::Dictionary getDictionary(aruco::Dict d);
137
138 //! Constructor
140
141 //! Destructor
142 virtual ~ArUco();
143
144 //! Initialize, create the detector and read the config files
145 void postInit() override;
146
147 //! Un-initialize, nuke allocated resources
148 void postUninit() override;
149
150 //! Detect markers
151 void detectMarkers(cv::InputArray image, cv::OutputArray ids, cv::OutputArrayOfArrays corners);
152
153 //! Estimate pose of individual markers
154 void estimatePoseSingleMarkers(cv::InputArrayOfArrays corners, cv::OutputArray rvecs, cv::OutputArray tvecs);
155
156 //! Draw any markers previously detected by detectMarkers()
157 /*! If txtx,txty are positive, also print a text string there */
158 void drawDetections(jevois::RawImage & outimg, int txtx, int txty, std::vector<int> ids,
159 std::vector<std::vector<cv::Point2f> > corners, std::vector<cv::Vec3d> const & rvecs,
160 std::vector<cv::Vec3d> const & tvecs);
161
162#ifdef JEVOIS_PRO
163 //! Draw any markers previously detected by detectMarkers()
164 void drawDetections(jevois::GUIhelper & helper, std::vector<int> ids,
165 std::vector<std::vector<cv::Point2f> > corners, std::vector<cv::Vec3d> const & rvecs,
166 std::vector<cv::Vec3d> const & tvecs);
167#endif
168
169 //! Send serial messages about detections
170 /*! The module given should be the owner of this component, we will use it to actually send each serial message
171 using some variant of jevois::Module::sendSerial(). */
172 void sendSerial(jevois::StdModule * mod, std::vector<int> ids, std::vector<std::vector<cv::Point2f> > corners,
173 unsigned int w, unsigned int h, std::vector<cv::Vec3d> const & rvecs,
174 std::vector<cv::Vec3d> const & tvecs);
175
176 protected:
177 cv::Ptr<cv::aruco::ArucoDetector> itsDetector;
179};
180
int h
Simple wrapper class over the opencv_contrib ArUco augmented reality markers.
Definition ArUco.H:133
void detectMarkers(cv::InputArray image, cv::OutputArray ids, cv::OutputArrayOfArrays corners)
Detect markers.
Definition ArUco.C:114
JEVOIS_DECLARE_PARAMETER(detparams, std::string, "Filename of detector parameters, or empty - Note that " "this parameter cannot be changed at runtime (must be set in the module's params.cfg).", "", ParamCateg)
Parameter.
JEVOIS_DECLARE_PARAMETER(showcube, bool, "Show a 3D cube on top of each detected marker, when dopose is also true", false, aruco::ParamCateg)
Parameter.
void postUninit() override
Un-initialize, nuke allocated resources.
Definition ArUco.C:105
cv::Ptr< cv::aruco::ArucoDetector > itsDetector
Definition ArUco.H:177
virtual ~ArUco()
Destructor.
Definition ArUco.C:57
jevois::CameraCalibration itsCalib
Definition ArUco.H:178
void drawDetections(jevois::RawImage &outimg, int txtx, int txty, std::vector< int > ids, std::vector< std::vector< cv::Point2f > > corners, std::vector< cv::Vec3d > const &rvecs, std::vector< cv::Vec3d > const &tvecs)
Draw any markers previously detected by detectMarkers()
Definition ArUco.C:164
JEVOIS_DEFINE_ENUM_CLASS(Dict,(Original)(D4X4_50)(D4X4_100)(D4X4_250)(D4X4_1000)(D5X5_50)(D5X5_100)(D5X5_250)(D5X5_1000)(D6X6_50)(D6X6_100)(D6X6_250)(D6X6_1000)(D7X7_50)(D7X7_100)(D7X7_250)(D7X7_1000)(ATAG_16h5)(ATAG_25h9)(ATAG_36h10)(ATAG_36h11))
Enum for parameter.
static cv::aruco::Dictionary getDictionary(aruco::Dict d)
Static method to allow anyone to get the ArUco dictionary for a given value of our dictionary paramet...
Definition ArUco.C:28
void sendSerial(jevois::StdModule *mod, std::vector< int > ids, std::vector< std::vector< cv::Point2f > > corners, unsigned int w, unsigned int h, std::vector< cv::Vec3d > const &rvecs, std::vector< cv::Vec3d > const &tvecs)
Send serial messages about detections.
Definition ArUco.C:127
JEVOIS_DECLARE_PARAMETER(markerlen, float, "Marker side length (millimeters), used only for pose estimation", 100.0F, ParamCateg)
Parameter.
JEVOIS_DECLARE_PARAMETER(dopose, bool, "Compute (and show) pose vectors, requires a valid camera calibration", false, ParamCateg)
Parameter.
JEVOIS_DECLARE_PARAMETER(dictionary, Dict, "Symbol dictionary to use - Note that " "this parameter cannot be changed at runtime (must be set in the module's params.cfg).", Dict::D4X4_50, Dict_Values, ParamCateg)
Parameter.
void postInit() override
Initialize, create the detector and read the config files.
Definition ArUco.C:61
void estimatePoseSingleMarkers(cv::InputArrayOfArrays corners, cv::OutputArray rvecs, cv::OutputArray tvecs)
Estimate pose of individual markers.
Definition ArUco.C:120
friend friend class Component
Definition ArUco.H:30