Demo ArUco
Simple demo of ArUco augmented reality markers detection and decoding.
By Laurent Ittiitti@usc.eduhttp://jevois.orgGPL v3
 Language:   C++            Supports mappings with USB output:   Yes            Supports mappings with NO USB output:   Yes
 Video Mapping:   NONE 0 0 0 YUYV 320 240 30.0 JeVois DemoArUco
 Video Mapping:   YUYV 320 260 30.0 YUYV 320 240 30.0 JeVois DemoArUco
 Video Mapping:   YUYV 640 500 20.0 YUYV 640 480 20.0 JeVois DemoArUco

Module Documentation

Detect and decode patterns known as ArUco markers, which are small 2D barcodes often used in augmented reality and robotics.

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 dictionaries 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 markers

We have created the 50 markers available in the default dictionary (4x4_50) as PNG images that you can download and print, at http://jevois.org/data/ArUco.zip

To make your own, for example, using another dictionary, see the documentation of the ArUco component of JeVoisBase. Some utilities are provided with the component.

Serial Messages

This module can send standardized serial messages as described in Standardized serial messages formatting.

When dopose is turned on, 3D messages will be sent, otherwise 2D messages.

One message is issued for every detected ArUco, on every video frame.

2D messages when dopose is off:

  • Serial message type: 2D
  • id: decoded ArUco marker ID, with a prefix 'U'
  • x, y, or vertices: standardized 2D coordinates of marker center or corners
  • w, h: standardized marker size
  • extra: none (empty string)

3D messages when dopose is on:

  • Serial message type: 3D
  • id: decoded ArUco marker ID, with a prefix 'U'
  • x, y, z, or vertices: 3D coordinates in millimeters of marker center or corners
  • w, h, d: marker size in millimeters, a depth of 1mm is always used
  • extra: none (empty string)

If you will use the quaternion data (Detail message style; see Standardized serial messages formatting), you should probably set the serprec parameter to something non-zero to get enough accuracy in the quaternion values.

Things to try

  • First, use a video viewer software on a host computer and select one of the video modes with video output over USB. Point your JeVois camera towards one of the screenshots provided with this module, or towards some ArUco markers that you find on the web or that you have printed from the collection above (note: the default dictionary is 4x4_50, see parameter dictionary).
  • Then try it with no video output, as it would be used by a robot. Connect to the command-line interface of your JeVois camera through the serial-over-USB connection (see Command-line interface user guide; on Linux, you would use sudo screen /dev/ttyACM0 115200) and try:
      setpar serout USB
      setmapping2 YUYV 320 240 30.0 JeVois DemoArUco
      streamon
    and point the camera to some markers; the camera should issue messages about all the markers it identifies.

Computing and showing 3D pose

The OpenCV ArUco module can also compute the 3D location and orientation of each marker in the world when dopose is true. The requires that the camera be calibrated, see the documentation of the ArUco component in JeVoisBase. A generic calibration that is for a JeVois camera with standard lens is included in files calibration640x480.yaml, calibration352x288.yaml, etc in the module's directory (on the MicroSD, this is in JEVOIS:/modules/JeVois/DemoArUco/).

When doing pose estimation, you should set the markerlen parameter to the size (width) in millimeters of your actual physical markers. Knowing that size will allow the pose estimation algorithm to know where in the world your detected markers are.

ParameterTypeDescriptionDefaultValid Values
(ArUco) camparamsstd::stringFile 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 the module's directory.calibration-
(ArUco) detparamsstd::stringFilename of detector parameters, or empty-
(ArUco) dictionaryDictSymbol dictionary to useDict::D4X4_50-
(ArUco) doposeboolCompute (and show) pose vectors, requires a valid camera calibrationfalse-
(ArUco) markerlenfloatMarker side length (millimeters), used only for pose estimation100.0F-
(ArUco) showcubeboolShow a 3D cube on top of each detected marker, when dopose is also truetrue-
Detailed docs:DemoArUco
Copyright:Copyright (C) 2016 by Laurent Itti, iLab and the University of Southern California
License:GPL v3
Distribution:Unrestricted
Restrictions:None
Support URL:http://jevois.org/doc
Other URL:http://iLab.usc.edu
Address:University of Southern California, HNB-07A, 3641 Watt Way, Los Angeles, CA 90089-2520, USA