Velocity Tracker II: The Revenge of Velocity Tracker

Bug: 5265529

Rewrote the velocity tracker to fit a polynomial curve
to pointer movements using least squares linear regression.
The velocity is simply the first derivative of this polynomial.

Clients can also obtain an Estimator that describes the
complete terms of the estimating polynomial including
the coefficient of determination which provides a measure
of the quality of the fit (confidence).

Enhanced PointerLocation to display the movement curve predicted
by the estimator in addition to the velocity vector.

By default, the algorithm computes a 2nd degree (quadratic)
polynomial based on a 100ms recent history horizon.

Change-Id: Id377bef44117fce68fee2c41f90134ce3224d3a1

Author: Jeff Brown

core/java/android/view/VelocityTracker.java

@@ -59,6 +59,8 @@ public void onReleased(VelocityTracker element) {
     private static native void nativeComputeCurrentVelocity(int ptr, int units, float maxVelocity);
     private static native float nativeGetXVelocity(int ptr, int id);
     private static native float nativeGetYVelocity(int ptr, int id);
+    private static native boolean nativeGetEstimator(int ptr, int id,
+            int degree, int horizonMillis, Estimator outEstimator);
 
     /**
      * Retrieve a new VelocityTracker object to watch the velocity of a
@@ -215,4 +217,94 @@ public float getXVelocity(int id) {
     public float getYVelocity(int id) {
         return nativeGetYVelocity(mPtr, id);
     }
+
+    /**
+     * Get an estimator for the movements of a pointer using past movements of the
+     * pointer to predict future movements.
+     *
+     * It is not necessary to call {@link #computeCurrentVelocity(int)} before calling
+     * this method.
+     *
+     * @param id Which pointer's velocity to return.
+     * @param degree The desired polynomial degree.  The actual estimator may have
+     * a lower degree than what is requested here.  If -1, uses the default degree.
+     * @param horizonMillis The maximum age of the oldest sample to consider, in milliseconds.
+     * If -1, uses the default horizon.
+     * @param outEstimator The estimator to populate.
+     * @return True if an estimator was obtained, false if there is no information
+     * available about the pointer.
+     *
+     * @hide For internal use only.  Not a final API.
+     */
+    public boolean getEstimator(int id, int degree, int horizonMillis, Estimator outEstimator) {
+        if (outEstimator == null) {
+            throw new IllegalArgumentException("outEstimator must not be null");
+        }
+        return nativeGetEstimator(mPtr, id, degree, horizonMillis, outEstimator);
+    }
+
+    /**
+     * An estimator for the movements of a pointer based on a polynomial model.
+     *
+     * The last recorded position of the pointer is at time zero seconds.
+     * Past estimated positions are at negative times and future estimated positions
+     * are at positive times.
+     *
+     * First coefficient is position (in pixels), second is velocity (in pixels per second),
+     * third is acceleration (in pixels per second squared).
+     *
+     * @hide For internal use only.  Not a final API.
+     */
+    public static final class Estimator {
+        // Must match VelocityTracker::Estimator::MAX_DEGREE
+        private static final int MAX_DEGREE = 2;
+
+        /**
+         * Polynomial coefficients describing motion in X.
+         */
+        public final float[] xCoeff = new float[MAX_DEGREE + 1];
+
+        /**
+         * Polynomial coefficients describing motion in Y.
+         */
+        public final float[] yCoeff = new float[MAX_DEGREE + 1];
+
+        /**
+         * Polynomial degree, or zero if only position information is available.
+         */
+        public int degree;
+
+        /**
+         * Confidence (coefficient of determination), between 0 (no fit) and 1 (perfect fit).
+         */
+        public float confidence;
+
+        /**
+         * Gets an estimate of the X position of the pointer at the specified time point.
+         * @param time The time point in seconds, 0 is the last recorded time.
+         * @return The estimated X coordinate.
+         */
+        public float estimateX(float time) {
+            return estimate(time, xCoeff);
+        }
+
+        /**
+         * Gets an estimate of the Y position of the pointer at the specified time point.
+         * @param time The time point in seconds, 0 is the last recorded time.
+         * @return The estimated Y coordinate.
+         */
+        public float estimateY(float time) {
+            return estimate(time, yCoeff);
+        }
+
+        private float estimate(float time, float[] c) {
+            float a = 0;
+            float scale = 1;
+            for (int i = 0; i <= degree; i++) {
+                a += c[i] * scale;
+                scale *= time;
+            }
+            return a;
+        }
+    }
 }

core/java/com/android/internal/widget/PointerLocationView.java

@@ -51,7 +51,10 @@ public static class PointerState {
         // Most recent velocity.
         private float mXVelocity;
         private float mYVelocity;
-        
+
+        // Position estimator.
+        private VelocityTracker.Estimator mEstimator = new VelocityTracker.Estimator();
+
         public void clearTrace() {
             mTraceCount = 0;
         }
@@ -75,6 +78,10 @@ public void addTrace(float x, float y) {
         }
     }
 
