Docs: Add reference and tutorial for Roll processor

docs/common-practices/tutorial-roll-gestures.md

@@ -0,0 +1,47 @@
+---
+layout: default
+title: 'Creating Roll Gestures'
+parent: Common practices
+nav_order: 26
+---
+
+# Creating Roll Gestures
+
+The Puara **Roll** processor is a powerful tool for interpreting real-world motion as a rotational gesture. It intelligently combines data from multiple sensors to calculate a device's side-to-side tilt (its "roll" angle).
+
+This tutorial will guide you through a complete example. We will use a smartphone as a live sensor to provide data to the Roll processor and visualize its output, but the same principles apply to any hardware that provides accelerometer, gyroscope, and magnetometer data.
+
+### Part 1: Setting Up the Live Sensor Data
+
+To see the Roll processor in action, we first need a source of motion data. We'll use a smartphone app to stream sensor data over Wi-Fi. This tutorial uses **[Sensors2OSC](https://sensors2.org) (Android)**, but the setup is similar for iPhone apps like **[GyroOSC](https://www.bitshapesoftware.com/instruments/gyrosc/)**.
+
+1.  **Configure the App:** In the Sensors2OSC settings, set the **Host** to your computer's IP address and the **Port** to `9997`.
+    <img src="/assets/images/reference/processes/puara/sensors-to-osc-settings.jpeg" alt="Sensors2OSC Settings" width="40%">
+
+2.  **Enable Required Sensors:** On the app's main screen, enable the toggles for **Accelerometer**, **Gyroscope**, and **Magnetic Field**. Then, enable the main **Send data** toggle at the top.
+    <img src="/assets/images/reference/processes/puara/sensors-to-osc-main.jpeg" alt="Sensors Enabled" width="40%">
+
+3.  **Set up OSC in score:** In the Device Explorer, add a new OSC device. Set its **`score listening port`** to `9997`.
+    <img src="/assets/images/reference/processes/puara/score-to-osc-adddevice.png" alt="Add OSC Device" width="70%">
+
+4.  **Learn OSC Addresses:** Right-click the new OSC device and select `Learn`. Move your phone around until you see `/accelerometer`, `/gyroscope`, and `/magneticfield` appear, then click OK.
+    <img src="/assets/images/reference/processes/puara/score-to-osc-learn.png" alt="OSC Learning" width="50%">
+
+### Part 2: Building the Roll Gesture Patch
+
+Now that score is receiving sensor data, we can use our processor.
+
+1.  **Add Processes:** From the Process Library, add a `Gestures/Roll` processor and a `Monitoring/Signal display`.
+
+2.  **Connect Inputs:** Drag the learned OSC addresses from the Device Explorer directly onto the corresponding inputs of the Roll processor in the Inspector.
+    *   `/accelerometer` -> `Acceleration` input
+    *   `/gyroscope` -> `Gyroscope` input
+    *   `/magneticfield` -> `Magnetometer` input
+
+3.  **Visualize the Output:** Connect the `Output` of the Roll processor to the `Signal display`.
+
+4.  **Run and Test!** Run the scenario. As you tilt your phone side-to-side, you will see the signal display draw a curve representing the roll angle in radians. Experiment with the `Enable Smooth` and `Enable Unwrap` toggles to see how they provide a cleaner, more continuous gestural controller.
+
+<img src="/assets/images/reference/processes/puara/roll-processor-example.png" alt="Roll Processor Example" width="100%">
+
+You can download a complete example score here: [/assets/scores/reference/processes/RollExample.score](/assets/scores/reference/processes/RollExample.score)

docs/reference-manual/processes/library/puara-gestures.md

@@ -0,0 +1,56 @@
+---
+layout: default
+title: Puara Gestures
+parent: Processes
+grand_parent: Reference
+
+
+nav_order: 60
+---
+
+# Puara Gestures
+
+This section describes the processes ported from the [Puara-gestures](https://github.com/Puara/puara-gestures/) library. This library provides a powerful toolkit for creating and managing high-level gestural descriptors from sensor data.
+
+---
+
+## Leaky Integrator
+
+The **Leaky Integrator** process applies a smoothing algorithm to an input signal. It's particularly useful for reducing jitter from noisy sensors or creating smooth transitions in parameter values. The amount of smoothing can be controlled in real-time by adjusting the leak factor and the update frequency.
+
+### Parameters
+
+| Parameter               | Description                                                                                                                              |
+| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| **Inputs**              |                                                                                                                                          |
+| `Input`                 | The incoming signal to be smoothed.                                                                                                      |
+| `Leak Factor`           | A `float` from 0.0 to 1.0 that controls the amount of smoothing. A value of `0.0` means the output immediately jumps to the new input (no smoothing), while a value of `1.0` means the output does not change (full smoothing). Default is `0.5`. |
+| `Leak Frequency (Hz)`   | A `float` from 0.0 to 200.0 Hz that sets the rate at which the integrator updates its value. The control uses a logarithmic mapping for more intuitive musical control. Default is `100.0`. |
+| **Outputs**             |                                                                                                                                          |
+| `Output`                | The smoothed output signal.                                                                                                              |
+
+
+---
+
+## Roll
+
+The **Roll** process calculates the side-to-side tilt (roll angle) of a device. It uses a combination of accelerometer, gyroscope, and magnetometer data for a stable and accurate orientation reading. This is ideal for gestural control where you want to map the rotation of a device (like a phone) to a parameter.
+
+The process includes built-in options for transforming the output:
+- **Unwrap:** Prevents the angle from jumping when it crosses the -π to +π boundary, allowing for continuous rotation tracking.
+- **Smooth:** Averages recent values to reduce jitter from noisy sensors.
+- **Wrap:** Confines the final output to a specific range (e.g., 0 to 2π).
+
+### Parameters
+
+| Parameter          | Description                                                                                             |
+| :----------------- | :------------------------------------------------------------------------------------------------------ |
+| **Inputs**         |                                                                                                         |
+| `Acceleration`     | Expects 3D coordinate data (`{x, y, z}`) from an accelerometer.                                         |
+| `Gyroscope`        | Expects 3D coordinate data (`{x, y, z}`) from a gyroscope.                                              |
+| `Magnetometer`     | Expects 3D coordinate data (`{x, y, z}`) from a magnetometer.                                           |
+| `Enable Unwrap`    | A boolean toggle. When `true`, allows the output angle to increase or decrease indefinitely. Default is `true`.  |
+| `Enable Smooth`    | A boolean toggle. When `true`, applies a smoothing filter to the output. Default is `true`.                    |
+| `Enable Wrap`      | A boolean toggle. When `true`, wraps the final output to a specific range (e.g., 0 to 2π). Default is `false`. |
+| **Outputs**        |                                                                                                         |
+| `Output`           | The calculated roll angle in radians.                                                                   |