Thursday, September 26, 2013

Frances's Tracing Game v1.04: On Coordinate Transforms

As one bug dies, another is born. So it goes, so it goes. :)

As  I prepared to publish version 1.03 of Frances's Tracing Game, I took a glance at the statistics and suggestions from the Google Play Store and noticed that many newer Androids couldn't pick up the latest build because I had the minimum SDK version set to 1. I forked the project (Play Store lets you publish multiple binaries under the same app depending on the version of the client's phone), then in the fork I bumped the minimum up to SDK 4 and targeted SDK 11.

That introduced a new oddity: Apparently, my game had been running in a compatibility mode this entire time (due to its claim that it targeted SDK 1); as a result, the screen had been scaled automatically to fit the ancient Android form factor seen in the days of the Nexus 1. When I bumped to SDK4, the compatibility mode went away and my shapes were suddenly far too small to be traced by even clever fingers (screen resolution has improved a lot since the Nexus One days). The Android screen format rules have an awful lot of complexity to them, but to make a long story short: it is best to assume that your client's device could fit just about any rectangular form factor, much like we do with desktop PC programming.

Fortunately, this is an old problem with some old solutions. Many graphics libraries (such as OpenGL) provide a layer of transformations to make it easy to convert from one coordinate space to another. Android's graphics SDK is no exception; the Canvas object supports scaling and translation methods to tweak the underlying matrix that maps pixels in the canvas to pixels on the screen. I'd already used translation previously to center the image; now I just need to use scaling to balloon the image to fit the width of the screen.

Here's the basics of the tweaks I made; if you want to see the full code, it's hosted on GitHub.

Step 1: Tweak the scale

Tweaking the scale is extremely straightforward in Android; there's a pair of scale() methods that wrap the matrix multiplication logic for convenience (note: if you haven't done graphics programming, matrix algebra is basically the bread and butter of shifting coordinate spaces; Wikipedia can get you started on the concepts). I'm using this method, which includes the concept of a pivot point (the point around which the scaling should occur) to scale from the center of my image.

The only interesting part is determining how much to scale. I want to take up about 80% of the space, so I'm solving for S in the equations
final_image_width = 80% * screen_width
final_image_width = S * initial_image_width

This resolves to S = 80% * screen_width / initial_image_width, which I store and use as the scaling factor to rescale the canvas. Since the canvas itself is scaled, the image, line thickness I use for drawing, and pink tracing overlays are all correctly rendered without having to change the rest of the drawing logic.

Step 2: Unscale the touch

The only remaining issue is that the touch events we receive don't go through the rendering logic to be scaled. So for touch events we get from the screen, we need to reverse the scaling operation to get them back into the image coordinate space to determine if they were close to one of the tracing lines. I could have done this by grabbing the canvas's matrix with getMatrix() and inverting it (for a given transformation matrix, inverting the matrix gives you the reverse transformation). But I got a little bit fancy instead; the steps to reverse the scaling of the point (factoring in the pivot) are basically as follows:
  1. subtract the pivot coordinates from the point coordinates (this would translate a point on the pivot to (0,0), which is what you want because that point doesn't move under scaling).
  2. Multiply the point coordinates by 1/scale_factor.
  3. Add the pivot coordinates back to the point coordinates (reversing the translation).
It's mathematically simple enough that I think it's clearer to just represent it directly without the matrix (though just using the matrix inverse might very well have been less code!).

The Result

Image from the game: A smiling face, with the word "Smile" beneath it.
I am not unhappy. :)

I'm pretty happy with the result. Frances's game looks good on a 7-inch tablet and on a smartphone. I also added a text label for each picture, because she's getting older and is starting to read and write. I passed the labels through the canvas transformation, which leads to some odd scaling that's dependent upon the underlying size of the traced image; I might make some time to clean that up later. 

Feel free to download it to your own device if you'd like; it's free and will never include ads (because what possible use could ads be in a toddler's tracing game other than to junk-up the advertiser's signal with unintended clicks?).

I have no idea if this simple game will hold her interest much longer; it may soon be time to make her something new. And there's still the question of what to make for Cecilia, but there's a bit of time there; she's not very interested in tablets right now because she just realized that when she kicks her legs, her bounce-chair moves. I have to admit, that's pretty cool.