Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Creating and using square pictorial markers
artoolkitX includes a tracking module that looks for known square visual landmarks ("fiducial markers") in a video stream and tracks the position and orientation (pose) of these relative to the camera.
These markers are either simple images enclosed in a continuous square border, or a special two-dimensional barcode conforming to one of several preset encodings.
For pictorial markers (named "template" markers because of the way in which they are recognised), a "pattern file" must be generated and supplied to artoolkitX so that it knows what marker to look for. The
mk_patt utility allows you to generate pattern files by pointing your camera at a printed square marker. Alternately, the
genMarkerSet utility allows the generation of pattern files by supplying a JPEG image file containing an image of the marker. More detail on these utilities is provided below.
For barcode markers (again, named "matrix" markers because of the way in which they are recognised), no pattern file is required, however the artoolkitX must be configured with the encoding being used. artoolkitX is pre-supplied with printable versions of the most useful barcode marker sets for you to print out.
Additionally, pictorial or barcode markers can be combined in a multi-marker set. This is a grouping of markers which are able to move as a group, but individual markers in the group cannot move (e.g. the markers are grouped on a single printed surface, or on the sides of a cube). Multi-markers offer improved tracking robustness and accuracy.
Creating pictorial (template) square markers
Designing your marker:
Your marker design must conform to the following minimum requirements:
- It must be square.
- It must have a continuous border (generally either full black or pure white). And, with the marker in foreground, the background must be a contrasting color (generally, a dark versus a light color or shade).
- By default, the border thickness is 25% of the length of an edge of the marker, but this may be varied, provided the same border percentage applies to ALL markers in use at any one time.
- The area inside the border, which we refer to as the pattern, must be rotationally asymmetric.
A new marker can be designed and created by editing the marker template image file provided in the artoolkitX SDK:
Documentation/Square marker pattern images/Blank pattern with border.pdf.
The area inside the border can be color, white on black or black on white, and it can extend into the border region. Remember that if part of the image falls inside the border, it will be ignored by artoolkitX though - and also be sure not to extend too far into the border, or else artoolkitX might not recognize the marker at all when its at a very oblique angle to the camera.
Generating a pattern file using mk_patt
mk_patt is an easy to use utility for training new markers. Open a command-line session window (on macOS / Linux, open a Terminal window, on Windows, choose "Run" from the Start menu, type "cmd").
On Linux / macOS, type
./artoolkitx_mk_patt. On Windows, type
You will see some output in your terminal, and a live camera window: ![mk_patt][mk_patt]
Point the camera directly at your marker. Try to align the camera so that the marker appears square on the screen and fills the camera's view. If artoolkitX has identified the marker, it will outline it with red lines.
Rotate the marker so that the corner of the square with the line extending into the middle is at the top-left corner of your marker, then press the left mouse button (for left-handed mouse users, this may be the configured primary mouse button). The image will be captured, and in your terminal window you will see the prompt
Type a filename for your pattern. By convention, this is a a unique pattern name ending with ".patt", and press return. If you don't want to save it, just press return to restart the video. That's it! You can train more patterns, or press [esc] to exit the program.
There are more options that you can customize when training markers (such as size of the marker border). Running the utility with the
--help option will show the various command-line options for adjusting the default settings. The help text is reproduced here:
Usage: artoolkitx_mk_patt [options] Options: --vconf <video parameter for the camera> --cpara <camera parameter file for the camera> --pattRatio f: Specify the proportion of the marker width/height, occupied by the marker pattern. Range (0.0 - 1.0) (not inclusive). (I.e. 1.0 - 2*borderSize). Default value is 0.5. --pattSize n: Specify the number of rows and columns in the pattern space for template (pictorial) markers. Default value 16 (required for compatibility with ARToolKit prior to version 5.2). Range is [16, %d] (inclusive).\n", AR_PATT_SIZE1_MAX); --pattCountMax n: Specify the maximum number of template (pictorial) markers that may be loaded for use in a single matching pass. Default value %d. Must be > 0.\n", AR_PATT_NUM_MAX); --borderSize f: DEPRECATED specify the width of the pattern border, as a percentage of the marker width. Range (0.0 - 0.5) (not inclusive). (I.e. (1.0 - pattRatio)/2). Default value is 0.25. -border=f: Alternate syntax for --borderSize f. --labelingMode AR_LABELING_BLACK_REGION|AR_LABELING_WHITE_REGION --patternDetectionMode k: specify the pattern detection mode, where k is one of: AR_TEMPLATE_MATCHING_COLOR AR_TEMPLATE_MATCHING_MONO --version: Print artoolkitX version and exit. -loglevel=l: Set the log level to l, where l is one of DEBUG INFO WARN ERROR. -h -help --help: show this message
Changing Marker Border Width
The border width can be set at runtime. See the documentation for
Changing Marker Pattern Size
The marker's pattern size (the number of pixels sampled for the pattern) can be changed at runtime. By default it is 16x16 pixels, and if you wish to maintain compatibility with previous versions, it is recommended to retain this setting. If you wish to change the size this is done during AR setup by using parameters to the
Using Really Large Square Markers
If using large images, you may want to edit the definitions of the values for
AR_PATT_NUM_MAX (in `Source/ARX/AR/include/ARX/AR/config.h.in), and recompile artoolkitX. These influence memory use so are usually set to a conservative minimum.
Tips for Best Results
- The markers will work best if they're trained on the same camera that is used for the actual application. The camera should be [accurately calibrated][config_camera_calibration] prior to running mk_patt.
- Don't forget that markers can be color. Adding color to markers can enhance the AR application.
- A common mistake is to try and use markers with too much fine detail in the pattern. By default, artoolkitX samples the pattern at only a resolution of 16x16 pixels, so if you're getting markers mistaken for each other or not recognized, check whether your markers appear similar to each other when the pattern graphic is scaled down to a 16x16 pixel image.