Development

.clang-format

@@ -0,0 +1,100 @@
+BasedOnStyle: WebKit
+
+BraceWrapping:
+  AfterClass: true
+  AfterControlStatement: true
+  AfterEnum: true
+  AfterExternBlock: false
+  AfterFunction: true
+  AfterNamespace: true
+  AfterStruct: true
+  AfterUnion: true
+  BeforeCatch: true
+  BeforeElse: true
+  IndentBraces: false
+
+# BreakBeforeConceptDeclarations: Always
+# IndentRequiresClause: false
+AccessModifierOffset: -2
+AlignAfterOpenBracket: AlwaysBreak
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlinesLeft: true
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllArgumentsOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: false
+AlwaysBreakBeforeMultilineStrings: true
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: true
+BinPackParameters: true
+BreakBeforeBinaryOperators: All
+BreakBeforeBraces: Custom
+BreakBeforeConceptDeclarations: true
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeComma
+BreakConstructorInitializersBeforeComma: true
+BreakInheritanceList: BeforeComma
+ColumnLimit: 89
+CommentPragmas: "^ clang-format:"
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
+IndentCaseLabels: true
+IndentExternBlock: NoIndent
+IndentWidth: 2
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: true
+LambdaBodyIndentation: OuterScope
+Language: Cpp
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+PackConstructorInitializers: Never
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 60
+PointerAlignment: Left
+ReferenceAlignment: Left
+ReflowComments: false
+SortIncludes: true
+SpaceAfterCStyleCast: false
+SpaceAroundPointerQualifiers: Default
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeParens: Never
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: Latest
+TabWidth: 2
+UseTab: Never
+
+IncludeCategories:
+  - Regex: '<.*\.(c|cpp)>'
+    Priority: 1000
+  - Regex: '^"'
+    Priority: 10
+  - Regex: "^<boost"
+    Priority: 70
+  - Regex: "^<Q"
+    Priority: 80
+  - Regex: '<([[:alnum:]_]+\/)+([[:alnum:]_])+.(h|hpp)>'
+    Priority: 700
+  - Regex: '<([[:alnum:]_]+\/?)+.(h|hpp)>'
+    Priority: 800
+  - Regex: "<[[:alnum:]_]+>"
+    Priority: 900

.github/workflows/cmake.yml

@@ -0,0 +1,41 @@
+name: Build
+on:
+  push:
+
+jobs:
+  build-project:
+    strategy:
+      matrix:
+        config:
+          - {
+              os: ubuntu-latest,
+              cmake_options: "",
+              dependencies: "sudo apt update -yqq && sudo apt -yqq install libboost-dev"
+            }
+          - {
+              os: macos-latest,
+              cmake_options: "CMAKE_PREFIX_PATH=/opt/homebrew",
+              dependencies: "brew install boost eigen && brew link boost eigen"
+            }
+          - {
+              os: windows-latest,
+              cmake_options: "Boost_INCLUDE_DIR=D:/a/puara-gestures/puara-gestures/3rdparty",
+              dependencies: "choco install eigen -y --no-progress"
+            }
+
+    runs-on: ${{ matrix.config.os }}
+    steps:
+      - name: Checkout Project
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Dependencies
+        run: ${{ matrix.config.dependencies }}
+
+      - name: Build Project
+        uses: threeal/[email protected]
+        with:
+          options: |
+            PUARA_GESTURES_ENABLE_STANDALONE=0
+            ${{ matrix.config.cmake_options }}

.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+build/
+.vscode/
+*.user
+*code-workspace
+.pio
+exampleProjects/touch/.gitignore

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "IMU_Sensor_Fusion"]
-	path = IMU_Sensor_Fusion
-	url = https://github.com/malloch/IMU_Sensor_Fusion
+[submodule "3rdparty"]
+	path = 3rdparty
+	url = git@github.com:Puara/3rdparty.git

CMakeLists.txt

