ArUco Class Reference

Simple wrapper class over the opencv_contrib ArUco augmented reality markers. More...

#include <jevoisbase/Components/ArUco/ArUco.H>

Inheritance diagram for ArUco:

Collaboration diagram for ArUco:

Public Member Functions
virtual	~ArUco ()
	Destructor. More...
void	postInit () override
	Initialize, create the detector and read the config files. More...
void	postUninit () override
	Un-initialize, nuke allocated resources. More...
void	detectMarkers (cv::InputArray image, cv::OutputArray ids, cv::OutputArrayOfArrays corners)
	Detect markers. More...
void	estimatePoseSingleMarkers (cv::InputArrayOfArrays corners, cv::OutputArray rvecs, cv::OutputArray tvecs)
	Estimate pose of individual markers. More...
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() More...
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. More...
Public Member Functions inherited from jevois::Component
	Component (std::string const &instance)
virtual	~Component ()
std::shared_ptr< Comp >	addSubComponent (std::string const &instance, Args &&...args)
void	removeSubComponent (std::shared_ptr< Comp > &component)
void	removeSubComponent (std::string const &instance, bool warnIfNotFound=true)
std::shared_ptr< Comp >	getSubComponent (std::string const &instance) const
bool	isTopLevel () const
Engine *	engine () const
bool	initialized () const
const std::string &	className () const
const std::string &	instanceName () const
std::vector< std::string >	setParamVal (std::string const &paramdescriptor, T const &val)
void	setParamValUnique (std::string const &paramdescriptor, T const &val)
std::vector< std::pair< std::string, T > >	getParamVal (std::string const &paramdescriptor) const
T	getParamValUnique (std::string const &paramdescriptor) const
std::vector< std::string >	setParamString (std::string const &paramdescriptor, std::string const &val)
void	setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
std::vector< std::pair< std::string, std::string > >	getParamString (std::string const &paramdescriptor) const
std::string	getParamStringUnique (std::string const &paramdescriptor) const
void	freezeParam (std::string const &paramdescriptor)
void	unFreezeParam (std::string const &paramdescriptor)
void	freezeAllParams ()
void	unFreezeAllParams ()
std::string	descriptor () const
void	setParamsFromFile (std::string const &filename)
std::istream &	setParamsFromStream (std::istream &is, std::string const &absfile)
virtual void	paramInfo (std::shared_ptr< UserInterface > s, std::map< std::string, std::string > &categs, bool skipFrozen, std::string const &cname="", std::string const &pfx="")
void	foreachParam (std::function< void(std::string const &compname, ParameterBase *p)> func, std::string const &cname="")
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ParameterCategory const &category)
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ValidValuesSpec< T > const &validValuesSpec, ParameterCategory const &category)
void	setDynamicParameterCallback (std::string const &name, std::function< void(T const &)> cb, bool callnow=true)
void	removeDynamicParameter (std::string const &name)
void	setPath (std::string const &path)
std::filesystem::path	absolutePath (std::filesystem::path const &path="")
std::shared_ptr< Comp >	addSubComponent (std::string const &instance, Args &&...args)
void	removeSubComponent (std::shared_ptr< Comp > &component)
void	removeSubComponent (std::string const &instance, bool warnIfNotFound=true)
std::shared_ptr< Comp >	getSubComponent (std::string const &instance) const
bool	isTopLevel () const
Engine *	engine () const
bool	initialized () const
const std::string &	className () const
const std::string &	instanceName () const
std::vector< std::string >	setParamVal (std::string const &paramdescriptor, T const &val)
void	setParamValUnique (std::string const &paramdescriptor, T const &val)
std::vector< std::pair< std::string, T > >	getParamVal (std::string const &paramdescriptor) const
T	getParamValUnique (std::string const &paramdescriptor) const
std::vector< std::string >	setParamString (std::string const &paramdescriptor, std::string const &val)
void	setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
std::vector< std::pair< std::string, std::string > >	getParamString (std::string const &paramdescriptor) const
std::string	getParamStringUnique (std::string const &paramdescriptor) const
void	freezeParam (std::string const &paramdescriptor)
void	unFreezeParam (std::string const &paramdescriptor)
void	freezeAllParams ()
void	unFreezeAllParams ()
std::string	descriptor () const
void	setParamsFromFile (std::string const &filename)
std::istream &	setParamsFromStream (std::istream &is, std::string const &absfile)
virtual void	paramInfo (std::shared_ptr< UserInterface > s, std::map< std::string, std::string > &categs, bool skipFrozen, std::string const &cname="", std::string const &pfx="")
void	foreachParam (std::function< void(std::string const &compname, ParameterBase *p)> func, std::string const &cname="")
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ParameterCategory const &category)
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ValidValuesSpec< T > const &validValuesSpec, ParameterCategory const &category)
void	setDynamicParameterCallback (std::string const &name, std::function< void(T const &)> cb, bool callnow=true)
void	removeDynamicParameter (std::string const &name)
void	setPath (std::string const &path)
std::filesystem::path	absolutePath (std::filesystem::path const &path="")
Public Member Functions inherited from jevois::ParameterRegistry
virtual	~ParameterRegistry ()