+    private final int ESTIMATE_PAST_POINTS = 4;
+    private final int ESTIMATE_FUTURE_POINTS = 2;
+    private final float ESTIMATE_INTERVAL = 0.02f;
+
     private final ViewConfiguration mVC;
     private final Paint mTextPaint;
     private final Paint mTextBackgroundPaint;
@@ -278,8 +285,20 @@ protected void onDraw(Canvas canvas) {
                     haveLast = true;
                 }
 
-                // Draw velocity vector.
                 if (drawn) {
+                    // Draw movement estimate curve.
+                    mPaint.setARGB(128, 128, 0, 128);
+                    float lx = ps.mEstimator.estimateX(-ESTIMATE_PAST_POINTS * ESTIMATE_INTERVAL);
+                    float ly = ps.mEstimator.estimateY(-ESTIMATE_PAST_POINTS * ESTIMATE_INTERVAL);
+                    for (int i = -ESTIMATE_PAST_POINTS + 1; i <= ESTIMATE_FUTURE_POINTS; i++) {
+                        float x = ps.mEstimator.estimateX(i * ESTIMATE_INTERVAL);
+                        float y = ps.mEstimator.estimateY(i * ESTIMATE_INTERVAL);
+                        canvas.drawLine(lx, ly, x, y, mPaint);
+                        lx = x;
+                        ly = y;
+                    }
+
+                    // Draw velocity vector.
                     mPaint.setARGB(255, 255, 64, 128);
                     float xVel = ps.mXVelocity * (1000 / 60);
                     float yVel = ps.mYVelocity * (1000 / 60);
@@ -517,6 +536,7 @@ public void addPointerEvent(MotionEvent event) {
                     ps.addTrace(coords.x, coords.y);
                     ps.mXVelocity = mVelocity.getXVelocity(id);
                     ps.mYVelocity = mVelocity.getYVelocity(id);
+                    mVelocity.getEstimator(id, -1, -1, ps.mEstimator);
                     ps.mToolType = event.getToolType(i);
                 }
             }

core/jni/android_view_VelocityTracker.cpp

