diff --git a/assets/images/reference/processes/puara/score-to-osc-adddevice.png b/assets/images/reference/processes/puara/score-to-osc-adddevice.png new file mode 100644 index 00000000..9b040cca Binary files /dev/null and b/assets/images/reference/processes/puara/score-to-osc-adddevice.png differ diff --git a/assets/images/reference/processes/puara/score-to-osc-learn-accelerometer.png b/assets/images/reference/processes/puara/score-to-osc-learn-accelerometer.png new file mode 100644 index 00000000..1c674bd5 Binary files /dev/null and b/assets/images/reference/processes/puara/score-to-osc-learn-accelerometer.png differ diff --git a/assets/images/reference/processes/puara/sensors-to-osc-main.jpeg b/assets/images/reference/processes/puara/sensors-to-osc-main.jpeg new file mode 100644 index 00000000..ba47b1aa Binary files /dev/null and b/assets/images/reference/processes/puara/sensors-to-osc-main.jpeg differ diff --git a/assets/images/reference/processes/puara/sensors-to-osc-settings.jpeg b/assets/images/reference/processes/puara/sensors-to-osc-settings.jpeg new file mode 100644 index 00000000..9fb6b345 Binary files /dev/null and b/assets/images/reference/processes/puara/sensors-to-osc-settings.jpeg differ diff --git a/assets/images/reference/processes/puara/shake-processor-example.png b/assets/images/reference/processes/puara/shake-processor-example.png new file mode 100644 index 00000000..a3eb7c39 Binary files /dev/null and b/assets/images/reference/processes/puara/shake-processor-example.png differ diff --git a/assets/scores/reference/processes/ShakeExample.score b/assets/scores/reference/processes/ShakeExample.score new file mode 100644 index 00000000..e5732bbf --- /dev/null +++ b/assets/scores/reference/processes/ShakeExample.score @@ -0,0 +1 @@ +{"Document":{"ObjectName":"Scenario::ScenarioDocumentModel","id":1,"BaseScenario":{"ObjectName":"Scenario::BaseScenario","id":0,"Constraint":{"ObjectName":"Scenario::IntervalModel","id":0,"Metadata":{"ScriptingName":"ShakeExample","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Audio in","Exposed":"audio in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Audio out","Exposed":"audio out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"Processes":[{"uuid":"9906e563-ddeb-4ecd-908c-952baee2a0a5","ObjectName":"SignalDisplay","id":2,"Metadata":{"ScriptingName":"Signal display","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Duration":10584000000,"Height":300.0,"StartOffset":0,"LoopDuration":10584000000,"Pos":[-298.67999999999995,-92.918],"Size":[582.0,314.0],"Loops":true,"Inlets":[{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":0,"Hidden":true,"Custom":"in","Exposed":"in","Value":{},"Init":{},"Domain":{}}],"Outlets":[{"uuid":"3620ea94-5991-41cf-89b3-11f842cc39d0","ObjectName":"Outlet","id":0,"Hidden":true,"Custom":"out","Exposed":"out","Value":{"Tuple":[{"Float":0.9585777521133423},{"Float":19.91214942932129}]},"Domain":{}}]},{"uuid":"de035912-5b03-49a8-bc4d-b2cba68e21d9","ObjectName":"Scenario","id":1,"Metadata":{"ScriptingName":"Scenario.1","Comment":"","Color":"Transparent1","Label":"","Touched":false},"Duration":10584000000,"Height":1500.0,"StartOffset":0,"LoopDuration":10584000000,"Pos":[-341.0,-459.0],"Size":[722.0,325.0],"Loops":false,"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"In","Exposed":"in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Out","Exposed":"out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"StartTimeNodeId":0,"StartEventId":0,"StartStateId":0,"Exclusive":false,"TimeNodes":[{"ObjectName":"Scenario::TimeSyncModel","id":0,"Metadata":{"ScriptingName":"Sync.start","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":0,"Events":[0],"MusicalSync":-1.0,"AutoTrigger":false,"Start":true,"Active":false,"Expression":" { true == false } "},{"ObjectName":"Scenario::TimeSyncModel","id":1,"Metadata":{"ScriptingName":"Sync.laue34","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":674044946,"Events":[1],"MusicalSync":-1.0,"AutoTrigger":false,"Start":false,"Active":false,"Expression":" { true == false } "},{"ObjectName":"Scenario::TimeSyncModel","id":2,"Metadata":{"ScriptingName":"Sync.axis84","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":10134166830,"Events":[2],"MusicalSync":-1.0,"AutoTrigger":false,"Start":false,"Active":false,"Expression":" { true == false } "}],"Events":[{"ObjectName":"Scenario::EventModel","id":0,"Metadata":{"ScriptingName":"Event.start","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":0,"States":[0],"Condition":"","Date":0,"Offset":0},{"ObjectName":"Scenario::EventModel","id":1,"Metadata":{"ScriptingName":"Event.lilt94","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":1,"States":[1],"Condition":"","Date":674044946,"Offset":0},{"ObjectName":"Scenario::EventModel","id":2,"Metadata":{"ScriptingName":"Event.omen13","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":2,"States":[2],"Condition":"","Date":10134166830,"Offset":0}],"States":[{"ObjectName":"Scenario::StateModel","id":0,"Metadata":{"ScriptingName":"State.start","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":0,"PreviousConstraint":null,"NextConstraint":1,"HeightPercentage":0.05466666666666667,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]},{"ObjectName":"Scenario::StateModel","id":1,"Metadata":{"ScriptingName":"State.zeta20","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":1,"PreviousConstraint":1,"NextConstraint":2,"HeightPercentage":0.05466666666666667,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]},{"ObjectName":"Scenario::StateModel","id":2,"Metadata":{"ScriptingName":"State.glut10","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":2,"PreviousConstraint":2,"NextConstraint":null,"HeightPercentage":0.05466666666666667,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]}],"Constraints":[{"ObjectName":"Scenario::IntervalModel","id":1,"Metadata":{"ScriptingName":"Interval.slab30","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Audio in","Exposed":"audio in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Audio out","Exposed":"audio out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"Processes":[],"SmallViewRack":[],"FullViewRack":[],"DefaultDuration":674044946,"MinDuration":674044946,"MaxDuration":674044946,"GuiDuration":741449440,"Speed":1.0,"Rigidity":true,"MinNull":false,"MaxInf":false,"Signatures":[],"StartState":0,"EndState":1,"StartDate":0,"HeightPercentage":0.05466666666666667,"NodalSlotHeight":100.0,"QuantizationRate":-1.0,"Zoom":-1.0,"Center":0,"ViewMode":0,"SmallViewShown":false,"HasSignature":false},{"ObjectName":"Scenario::IntervalModel","id":2,"Metadata":{"ScriptingName":"Shake","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Audio in","Exposed":"audio in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Audio out","Exposed":"audio out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"Processes":[{"uuid":"ecb5dc46-164c-46a0-a01e-90e3c3bd7527","ObjectName":"puara_shake","id":1,"Metadata":{"ScriptingName":"Shake","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Duration":9460121884,"Height":300.0,"StartOffset":0,"LoopDuration":7056000000,"Pos":[82.0,-3.0],"Size":[75.0,22.0],"Loops":false,"Inlets":[{"uuid":"769dd38a-bfb3-4dc6-b52a-b6abb7afe2a3","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Acceleration","Exposed":"acceleration","Address":"OSC:/accelerometer"},{"uuid":"edb5dc46-164c-46a0-a11e-90e3c3bd7527","ObjectName":"Inlet","id":1,"Hidden":true,"Custom":"Integrator Frequency (Hz)","Exposed":"integrator frequency (hz)","Value":{"Float":10.0},"Init":{"Float":10.0},"Domain":{"Float":{"Min":0.0,"Max":200.0}}},{"uuid":"82427d27-084a-4ab6-9c4e-db83929a1200","ObjectName":"Inlet","id":2,"Hidden":true,"Custom":"Fast Leak","Exposed":"fast leak","Value":{"Float":0.6000000238418579},"Init":{"Float":0.6000000238418579},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},{"uuid":"82427d27-084a-4ab6-9c4e-db83929a1200","ObjectName":"Inlet","id":3,"Hidden":true,"Custom":"Slow Leak","Exposed":"slow leak","Value":{"Float":0.30000001192092896},"Init":{"Float":0.30000001192092896},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},{"uuid":"82427d27-084a-4ab6-9c4e-db83929a1200","ObjectName":"Inlet","id":4,"Hidden":true,"Custom":"Activation Threshold","Exposed":"activation threshold","Value":{"Float":0.10000000149011612},"Init":{"Float":0.10000000149011612},"Domain":{"Float":{"Min":0.0,"Max":1.0}}}],"Outlets":[{"uuid":"cff96158-cc72-46d7-99dc-b6038171375b","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Output","Exposed":"output"}]}],"SmallViewRack":[{"Processes":[1],"Process":null,"Height":245.0,"Nodal":true}],"FullViewRack":[{"Process":0,"Nodal":true}],"DefaultDuration":9460121884,"MinDuration":9460121884,"MaxDuration":9460121884,"GuiDuration":9535372853,"Speed":1.0,"Rigidity":true,"MinNull":false,"MaxInf":false,"Signatures":[],"StartState":1,"EndState":2,"StartDate":674044946,"HeightPercentage":0.05466666666666667,"NodalSlotHeight":100.0,"QuantizationRate":-1.0,"Zoom":-1.0,"Center":0,"ViewMode":0,"SmallViewShown":true,"HasSignature":false}],"Comments":[]}],"SmallViewRack":[{"Processes":[2],"Process":2,"Height":200.0,"Nodal":false}],"FullViewRack":[{"Process":1,"Nodal":false},{"Process":2,"Nodal":false}],"DefaultDuration":10584000000,"MinDuration":10584000000,"MaxDuration":11113200000,"GuiDuration":11642400000,"Speed":1.0,"Rigidity":false,"MinNull":false,"MaxInf":true,"Signatures":[[0,[4,4]]],"StartState":0,"EndState":1,"StartDate":0,"HeightPercentage":0.0,"NodalSlotHeight":100.0,"QuantizationRate":-1.0,"Zoom":15120000.0,"Center":0,"ViewMode":1,"SmallViewShown":true,"HasSignature":true},"StartTimeNode":{"ObjectName":"Scenario::TimeSyncModel","id":0,"Metadata":{"ScriptingName":"Sync.start","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":0,"Events":[0],"MusicalSync":-1.0,"AutoTrigger":false,"Start":true,"Active":false,"Expression":" { true == false } "},"EndTimeNode":{"ObjectName":"Scenario::TimeSyncModel","id":1,"Metadata":{"ScriptingName":"Sync.end","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":10584000000,"Events":[1],"MusicalSync":-1.0,"AutoTrigger":false,"Start":false,"Active":true,"Expression":" { true == false } "},"StartEvent":{"ObjectName":"Scenario::EventModel","id":0,"Metadata":{"ScriptingName":"Event.start","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":0,"States":[0],"Condition":"","Date":0,"Offset":0},"EndEvent":{"ObjectName":"Scenario::EventModel","id":1,"Metadata":{"ScriptingName":"Event.end","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":1,"States":[1],"Condition":"","Date":10584000000,"Offset":0},"StartState":{"ObjectName":"Scenario::StateModel","id":0,"Metadata":{"ScriptingName":"State.start","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":0,"PreviousConstraint":null,"NextConstraint":0,"HeightPercentage":0.0,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]},"EndState":{"ObjectName":"Scenario::StateModel","id":1,"Metadata":{"ScriptingName":"State.end","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":1,"PreviousConstraint":0,"NextConstraint":null,"HeightPercentage":0.0,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]}},"Speed":1.0,"Cables":[{"ObjectName":"Process::Cable","id":1,"Type":0,"Source":[{"ObjectName":"Scenario::ScenarioDocumentModel","ObjectId":1},{"ObjectName":"Scenario::BaseScenario","ObjectId":0},{"ObjectName":"Scenario::IntervalModel","ObjectId":0},{"ObjectName":"Scenario","ObjectId":1},{"ObjectName":"Scenario::IntervalModel","ObjectId":2},{"ObjectName":"puara_shake","ObjectId":1},{"ObjectName":"Outlet","ObjectId":0}],"Sink":[{"ObjectName":"Scenario::ScenarioDocumentModel","ObjectId":1},{"ObjectName":"Scenario::BaseScenario","ObjectId":0},{"ObjectName":"Scenario::IntervalModel","ObjectId":0},{"ObjectName":"SignalDisplay","ObjectId":2},{"ObjectName":"Inlet","ObjectId":0}]}],"BusIntervals":[]},"Plugins":[{"uuid":"1f923578-08c3-49be-9ba9-69c144ee2e32","Refresh":false,"Reconnect":false,"MidiRatio":1.0},{"uuid":"6e610e1f-9de2-4c36-90dd-0ef570002a21","RootNode":{},"Children":[{"Device":{"Name":"OSC","Protocol":"9a42de4b-f6eb-4bca-9564-01b975f601b9","Config":{"Mode":1,"Version":0,"Framing":1,"Bundle":0,"Transport":{"UDP":{"Local":{"Bind":"0.0.0.0","Port":9997},"Remote":{"Host":"127.0.0.1","Port":9996,"Broadcast":false}}}}},"Children":[{"Address":{"ioType":"<->","ClipMode":"Free","RepetitionFilter":false,"Value":{"Vec3f":[-0.004788403399288654,0.2777273952960968,9.418789863586426]},"Domain":{},"Name":"accelerometer"}}]}]}],"Version":4,"Commit":"e7fcc31bb79d240c34f9a9d7bf1bc1a88a3eed89","Tag":"3.5.2"} \ No newline at end of file diff --git a/docs/common-practices/tutorial-shake-gestures.md b/docs/common-practices/tutorial-shake-gestures.md new file mode 100644 index 00000000..d06dbe3c --- /dev/null +++ b/docs/common-practices/tutorial-shake-gestures.md @@ -0,0 +1,51 @@ +--- +layout: default +title: 'Detecting Shake Gestures' +parent: Common practices +nav_order: 28 +--- + +# Detecting Shake Gestures + +The Puara **Shake** processor is designed to detect energetic shaking motions from a device. Unlike the `Roll` or `Tilt` processors, it only requires accelerometer data, making it a simple yet powerful tool for gestural interaction. + +This tutorial will show you how to set up the `Shake` processor using a smartphone as a sensor and how to tune its parameters to customize the gesture detection. + +### Part 1: Setting Up the Live Sensor Data + +We'll use a smartphone app to stream accelerometer data from a phone. 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`. + Sensors2OSC Settings + +2. **Enable the Accelerometer:** On the app's main screen, you only need to enable the **Accelerometer**. Then, enable the main **Send data** toggle at the top. + Sensors Enabled + +3. **Set up OSC in score:** In the Device Explorer, add a new OSC device and set its **`score listening port`** to `9997`. + +4. **Learn the OSC Address:** Right-click the new OSC device and select `Learn`. Shake your phone until you see the `/accelerometer` address appear, then click OK. + OSC Learning Accelerometer + *(Note: You can reuse the general learning image, but this one is more specific to the task)* + +### Part 2: Building the Shake Gesture Patch + +With the sensor data streaming, we can build our scenario. + +1. **Add Processes:** From the Process Library, add a `Gestures/Shake` processor and a `Monitoring/Signal display`. + +2. **Connect the Input:** Drag the `/accelerometer` address from the Device Explorer directly onto the `Acceleration` input of the Shake processor. + +3. **Visualize the Output:** Connect the `Output` of the Shake processor to the `Signal display`. + +4. **Run and Test!** Run the scenario. Shake your phone and watch the signal display. You'll see the output value rise and fall with your motion. + +Shake Processor Example + +### Part 3: Tuning the Response + +The power of the Shake processor lies in its parameters. Try adjusting them while the scenario is running: +* **Activation Threshold:** Increase this to make the detector less sensitive, requiring a more vigorous shake to trigger a response. +* **Fast Leak:** Lower this value to make the output rise much more sharply when you shake the device. +* **Slow Leak:** Lower this value to make the output drop to zero almost instantly when you stop shaking. Increase it to make the value fade out more slowly. + +You can download a complete example score here: [/assets/scores/reference/processes/ShakeExample.score](/assets/scores/reference/processes/ShakeExample.score) \ No newline at end of file diff --git a/docs/reference-manual/processes/library/puara-gestures.md b/docs/reference-manual/processes/library/puara-gestures.md new file mode 100644 index 00000000..ac93a510 --- /dev/null +++ b/docs/reference-manual/processes/library/puara-gestures.md @@ -0,0 +1,97 @@ +--- +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. | + + + +--- + +## Tilt + +The **Tilt** process calculates the forward-and-backward tilt (also known as "pitch") of a device. It uses a combination of accelerometer, gyroscope, and magnetometer data to provide a stable and accurate orientation reading. This is useful for gestural control where you want to map the forward/backward tilting of a device to a parameter. + +### 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. | +| **Outputs** | | +| `Output` | The calculated tilt (pitch) angle in radians, ranging from `-π/2` to `+π/2`. | + + + + +--- + +## Shake + +The **Shake** process detects shaking gestures from 3D accelerometer data. It calculates the overall magnitude of the shake, making it ideal for triggering events or controlling parameters based on energetic motion. The detection algorithm's sensitivity and response curve can be finely tuned using the provided parameters. + +### Parameters + +| Parameter | Description | +| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | +| **Inputs** | | +| `Acceleration` | Expects 3D coordinate data (`{x, y, z}`) from an accelerometer. | +| `Integrator Frequency (Hz)` | A `float` from 0.0 to 200.0 Hz that sets the update rate of the internal smoothing filter. Higher values are more responsive. Default is `10.0`. | +| `Fast Leak` | A `float` from 0.0 to 1.0. This controls how quickly the shake value increases when a shake is detected (i.e., when motion exceeds the `Activation Threshold`). A lower value means a faster rise. Default is `0.6`. | +| `Slow Leak` | A `float` from 0.0 to 1.0. This controls how quickly the shake value decays when the device is still. A lower value means a faster decay. Default is `0.3`. | +| `Activation Threshold` | A `float` from 0.0 to 1.0 that sets the motion sensitivity. Acceleration above this threshold is considered a shake. Default is `0.1`. | +| **Outputs** | | +| `Output` | The calculated shake magnitude, a single `float` value. | \ No newline at end of file