v3.0

* Add Kotlin

Author: KalebKE

README.md

@@ -4,10 +4,10 @@ Android Sensor Filter and Fusion
 ![Alt text](http://kircherelectronics.com.23.38-89-161.groveurl.com/wp-content/uploads/2017/12/FSensor.png "FSensor")
 
 ## Introduction
-FSensor (FusionSensor) is an Android library that (hopefully) removes some/most of the complexity of using Androids orientation sensors (Acceleration, Magnetic and Gyroscope). FSensor expands greatly on the "out-of-the-box" sensor implementations provided by Android allowing you to customize sensor filters and fusions for your specific needs, or just add default filters on what Android already provides. 
+FSensor (FusionSensor) is an Android library that (hopefully) removes some/most of the complexity of using Androids rotation sensors (Acceleration, Magnetic and Gyroscope). FSensor expands greatly on the "out-of-the-box" sensor implementations provided by Android allowing you to customize sensor filters and fusions for your specific needs, or just add default filters on what Android already provides. 
 
 * Provides device/sensor agnostic averaging filters in the of mean, median and low-pass varieties
-* Provides IMU sensor fusion backed estimations of device orientation in the complimentary and Kalman varieties
+* Provides IMU sensor fusion backed estimations of device rotation in the complimentary and Kalman varieties
 * Provides estimations of linear acceleration (linear acceleration = acceleration - gravity) in the averaging filter and sensor fusion varieties
 
 ## Get FSensor
@@ -61,17 +61,17 @@ FSensor uses a median filter designed to smooth the data points based on a time
 
 ## Orientation Sensor Fusions
 
-FSensor offers two different estimations of rotation using IMU sensor fusions. These filters can be found in the *.filter.fusion* package. One fusion is based on a quaternion backed complimentary filter and the second fusion is based on a quaternion backed Kalman filter. Both fusions use the acceleration sensor, magnetic sensor and gyroscope sensor to provide an estimation the devices orientation relative to world space coordinates.
+FSensor offers two different estimations of rotation using IMU sensor fusions. These filters can be found in the *.filter.fusion* package. One fusion is based on a quaternion backed complimentary filter and the second fusion is based on a quaternion backed Kalman filter. Both fusions use the acceleration sensor, magnetic sensor and gyroscope sensor to provide an estimation the devices rotation relative to world space coordinates.
 
-The gyroscope is used to measure the devices orientation. However, the gyroscope tends to drift due to round off errors and other factors. Most gyroscopes work by measuring very small vibrations in the earth's rotation, which means they really do not like external vibrations. Because of drift and external vibrations, the gyroscope has to be compensated with a second estimation of the devices orientation, which comes from the acceleration sensor and magnetic sensor. The acceleration sensor provides the pitch and roll estimations while the magnetic sensor provides the azimuth.
+The gyroscope is used to measure the devices rotation. However, the gyroscope tends to drift due to round off errors and other factors. Most gyroscopes work by measuring very small vibrations in the earth's rotation, which means they really do not like external vibrations. Because of drift and external vibrations, the gyroscope has to be compensated with a second estimation of the devices rotation, which comes from the acceleration sensor and magnetic sensor. The acceleration sensor provides the pitch and roll estimations while the magnetic sensor provides the azimuth.
 
 ### Quaternions Complimentary Filter
 
 Quaternions offer an angle-axis solution to rotations which do not suffer from many of the singularies, including gimbal lock, that you will find with rotation matrices. Quaternions can also be scaled and applied to a complimentary filter. The quaternion complimentary filter is probably the most elegant, robust and accurate of the filters, although it can also be the most difficult to implement.
 
 The complementary filter is a frequency domain filter. In its strictest sense, the definition of a complementary filter refers to the use of two or more transfer functions, which are mathematical complements of one another. Thus, if the data from one sensor is operated on by G(s), then the data from the other sensor is operated on by I-G(s), and the sum of the transfer functions is I, the identity matrix. In practice, it looks nearly identical to a low-pass filter, but uses two different sets of sensor measurements to produce what can be thought of as a weighted estimation.
 
- A complimentary filter is used to fuse the two orientation estimations (the gyroscope and acceleration/magnetic, respectively) together. It takes the form of gyro[0] = alpha * gyro[0] + (1 - alpha) * accel/magnetic[0]. Alpha is defined as alpha = timeConstant / (timeConstant + dt) where the time constant is the length of signals the filter should act on and dt is the sample period (1/frequency) of the sensor.
+ A complimentary filter is used to fuse the two rotation estimations (the gyroscope and acceleration/magnetic, respectively) together. It takes the form of gyro[0] = alpha * gyro[0] + (1 - alpha) * accel/magnetic[0]. Alpha is defined as alpha = timeConstant / (timeConstant + dt) where the time constant is the length of signals the filter should act on and dt is the sample period (1/frequency) of the sensor.
 
  ### Quaternion Kalman Filter
 
@@ -93,7 +93,7 @@ The most simple linear acceleration filter is based on a low-pass filter. It has
 
 ### IMU Sensor Fusion Linear Acceleration
 
-Calculating the gravity components of a normalized orientation is trivial, so FSensor can use the IMU orientation fusions to provide an estimation of linear acceleration that is far more customizable than what Android provides alone.
+Calculating the gravity components of a normalized rotation is trivial, so FSensor can use the IMU rotation fusions to provide an estimation of linear acceleration that is far more customizable than what Android provides alone.
 
 ## Sensor Offset Calibration
 

build.gradle

@@ -10,8 +10,7 @@ buildscript {
 
     dependencies {
         classpath 'com.android.tools.build:gradle:8.1.4'
-
-        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
 

documentation/USAGE.md

@@ -120,7 +120,7 @@ public void onSensorChanged(SensorEvent event) {
       System.arraycopy(event.values, 0, acceleration, 0, event.values.length);
       orientationFusion.setAcceleration(acceleration);
       
-      // Apply the orientation to the raw acceleration to estimate linear acceleration
+      // Apply the rotation to the raw acceleration to estimate linear acceleration
       linearAcceleration = linearAccelerationFilter.filter(acceleration)
     } else  if (event.sensor.getType() == Sensor.TYPE_MAGNETIC_FIELD) {
      // Android reuses events, so you probably want a copy
@@ -172,7 +172,7 @@ public void onSensorChanged(SensorEvent event) {
       System.arraycopy(event.values, 0, magnetic, 0, event.values.length);
       orientationFusion.setMagneticField(this.magnetic);
       
-      // Compensate for tilt. Note: This sensor orientation assumes portrait mode with the device laying flat and the compass       // pointing out of the top of the device. Your milage may vary.
+      // Compensate for tilt. Note: This sensor rotation assumes portrait mode with the device laying flat and the compass       // pointing out of the top of the device. Your milage may vary.
       float[] output = TiltCompensationUtil.compensateTilt(new float[]{magnetic[0], -magnetic[1], magnetic[2]}, new float[]{fusedOrientation[1], fusedOrientation[2], 0});
       // Reorient to the device
       output[1] = -output[1];
@@ -264,7 +264,7 @@ public class MainActivity extends AppCompatActivity implements SensorEventListen
             System.arraycopy(event.values, 0, acceleration, 0, event.values.length);
             orientationFusion.setAcceleration(acceleration);
 
-            // Apply the orientation to the raw acceleration to estimate linear acceleration
+            // Apply the rotation to the raw acceleration to estimate linear acceleration
             linearAcceleration = linearAccelerationFilter.filter(acceleration);
         } else  if (event.sensor.getType() == Sensor.TYPE_MAGNETIC_FIELD) {
             // Android reuses events, so you probably want a copy
@@ -350,7 +350,7 @@ public class MainActivity extends AppCompatActivity implements SensorEventListen
             System.arraycopy(event.values, 0, acceleration, 0, event.values.length);
             orientationFusion.setAcceleration(acceleration);
 
-            // Apply the orientation to the raw acceleration to estimate linear acceleration
+            // Apply the rotation to the raw acceleration to estimate linear acceleration
             linearAcceleration = linearAccelerationFilter.filter(acceleration);
         } else  if (event.sensor.getType() == Sensor.TYPE_MAGNETIC_FIELD) {
             // Android reuses events, so you probably want a copy

fsensor/src/main/java/com/tracqi/fsensor/filter/MeanFilter.java

@@ -1,5 +1,7 @@
 package com.tracqi.fsensor.filter;
 
+import android.util.Log;
+
 import java.util.ArrayDeque;
 import java.util.Arrays;
 
@@ -108,9 +110,4 @@ private float[] getMean(ArrayDeque<float[]> data) {
 
         return mean;
     }
-
-    public void reset() {
-        super.reset();
-        this.values.clear();
-    }
 }

fsensor/src/main/java/com/tracqi/fsensor/filter/MedianFilter.java

@@ -117,9 +117,4 @@ private float[] getMedian(ArrayDeque<float[]> data) {
 
         return mean;
     }
-
-    public void reset() {
-        super.reset();
-        this.values.clear();
-    }
 }

fsensor/src/main/java/com/tracqi/fsensor/filter/SensorFilter.java

@@ -37,11 +37,6 @@ public SensorFilter(float timeConstant) {
         this.timeConstant = timeConstant;
     }
 
-    public void reset() {
-        startTime = 0;
-        count = 0;
-    }
-
     public void setTimeConstant(float timeConstant) {
         this.timeConstant = timeConstant;
     }

fsensor/src/main/java/com/tracqi/fsensor/math/angle/AngleUtils.java fsensor/src/main/java/com/tracqi/fsensor/math/angle/Angles.java

@@ -18,8 +18,8 @@
  * limitations under the License.
  */
 
-public class AngleUtils {
-    private static final String TAG = AngleUtils.class.getSimpleName();
+public class Angles {
+    private static final String TAG = Angles.class.getSimpleName();
 
     /**
      * https://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToEuler/index.htm

fsensor/src/main/java/com/tracqi/fsensor/math/gravity/GravityUtil.java fsensor/src/main/java/com/tracqi/fsensor/math/gravity/Gravity.java

@@ -1,9 +1,6 @@
 package com.tracqi.fsensor.math.gravity;
 
 import android.hardware.SensorManager;
-import android.util.Log;
-
-import java.util.Arrays;
 
 /*
  * Copyright 2024, Tracqi Technology, LLC
@@ -24,7 +21,7 @@
 /**
  * Created by kaleb on 7/6/17.
  */
-public class GravityUtil {
+public class Gravity {
     /**
      * Assumes a positive, counter-clockwise, right-handed rotation
      * orientation[0] = pitch, rotation around the X axis.

fsensor/src/main/java/com/tracqi/fsensor/math/magnetic/AzimuthUtil.java fsensor/src/main/java/com/tracqi/fsensor/math/magnetic/Azimuth.java

@@ -20,7 +20,7 @@
  * A helper class for
  * Created by kaleb on 3/18/18.
  */
-public class AzimuthUtil {
+public class Azimuth {
 
     /**
      * Get the azimuth from a magnetic sensor.

fsensor/src/main/java/com/tracqi/fsensor/math/magnetic/declination/DeclinationUtil.java fsensor/src/main/java/com/tracqi/fsensor/math/magnetic/declination/Declination.java

@@ -24,15 +24,15 @@
  *
  * Created by kaleb on 3/18/18.
  */
-public class DeclinationUtil {
+public class Declination {
 
     private GeomagneticField geoMagField;
 
     /**
      * Default constructor.
      * @param location The location to use for the compensation.
      */
-    public DeclinationUtil(Location location) {
+    public Declination(Location location) {
         setGeomagneticField(location);
     }
 

fsensor/src/main/java/com/tracqi/fsensor/math/magnetic/tilt/TiltCompensationUtil.java fsensor/src/main/java/com/tracqi/fsensor/math/magnetic/tilt/TiltCompensation.java

@@ -20,7 +20,7 @@
  * Providers helpers to compensate for the tilt of a magnetic sensor.
  * Created by kaleb on 3/18/18.
  */
-public class TiltCompensationUtil {
+public class TiltCompensation {
 
     /**
      * Get the rotation vector based on the tilt of the acceleration sensor.

fsensor/src/main/java/com/tracqi/fsensor/math/rotation/RotationUtil.java fsensor/src/main/java/com/tracqi/fsensor/math/rotation/Rotation.java

@@ -2,7 +2,6 @@
 
 import android.hardware.SensorManager;
 import android.renderscript.Matrix3f;
-import android.util.Log;
 
 import org.apache.commons.math3.complex.Quaternion;
 
@@ -28,7 +27,7 @@
  * Created by kaleb on 4/1/18.
  */
 
-public class RotationUtil {
+public class Rotation {
 
     /**
      * Calculates a rotation vector from the gyroscope angular speed values.

fsensor/src/main/java/com/tracqi/fsensor/orientation/Orientation.java fsensor/src/main/java/com/tracqi/fsensor/rotation/Rotation.java

@@ -1,4 +1,4 @@
-package com.tracqi.fsensor.orientation;
+package com.tracqi.fsensor.rotation;
 
 
 /*
@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 
-public interface Orientation {
+public interface Rotation {
     void start(int sensorDelay);
     void stop();
     float[] getOrientation();

fsensor/src/main/java/com/tracqi/fsensor/orientation/fusion/FusedOrientation.java fsensor/src/main/java/com/tracqi/fsensor/rotation/fusion/FusedRotation.java

@@ -1,6 +1,6 @@
-package com.tracqi.fsensor.orientation.fusion;
+package com.tracqi.fsensor.rotation.fusion;
 
-import com.tracqi.fsensor.orientation.Orientation;
+import com.tracqi.fsensor.rotation.Rotation;
 
 import org.apache.commons.math3.complex.Quaternion;
 
@@ -25,7 +25,7 @@
  * Created by kaleb on 7/6/17.
  */
 
-public abstract class FusedOrientation implements Orientation {
+public abstract class FusedRotation implements Rotation {
 
     protected static final float EPSILON = 0.000000001f;
     // Nano-second to second conversion

fsensor/src/main/java/com/tracqi/fsensor/orientation/fusion/complementary/ComplimentaryOrientation.java fsensor/src/main/java/com/tracqi/fsensor/rotation/fusion/complementary/ComplimentaryRotation.java

@@ -1,20 +1,17 @@
-package com.tracqi.fsensor.orientation.fusion.complementary;
+package com.tracqi.fsensor.rotation.fusion.complementary;
 
 import android.hardware.Sensor;
 import android.hardware.SensorEvent;
 import android.hardware.SensorEventListener;
 import android.hardware.SensorManager;
-import android.util.Log;
 
-import com.tracqi.fsensor.math.gravity.GravityUtil;
-import com.tracqi.fsensor.orientation.fusion.FusedOrientation;
-import com.tracqi.fsensor.math.angle.AngleUtils;
-import com.tracqi.fsensor.math.rotation.RotationUtil;
+import com.tracqi.fsensor.math.gravity.Gravity;
+import com.tracqi.fsensor.rotation.fusion.FusedRotation;
+import com.tracqi.fsensor.math.angle.Angles;
+import com.tracqi.fsensor.math.rotation.Rotation;
 
 import org.apache.commons.math3.complex.Quaternion;
 
-import java.util.Arrays;
-
 /*
  * Copyright 2024, Tracqi Technology, LLC
  *
@@ -84,9 +81,9 @@
  *
  * @author Kaleb
  */
-public class ComplimentaryOrientation extends FusedOrientation {
+public class ComplimentaryRotation extends FusedRotation {
 
-    private static final String TAG = ComplimentaryOrientation.class.getSimpleName();
+    private static final String TAG = ComplimentaryRotation.class.getSimpleName();
 
     private static final float DEFAULT_TIME_CONSTANT = 0.18f;
 
@@ -111,11 +108,11 @@ public class ComplimentaryOrientation extends FusedOrientation {
     /**
      * Initialize a singleton instance.
      */
-    public ComplimentaryOrientation(SensorManager sensorManager) {
+    public ComplimentaryRotation(SensorManager sensorManager) {
         this.sensorManager = sensorManager;
     }
 
-    public ComplimentaryOrientation(SensorManager sensorManager, float timeConstant) {
+    public ComplimentaryRotation(SensorManager sensorManager, float timeConstant) {
         this.sensorManager = sensorManager;
         this.timeConstant = timeConstant;
     }
@@ -177,10 +174,10 @@ private void calculateFusedOrientation(float[] gyroscope, long timestamp, float[
                 float oneMinusAlpha = (1.0f - alpha);
 
                 // Get last known orientation
-                float[] orientation = AngleUtils.getAngles(rotationVector.getQ0(), rotationVector.getQ1(), rotationVector.getQ2(), rotationVector.getQ3());
+                float[] orientation = Angles.getAngles(rotationVector.getQ0(), rotationVector.getQ1(), rotationVector.getQ2(), rotationVector.getQ3());
 
                 // Calculate the gravity vector from the orientation
-                float[] gravity = GravityUtil.getGravityFromOrientation(orientation);
+                float[] gravity = Gravity.getGravityFromOrientation(orientation);
 
                 for(int i = 0; i < gravity.length; i++) {
                     // Apply acceleration sensor
@@ -189,11 +186,11 @@ private void calculateFusedOrientation(float[] gyroscope, long timestamp, float[
                 }
 
                 // Get orientation from acceleration and magnetic
-                Quaternion rotationVectorAccelerationMagnetic = RotationUtil.getOrientationVector(gravity, magnetic);
+                Quaternion rotationVectorAccelerationMagnetic = Rotation.getOrientationVector(gravity, magnetic);
 
                 if (rotationVectorAccelerationMagnetic != null) {
 
-                    rotationVector = RotationUtil.integrateGyroscopeRotation(rotationVector, gyroscope, dT, EPSILON);
+                    rotationVector = Rotation.integrateGyroscopeRotation(rotationVector, gyroscope, dT, EPSILON);
 
                     // Apply the complementary fusedOrientation. // We multiply each rotation by their
                     // coefficients (scalar matrices)...
@@ -206,7 +203,7 @@ private void calculateFusedOrientation(float[] gyroscope, long timestamp, float[
                     // output[0] = alpha * output[0] + (1 - alpha) * input[0];
                     Quaternion result = scaledRotationVectorGyroscope.add(scaledRotationVectorAccelerationMagnetic);
 
-                    float[] angles = AngleUtils.getAngles(result.getQ0(), result.getQ1(), result.getQ2(), result.getQ3());
+                    float[] angles = Angles.getAngles(result.getQ0(), result.getQ1(), result.getQ2(), result.getQ3());
                     System.arraycopy(angles, 0, this.output, 0, angles.length);
                 }
             }
@@ -242,7 +239,7 @@ public void onSensorChanged(SensorEvent event) {
                 hasMagnetic = false;
 
                 if (!isBaseOrientationSet()) {
-                    setBaseOrientation(RotationUtil.getOrientationVector(acceleration, magnetic));
+                    setBaseOrientation(Rotation.getOrientationVector(acceleration, magnetic));
                 } else {
                     calculateFusedOrientation(rotation, rotationTimestamp, acceleration, magnetic);
                 }