Public Attributes
cv::Mat	itsCamMatrix
	Our current camera matrix. More...
cv::Mat	itsDistCoeffs
	Our current distortion coefficients. More...

Protected Attributes
cv::Ptr< cv::aruco::ArucoDetector >	itsDetector

Related Functions
(Note that these are not member functions.)
	JEVOIS_DECLARE_PARAMETER (camparams, std::string, "File stem of camera parameters, or empty. Camera resolution " "will be appended, as well as a .yaml extension. For example, specifying 'calibration' " "here and running the camera sensor at 320x240 will attempt to load " "calibration320x240.yaml from within directory " JEVOIS_SHARE_PATH "/camera/ - Note that " "this parameter cannot be changed at runtime (must be set in the module's params.cfg).", "calibration", ParamCateg)
	Parameter. More...
	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. More...
	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. More...
	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. More...
	JEVOIS_DECLARE_PARAMETER (dopose, bool, "Compute (and show) pose vectors, requires a valid camera calibration", false, ParamCateg)
	Parameter. More...
	JEVOIS_DECLARE_PARAMETER (markerlen, float, "Marker side length (millimeters), used only for pose estimation", 100.0F, ParamCateg)
	Parameter. More...
	JEVOIS_DECLARE_PARAMETER (showcube, bool, "Show a 3D cube on top of each detected marker, when dopose is also true", false, aruco::ParamCateg)
	Parameter. More...

Additional Inherited Members
Protected Member Functions inherited from jevois::Component
virtual void	preInit ()
virtual void	preUninit ()
virtual void	preInit ()
virtual void	preUninit ()
Protected Member Functions inherited from jevois::ParameterRegistry
void	addParameter (ParameterBase *const param)
void	removeParameter (ParameterBase *const param)
void	callbackInitCall ()

Detailed Description

Simple wrapper class over the opencv_contrib ArUco augmented reality markers.

ArUco markers are small 2D barcodes. Each ArUco marker corresponds to a number, encoded into a small grid of black and white pixels. The ArUco decoding algorithm is capable of locating, decoding, and of estimating the pose (location and orientation in space) of any ArUco markers in the camera's field of view.

ArUcos are very useful as tags for many robotics and augmented reality applications. For example, one may place an ArUco next to a robot's charging station, an elevator button, or an object that a robot should manipulate.

For more information about ArUco, see https://www.uco.es/investiga/grupos/ava/node/26

The implementation of ArUco used by JeVois is the one of OpenCV-Contrib, documented here: http://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html

ArUco markers can be created with several standard dictionaries. Different disctionaries give rise to different numbers of pixels in the markers, and to different numbers of possible symbols that can be created using the dictionary. The default dictionary used by JeVois is 4x4 with 50 symbols. Other dictionaries are also supported by setting the appropriate parameter over serial port or in a config file, up to 7x7 with 1000 symbols.

Creating and printing ArUco markers

To create some markers, have a look at the samples here: https://github.com/opencv/opencv_contrib/tree/master/modules/aruco

To make sure that the files you compile are compatible with JeVois which uses OpenCV 3.2.0 release, get that exact release from GitHub as opposed to just the latest version of those files:

wget wget https://github.com/opencv/opencv_contrib/archive/3.2.0.tar.gz
tar zxvf 3.2.0.tar.gz
# The files referenced below are in: opencv_contrib-3.2.0/modules/aruco/samples/

To compile the sample program that can generate some ArUco markers (e.g., to be printed on paper):

g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib create_marker.cpp \\
    -o create_marker -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco

Then, to make images of the markers in dictionary 0 (4x4_50):

for id in {0..49}; do ./create_marker -d=0 --id=${id} aruco${id}.png; done

You can then print them and later detect them using this Component. Make sure you select the same dictionary in the component as you did when you generated the markers.

Recovering 3D pose of markers

To enable recovery of the 3D pose of a marker, you need to calibrate your camera. Again using the sample code:

g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib create_board_charuco.cpp \\
    -o create_board_charuco -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco -lopencv_imgproc -lopencv_videoio
 
g++ -I/usr/share/jevois-opencv-3.2.0/include -L/usr/share/jevois-opencv-3.2.0/lib calibrate_camera_charuco.cpp \\
    -o calibrate_camera_charuco -lopencv_core -lopencv_imgcodecs -lopencv_highgui -lopencv_aruco -lopencv_imgproc -lopencv_videoio

