# SwisTrack/Examples/IDReaderRing

The IDReaderRing component in SwisTrack can read a circular barcode around a blob. The implementation assumes that there is a white blob in the middle that can be detected with a standard blob detection algorithm, and a gray-black bar code around. This example contains Matlab code to create such barcode blobs, and information on how to use it.

## Creating a new Set of Blobs

The Matlab scripts for creating blobs are located in the CreateBarCodes folder. The following procedure will create bar codes:
* Create a list of symbols, e.g. with 14 chips and Hamming distance 4:
* (optional) Check the symbol distances:
* (optional) Draw one symbol:
* Draw (and save/export) all symbols:
You may want to modify "drawsymbol" to change the size/proportions of the blob. The algorithm finds codes with 14 chips that are rotationally independent (i.e. no two codes are the same in any rotation), and have a Hamming distance of at least 4 chips (i.e. any two codes in any rotation differ by at least 4 chips). This is done in a heuristic fashion, and when running the algorithm several times, it may come up with a slightly different number of codes.

## Choosing the Right Number of Chips

The number of chips as well as the Hamming distance will greatly influence the number of available codes. There are a number of trade-offs involved, however:
* The more chips you use, the more codes you'll get.
* The bigger the Hamming distance, the fewer codes you'll get.
* The more chips you use, the more resolution you need (i.e. better camera resolution or bigger blobs on the camera image). This is a constraint imposed by the Nyquist criterion. As a rule of thumb, the image should be at least N by N pixels for a code with 0.7N chips.
* The bigger the Hamming distance, the more robust the detection/discrimination is going to be.
Hence, you should find a configuration that provides about the number of blobs that you really need. One or two times more codes than you need is OK and may serve you as spare codes in case you'll need more at some later time, but if your configuration yields 10 or 100 times more codes, you unnecessarily trading off detection quality with number of codes.

## Creating the Object List

To create the list of bar codes, run exportsymbols.m for a full XML file with all your symbols, or modify existing robotlist.xml. Optimally, you'd only enter the barcodes that you are using in your experiment here. The more barcodes the file contains, the longer it will take to detect the barcodes.

## Playing with the Detection Algorithm

To play around with the detection algorithm, there is a Matlab script available in the DetectionAlgorithm folder.

## Practical Hints and Limitations

The current implementation assumes a perfectly circular barcode. On cameras with high distortions, this does not produce satisfactory results.
The inner radius of the ring should be chosen such that the blob in the center does not interfere in any case. As the blob is white, the algorithm will take it for a white chip. Especially if small deformations are expected, the distance between the barcode and the blob in the center (black ring) should be sufficiently big. The same might happen with the outer radius of the ring if the robot or floor is white. In this case, it helps adding a large black ring on the outside of the barcode.
The implementation is somewhat robust with respect to illumination (brightness average is removed), but will fail if there are reflections on the blob. This is usually not a problem with paper blobs, but could be an issue with plastic coated blobs.
In some cases, the white chips in the barcode ring are detected as blobs. Some ways to fix that include: - Making the barcode grey-black instead of white-black, and put a white blob in the middle. The barcode discrimination quality will suffer slightly, but this is a OK in many cases. - Keeping the barcode ring thin, and the blob in the center big. A threshold on the blob size will then filter out a few consecutive white chips and everything else that is too small to be a blob.
When using Bayer pattern color cameras, you might need a higher effective resolution to detect the barcode reliably.