@@ -0,0 +1,81 @@
+cmake_minimum_required(VERSION 3.24...3.30)
+
+project(
+    puara-gestures
+    VERSION 0.2
+    LANGUAGES CXX
+)
+
+### Library options ###
+option(PUARA_GESTURES_ENABLE_TESTING "Enable building and running Puara gestures tests" ON)
+option(PUARA_GESTURES_ENABLE_STANDALONE "Enable building and running Puara standalone" OFF)
+
+### Dependencies ###
+if(POLICY CMP0167)
+  cmake_policy(SET CMP0167 OLD)
+endif()
+
+set(BOOST_ROOT "${CMAKE_SOURCE_DIR}/3rdparty")
+set(Boost_NO_SYSTEM_PATHS ON)
+find_package(Boost REQUIRED)
+
+### Main library ###
+add_library(puara_gestures
+  3rdparty/IMU_Sensor_Fusion/imu_orientation.h
+  3rdparty/IMU_Sensor_Fusion/imu_orientation.cpp
+
+  include/puara/descriptors/button.h
+  include/puara/descriptors/jab.h
+  include/puara/descriptors/roll.h
+  include/puara/descriptors/shake.h
+  include/puara/descriptors/tilt.h
+  include/puara/descriptors/touchArrayGestureDetector.h
+
+  include/puara/utils/blobDetector.h
+  include/puara/utils/calibration.h
+  include/puara/utils/circularbuffer.h
+  include/puara/utils/leakyintegrator.h
+  include/puara/utils/maprange.h
+  include/puara/utils/rollingminmax.h
+  include/puara/utils/smooth.h
+  include/puara/utils/threshold.h
+  include/puara/utils/wrap.h
+
+  include/puara/structs.h
+  include/puara/gestures.h
+  include/puara/utils.h
+
+  src/puara_gestures.cpp
+
+)
+
+target_compile_definitions(puara_gestures PUBLIC $<$<BOOL:${WIN32}>:_USE_MATH_DEFINES>)
+target_include_directories(puara_gestures PUBLIC include 3rdparty)
+target_compile_features(puara_gestures PUBLIC cxx_std_20)
+target_link_libraries(puara_gestures PUBLIC Boost::headers)
+
+### Tests ###
+if(PUARA_GESTURES_ENABLE_TESTING)
+  include(CTest)
+
+target_sources(Continuous
+  PRIVATE
+  tests/testing_touch.cpp
+
+)
+add_executable(testing_roll tests/testing_roll.cpp)
+  add_executable(testing_tilt tests/testing_tilt.cpp)
+  add_executable(testing_touch tests/testing_touch.cpp)
+  target_compile_definitions(testing_roll PRIVATE "-DPUARA_TESTS_DIR=\"${CMAKE_CURRENT_SOURCE_DIR}/testing files\"")
+  target_compile_definitions(testing_tilt PRIVATE "-DPUARA_TESTS_DIR=\"${CMAKE_CURRENT_SOURCE_DIR}/testing files\"")
+  target_compile_definitions(testing_touch PRIVATE "-DPUARA_TESTS_DIR=\"${CMAKE_CURRENT_SOURCE_DIR}/testing files\"")
+  target_link_libraries(testing_roll PRIVATE puara_gestures)
+  target_link_libraries(testing_tilt PRIVATE puara_gestures)
+  target_link_libraries(testing_touch PRIVATE puara_gestures)
+
+endif()
+
+### Example ###
+if(PUARA_GESTURES_ENABLE_STANDALONE)
+  add_subdirectory(standalone)
+endif()

README.md