To create a ChArUco board that can be printed, using dictionary 0, and then derive the camera parameters from it (set the --ml and --sl parameters to what you measure on your printed board; below are what we measured after printing the 5x8 charuco board on US Letter paper with auto scaling/rotate to fit paper):

./create_board_charuco -d=0 -h=5 -w=8 --ml=200 --sl=350 charuco.png
./calibrate_camera_charuco -d=0 -h=5 -w=8 --ml=.0172 --sl=.0303 --rs --sc calibration.yaml

Definition at line 137 of file ArUco.H.

Constructor & Destructor Documentation

~ArUco()

ArUco::~ArUco ( )

virtual

Destructor.

Definition at line 27 of file ArUco.C.

Member Function Documentation

detectMarkers()

void ArUco::detectMarkers	(	cv::InputArray	image,
		cv::OutputArray	ids,
		cv::OutputArrayOfArrays	corners
	)

Detect markers.

Definition at line 110 of file ArUco.C.

References demo::image, itsCamMatrix, itsDetector, itsDistCoeffs, LERROR, LINFO, and to_string().

drawDetections()

void ArUco::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()

If txtx,txty are positive, also print a text string there

Definition at line 179 of file ArUco.C.

References jevois::rawimage::drawDisk(), jevois::rawimage::drawLine(), demo::int, itsCamMatrix, itsDistCoeffs, to_string(), and jevois::rawimage::writeText().

Referenced by PythonObject6D.PythonObject6D::process(), and FirstPython.FirstPython::process().

estimatePoseSingleMarkers()

void ArUco::estimatePoseSingleMarkers	(	cv::InputArrayOfArrays	corners,
		cv::OutputArray	rvecs,
		cv::OutputArray	tvecs
	)

Estimate pose of individual markers.

Definition at line 136 of file ArUco.C.

References itsCamMatrix, and itsDistCoeffs.

postInit()

void ArUco::postInit ( )

overridevirtual

Initialize, create the detector and read the config files.

Reimplemented from jevois::Component.

Definition at line 31 of file ArUco.C.

References freeze(), itsDetector, and LERROR.

postUninit()

void ArUco::postUninit ( )

overridevirtual

Un-initialize, nuke allocated resources.

Reimplemented from jevois::Component.

Definition at line 99 of file ArUco.C.

References itsCamMatrix, itsDetector, itsDistCoeffs, and unFreeze().

sendSerial()

void ArUco::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.

The module given should be the owner of this component, we will use it to actually send each serial message using some variant of jevois::Module::sendSerial().

Definition at line 142 of file ArUco.C.

References h, quantize-inc::q, jevois::StdModule::sendSerialContour2D(), jevois::StdModule::sendSerialStd3D(), to_string(), and demo::w.

Friends And Related Function Documentation

JEVOIS_DECLARE_PARAMETER() [1/6]

JEVOIS_DECLARE_PARAMETER ( camparams  , std::string  , "File stem of camera  parameters, or empty. Camera resolution " "will be  appended, as well as a .yaml extension. For  example, specifying 'calibration' " "here and running the camera sensor at 320x240 will attempt to load " "calibration320x240.yaml from within directory " JEVOIS_SHARE_PATH "/camera/- Note that " "this parameter cannot be changed at runtime(must be set in the module 's params.cfg)."  , "calibration"  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [2/6]

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    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [3/6]

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    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [4/6]

JEVOIS_DECLARE_PARAMETER ( dopose  , bool  , "Compute (and show) pose  vectors, requires a valid camera calibration"  , false  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [5/6]

JEVOIS_DECLARE_PARAMETER ( markerlen  , float  , "Marker side length   millimeters, used only for pose estimation"  , 100.  0F, ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [6/6]

JEVOIS_DECLARE_PARAMETER ( showcube  , bool  , "Show a 3D cube on top of each detected  marker, when dopose is also true"  , false  , aruco::ParamCateg    )

related

Parameter.

JEVOIS_DEFINE_ENUM_CLASS()

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)    )

related

Enum for parameter.

Member Data Documentation

itsCamMatrix

cv::Mat ArUco::itsCamMatrix

Our current camera matrix.

Definition at line 181 of file ArUco.H.

Referenced by detectMarkers(), drawDetections(), estimatePoseSingleMarkers(), and postUninit().

itsDetector

cv::Ptr<cv::aruco::ArucoDetector> ArUco::itsDetector

protected

Definition at line 187 of file ArUco.H.

Referenced by detectMarkers(), postInit(), and postUninit().

itsDistCoeffs

cv::Mat ArUco::itsDistCoeffs

Our current distortion coefficients.

Definition at line 184 of file ArUco.H.

Referenced by detectMarkers(), drawDetections(), estimatePoseSingleMarkers(), and postUninit().

---

The documentation for this class was generated from the following files:

• include/jevoisbase/Components/ArUco/ArUco.H
• src/Components/ArUco/ArUco.C