Token Construction Validation

[Peter Law]

Hi,

This year's tokens are somewhat more complicated than in the past,
given that they not only have a right-way-up, but also fixed marker
orientations. Inspired by some semi-automated checking which happened
in SR2014, when the "Slots" game's markers had a right-way-up, I
thought we should have something for this year as well [#3165].

As a result I recently investigated creating a solution based on the
vision system as exposed to the robots. The intent of this was
two-fold: it would create a useful validation mechanism for anyone
creating tokens and it would validate that the vision system returned
the information we thought it should.

I was primarily expecting that the latter would be trivial, and that
as a tertiary benefit I'd be better placed to help improve the vision
docs. While this did happen (there are a number of vision docs patches
awaiting review [1], it turns out that there's a bug [#3176] in the
data returned.

I don't think that we should ship a fix for the bug this year, since
it would silently break the code of anyone using that part of the API.
However anyone wanting to use the token checker needs to be aware of
it since the checker relies on it having been fixed, and will silently
produce confusing results if run without the fix.

While building the tool I also found that libkoki sometimes claims to
see arena dev marker 10, though investigation showed [#3177] that this
is unlikely to be an issue outside of my particular setup. If anyone
else hits that please do comment on the trac ticket, ideally with some
reproduce images.

The checker itself lives in the arena.git repo, under
comp16/token-check [2]. There's a readme present which contains brief
details for setting up and using the tool. My expectation is that
those using the tool will have some experience using libkoki and I
would suggesting having the 'realtime_gl' example on-hand as a further
diagnostic tool when validating tokens.

If you've built, or are planning to build, a token and would like to
check it then please do try out the tool. Feedback on what works or
doesn't, particularly around the handling of invalid tokens, would be
most welcome.

Thanks,
Peter

#3165: https://www.studentrobotics.org/trac/ticket/3165
#3176: https://www.studentrobotics.org/trac/ticket/3176
#3177: https://www.studentrobotics.org/trac/ticket/3177
[1] https://www.studentrobotics.org/gerrit/#/c/2684/ and parents
[2] https://www.studentrobotics.org/cgit/arena.git/tree/comp16/token-check