Merge pull request #65 from JacobPalecki/Directional

Directionality Features + Graph Fidelity

Author: JacobPalecki

common/accel-base.hpp

@@ -17,6 +17,11 @@ namespace rawaccel {
         double speed_cap = 0;
     };
 
+    struct domain_args {
+        vec2d domain_weights = { 1, 1 };
+        double lp_norm = 2;
+    };
+
     template <typename Func>
     struct accel_val_base {
         bool legacy_offset = false;

common/accel-motivity.hpp

@@ -55,28 +55,40 @@ namespace rawaccel {
 		inline void fill(si_pair* lookup) const
 		{
 			double lookup_speed = 0;
+			double integral_interval = 0;
 			double gain_integral_speed = 0;
+			double gain_integral_speed_prev = 0;
 			double gain = 0;
 			double intercept = 0;
 			double output = 0;
+			double output_prev = 0;
 			double x = -2;
 
+			double logarithm_interval = 0.01;
+			double integral_intervals_per_speed = 10;
+			double integral_interval_factor = pow(10, logarithm_interval) / integral_intervals_per_speed;
+
 			lookup[0] = {};
 
 			for (size_t i = 1; i < LUT_SIZE; i++)
 			{
-				x += 0.01;
+				x += logarithm_interval;
 
+				// Each lookup speed will be 10^0.01 = 2.33% higher than the previous
+				// To get 10 integral intervals per speed, set interval to 0.233%
 				lookup_speed = pow(10, x);
+				integral_interval = lookup_speed * integral_interval_factor;
 
 				while (gain_integral_speed < lookup_speed)
 				{
-					gain_integral_speed += 0.001;
+					output_prev = output;
+					gain_integral_speed_prev = gain_integral_speed;
+					gain_integral_speed += integral_interval;
 					gain = operator()(gain_integral_speed);
-					output += gain * 0.001;
+					output += gain * integral_interval;
 				}
 
-				intercept = output - gain * lookup_speed;
+				intercept = output_prev - gain_integral_speed_prev * gain;
 
 				lookup[i] = { gain, intercept };
 			}

common/rawaccel-settings.h

@@ -24,6 +24,8 @@ namespace rawaccel {
         vec2<accel_args> argsv;
         vec2d sens = { 1, 1 };
         vec2d dir_multipliers = {};
+        domain_args domain_args = {};
+        vec2d range_weights = { 1, 1 };
         milliseconds time_min = DEFAULT_TIME_MIN;
         wchar_t device_id[MAX_DEV_ID_LEN] = {0};
     };

common/rawaccel-version.h

@@ -1,7 +1,7 @@
 #pragma once
 
 #define RA_VER_MAJOR 1
-#define RA_VER_MINOR 3
+#define RA_VER_MINOR 4
 #define RA_VER_PATCH 0
 
 #define RA_MIN_OS "Win7"
@@ -20,7 +20,7 @@ namespace rawaccel {
 	};
 
 #ifndef _KERNEL_MODE
-	inline constexpr version_t min_driver_version = { 1, 3, 0 };
+	inline constexpr version_t min_driver_version = { 1, 4, 0 };
 #endif
 
 }

common/rawaccel.hpp

@@ -225,12 +225,90 @@ namespace rawaccel {
         accelerator() = default;
     };
 
+    struct weighted_distance {
+        double p = 2.0;
+        double p_inverse = 0.5;
+        bool lp_norm_infinity = false;
+        double sigma_x = 1.0;
+        double sigma_y = 1.0;
+
+        weighted_distance(domain_args args)
+        {
+            sigma_x = args.domain_weights.x;
+            sigma_y = args.domain_weights.y;
+            if (args.lp_norm <= 0)
+            {
+                lp_norm_infinity = true;
+                p = 0.0;
+                p_inverse = 0.0;
+            }
+            else
+            {
+                lp_norm_infinity = false;
+                p = args.lp_norm;
+                p_inverse = 1 / args.lp_norm;
+            }
+        }
+
+        double calculate(double x, double y)
+        {
+			double abs_x = fabs(x);
+			double abs_y = fabs(y);
+
+            if (lp_norm_infinity)
+            {
+                return abs_x > abs_y ? abs_x : abs_y;
+            }
+
+            double x_scaled = abs_x * sigma_x;
+            double y_scaled = abs_y * sigma_y;
+            return pow(pow(x_scaled, p) + pow(y_scaled, p), p_inverse);
+        }
+
+        weighted_distance() = default;
+    };
+
+    struct direction_weight {
+        double diff = 0.0;
+        double start = 1.0;
+        bool should_apply = false;
+
+        direction_weight(vec2d thetas)
+        {
+            diff = thetas.y - thetas.x;
+            start = thetas.x;
+
+            if (diff != 0)
+            {
+                should_apply = true;
+            }
+            else
+            {
+                should_apply = false;
+            }
+        }
+
+        inline double atan_scale(double x, double y)
+        {
+            return M_2_PI * atan2(fabs(y), fabs(x));
+        }
+
+        double apply(double x, double y)
+        {
+            return atan_scale(x, y) * diff + start;
+        }
+
+        direction_weight() = default;
+    };
+
     /// <summary> Struct to hold variables and methods for modifying mouse input </summary>
     struct mouse_modifier {
         bool apply_rotate = false;
         bool apply_accel = false;
         bool combine_magnitudes = true;
         rotator rotate;
+        weighted_distance distance;
+        direction_weight directional;
         vec2<accelerator> accels;
         vec2d sensitivity = { 1, 1 };
         vec2d directional_multipliers = {};
@@ -257,6 +335,10 @@ namespace rawaccel {
 
             accels.x = accelerator(args.argsv.x, args.modes.x, luts.x);
             accels.y = accelerator(args.argsv.y, args.modes.y, luts.y);
+
+            distance = weighted_distance(args.domain_args);
+            directional = direction_weight(args.range_weights);
+
             apply_accel = true;
         }
 
@@ -276,9 +358,15 @@ namespace rawaccel {
                 milliseconds time = time_supp();
 
                 if (combine_magnitudes) {
-                    double mag = sqrtsd(movement.x * movement.x + movement.y * movement.y);
+                    double mag = distance.calculate(movement.x, movement.y);
                     double speed = mag / time;
                     double scale = accels.x.apply(speed);
+
+                    if (directional.should_apply)
+                    {
+                        scale = (scale - 1)*directional.apply(movement.x, movement.y) + 1;
+                    }
+
                     movement.x *= scale;
                     movement.y *= scale;
                 }

doc/Guide.md

@@ -19,9 +19,9 @@ Visit the [Releases page](https://github.com/a1xd/rawaccel/releases) and navigat
 The Raw Accel driver and GUI's workings and exposed parameters are based on our understanding of mouse acceleration. Our understanding includes the concepts of "gain", "whole vs by component", and "anisotropy." For clarity, we will outline this understanding here. Those uninterested can skip to Features below.
 
 ### Measurements from Input Speed
-Raw Accel, like any mouse modification program, works by acting on a passed-in (x,y) input in order to pass back out an (x,y) output. The GUI program creates charts by feeding a set of (x,y) inputs to the driver code to receive a set of (x,y) outputs. The following measurements, available as charts in Raw Accel, are then found from the outputs:
+Raw Accel, like any mouse modification program, works by acting on a passed-in (x,y) input in order to pass back out an (x,y) output. The GUI program creates charts by feeding a set of (x,y) inputs and times to the driver code to receive a set of (x,y) outputs. The following measurements, available as charts in Raw Accel, are then found from the outputs:
 
-- **Sensitivity**: The ratio of the output speed to the input speed. The "sensitivity" parameter in the program is a multiplier used on the post-calculation output vector.
+- **Sensitivity**: The ratio of the output speed to the input speed. The "sensitivity multiplier" parameter in the program is a multiplier used on the post-calculation output vector.
 - **(Output) Velocity**: The speed of the final output vector. The output vs input velocity curve is perhaps the most important relationship in a particular setup because it directly describes the output for any given input. (We use "speed" and "velocity" interchangeably, and are aware of the difference elsewhere.)
 - **Gain**: The slope of the output vs input velocity curve. It answers the question: "if I move my hand a little faster, how much faster will my cursor move?" The relationship between gain and sensitivity is that if gain is continuous, so is sensitivity. The reverse is not necessarily true, so keeping the gain "nice" ensures "nice" sensitivity but not vice versa.
 - For the mathematically inclined: for input speed "v" and Output Velocity f(v), Sensitivity is f(v)/v and Gain is f'(v) = d/dv(f(v)).
@@ -40,17 +40,44 @@ Then our input speed is sqrt(30^2 + 40^2) = 50 counts/ms. Our accelerated sensit
 ![SensVelocityGainExample](images/accel_readme_example.png)
 
 ### Horizontal and Vertical
-If you wish, horizontal and vertical components of a mouse movement can be treated completely separately in Raw Accel. In the above example, they are not treated separately; rather they are "combined" by using the magnitude if the input vector: *sqrt(30^2 + 40^2) = 50 counts/ms*. This is called "Whole" application because the whole speed of the input is used. Application styles include:
+Due to the mechanics of holding a mouse on a desk, users generally move their mouses horizontally (left and right) differently than they move them vertically (forward and back), with more freedom for the wrist and\or arm to move the mouse horizontally than vertically. A user may then desire for various aspects of their output to change based on the direction of their input. For settings which allow this we have co-opted the term "anisotropy", which is "the property of a material which allows it to change or assume different properties in different directions."
 
-- Whole: magnitude of vector is input to sensitivity calculation, and applied to whole vector, as in example above.
-    - (out_x, out_y) = (in_x\*sens_x, in_y\*sens_y) \* f(sqrt(in_x^2 + in_y^2)), where f(v) is our sensitvity function
-    - Separate horizontal and vertical sensitivites still feel great in this mode.
-- By Component: The horizontal components are separated and each is given as input to the sensitivity calculation to multiplied by itself before being recombined at output.
+In the above "example" section, the x and y inputs are not treated separately; rather they are "combined" by using the magnitude if the input vector: *sqrt(30^2 + 40^2) = 50 counts/ms*. This is called "Whole" application because the whole speed of the input is used and the result is applied to the whole vector. Application styles include:
+
+#### ***Whole***
+In this case, the magnitude of the input vector is input to sensitivity calculation, and applied to whole vector, as in example above.
+    - (out_x, out_y) = (in_x\*sens_x, in_y\*sens_y) \* f(sqrt(in_x^2 + in_y^2)), where f(v) is our sensitivity function
+
+Separate horizontal and vertical sensitivites still feel great in this mode. (For the mathematically inclined, that's because differing horizontal and vertical sensitivities create a vector field without curl or other oddities.)
+
+There are anisotropic settings for whole mode.  
+- **Range**. This scales the range of the sensitivity curve around 1 for the horizontal or vertical direction.  
+    - If a given curve varies from 1 to 2 sensitivity, then a range_y of 0.5 would mean that vertical movements vary from 1 to 1.5 sensitivity instead.  
+- **Domain**. This scales the domain of curve around 0 for the horizontal or vertical direction.  
+    - If a given curve has an offset at 5 count/ms and a cap that is hit at 15 counts/ms, then a domain_y of 2 would mean that vertical movements hit the offset at 2.5 counts/ms and the cap at 7.5 counts/ms instead.  
+- **Lp Norm**. The distance calculation can be generalized to ((in_x)^p + (in_y)^p)^(1/p)), bringing the calculation into [Lp space](https://en.wikipedia.org/wiki/Lp_space).  
+    - p = 2 is then the "real world" value, yielding the pythagorean theorem as the distance calculation.  
+    - Increasing p makes distances for diagonal movements (where in_x and in_y are close) smaller, and increases the dominance of the larger of the two in determining the distance.  
+    - We recommend almost everyone leave this at 2.  
+
+![AnisotropyExample](images/anisotropy_example.png)
+
+With all anisotropic settings considered, the full formula looks like:  
+- (out_x, out_y) = (in_x\*sens_x, in_y\*sens_y) \* ((f(((domain_x\*in_x)^p + (domain_y\*in_y)^p)^(1/p)) - 1) \* ((2 / Pi) \* arctan(abs(in_y/in_x)) \* (range_y - range_x) + range_x) + 1, where f(v) is our sensitivity function
+
+This can be more easily understood as  
+- (out_x, out_y) = (in_x\*sens_x, in_y\*sens_y) \* ((f( domain-weighted lp-space speed) - 1) \* (directional weight) + 1), where f(v) is our sensitivity function
+
+This formula gaurantees the smooth transition from the horizontal to vertical curve and vice versa as the user moves their hand diagonally.
+
+#### ***By Component***  
+In this case, the horizontal components are separated and each is given as input to the sensitivity calculation to multiplied by itself before being recombined at output.
     - (out_x, out_y) = (in_x \* f(in_x) \* sens_x, in_y \* f(in_y) \* sens_y))
-- Anisotropy: This is a sub-mode of By Component in which the x and y can have separate sensitivity curves.
-    - (out_x, out_y) = (in_x \* f(in_x) \* sens_x, in_y \* g(in_y) \* sens_y)) where g(v) is some other sensitivity function.
+    - You can also do: (out_x, out_y) = (in_x \* f(in_x) \* sens_x, in_y \* g(in_y) \* sens_y)) where g(v) is some other sensitivity function.
+
+All anisotropic effects for By Component mode can be achieved by setting different x and y curves.  
 
-The authors of this program feel that Whole is the best style for most users, but that users who play games which have very separate horizontal and vertical actions to manage (such as tracking an enemy and controlling recoil) might benefit from trying By Component or Anisotropy.
+The authors of this program feel that Whole is the best style for most users, but that users who play games which have very separate horizontal and vertical actions to manage (such as tracking an enemy and controlling recoil) might benefit from trying By Component. By Component may seem more flexible, but it is precisely the restrictions imposed by Whole (no curl) that make it smoother.
 
 
 ## Features
@@ -66,14 +93,14 @@ Our acceleration functions generally have sensitivity functions that start at 1
 
 Weight is primarily a quick and dirty way to test a new curve. It also can be given a negative value to allow negative acceleration. Most acceleration styles could just change the parameters to have the same affect as setting a weight. Some curves, like the logarithm style, can achieve a greater range of shapes by changing weight.
 
-### By Component & Anisotropy
-See "Horizontal and Vertical" in the philosophy section to understand what these do.
+### Anisotropy
+See "Horizontal and Vertical" in the philosophy section to understand what these options do.
 
 ### Last Mouse Move
 The Raw Accel GUI reads the output of the raw input stream, and thus the output of the Raw Accel Driver, and displays on the graphs red points corresponding to the last mouse movements. These calulations should be fast and your graph responsive, but it comes at the cost of higher CPU usage due to needing to refresh the graph often. This feature can be turned off in the "Charts" menu.
 
 ### Scale by DPI and Poll Rate
-This option does not scale your acceleration curve in any way. Rather, it scales the set of points used to graph your curve, and shows you a window of input speed relevant for your chosen DPI and Poll Rate. The poll rate is also used to determine the Last Mouse Move points and therefore should be set for accuracy in that measurement.
+This option does not scale your acceleration curve in any way. Rather, DPI scales the set of points used to graph your curve, and shows you a window of input speed relevant for your chosen DPI. The poll rate is used as a safeguard for the Last Mouse Move points and therefore should be set for accuracy in that measurement.
 
 ## Acceleration Styles
 The examples of various types below show some typical settings, without a cap or offset, for a mouse at 1200 DPI and 1000 hz.

doc/images/anisotropy_example.png

@@ -14,13 +14,10 @@ public static class Constants
         public const int DefaultPollRate = 1000;
 
         /// <summary> Resolution of chart calulation. </summary>
-        public const int Resolution = 100;
+        public const int Resolution = 500;
 
         /// <summary> Multiplied by DPI over poll rate to find rough max expected velocity. </summary>
-        public const double MaxMultiplier = 85;
-
-        /// <summary> Ratio of max (X, Y) used in "by component" calulations to those used in "whole vector" calculations. </summary>
-        public const double XYToCombinedRatio = 1.4;
+        public const double MaxMultiplier = .05;
 
         /// <summary> Separation between X and Y active value labels, in pixels. </summary>
         public const int ActiveLabelXYSeparation = 2;
@@ -46,6 +43,12 @@ public static class Constants
         /// <summary> Horizontal separation between left side of single dropdown and left side of labels beneath dropdown </summary>
         public const int DropDownLeftSeparation = 10;
 
+        /// <summary> Height of sensitivity chart when displayed alone. </summary>
+        public const int SensitivityChartAloneHeight = 450;
+
+        /// <summary> Height of sensitivity chart when displayed alongside Velocity and Gain charts. </summary>
+        public const int SensitivityChartTogetherHeight = 328;
+
         /// <summary> Width of charts when widened </summary>
         public const int WideChartWidth = 723;
 
@@ -61,8 +64,14 @@ public static class Constants
         /// <summary> Vertical placement of write button above bottom of sensitivity graph </summary>
         public const int ButtonVerticalOffset = 60;
 
+        /// <summary> Padding between directionality title and containing panel </summary>
+        public const int DirectionalityTitlePad = 8;
+
         public const float SmallButtonSizeFactor = 0.666f;
 
+        /// <summary> Number of divisions between 0 and 90 degrees for directional lookup. For 19: 0, 5, 10... 85, 90.</summary>
+        public const int AngleDivisions = 19;
+
         /// <summary> Format string for shortened x and y textboxes. </summary>
         public const string ShortenedFormatString = "0.###";
 
@@ -111,6 +120,12 @@ public static class Constants
         /// <summary> Default name of settings file. </summary>
         public const string DefaultSettingsFileName = @"settings.json";
 
+        /// <summary> Text to direcitonality panel title when panel is closed. </summary>
+        public const string DirectionalityTitleClosed = "Anisotropy \u25BC";
+
+        /// <summary> Text to direcitonality panel title when panel is open. </summary>
+        public const string DirectionalityTitleOpen = "Anisotropy \u25B2";
+
         /// <summary> Style used by System.Double.Parse </summary>
         public const NumberStyles FloatStyle = NumberStyles.Float | NumberStyles.AllowThousands;