@@ -29,6 +29,14 @@ namespace android {
 // Special constant to request the velocity of the active pointer.
 static const int ACTIVE_POINTER_ID = -1;
 
+static struct {
+    jfieldID xCoeff;
+    jfieldID yCoeff;
+    jfieldID degree;
+    jfieldID confidence;
+} gEstimatorClassInfo;
+
+
 // --- VelocityTrackerState ---
 
 class VelocityTrackerState {
@@ -39,6 +47,8 @@ class VelocityTrackerState {
     void addMovement(const MotionEvent* event);
     void computeCurrentVelocity(int32_t units, float maxVelocity);
     void getVelocity(int32_t id, float* outVx, float* outVy);
+    bool getEstimator(int32_t id, uint32_t degree, nsecs_t horizon,
+            VelocityTracker::Estimator* outEstimator);
 
 private:
     struct Velocity {
@@ -118,6 +128,11 @@ void VelocityTrackerState::getVelocity(int32_t id, float* outVx, float* outVy) {
     }
 }
 
+bool VelocityTrackerState::getEstimator(int32_t id, uint32_t degree, nsecs_t horizon,
+        VelocityTracker::Estimator* outEstimator) {
+    return mVelocityTracker.getEstimator(id, degree, horizon, outEstimator);
+}
+
 
 // --- JNI Methods ---
 
@@ -169,6 +184,30 @@ static jfloat android_view_VelocityTracker_nativeGetYVelocity(JNIEnv* env, jclas
     return vy;
 }
 
+static jboolean android_view_VelocityTracker_nativeGetEstimator(JNIEnv* env, jclass clazz,
+        jint ptr, jint id, jint degree, jint horizonMillis, jobject outEstimatorObj) {
+    VelocityTrackerState* state = reinterpret_cast<VelocityTrackerState*>(ptr);
+    VelocityTracker::Estimator estimator;
+    bool result = state->getEstimator(id,
+            degree < 0 ? VelocityTracker::DEFAULT_DEGREE : uint32_t(degree),
+            horizonMillis < 0 ? VelocityTracker::DEFAULT_HORIZON :
+                    nsecs_t(horizonMillis) * 1000000L,
+            &estimator);
+
+    jfloatArray xCoeffObj = jfloatArray(env->GetObjectField(outEstimatorObj,
+            gEstimatorClassInfo.xCoeff));
+    jfloatArray yCoeffObj = jfloatArray(env->GetObjectField(outEstimatorObj,
+            gEstimatorClassInfo.yCoeff));
+
+    env->SetFloatArrayRegion(xCoeffObj, 0, VelocityTracker::Estimator::MAX_DEGREE + 1,
+            estimator.xCoeff);
+    env->SetFloatArrayRegion(yCoeffObj, 0, VelocityTracker::Estimator::MAX_DEGREE + 1,
+            estimator.yCoeff);
+    env->SetIntField(outEstimatorObj, gEstimatorClassInfo.degree, estimator.degree);
+    env->SetFloatField(outEstimatorObj, gEstimatorClassInfo.confidence, estimator.confidence);
+    return result;
+}
+
 
 // --- JNI Registration ---
 
@@ -195,12 +234,35 @@ static JNINativeMethod gVelocityTrackerMethods[] = {
     { "nativeGetYVelocity",
             "(II)F",
             (void*)android_view_VelocityTracker_nativeGetYVelocity },
+    { "nativeGetEstimator",
+            "(IIIILandroid/view/VelocityTracker$Estimator;)Z",
+            (void*)android_view_VelocityTracker_nativeGetEstimator },
 };
 
+#define FIND_CLASS(var, className) \
+        var = env->FindClass(className); \
+        LOG_FATAL_IF(! var, "Unable to find class " className);
+
+#define GET_FIELD_ID(var, clazz, fieldName, fieldDescriptor) \
+        var = env->GetFieldID(clazz, fieldName, fieldDescriptor); \
+        LOG_FATAL_IF(! var, "Unable to find field " fieldName);
+
 int register_android_view_VelocityTracker(JNIEnv* env) {
     int res = jniRegisterNativeMethods(env, "android/view/VelocityTracker",
             gVelocityTrackerMethods, NELEM(gVelocityTrackerMethods));
     LOG_FATAL_IF(res < 0, "Unable to register native methods.");
+
+    jclass clazz;
+    FIND_CLASS(clazz, "android/view/VelocityTracker$Estimator");
+
+    GET_FIELD_ID(gEstimatorClassInfo.xCoeff, clazz,
+            "xCoeff", "[F");
+    GET_FIELD_ID(gEstimatorClassInfo.yCoeff, clazz,
+            "yCoeff", "[F");
+    GET_FIELD_ID(gEstimatorClassInfo.degree, clazz,
+            "degree", "I");
+    GET_FIELD_ID(gEstimatorClassInfo.confidence, clazz,
+            "confidence", "F");
     return 0;
 }
 

include/ui/Input.h

@@ -620,10 +620,41 @@ class PreallocatedInputEventFactory : public InputEventFactoryInterface {
  */
 class VelocityTracker {
 public:
+    // Default polynomial degree.  (used by getVelocity)
+    static const uint32_t DEFAULT_DEGREE = 2;
+
+    // Default sample horizon.  (used by getVelocity)
+    // We don't use too much history by default since we want to react to quick
+    // changes in direction.
+    static const nsecs_t DEFAULT_HORIZON = 100 * 1000000; // 100 ms
+
     struct Position {
         float x, y;
     };
 
+    struct Estimator {
+        static const size_t MAX_DEGREE = 2;
+
+        // Polynomial coefficients describing motion in X and Y.
+        float xCoeff[MAX_DEGREE + 1], yCoeff[MAX_DEGREE + 1];
+
+        // Polynomial degree (number of coefficients), or zero if no information is
+        // available.
+        uint32_t degree;
+
+        // Confidence (coefficient of determination), between 0 (no fit) and 1 (perfect fit).
+        float confidence;
+
+        inline void clear() {
+            degree = 0;
+            confidence = 0;
+            for (size_t i = 0; i <= MAX_DEGREE; i++) {
+                xCoeff[i] = 0;
+                yCoeff[i] = 0;
+            }
+        }
+    };
+
     VelocityTracker();
 
     // Resets the velocity tracker state.
@@ -645,10 +676,16 @@ class VelocityTracker {
     void addMovement(const MotionEvent* event);
 
     // Gets the velocity of the specified pointer id in position units per second.
-    // Returns false and sets the velocity components to zero if there is no movement
-    // information for the pointer.
+    // Returns false and sets the velocity components to zero if there is
+    // insufficient movement information for the pointer.
     bool getVelocity(uint32_t id, float* outVx, float* outVy) const;
 
+    // Gets a quadratic estimator for the movements of the specified pointer id.
+    // Returns false and clears the estimator if there is no information available
+    // about the pointer.
+    bool getEstimator(uint32_t id, uint32_t degree, nsecs_t horizon,
+            Estimator* outEstimator) const;
+
     // Gets the active pointer id, or -1 if none.
     inline int32_t getActivePointerId() const { return mActivePointerId; }
 
@@ -657,13 +694,7 @@ class VelocityTracker {
 
 private:
     // Number of samples to keep.
-    static const uint32_t HISTORY_SIZE = 10;
-
-    // Oldest sample to consider when calculating the velocity.
-    static const nsecs_t MAX_AGE = 100 * 1000000; // 100 ms
-
-    // The minimum duration between samples when estimating velocity.
-    static const nsecs_t MIN_DURATION = 5 * 1000000; // 5 ms
+    static const uint32_t HISTORY_SIZE = 20;
 
     struct Movement {
         nsecs_t eventTime;