diff --git a/docs/documentation/android/code_documentation/MotionProcessor.md b/docs/documentation/android/code_documentation/MotionProcessor.md new file mode 100644 index 0000000..7f3f782 --- /dev/null +++ b/docs/documentation/android/code_documentation/MotionProcessor.md @@ -0,0 +1,65 @@ +## Class Implementation - MotionProcessor + +--- + +#### Methods + +Creates a WebSocket server and starts listening for incoming MotionData messages +```java +public void startListening() { ... } +``` + +Stops the WebSocket server and stops listening for incoming MotionData messages +```java +public void stopListening() { ... } +``` + +Parses an incoming WebSocket message packet and processes the data. +The data that is accepted is a string that can be of the following formats: +- "data `Ax`;`Ay`;`Az`;`Rx`;`Ry`;`Rz`" +- "sampleRate `x`" +- "calibrate `x`;`y`;`z`" +```java +public void parsePacket(@NotNull String message) { ... } +``` + +Processes the provided MotionData object, uses it as a relative path point, and calls the +motionDataEventHandler with the calculated vector. +```java +public void addMotionData(MotionData data) { ... } +``` + +Updates the relative path to the provided path. +```java +public void setRelativePath(List relativePath) { ... } +``` + +Sets the motionDataEventHandler to the provided handler. +```java +public void setMotionDataEventHandler(Consumer consumer) { ... } +``` + +Calculate the relative vector given a MotionData object. +This converts relative acceleration and rotation to a vector, taking the +sample rate into account. +```java +public Vector3 getRelativeVector(MotionData motionData) { ... } +``` + +Get a list of error values given the provided GesturePath. +This compares the relative path (calibrated) to the provided path segments, +and returns the offsets. +```java +public List getErrors(GesturePath referencePath) { ... } +``` + +Get the error offset of the provided vector to the provided path. +This compares a given vector to the provided GesturePath object. +```java +public double getError(GesturePath path, Vector3 referencePoint) { ... } +``` + +Get the average error offset of the relative path and the provided GesturePath object. +```java +public double getAverageError(GesturePath referencePath) { ... } +``` \ No newline at end of file diff --git a/docs/documentation/android/robot_motion_tracking_system.md b/docs/documentation/android/robot_motion_tracking_system.md new file mode 100644 index 0000000..e222e3d --- /dev/null +++ b/docs/documentation/android/robot_motion_tracking_system.md @@ -0,0 +1,108 @@ +## Motion Tracking System + +--- + +To capture the user's motion with the sensing devices, we'll need to use a tracking system that calculates the +path the user makes to be able to determine the user's position and orientation, and therefore whether the movement +that was made correlates to the provided path. +This is done by some calculations in the `MotionProcessor` class. To get started, create an instance of the `MotionProcessor` class and call the `processMotion` method with the `MotionData` object as a parameter. This will return a `MotionResult` object that contains the calculated path. + +```java +// create the motion processor +MotionProcessor motionProcessor = new MotionProcessor(); +``` + +To start listening for input, one must call the following method: + +```java +// start listening for input +motionProcessor.startListening(); +``` + +Calling this function creates a WebSocket server, which the sensing devices can connect to. +The `MotionProcessor` class will then start listening for a set of messages that start with specified kind of keywords. +The messages always start with the keyword, separated by a space, and then the data is sent. +The default data separator is `;`. +An example of the message format is shown below: +```java +// Sending data +"data accelerationX;accelerationY;accelerationZ;rotationX;rotationY;rotationZ" // all values are floats + +// Changing the sample rate +"sampleRate rate" // rate is an integer + +// Calibrating the zero point +"zero x;y;z" // x, y, z are floats +``` + +To add a custom message received handler, one can simply call the following method: + +```java +// Add a custom message handler +motionProcessor.setMotionDataEventHandler((Vector3 vector) -> { ... }); +``` +*Note: The message handler provides a vector as a parameter; this vector is already converted from relative acceleration and rotation.* + +### Error checking + +To check whether the made movements correlate with a given path, one must check for their differences. +This can be done by a few implemented methods: + +***Get the error of a vector compared to a path*** +```java +GesturePath path = new GesturePath.Builder() + .addVector(...) + .build(); + +Vector3 referencePoint = new Vector3(...); +double error = motionProcessor.getError(path, referencePoint); +``` + +***Get the average error of a computed path to a `GesturePath`*** +```java +GesturePath path = new GesturePath.Builder() + .addVector(...) + .build(); + +double error = motionProcessor.getAverageError(path); +``` + +***Get a list of error values from a computed path to a `GesturePath`*** +```java +GesturePath path = new GesturePath.Builder() + .addVector(...) + .build(); + +List errorList = motionProcessor.getErrors(path); +``` + +### Example + +An example of how to use a motion tracking system is shown below: + +```java + +// create the motion processor +MotionProcessor motionProcessor = new MotionProcessor(); + +// Create a gesture path +GesturePath.Builder pathBuilder = new GesturePath.Builder(); + +for ( int i = 0; i < 100; i++ ) + pathBuilder.addVector(new Vector3(i, i, i)); + +GesturePath path = pathBuilder.build(); + +// Set the path +for ( int i = 0; i < 100; i++ ) { + motionProcessor.addMotionData(new MotionData(i, i, i, i, i, i)); +} + +// Get error values +List errorList = motionProcessor.getErrors(path); + +// Get average error +double averageError = motionProcessor.getAverageError(path); + +// Now you can do whatever you want with these results. +``` \ No newline at end of file