aruco is a package to generate aruco codes

Overview

This package creates 7x7 arrays of boolean values that capture the “original” Aruco codes for values 0 to 1023. The provided tool examples/generate.go generates the aruco mark for the provided --code.

How to use

$ git clone https://github.com/tinkerator/aruco.git
$ cd aruco
$ go run examples/gencode.go --code 137
code 137 (turned=0):
.......
.#.....
..#..#.
.#.....
..#..#.
.#.###.
.......
decoded to ans=137 (turns=0): <nil>

• # is a white dot, . is a black dot.

The tool also supports creating an SVG of a code:

$ go run examples/gencode.go --code 765 --svg 765.svg

which creates this image:

How do aruco codes work?

At a technical level, an Aruco code is a 7x7 square grid of black or white blocks. Since most readers convert to grayscale, and it is designed to be read in different forms of light, the codes can typically be read in dark or light colors.

The outer square ring (24 blocks) is all dark. The inner 5x5 array of blocks holds the information contained in the marker. The marker can represent 10 bits of information (the code in the range [0,1023]). Dividing these 10 bits into 5 groups of two, the 2 most significant bits are represented by the 2nd line down the 7x7 grid - in the top row of the inner 5x5 grid with a code from the following table:

Each successive row accounts for the next lower order two bits of the code, and has values mapped from this table. So, to encode, you divide the 10-bit code into successive pairs of 2 bits and perform a lookup in this table to determine the content of the corresponding row in the table. More significant pairs of bits coming before less significant bits as you work down the rows.

To decode, you compare the content of the found 5x5 grid rows with the content of this table. If you find 0b01001 for example, you conclude that the 2-bit value it represents is 0b10 etc. By way of a worked example, the image above reads from top to bottom as {0b10, 0b11, 0b11, 0b11, 0b01} or 0b1011111101 = 765 decimal, as expected.

The decoding process can overcome some bit corruption, by comparing with “nearest” Hamming distance matches. That is XOR the observed value with the entries in this table and minimize the number of non-matching bits. Also, decoding allows for the possibility that the code has been rotated when scanned, so the decode process considers which rotation generates the least Hamming distance match.

This package considers a rotation turn count of one to represent a 90 degree counter clockwise rotation of the 5x5 grid.

TODO

• Independently validate this package works. Likely with gocv. The SVG images have a black boarder with white space which may confuse readers.

License info

The aruco package is distributed with the same BSD 3-clause license as that used by golang itself.

Reporting bugs

This is a hobby project, so I can’t guarantee a fix, but do use the github aruco bug tracker.