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