Whenever we're participating in events and showcasing the Spartez add-ons, the most eye-catching and "wow-triggering" of them all is always Agile Cards for JIRA. At every conference we go to, the Spartez booth always features a physical board with issues or tasks displayed on it in the form of printed cards. Each time when we run an Agile Cards live demo and showcase the scanner feature, we get genuine looks of disbelief and amazement, followed by a series of questions about how this works and what do these little black circles, rectangles and squares printed on the cards stand for.
So here it is: the story behind our very own Agile Cards "KR codes".
A long time ago in an office far, far away...
One of the features that make our Agile Cards for JIRA add-on unique is the embedded scanner app. Each time a user takes a photograph of their physical board and uploads it to JIRA®, the scanner app automatically recognizes the differences between the issues' statuses and resolutions on the physical and digital boards, and rearranges the issues in JIRA® in accordance with the uploaded photograph. Although this may sound simple, there's there's much more to this feature than meets the eye.
The first version of the photo scanner, as part of Agile Cards 2.0, saw the light of day November 2011. Back then we were experimenting with encoding information on the cards and column dividers with QR codes and Data Matrix codes, but both of these approaches proved unsuccessful because of their high data density. The board photos were most often taken using smartphones but five years ago a code measuring a few centimeters on the board photographed with a run of the mill smartphone camera was too small to be legible on the resulting image.
This is why Sławek Ginter, one of the co-founders of Spartez, designed and implemented his unique "RGBK" codes, which is an acronym for "Red Green Blue blacK". This solution featured a combination of 16 squares, each of which could be one of 4 colors (red, green, blue or black) and could contain up to 32 bits of data in total.
Unfortunately, this solution too had its limitations:
- A color printer was necessary to print the cards properly,
- the photographed board needed to be very well lit for the scanner to be able to interpret the data accurately,
- the scanner worked on a trial & error basis, interpreting all dark squares visible on the photograph as possible sources of data, which consumed a lot of time and computing power,
- the 32 bits quickly proved not enough to uniquely identify the issues displayed on the board (increasing the amount of bits would have required either bigger codes, consuming more of the precious card "real estate", or higher resolution cameras, which were not commonly used at the time).
A new hope
Spartez prides itself in encouraging its employees to devote 20% of their work time to try and tackle issues often believed to be insolvable by others, so during the long evenings of winter 2014/2015 I decided to take a shot at figuring out a fix. I based my line of thought on the following assumptions and requirements:
- Digital technology has become successful mainly because it's based on the binary system, which uses only 1's and 0's, and only black and white with regard to images. If we could reduce the codes from 4 colors to just black and white, this would solve the problems with board lighting.
- The codes had to be distinctive enough to be easily locatable on a photograph.
- The codes had to be immune to rotation, so that their legibility would not be affected by the precision to the arrangement of the card printouts on a given board.
- The codes had to be able to contain more data.
It wasn't long before I arrived at a solution involving black circles and slightly "tetris-looking" shapes. Since the original inspiration for this came from QR codes, and the first two letters of my first name, Krystian Wróblewski, sound a little like "QR", the name "KR codes" was quite organic and that is how they are known to-date.
The KR code markers, i.e. the distinctive part of the code which is easily locatable for the algorithm, are based on the QR code idea, but ours are round, so that they always look the same regardless of their rotation. Both the QR code and KR code algorithms can interpret rectangular as well as round shapes. What needs to be maintained here is the proportions between the black and white sections located on one (horizontal or vertical) line: 1:1:3:1:1.
Between 2 markers located within an adequate distance of each other, we can fit 64 bits of data. The white fields within the code area stand for the 0's, and the black fields represent 1's: in a statistical code there's usually more 0's than 1's, so that means less ink is needed to print the codes rather than if it were the other way around.
The encoded data consists of:
- (red area) - 16 bits per type of code in order to determine whether we're looking at an issue, column splitter, row splitter or some other out of the tens of thousands of possibilities we might want to use in the future.
- (green area) - 32 bits per code value, so in the case of a card this stands for the issue ID. There's actually over... 4 billion combinations (4 294 967 296 to be precise) possible here, so it should be enough for a while. If a users project outgrows this volume (way to go!) we can easily increase the capacity.
- (yellow area) - The remaining 16 bits are used as a CRC checksum.
The force awakened
The application of the round markers for the location of the codes makes the currently used algorithm ten times faster than the old one.
The old version of the scanner was unable to deal with white boards and backgrounds - the new algorithm no longer has this problem; in fact it is even slightly quicker with white boards than cork ones, because the cork structure in the background feeds the algorithm with numerous false markers. Still, it's better to find and dismiss 1000 additional markers than miss a single genuine one. The image below illustrates the bogus cork markers as seen by the algorithm, prior to their verification:
Hint: in the Agile Cards URL you can actually add the following "scannerdebug=true" parameter in order to see the photo exactly the way as it is seen by the scanner.
The maximum number of cards which can be recognized in one photograph is limited only by the photo's resolution.
On a reasonable quality image the scanner would be able to recognize KR codes, whose markers measure at least 15 pixels in diameter (although 20 pixels would likely enable it to work even better), which means that if we're photographing a 150x100 cm board using an 8 megapixel camera, the smallest legible KR code marker would have a diameter of 7mm (slightly more than 1/4 inches) and the entire KR code would be roughly 45 mm long (slightly more than 1 3/4 inches).
On the image below the card measures 5x5 cm (almost precisely 2x2 inches), so a board this size could fit up to... 600 cards. This is already quite a few, but we have implemented the Agile Cards' algorithms in such a way that this is not a hard limit. It is possible to upload a single photo taken in panorama mode with potentially many thousands of pixels in width. It is also possible to make several snapshots of the physical boards in separate photos and upload them to Agile Cards in a sequence. So in reality there is almost no limit to the amount of cards scanned on a physical board at once.
And that's the story of KR codes so far. We continue to improve the algorithm so that it works flawlessly in even harsher conditions, stay tuned for updates.
We'd love for you to try Agile Cards for JIRA for free on the Atlassian Marketplace and let us know what you think about our idea. We genuinely appreciate good input!
If you have a need or proposal for a new feature just drop us an email at firstname.lastname@example.org - we really look to user feedback as one of the best sources for new feature and product ideas.