Home | History | Annotate | Download | only in orientationplot
      1 This directory contains a simple python script for visualizing
      2 the behavior of the WindowOrientationListener.
      3 
      4 
      5 PREREQUISITES
      6 -------------
      7 
      8 1. Python 2.6
      9 2. numpy
     10 3. matplotlib
     11 
     12 
     13 USAGE
     14 -----
     15 
     16 The tool works by scaping the debug log output from WindowOrientationListener
     17 for interesting data and then plotting it.
     18 
     19 1. Plug in the device.  Ensure that it is the only device plugged in
     20    since this script is of very little brain and will get confused otherwise.
     21 
     22 2. Enable the Window Orientation Listener debugging data log.
     23    adb shell setprop debug.orientation.log true
     24    adb shell stop
     25    adb shell start
     26 
     27 3. Run "orientationplot.py".
     28 
     29 
     30 WHAT IT ALL MEANS
     31 -----------------
     32 
     33 The tool displays several time series graphs that plot the output of the
     34 WindowOrientationListener.  Here you can see the raw accelerometer data,
     35 filtered accelerometer data, measured tilt and orientation angle, confidence
     36 intervals for the proposed orientation and accelerometer latency.
     37 
     38 Things to look for:
     39 
     40 1. Ensure the filtering is not too aggressive.  If the filter cut-off frequency is
     41    less than about 1Hz, then the filtered accelorometer data becomes too smooth
     42    and the latency for orientation detection goes up.  One way to observe this
     43    is by holding the device vertically in one orientation then sharply turning
     44    it 90 degrees to a different orientation.  Compared the rapid changes in the
     45    raw accelerometer data with the smoothed out filtered data.  If the filtering
     46    is too aggressive, the filter response may lag by hundreds of milliseconds.
     47 
     48 2. Ensure that there is an appropriate gap between adjacent orientation angles
     49    for hysteresis.  Try holding the device in one orientation and slowly turning
     50    it 90 degrees.  Note that the confidence intervals will all drop to 0 at some
     51    point in between the two orientations; that is the gap.  The gap should be
     52    observed between all adjacent pairs of orientations when turning the device
     53    in either direction.
     54 
     55    Next try holding the device in one orientation and rapidly turning it end
     56    over end to a midpoint about 45 degrees between two opposing orientations.
     57    There should be no gap observed initially.  The algorithm should pick one
     58    of the orientations and settle into it (since it is obviously quite
     59    different from the original orientation of the device).  However, once it
     60    settles, the confidence values should start trending to 0 again because
     61    the measured orientation angle is now within the gap between the new
     62    orientation and the adjacent orientation.
     63 
     64    In other words, the hysteresis gap applies only when the measured orientation
     65    angle (say, 45 degrees) is between the current orientation's ideal angle
     66    (say, 0 degrees) and an adjacent orientation's ideal angle (say, 90 degrees).
     67 
     68 3. Accelerometer jitter.  The accelerometer latency graph displays the interval
     69    between sensor events as reported by the SensorEvent.timestamp field.  It
     70    should be a fairly constant 60ms.  If the latency jumps around wildly or
     71    greatly exceeds 60ms then there is a problem with the accelerometer or the
     72    sensor manager.
     73 
     74 4. The orientation angle is not measured when the tilt is too close to 90 or -90
     75    degrees (refer to MAX_TILT constant).  Consequently, you should expect there
     76    to be no data.  Likewise, all dependent calculations are suppressed in this case
     77    so there will be no orientation proposal either.
     78 
     79 5. Each orientation has its own bound on allowable tilt angles.  It's a good idea to
     80    verify that these limits are being enforced by gradually varying the tilt of
     81    the device until it is inside/outside the limit for each orientation.
     82 
     83 6. Orientation changes should be significantly harder when the device is held
     84    overhead.  People reading on tablets in bed often have their head turned
     85    a little to the side, or they hold the device loosely so its orientation
     86    can be a bit unusual.  The tilt is a good indicator of whether the device is
     87    overhead.
     88