@@ -1,2 +1,79 @@
-# puara-gestures
-High-level gestural descriptor functions for the Puara Framework
+# Puara Gestures
+The `puara-gestures` library provides a set of tools for creating and managing high-level gestural descriptors using data from various sensors such as accelerometers, gyroscopes, and magnetometers. The library includes classes for handling different types of gestures, including shakes, rolls, tilts, jabs, and touches.
+
+## Gestures (descriptors) and Features
+
+- **Shake**: Detects "shake" movements. It is often used on accelerometer data, but it can be applied to any 1 to 3DoF data flow.
+- - **Jab**: Detects jab movements using accelerometer data.
+- **Roll**: Measures roll gestures using 9DoF (IMU data) info from an accelerometer, gyroscope, and magnetometer.
+- **Tilt**: Measures tilt gestures using 9DoF (IMU data) info from an accelerometer, gyroscope, and magnetometer.
+- **Touch (Brush/Rub)**: Extract features for 1 to 3DoF agnostic data. It is often used to interpret standard touch features (swipe/brush, rub, positional, area, etc.) based on movement input.
+- **Button**: Interaction (feature) extraction using a discrete input. It can be used for buttons or any other discrete binary data.
+
+## Example Projects
+
+A basic example of puara-gestures can be found on the [puara-module-templates](https://github.com/Puara/puara-module-templates/tree/main/basic-gestures) repository.
+The included `exampleProjects` directory also contains example projects and is a good starting point for new users. 
+See [exampleProjects](/exampleProjects) for details.
+
+## Building the Library
+
+### Prerequisites
+
+- CMake 3.24 or higher
+- A compatible C++ compiler
+- Arduino IDE (for running the example project on hardware)
+
+### Building
+
+To build the `puara-gestures` library, follow these steps:
+
+1. Clone the repository:
+    ```sh
+    git clone https://github.com/Puara/puara-gestures.git
+    cd puara-gestures
+    ```
+2. Configure the project using CMake:
+    ```sh
+    cmake -B build
+    ```
+3. Build the project:
+    ```sh
+    cmake --build build
+    ```
+
+## Usage in PlatformIO
+
+Puara-gestures can be easily included in PlatformIo projects. The recommended method is to manually edit the `platformio.ini` file of the project and add this repository to `lib_deps`. It is recommended to specify the puara-gestures version (in the example below, we will use version 0.2.0): 
+
+```
+lib_deps = https://github.com/Puara/puara-gestures.git#v0.2.0
+```
+
+If planning to use the 3rd-party library for sensor fusion, it also needs to be manually added:
+
+```
+lib_deps = 
+	https://github.com/Puara/puara-gestures.git#v0.2.0
+	https://github.com/malloch/IMU_Sensor_Fusion.git
+```
+
+When using PlatformIO, it is also important to use the **espressif32** platform and **arduino** framework if using an ESP32. 
+To use esp-idf, it is recommended to manually copy the `src` and `include` folders into your project rather than using lib_deps.
+The reason is that esp-idf will try to compile all cpp files in this project, resulting in include errors.
+
+## Contributing with new gestures
+
+It is easy to contribute new gestures for puara-gestures.
+Gestures are organized in single-header files that contain the feature class.
+We only need to add a class (header) in the [descriptors folder](include/puara/descriptors) and include it in [gestures.h](include/puara/gestures.h).
+
+
+## More Info on the research related to [Puara](https://github.com/Puara)
+
+- [SAT](http://www.sat.qc.ca)
+- [IDMIL](http://www.idmil.org)
+
+## Licensing
+
+The code in this project is licensed under the MIT license, unless otherwise specified within the file.

exampleProjects/touch/README.md

@@ -0,0 +1,49 @@
+# Touch Project
+
+This project is part of the Puara Framework and showcases the integration of `puara-gestures` with a touchscreen in a [Wokwi](https://wokwi.com/) simulation to detect and display touch interactions.
+
+## Project Overview
+
+This example project has 3 main components:
+- A Wokwi `diagram.json` containing a simple circuit simulation consisting of a ILI9341 touch screen and a TinyPico ESP32 development board.
+- A simple `main.cpp` which mainly initiates and update a `TinyTouch` object.
+- A `TinyTouch` class, which is closely tied to the Wokwi `diagram.json`, and displays rectangles on a screen to simulate a touch array. As the screen is touched, `TinyTouch` updates its `TouchArrayGestureDetector` class member (which is part of the `puara-gesture` namespace), which calculates brush and rub gestures. The resulting total `brush` and `rub` values are printed to the terminal.
+
+## Running the Project Using Wokwi in Visual Studio Code
+
+1. Install [Visual Studio Code](https://code.visualstudio.com/), as well as the [PlatformIO](https://platformio.org/install/ide?install=vscode) and [Wokwi](https://docs.wokwi.com/vscode/getting-started) VS Code extensions. As part of the process you'll need to create a free [Wokwi](https://wokwi.com/) online account.
+
+2. Clone this repository and open the `exampleProjects/touch` directory in Visual Studio Code.
+
+    ```sh
+    git clone https://github.com/Puara/puara-gestures.git
+    code puara-gestures/exampleProjects/touch
+    ```
+
+    Once you open the `touch` directory in VS Code, PlatformIO should take a moment to install all the dependencies listed in `exampleProjects/touch/platformio.ini`.
+
+3. Open the `diagram.json` file.
+
+4. If you've never signed in your wokwi account from VS Code, or it's been more than a month since you got your last license, you might get this dialog in the bottom right of the IDE. If so, click on "Request a New License" and follow the instructions to get another free Wokwi license.
+
+<p align="center">
+  <img width="450" src="https://github.com/user-attachments/assets/3502135c-9326-40aa-9887-8d796e464ff9">
+</p>
+
+5. Click on the green arrow "Start Simulation" button in the top left to build and run the project in Wokwi:
+
+<p align="center">
+  <img width="600" src="https://github.com/user-attachments/assets/f073b596-53a7-4404-a2aa-0ac49ad176b6">
+</p>
+
+6. Once the simulation is started, click on the touch screen to start the touch example. Now if you "brush" and "rub" the touch screen up and down with your mouse cursor you should see `brush` and `rub` values printed in the VS Code Wokwi Terminal:
+
+<p align="center">
+  <img width="600" src="https://github.com/user-attachments/assets/bafca748-f5d7-46ba-8f48-a05db5cf996e">
+</p>
+
+7. The firmware code to run this simulation is located in `exampleProjects/touch/src`. Feel free to explore and modify the code to understand how it all works. Have fun!
+
+## License
+
+This project is licensed under the MIT License.