We’ve heard a few people struggling with map building, so thought I’d provide some more hints here. We’ll look to incorporate these into the setup guide soon, and try and film a video too as it’s much easier in practice when you get the hang of it than it is to describe!
There are two things needed for us to build a map:
- Working out the orientation of each pointcode marker with respect to gravity (ie is it horizontal, vertical, etc)
- Sufficient views of multiple pointcodes so we can work out all their relative positions
With some practice usually you can achieve both of these requirements in a single motion, but if you’re struggling it’s helpful to deal with them separately.
Pointcode Orientation
Determining orientation is independent for each pointcode, and that’s the part responsible for making pointcodes go from red to their “active” colour (the colour of the set that you have paired with the app). So if you’re struggling you can move in closer to each individual pointcode and deal with them separately.
To determine the orientation of each pointcode, we need to see it from different angles with respect to gravity. We use a tracking approach for this determination, so you need to move slowly and smoothly around the marker. For horizontal pointcodes imagine a bike wheel centred on the marker and sticking up vertically. An ideal motion is to attach the phone to the tire of this imaginary wheel and slowly rotate the wheel around. In that way you view the marker from different angles but with it always in the centre of the camera image.
Once you get the hang of it you can often do multiple markers in one go and you won’t need to move very far to activate each marker. Just remember it’s that angular variation with respect to gravity that is all-important.
We’d recommend sticking with all-horizontal maps for now anyway, but if you do have some vertical pointcodes, the angular motion needed involves rotating around the code from below it to above it - other directions (spinning the phone landscape/portrait or rotating around left to right) don’t really help as they don’t provide any more information of the orientation of the code with respect to gravity.
Obtaining Views of Multiple Pointcodes
The second requirement for map building is to see sufficient views with multiple codes in them. That allows us to work out the relative positions of all of the codes so we can combine them into a single map. This phase is usually quite straightforward.
One thing to note is that you may sometimes see a yellow ring around a pointcode on-screen even when its orientation has been determined. This will happen if you’re viewing it straight-on in the centre of the screen, for example, and indicates that this view of the code will not be used in map building [technically because the direction of gravity from the phone’s accelerometer is not sufficient to disambiguate the full 3D orientation of the code in this view]. So we’ll need views that contain multiple codes without yellow rings so that we can work out all their relative positions and orientations.
In practice with horizontal maps this is usually straightforward; you can often stand off to one side of the map and view all the codes when holding the phone at a 45-degree-ish angle - you can probably fit all of the codes in view at once, and none of them are likely to have the yellow ring. It’s still wise to move around a little to obtain multiple views from a few different viewpoints in this way (which will lead to a more accurate map) but generally it should be pretty easy.
Map Origin and Coordinates
This section isn’t required to successfully build maps, but might be of interest to some users wondering how the coordinate system is determined for the world map.
The current app build will identify the horizontal plane with the most pointcodes on it as the “primary” plane. In stereo we’ll render the camera image onto this plane. With a horizontal primary plane, the Z axis points upwards towards the sky.
To determine the origin, and the x and y axis orientations, we surround the pointcodes in a rectangular bounding box that is as small as possible. For this reason we recommend the outermost codes are in a roughly rectangular layout as then the x and y axes will be in a predictable orientation (parallel with the edges of that rectangle). The origin of the world coordinate system is in the centre of that bounding rectangle. That’s where the cube pops out of when you complete the map building flow.
The x and y axis are assigned based on the location of the device when the user taps the screen to build the map. Whichever side of the bounding rectangle the device is on can be thought of as the “front” of the map. Viewed from the front, the x axis goes from left-to-right, and the y axis is positive away from the user.
One interesting feature of this current scheme for assigning the “primary” plane means that if you want to have a table-top map but want to support viewing content from relatively edge-on to the table, you can lay out some codes on the table itself (I usually go for an outer rectangle with one or two extra codes in the middle for table-top setups), but you can also stick some others at different angles (maybe on a 45 degree stand on the table or something) so they can be seen when viewing the table more edge-on.
When building a map we’ll still identify the primary plane and hence the overall world coordinate system in the same way, using just the codes on the surface of the table. That will also determine the world geometry we use for rendering the camera in stereo. However the other codes that are not on the table surface will also be part of the map and can be used for tracking when the ones on the table surface itself can’t be tracked due to the viewing angle.