├── .github ├── PULL_REQUEST_TEMPLATE.md └── workflows │ └── auto-publish.yml ├── .gitignore ├── .pr-preview.json ├── CONTRIBUTING.md ├── LICENSE.md ├── README.md ├── a-rotation.png ├── b-rotation.png ├── c-rotation.png ├── equation1.png ├── equation1.xhtml ├── equation13a.png ├── equation13a.xhtml ├── equation14.png ├── equation14.xhtml ├── equation18.png ├── equation18.xhtml ├── equation2.png ├── equation2.xhtml ├── equation3.png ├── equation3.xhtml ├── equation4.png ├── equation4.xhtml ├── equation5a.png ├── equation5a.xhtml ├── equation5e.png ├── equation5e.xhtml ├── equation6.png ├── equation6.xhtml ├── equation7.png ├── equation7.xhtml ├── equation8a.png ├── equation8a.xhtml ├── equation8b.png ├── equation8b.xhtml ├── index.bs ├── security-privacy-self-assessment.md ├── spec-source-orientation.html ├── start.png └── w3c.json /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | Closes #??? 2 | 3 | The following tasks have been completed: 4 | 5 | * [ ] Modified Web platform tests (link to pull request) 6 | 7 | Implementation commitment: 8 | 9 | * [ ] Gecko (https://bugzilla.mozilla.org/show_bug.cgi?id=) 10 | * [ ] WebKit (https://bugs.webkit.org/show_bug.cgi?id=) 11 | * [ ] Chromium (https://bugs.chromium.org/p/chromium/issues/detail?id=) 12 | -------------------------------------------------------------------------------- /.github/workflows/auto-publish.yml: -------------------------------------------------------------------------------- 1 | # Workflow based on the w3c/spec-prod action example to deploy to W3C using Echidna: 2 | # https://github.com/w3c/spec-prod/blob/main/docs/examples.md#deploy-to-w3c-using-echidna 3 | 4 | name: CI 5 | 6 | on: 7 | pull_request: {} 8 | push: 9 | branches: [main] 10 | 11 | jobs: 12 | main: 13 | name: Build, Validate and Deploy 14 | runs-on: ubuntu-latest 15 | steps: 16 | - uses: actions/checkout@v2 17 | - uses: w3c/spec-prod@v2 18 | with: 19 | GH_PAGES_BRANCH: gh-pages 20 | W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }} 21 | # Replace following with appropriate value. See options.md for details. 22 | W3C_WG_DECISION_URL: https://lists.w3.org/Archives/Public/public-device-apis/2021May/0008.html 23 | W3C_BUILD_OVERRIDE: | 24 | status: CRD 25 | shortname: orientation-event 26 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | deploy_key 2 | -------------------------------------------------------------------------------- /.pr-preview.json: -------------------------------------------------------------------------------- 1 | { 2 | "src_file": "index.bs", 3 | "type": "bikeshed", 4 | "params": { 5 | "force": 1 6 | } 7 | } -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Contributions to this repository are intended to become part of Recommendation-track documents governed by the 2 | [W3C Patent Policy](https://www.w3.org/Consortium/Patent-Policy/) and 3 | [Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). 4 | To make substantive contributions to specifications, you must either participate 5 | in the relevant W3C Working Group or make a non-member patent licensing commitment. 6 | 7 | If you are not the sole contributor to a contribution (pull request), please identify all 8 | contributors in the pull request comment. 9 | 10 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 11 | 12 | ``` 13 | +@github_username 14 | ``` 15 | 16 | If you added a contributor by mistake, you can remove them in a comment with: 17 | 18 | ``` 19 | -@github_username 20 | ``` 21 | 22 | If you are making a pull request on behalf of someone else but you had no part in designing the 23 | feature, you can remove yourself with the above syntax. 24 | 25 | # Tests 26 | 27 | For normative changes, a corresponding 28 | [web-platform-tests](https://github.com/web-platform-tests/wpt) PR is highly appreciated. Typically, 29 | both PRs will be merged at the same time. Note that a test change that contradicts the spec should 30 | not be merged before the corresponding spec change. If testing is not practical, please explain why 31 | and if appropriate [file a web-platform-tests issue](https://github.com/web-platform-tests/wpt/issues/new) 32 | to follow up later. Add the `type:untestable` or `type:missing-coverage` label as appropriate. 33 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All documents in this Repository are licensed by contributors 2 | under the 3 | [W3C Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). 4 | 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Device Orientation and Motion Specification 2 | 3 | This is the repository in which the W3C's [Device Orientation and Motion](https://www.w3.org/TR/orientation-event/) specification is jointly maintained by the [Devices and Sensors Working Group](https://www.w3.org/groups/wg/das/) and the [Web Applications Working Group](https://www.w3.org/groups/wg/webapps/). 4 | 5 | ## Contributing to this specification 6 | 7 | Please see [CONTRIBUTING.md](CONTRIBUTING.md) 8 | -------------------------------------------------------------------------------- /a-rotation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/a-rotation.png -------------------------------------------------------------------------------- /b-rotation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/b-rotation.png -------------------------------------------------------------------------------- /c-rotation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/c-rotation.png -------------------------------------------------------------------------------- /equation1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation1.png -------------------------------------------------------------------------------- /equation1.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | v 4 | = 5 | 6 | 7 | 8 | 0 9 | 0 10 | -1 11 | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /equation13a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation13a.png -------------------------------------------------------------------------------- /equation13a.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | R 5 | = 6 | Z 7 | X 8 | Y 9 | = 10 | 11 | 12 | 13 | 14 | 15 | 16 | cos 17 | 18 | ( 19 | α 20 | ) 21 | 22 | 23 | 24 | cos 25 | 26 | ( 27 | γ 28 | ) 29 | 30 | 31 | - 32 | 33 | sin 34 | 35 | ( 36 | α 37 | ) 38 | 39 | 40 | 41 | sin 42 | 43 | ( 44 | β 45 | ) 46 | 47 | 48 | 49 | sin 50 | 51 | ( 52 | γ 53 | ) 54 | 55 | 56 | 57 | 58 | - 59 | 60 | cos 61 | 62 | ( 63 | β 64 | ) 65 | 66 | 67 | 68 | sin 69 | 70 | ( 71 | α 72 | ) 73 | 74 | 75 | 76 | 77 | 78 | cos 79 | 80 | ( 81 | γ 82 | ) 83 | 84 | 85 | 86 | sin 87 | 88 | ( 89 | α 90 | ) 91 | 92 | 93 | 94 | sin 95 | 96 | ( 97 | β 98 | ) 99 | 100 | 101 | + 102 | 103 | cos 104 | 105 | ( 106 | α 107 | ) 108 | 109 | 110 | 111 | sin 112 | 113 | ( 114 | γ 115 | ) 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | cos 124 | 125 | ( 126 | γ 127 | ) 128 | 129 | 130 | 131 | sin 132 | 133 | ( 134 | α 135 | ) 136 | 137 | 138 | + 139 | 140 | cos 141 | 142 | ( 143 | α 144 | ) 145 | 146 | 147 | 148 | sin 149 | 150 | ( 151 | β 152 | ) 153 | 154 | 155 | 156 | sin 157 | 158 | ( 159 | γ 160 | ) 161 | 162 | 163 | 164 | 165 | 166 | cos 167 | 168 | ( 169 | α 170 | ) 171 | 172 | 173 | 174 | cos 175 | 176 | ( 177 | β 178 | ) 179 | 180 | 181 | 182 | 183 | 184 | sin 185 | 186 | ( 187 | α 188 | ) 189 | 190 | 191 | 192 | sin 193 | 194 | ( 195 | γ 196 | ) 197 | 198 | 199 | - 200 | 201 | cos 202 | 203 | ( 204 | α 205 | ) 206 | 207 | 208 | 209 | cos 210 | 211 | ( 212 | γ 213 | ) 214 | 215 | 216 | 217 | sin 218 | 219 | ( 220 | β 221 | ) 222 | 223 | 224 | 225 | 226 | 227 | 228 | - 229 | 230 | cos 231 | 232 | ( 233 | β 234 | ) 235 | 236 | 237 | 238 | sin 239 | 240 | ( 241 | γ 242 | ) 243 | 244 | 245 | 246 | 247 | 248 | sin 249 | 250 | ( 251 | β 252 | ) 253 | 254 | 255 | 256 | 257 | 258 | cos 259 | 260 | ( 261 | β 262 | ) 263 | 264 | 265 | 266 | cos 267 | 268 | ( 269 | γ 270 | ) 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | -------------------------------------------------------------------------------- /equation14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation14.png -------------------------------------------------------------------------------- /equation14.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | q 5 | = 6 | 7 | 8 | 9 | 10 | 11 | 12 | q 13 | w 14 | 15 | 16 | 17 | 18 | 19 | 20 | q 21 | x 22 | 23 | 24 | 25 | 26 | 27 | 28 | q 29 | y 30 | 31 | 32 | 33 | 34 | 35 | 36 | q 37 | z 38 | 39 | 40 | 41 | 42 | 43 | 44 | = 45 | 46 | 47 | 48 | 49 | 50 | 51 | cos 52 | 53 | ( 54 | 55 | β 56 | 2 57 | 58 | ) 59 | 60 | 61 | 62 | cos 63 | 64 | ( 65 | 66 | γ 67 | 2 68 | 69 | ) 70 | 71 | 72 | 73 | cos 74 | 75 | ( 76 | 77 | α 78 | 2 79 | 80 | ) 81 | 82 | 83 | - 84 | 85 | sin 86 | 87 | ( 88 | 89 | β 90 | 2 91 | 92 | ) 93 | 94 | 95 | 96 | sin 97 | 98 | ( 99 | 100 | γ 101 | 2 102 | 103 | ) 104 | 105 | 106 | 107 | sin 108 | 109 | ( 110 | 111 | α 112 | 2 113 | 114 | ) 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | sin 123 | 124 | ( 125 | 126 | β 127 | 2 128 | 129 | ) 130 | 131 | 132 | 133 | cos 134 | 135 | ( 136 | 137 | γ 138 | 2 139 | 140 | ) 141 | 142 | 143 | 144 | cos 145 | 146 | ( 147 | 148 | α 149 | 2 150 | 151 | ) 152 | 153 | 154 | - 155 | 156 | cos 157 | 158 | ( 159 | 160 | β 161 | 2 162 | 163 | ) 164 | 165 | 166 | 167 | sin 168 | 169 | ( 170 | 171 | γ 172 | 2 173 | 174 | ) 175 | 176 | 177 | 178 | sin 179 | 180 | ( 181 | 182 | α 183 | 2 184 | 185 | ) 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | cos 194 | 195 | ( 196 | 197 | β 198 | 2 199 | 200 | ) 201 | 202 | 203 | 204 | sin 205 | 206 | ( 207 | 208 | γ 209 | 2 210 | 211 | ) 212 | 213 | 214 | 215 | cos 216 | 217 | ( 218 | 219 | α 220 | 2 221 | 222 | ) 223 | 224 | 225 | + 226 | 227 | sin 228 | 229 | ( 230 | 231 | β 232 | 2 233 | 234 | ) 235 | 236 | 237 | 238 | cos 239 | 240 | ( 241 | 242 | γ 243 | 2 244 | 245 | ) 246 | 247 | 248 | 249 | sin 250 | 251 | ( 252 | 253 | α 254 | 2 255 | 256 | ) 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | cos 265 | 266 | ( 267 | 268 | β 269 | 2 270 | 271 | ) 272 | 273 | 274 | 275 | cos 276 | 277 | ( 278 | 279 | γ 280 | 2 281 | 282 | ) 283 | 284 | 285 | 286 | sin 287 | 288 | ( 289 | 290 | α 291 | 2 292 | 293 | ) 294 | 295 | 296 | + 297 | 298 | sin 299 | 300 | ( 301 | 302 | β 303 | 2 304 | 305 | ) 306 | 307 | 308 | 309 | sin 310 | 311 | ( 312 | 313 | γ 314 | 2 315 | 316 | ) 317 | 318 | 319 | 320 | cos 321 | 322 | ( 323 | 324 | α 325 | 2 326 | 327 | ) 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | -------------------------------------------------------------------------------- /equation18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation18.png -------------------------------------------------------------------------------- /equation18.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | q 7 | w 8 | 2 9 | 10 | 11 | + 12 | 13 | 14 | q 15 | x 16 | 2 17 | 18 | 19 | + 20 | 21 | 22 | q 23 | y 24 | 2 25 | 26 | 27 | + 28 | 29 | 30 | q 31 | z 32 | 2 33 | 34 | 35 | = 36 | 1 37 | 38 | 39 | -------------------------------------------------------------------------------- /equation2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation2.png -------------------------------------------------------------------------------- /equation2.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | Z 4 | = 5 | 6 | 7 | 8 | 9 | cos(α) 10 | -sin(α) 11 | 0 12 | 13 | 14 | sin(α) 15 | cos(α) 16 | 0 17 | 18 | 19 | 0 20 | 0 21 | 1 22 | 23 | 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /equation3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation3.png -------------------------------------------------------------------------------- /equation3.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | X 4 | = 5 | 6 | 7 | 8 | 9 | 1 10 | 0 11 | 0 12 | 13 | 14 | 0 15 | cos(β) 16 | -sin(β) 17 | 18 | 19 | 0 20 | sin(β) 21 | cos(β) 22 | 23 | 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /equation4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation4.png -------------------------------------------------------------------------------- /equation4.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | Y 4 | = 5 | 6 | 7 | 8 | 9 | cos(γ) 10 | 0 11 | sin(γ) 12 | 13 | 14 | 0 15 | 1 16 | 0 17 | 18 | 19 | -sin(γ) 20 | 0 21 | cos(γ) 22 | 23 | 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /equation5a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation5a.png -------------------------------------------------------------------------------- /equation5a.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | v' = R v 4 | 5 | -------------------------------------------------------------------------------- /equation5e.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation5e.png -------------------------------------------------------------------------------- /equation5e.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | v' 4 | = 5 | 6 | 7 | 8 | 9 | - 10 | cos(α) 11 | sin(γ) 12 | - 13 | sin(α) 14 | sin(β) 15 | cos(γ) 16 | 17 | 18 | - 19 | sin(α) 20 | sin(γ) 21 | + 22 | cos(α) 23 | sin(β) 24 | cos(γ) 25 | 26 | 27 | -cos(β) 28 | cos(γ) 29 | 30 | 31 | 32 | 33 | 34 | -------------------------------------------------------------------------------- /equation6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation6.png -------------------------------------------------------------------------------- /equation6.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | θ 4 | = 5 | tan - 1 6 | 7 | 8 | v' x 9 | v' y 10 | 11 | 12 | = 13 | tan - 1 14 | 15 | 16 | 17 | - 18 | cos ( α ) 19 | sin ( γ ) 20 | - 21 | sin ( α ) 22 | sin ( β ) 23 | cos ( γ ) 24 | 25 | 26 | - 27 | sin ( α ) 28 | sin ( γ ) 29 | + 30 | cos ( α ) 31 | sin ( β ) 32 | cos ( γ ) 33 | 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /equation7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation7.png -------------------------------------------------------------------------------- /equation7.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | θ 4 | = 5 | tan - 1 6 | 7 | 8 | 9 | - 10 | sin ( α ) 11 | sin ( β ) 12 | 13 | 14 | cos ( α ) 15 | sin ( β ) 16 | 17 | 18 | 19 | = 20 | -α 21 | 22 | -------------------------------------------------------------------------------- /equation8a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation8a.png -------------------------------------------------------------------------------- /equation8a.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | θ 4 | = 5 | tan - 1 6 | 7 | 8 | 9 | - 10 | cos ( α ) 11 | sin ( γ ) 12 | - 13 | sin ( α ) 14 | cos ( γ ) 15 | 16 | 17 | - 18 | sin ( α ) 19 | sin ( γ ) 20 | + 21 | cos ( α ) 22 | cos ( γ ) 23 | 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /equation8b.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/equation8b.png -------------------------------------------------------------------------------- /equation8b.xhtml: -------------------------------------------------------------------------------- 1 | 2 | 3 | θ 4 | = 5 | tan - 1 6 | 7 | 8 | 9 | - 10 | sin ( α + γ ) 11 | 12 | 13 | cos ( α + γ ) 14 | 15 | 16 | 17 | = 18 | - ( α + γ ) 19 | 20 | -------------------------------------------------------------------------------- /index.bs: -------------------------------------------------------------------------------- 1 | 
   2 | Title: Device Orientation and Motion
   3 | Shortname: orientation-event
   4 | Level: none
   5 | Status: ED
   6 | Group: dap
   7 | TR: https://www.w3.org/TR/orientation-event/
   8 | ED: https://w3c.github.io/deviceorientation/
   9 | Repository: w3c/deviceorientation
  10 | Editor: Reilly Grant 83788, Google LLC https://www.google.com
  11 | Editor: Marcos Cáceres 39125, Apple Inc. https://www.apple.com
  12 | Former Editor: Raphael Kubo da Costa 95850, Intel Corporation https://intel.com
  13 | Former Editor: Rich Tibbett, Opera Software ASA
  14 | Former Editor: Tim Volodine, Google Inc
  15 | Former Editor: Steve Block, Google Inc until July 2012
  16 | Former Editor: Andrei Popescu, Google Inc until July 2012
  17 | Abstract: This specification defines events that represent the physical orientation and motion of a hosting device. These events provide web applications with access to orientation and motion data. The specification is designed to be agnostic to the underlying sources of this data, aiming to achieve interoperability across different environments.
  18 | Boilerplate: omit issues-index, repository-issue-tracking no
  19 | Include MDN Panels: if possible
  20 | Implementation Report: https://wpt.fyi/results/orientation-event
  21 | Issue Tracking: Device Orientation and Motion Repository https://github.com/w3c/deviceorientation/issues
  22 | Status Text: New features since publication as a [Candidate Recommendation](https://www.w3.org/TR/2016/CR-orientation-event-20160818/) include integration of Permissions Policy and API, which now requires explicit user consent through {{DeviceOrientationEvent/requestPermission()}} for accessing device orientation data. Updates have been made to the coordinate system explanations and precision requirements to mitigate passive fingerprinting risks. The introduction of the deviceorientationabsolute event enhances applications requiring absolute orientation data (marked [=at risk=]). Interfaces are now only available in [=secure contexts=], and security and privacy considerations have been made normative. The specification now also provides a means to [[#automation|automate testing]] of this API (marked [=at risk=]). See [[#changes]] section for more information.
  23 | Markup Shorthands: css no
  24 | Markup Shorthands: markdown yes
  25 | text macro: JOINT yes
  26 | text macro: JOINTWEBAPPS yes
  27 |
28 | 
  29 | urlPrefix: https://w3c.github.io/sensors/; spec: GENERIC-SENSOR
  30 |     type: dfn
  31 |         text: can provide readings flag; url: virtual-sensor-can-provide-readings-flag
  32 |         text: virtual sensor mapping; url: virtual-sensor-mapping
  33 | urlPrefix: https://w3c.github.io/webdriver/; spec: WEBDRIVER2
  34 |     type: dfn
  35 |         text: get a property; url: dfn-getting-properties
  36 |
37 | 38 | Introduction {#introduction} 39 | ============================ 40 | 41 | This section is non-normative. 42 | 43 | This specification provides two new DOM events for obtaining information about the physical orientation and movement of the hosting device. The information provided by the events is not raw sensor data, but rather high-level data which is agnostic to the underlying source of information. Common sources of information include gyroscopes, compasses and accelerometers. 44 | 45 | The {{deviceorientation}} event represents the physical orientation of the device, expressed as a series of rotations from a local coordinate frame. 46 | 47 | The {{devicemotion}} event represents the acceleration of the device, expressed in Cartesian coordinates in a coordinate frame defined in the device. It also supplies the rotation rate of the device about a local coordinate frame. Where practically possible, the event should provide the acceleration of the device's center of mass. 48 | 49 | The following code extracts illustrate basic use of the events. 50 | 51 |
52 | Registering to receive {{deviceorientation}} events: 53 | 
  54 | window.addEventListener("deviceorientation", event => {
  55 |   // process event.alpha, event.beta and event.gamma
  56 | });
  57 | 
  58 | // Alternatively...
  59 | window.ondeviceorientation = event => {
  60 |   // process event.alpha, event.beta and event.gamma
  61 | };
  62 |
63 |
64 | 65 |
66 | A device lying flat on a horizontal surface with the top of the screen pointing West has the following orientation: 67 | 
  68 | {
  69 |   alpha: 90,
  70 |   beta: 0,
  71 |   gamma: 0
  72 | };
  73 |
74 | To get the compass heading, one would simply subtract {{DeviceOrientationEvent/alpha}} from 360 degrees. As the device is turned on the horizontal surface, the compass heading is (360 - alpha). 75 |
76 | 77 |
78 | A user is holding the device in their hand, with the screen in a vertical plane and the top of the screen pointing upwards. The value of {{DeviceOrientationEvent/beta}} is 90, irrespective of what {{DeviceOrientationEvent/alpha}} and {{DeviceOrientationEvent/gamma}} are. 79 |
80 | 81 |
82 | A user facing a compass heading of alpha degrees is holding the device in their hand, with the screen in a vertical plane and the top of the screen pointing to their right. The orientation of the device is: 83 | 
  84 | {
  85 |   alpha: 270 - alpha,
  86 |   beta: 0,
  87 |   gamma: 90
  88 | };
  89 |
90 |
91 | 92 |
93 | Registering to receive {{devicemotion}} events: 94 | 
  95 | window.addEventListener("devicemotion", (event) => {
  96 |   // Process event.acceleration, event.accelerationIncludingGravity,
  97 |   // event.rotationRate and event.interval
  98 | });
  99 | 
 100 | // Alternatively...
 101 | window.ondevicemotion = (event) => {
 102 |   // Process event.acceleration, event.accelerationIncludingGravity,
 103 |   // event.rotationRate and event.interval
 104 | };
 105 |
106 |
107 | 108 |
109 | A device lying flat on a horizontal surface with the screen upmost has an {{DeviceMotionEvent/acceleration}} of zero and the following value for {{DeviceMotionEvent/accelerationIncludingGravity}}: 110 | 
 111 | {
 112 |   x: 0,
 113 |   y: 0,
 114 |   z: 9.8
 115 | };
 116 |
117 |
118 | 119 |
120 | A device in free-fall, with the screen horizontal and upmost, has an {{DeviceMotionEvent/accelerationIncludingGravity}} of zero and the following value for acceleration: 121 | 
 122 | {
 123 |   x: 0,
 124 |   y: 0,
 125 |   z: -9.8
 126 | };
 127 |
128 |
129 | 130 |
131 | A device is mounted in a vehicle, with the screen in a vertical plane, the top uppermost and facing the rear of the vehicle. The vehicle is travelling at speed v around a right-hand bend of radius r. The device records a positive x component for both {{DeviceMotionEvent/acceleration}} and {{DeviceMotionEvent/accelerationIncludingGravity}}. The device also records a negative value for {{DeviceMotionEvent/rotationRate!!attribute}}.{{DeviceMotionEventRotationRate/gamma}}: 132 | 
 133 | {
 134 |   acceleration: {x: v^2/r, y: 0, z: 0},
 135 |   accelerationIncludingGravity: {x: v^2/r, y: 9.8, z: 0},
 136 |   rotationRate: {alpha: 0, beta: 0, gamma: -v/r*180/pi}
 137 | };
 138 |
139 |
140 | 141 | Scope {#scope} 142 | ============== 143 | 144 | This section is non-normative. 145 | 146 | Within the scope of this specification are events that represent the physical orientation and motion of the hosting device. Out of scope are utilities for manipulating orientation data, such as transformation libraries, and providing access to raw sensor data or methods for directly interfacing with these sensors. 147 | 148 | Model {#model} 149 | ===== 150 | 151 | Device Orientation {#device-orientation-model} 152 | ------------------ 153 | 154 | This specification expresses a device's physical orientation as a series of rotations relative to an [=implementation-defined=] reference coordinate frame. 155 | 156 | The sequence of rotation steps is a set of intrinsic Tait-Bryan angles of type Z - X' - Y'' ([[EULERANGLES]]) that are applied on the [=device coordinate system=] defined in [[!ACCELEROMETER]] and summarized below: 157 | 158 | * x is in the plane of the screen or keyboard and is positive towards the right hand side of the screen or keyboard. 159 | * y is in the plane of the screen or keyboard and is positive towards the top of the screen or keyboard. 160 | * z is perpendicular to the screen or keyboard, positive out of the screen or keyboard. 161 | 162 | For a mobile device such as a phone or tablet, the device coordinate frame is defined relative to the screen in its standard orientation, typically portrait. This means that slide-out elements such as keyboards are not deployed, and swiveling elements such as displays are folded to their default position. 163 | 164 | If the orientation of the screen changes when the device is rotated or a slide-out keyboard is deployed, this does not affect the orientation of the coordinate frame relative to the device. 165 | 166 | For a laptop computer, the device coordinate frame is defined relative to the integrated keyboard. 167 | 168 | Note: Developers wanting to detect changes in screen orientation can refer to [[SCREEN-ORIENTATION]]. 169 | 170 | Rotations use the right-hand convention, such that positive rotation around an axis is clockwise when viewed along the positive direction of the axis. 171 | 172 | Note: The coordinate system used by this specification differs from [[css-transforms-2#transform-rendering]], where the y axis is positive to the bottom and rotations follow the left-hand convention. 173 | Additionally, {{DOMMatrix/rotateSelf()}} and {{DOMMatrixReadOnly/rotate()}}, specified in [[GEOMETRY-1]], apply rotations in an Z - Y' - X'' order, which differs from the order specified here. 174 | 175 | A rotation represented by {{DeviceOrientationEvent/alpha}}, {{DeviceOrientationEvent/beta}} and {{DeviceOrientationEvent/gamma}} is carried out by the following steps: 176 | 177 | 1. Rotate the device frame around its [=Device Orientation/z=] axis by {{DeviceOrientationEvent/alpha}} degrees, with {{DeviceOrientationEvent/alpha}} in [0, 360). 178 |
179 | start orientation 180 |
Device in the initial position, with the reference (XYZ) and body (xyz) frames aligned.
181 |
182 |
183 | rotation about z axis 184 |
Device rotated through angle alpha about z axis, with previous locations of x and y axes shown as x0 and y0.
185 |
186 | 1. Rotate the device frame around its [=Device Orientation/x=] axis by {{DeviceOrientationEvent/beta}} degrees, with {{DeviceOrientationEvent/beta}} in [-180, 180). 187 |
188 | rotation about x axis 189 |
Device rotated through angle beta about new x axis, with previous locations of y and z axes shown as y0 and z0.
190 |
191 | 1. Rotate the device frame around its [=Device Orientation/y=] axis by {{DeviceOrientationEvent/gamma}} degrees, with {{DeviceOrientationEvent/gamma}} in [-90, 90). 192 |
193 | rotation about y axis 194 |
Device rotated through angle gamma about new y axis, with previous locations of x and z axes shown as x0 and z0.
195 |
196 | 197 | Note: This choice of angles follows mathematical convention, but means that alpha is in the opposite sense to a compass heading. It also means that the angles do not match the roll-pitch-yaw convention used in vehicle dynamics. 198 | 199 | ### Choice of reference coordinate system ### {#choice-of-reference-coordinate-system} 200 | 201 | A device's orientation is always relative to another coordinate system, whose choice influences the kind of information that the orientation conveys as well as the source of the orientation data. 202 | 203 | Relative device orientation is measured with an accelerometer and a gyroscope, and the reference coordinate system is arbitrary. Consequently, the orientation data provides information about changes relative to the initial position of the device. 204 | 205 | Note: In native platform terms, this is similar to a relative OrientationSensor on Windows, a game rotation vector sensor on Android, or the xArbitraryZVertical option for Core Motion. 206 | 207 | Absolute orientation is measured with an accelerometer, a gyroscope and a magnetometer, and the reference coordinate system is the Earth's reference coordinate system. 208 | 209 | Note: In native platform terms, this is similar to an absolute OrientationSensor on Windows, a rotation vector sensor on Android, or the xMagneticNorthZVertical option for Core Motion. 210 | 211 | Device Motion {#device-motion-model} 212 | ------------- 213 | 214 | This specification expresses a device's motion in space by measuring its acceleration and rotation rate, which are obtained from an accelerometer and a gyroscope. The data is provided relative to the [=device coordinate system=] summarized in the previous section. 215 | 216 | Acceleration is the rate of change of velocity of a device with respect to time. Is is expressed in meters per second squared (m/s2). 217 | 218 | Linear device acceleration represents the device's acceleration rate without the contribution of the gravity force. When the device is laying flat on a table, its linear acceleration is 0 m/s2. 219 | 220 | When the acceleration includes gravity, its value includes the effect of gravity and represents proper acceleration ([[PROPERACCELERATION]]). When the device is in free-fall, the acceleration is 0 m/s2. This is less useful in many applications but is provided as a means of providing best-effort support by implementations that are unable to provide linear acceleration (due, for example, to the lack of a gyroscope). 221 | 222 | Note: In practice, acceleration with gravity represents the raw readings obtained from an [[MOTION-SENSORS#accelerometer]], or the [[G-FORCE]] whereas linear acceleration provides the readings of a [[MOTION-SENSORS#linear-acceleration-sensor]] and is likely a fusion sensor. [[MOTION-SENSORS]] and [[ACCELEROMETER]] both contain a more detailed discussion about the different types of accelerometers and accelerations that can be measured. 223 | 224 | The rotation rate measures the rate at which the device rotates about a specified axis in the [=device coordinate system=]. As with device orientation, rotations must use the right-hand convention, such that positive rotation around an axis is clockwise when viewed along the positive direction of the axis. The [=rotation rate=] is measured in degrees per second (deg/s). 225 | 226 | Note: [[MOTION-SENSORS]] and [[GYROSCOPE]] both contain a more detailed discussion of gyroscopes, rotation rates and measurements. 227 | 228 | Permissions {#permissions-integration} 229 | ============================== 230 | 231 |
232 | This integration is [=at risk=] due to the low pass rate of the DeviceMotionEvent.requestPermission() and DeviceOrientationEvent.requestPermission() tests. 233 |
234 | 235 | This specification is a [=powerful feature=] and, as such, it defines the following [=permissions=] which are [=policy-controlled features=] with the given [=default allowlists=]: 236 | 237 | - "accelerometer", whose [=default allowlist=] is [=default allowlist/'self'=]. 238 | - "gyroscope", whose [=default allowlist=] is [=default allowlist/'self'=]. 239 | - "magnetometer", whose [=default allowlist=] is [=default allowlist/'self'=]. 240 | 241 |
242 | Note: Which events get [=dispatched=] depends on which [=permissions=] have been [=permission/granted=]: 243 | 244 | - When providing relative orientation data, the deviceorientation event is only [=dispatched=] if the "accelerometer" and "gyroscope" [=permissions=] are [=permission/granted=]. For the implementation to fall back to absolute orientation data, the "magnetometer" [=permission=] must also be [=permission/granted=]. 245 | - The deviceorientationabsolute event is only [=dispatched=] if the "accelerometer", "gyroscope", and "magnetometer" [=permissions=] are [=permission/granted=]. 246 | - The devicemotion event is only [=dispatched=] if the "accelerometer" and "gyroscope" [=permissions=] are [=permission/granted=]. 247 |
248 | 249 | Task Source {#taks-source} 250 | =========== 251 | 252 | The [=task source=] for the [=tasks=] mentioned in this specification is the device motion and orientation task source. 253 | 254 | API {#api} 255 | ========================== 256 | 257 |

deviceorientation Event

258 | 259 | 
 260 | partial interface Window {
 261 |     [SecureContext] attribute EventHandler ondeviceorientation;
 262 | };
 263 | 
 264 | [Exposed=Window, SecureContext]
 265 | interface DeviceOrientationEvent : Event {
 266 |     constructor(DOMString type, optional DeviceOrientationEventInit eventInitDict = {});
 267 |     readonly attribute double? alpha;
 268 |     readonly attribute double? beta;
 269 |     readonly attribute double? gamma;
 270 |     readonly attribute boolean absolute;
 271 | 
 272 |     static Promise<PermissionState> requestPermission(optional boolean absolute = false);
 273 | };
 274 | 
 275 | dictionary DeviceOrientationEventInit : EventInit {
 276 |     double? alpha = null;
 277 |     double? beta = null;
 278 |     double? gamma = null;
 279 |     boolean absolute = false;
 280 | };
 281 |
282 | 283 | The ondeviceorientation attribute is an [=event handler IDL attribute=] for the ondeviceorientation [=event handler=], whose [=event handler event type=] is deviceorientation. 284 | 285 | The alpha attribute must return the value it was initialized to. It represents the rotation around the Z axis in the Z - X' - Y'' intrinsic Tait-Bryan angles described in [[#device-orientation-model]]. 286 | 287 | The beta attribute must return the value it was initialized to. It represents the rotation around the X' axis (produced after the rotation around the Z axis has been applied) axis in the Z - X' - Y'' intrinsic Tait-Bryan angles described in [[#device-orientation-model]]. 288 | 289 | The gamma attribute must return the value it was initialized to. It represents the rotation around the Y'' axis (produced after the rotation around the Z and X' axes have been applied in this order) in the Z - X' - Y'' intrinsic Tait-Bryan angles described in [[#device-orientation-model]]. 290 | 291 | The absolute attribute must return the value it was initialized to. It indicates whether [=relative orientation=] or [=absolute orientation=] data is being provided. 292 | 293 |
294 | The requestPermission(|absolute|) method steps are: 295 | 296 | 1. Let |global| be the [=current global object=]. 297 | 1. Let |hasTransientActivation| be true if [=this=]'s [=relevant global object=] has [=transient activation=], and false otherwise. 298 | 1. Let |promise| be [=a new promise=] in [=this=]'s [=relevant Realm=]. 299 | 1. Let |permissions| be « "accelerometer", "gyroscope" ». 300 | 1. If |absolute| is true, [=set/append=] "magnetometer" » to |permissions|. 301 | 1. Run these steps in parallel: 302 | 1. [=list/For each=] |name| of |permissions|: 303 | 1. If |name|'s [=permission state=] is "{{PermissionState/prompt}}" and |hasTransientActivation| is false: 304 | 1. [=Queue a global task=] on the [=device motion and orientation task source=] given |global| to [=reject=] |promise| with a "{{NotAllowedError}}" {{DOMException}}. 305 | 1. Return. 306 | 1. Let |permissionState| be "{{PermissionState/granted}}". 307 | 1. [=list/For each=] |name| of |permissions|: 308 | 309 | Note: There is no algorithm for requesting multiple permissions at once. However, user agents are encouraged to bundle concurrent requests for different kinds of media into a single user-facing permission prompt. 310 | 311 | 1. If the result of requesting permission to use |name| is not "{{PermissionState/granted}}": 312 | 1. Set |permissionState| to "{{PermissionState/denied}}". 313 | 1. [=Break=]. 314 | 1. [=Queue a global task=] on the [=device motion and orientation task source=] given |global| to [=resolve=] |promise| with |permissionState|. 315 | 1. Return |promise|. 316 | 317 |
318 | 319 |
320 | To fire an orientation event given a {{DOMString}} |event|, {{Window}} |window| and {{boolean}} |absolute|: 321 | 322 | 1. Let |orientation| be null. 323 | 1. Let |topLevelTraversable| be |window|'s [=Window/navigable=]'s [=navigable/top-level traversable=]. 324 | 1. Let |virtualSensorType| be "relative-orientation" if |absolute| is false, and "absolute-orientation" otherwise. 325 | 1. If |topLevelTraversable|'s virtual sensor mapping contains |virtualSensorType|: 326 | 1. Let |virtualSensor| be |topLevelTraversable|'s virtual sensor mapping[|virtualSensorType|]. 327 | 1. If |virtualSensor|'s can provide readings flag is true: 328 | 1. Set |orientation| to the latest readings provided to |virtualSensor| with the "alpha", "beta", and "gamma" keys. 329 | 1. Otherwise: 330 | 1. If |absolute| is false: 331 | 1. Set |orientation| to the device's [=relative orientation=] in the tridimensional plane. 332 | 1. Otherwise: 333 | 1. Set |orientation| to the device's [=absolute orientation=] in the tridimensional plane. 334 | 1. Let |permissions| be null. 335 | 1. If |absolute| is false: 336 | 1. Set |permissions| to « "accelerometer", "gyroscope" ». 337 | 1. Otherwise: 338 | 1. Set |permissions| to « "accelerometer", "gyroscope", "magnetometer" ». 339 | 1. Let |environment| be |window|'s relevant settings object. 340 | 1. Run these steps in parallel: 341 | 1. [=list/For each=] |permission| in |permissions|: 342 | 1. Let |state| be the result of getting the current permission state with |permission| and |environment|. 343 | 1. If |state| is not "{{PermissionState/granted}}", return. 344 | 1. [=Queue a global task=] on the [=device motion and orientation task source=] given |window| to run the following steps: 345 | 1. Let |z| be |orientation|'s representation as intrinsic Tait-Bryan angles Z - X' - Y'' along the Z axis, or null if the implementation cannot provide an angle value. 346 | 1. If |z| is not null, limit |z|'s precision to 0.1 degrees. 347 | 1. Let |x| be |orientation|'s representation as intrinsic Tait-Bryan angles Z - X' - Y'' along the X' axis, or null if the implementation cannot provide an angle value. 348 | 1. If |x| is not null, limit |x|'s precision to 0.1 degrees. 349 | 1. Let |y| be |orientation|'s representation as intrinsic Tait-Bryan angles Z - X' - Y'' along the Y'' axis, or null if the implementation cannot provide an angle value. 350 | 1. If |y| is not null, limit |y|'s precision to 0.1 degrees. 351 | 1. [=Fire an event=] named |event| at |window|, using {{DeviceOrientationEvent}}, with the {{DeviceOrientationEvent/alpha}} attribute initialized to |z|, the {{DeviceOrientationEvent/beta}} attribute initialized to |x|, the {{DeviceOrientationEvent/gamma}} attribute initialized to |y|, and the {{DeviceOrientationEvent/absolute}} attribute initialized to |absolute|. 352 | 353 |
354 | 355 | A significant change in orientation indicates a difference in orientation values compared to the previous ones that warrants the firing of a deviceorientation or deviceorientationabsolute event. The process of determining whether a [=significant change in orientation=] has occurred is implementation-defined, though a maximum threshold for change of 1 degree is recommended. Implementations may also consider that it has occurred if they have reason to believe that the page does not have sufficiently fresh data. 356 | 357 | Note: Implementations must take [[#automation]] into account to determine whether a [=significant change in orientation=] has occurred, so that a virtual sensor reading update causes it to be assessed. 358 | 359 |
360 | Whenever a [=significant change in orientation=] occurs, the user agent must execute the following steps on a [=/navigable=]'s [=navigable/active window=] |window|: 361 | 362 | 1. Let |document| be |window|'s [=associated Document=]. 363 | 1. If |document|'s [=Document/visibility state=] is not `"visible"`, return. 364 | 1. Let |absolute| be false. 365 | 1. Let |features| be « "accelerometer", "gyroscope" ». 366 | 1. If the implementation cannot provide [=relative orientation=] or the resulting [=absolute orientation=] data is more accurate: 367 | 1. Set |absolute| to true. 368 | 1. [=list/Append=] "magnetometer" to |features|. 369 | 1. [=list/For each=] |feature| of |features|: 370 | 1. If |document| is not [=allowed to use=] |feature|, return. 371 | 1. [=Fire an orientation event=] with deviceorientation, |window|, and |absolute|. 372 | 373 |
374 | 375 | 379 | If an implementation can never provide orientation information, the event should be fired with the {{DeviceOrientationEvent/alpha}}, {{DeviceOrientationEvent/beta}} and {{DeviceOrientationEvent/gamma}} attributes set to null, and the {{DeviceOrientationEvent/absolute}} attribute set to false. 380 | 381 |

deviceorientationabsolute Event

382 | 383 |
384 | The {{deviceorientationabsolute}} event and its {{Window/ondeviceorientationabsolute}} event handler IDL attribute are [=at risk=] due to limited implementation experience. 385 |
386 | 387 | 
 388 | partial interface Window {
 389 |     [SecureContext] attribute EventHandler ondeviceorientationabsolute;
 390 | };
 391 |
392 | 393 | The ondeviceorientationabsolute attribute is an [=event handler IDL attribute=] for the ondeviceorientationabsolute [=event handler=], whose [=event handler event type=] is deviceorientationabsolute. 394 | 395 | A deviceorientationabsolute event is completely analogous to the deviceorientation event, except that it must always provide [=absolute orientation=] data. 396 | 397 |
398 | Whenever a [=significant change in orientation=] occurs, the user agent must execute the following steps on a [=/navigable=]'s [=navigable/active window=] |window|: 399 | 400 | 1. [=Fire an orientation event=] with deviceorientationabsolute, |window|, and true. 401 | 402 |
403 | 404 | 408 | If an implementation can never provide absolute orientation information, the event should be fired with the {{DeviceOrientationEvent/alpha}}, {{DeviceOrientationEvent/beta}} and {{DeviceOrientationEvent/gamma}} attributes set to null, and the {{DeviceOrientationEvent/absolute}} attribute set to true. 409 | 410 |

devicemotion Event

411 | 412 | ### The DeviceMotionEventAcceleration interface ### {#device-motion-event-acceleration-api} 413 | 414 | 
 415 | [Exposed=Window, SecureContext]
 416 | interface DeviceMotionEventAcceleration {
 417 |     readonly attribute double? x;
 418 |     readonly attribute double? y;
 419 |     readonly attribute double? z;
 420 | };
 421 |
422 | 423 | The {{DeviceMotionEventAcceleration}} interface represents the device's acceleration as described in [[#device-motion-model]]. It has the following associated data: 424 | 425 | : x axis acceleration 426 | :: The device's acceleration rate along the X axis, or null. It is initially null. 427 | : y axis acceleration 428 | :: The device's acceleration rate along the Y axis, or null. It is initially null. 429 | : z axis acceleration 430 | :: The device's acceleration rate along the Z axis, or null. It is initially null. 431 | 432 | The x getter steps are to return the value of [=this=]'s [=DeviceMotionEventAcceleration/x axis acceleration=]. 433 | 434 | The y getter steps are to return the value of [=this=]'s [=DeviceMotionEventAcceleration/y axis acceleration=]. 435 | 436 | The z getter steps are to return the value of [=this=]'s [=DeviceMotionEventAcceleration/z axis acceleration=]. 437 | 438 | ### The DeviceMotionEventRotationRate interface ### {#device-motion-event-rotation-rate-api} 439 | 440 | 
 441 | [Exposed=Window, SecureContext]
 442 | interface DeviceMotionEventRotationRate {
 443 |     readonly attribute double? alpha;
 444 |     readonly attribute double? beta;
 445 |     readonly attribute double? gamma;
 446 | };
 447 |
448 | 449 | The {{DeviceMotionEventRotationRate}} interface represents the device's [=rotation rate=] as described in [[#device-motion-model]]. It has the following associated data: 450 | 451 | : x axis rotation rate 452 | :: The device's rotation rate about the X axis, or null. It is initially null. 453 | : y axis rotation rate 454 | :: The device's rotation rate about the Y axis, or null. It is initially null. 455 | : z axis rotation rate 456 | :: The device's rotation rate about the Z axis, or null. It is initially null. 457 | 458 | The alpha getter steps are to return the value of [=this=]'s x axis rotation rate. 459 | 460 | The beta getter steps are to return the value of [=this=]'s y axis rotation rate. 461 | 462 | The gamma getter steps are to return the value of [=this=]'s z axis rotation rate. 463 | 464 | ### The DeviceMotionEvent interface ### {#device-motion-event-api} 465 | 466 | 
 467 | partial interface Window {
 468 |     [SecureContext] attribute EventHandler ondevicemotion;
 469 | };
 470 | 
 471 | [Exposed=Window, SecureContext]
 472 | interface DeviceMotionEvent : Event {
 473 |     constructor(DOMString type, optional DeviceMotionEventInit eventInitDict = {});
 474 |     readonly attribute DeviceMotionEventAcceleration? acceleration;
 475 |     readonly attribute DeviceMotionEventAcceleration? accelerationIncludingGravity;
 476 |     readonly attribute DeviceMotionEventRotationRate? rotationRate;
 477 |     readonly attribute double interval;
 478 | 
 479 |     static Promise<PermissionState> requestPermission();
 480 | };
 481 | 
 482 | dictionary DeviceMotionEventAccelerationInit {
 483 |     double? x = null;
 484 |     double? y = null;
 485 |     double? z = null;
 486 | };
 487 | 
 488 | dictionary DeviceMotionEventRotationRateInit {
 489 |     double? alpha = null;
 490 |     double? beta = null;
 491 |     double? gamma = null;
 492 | };
 493 | 
 494 | dictionary DeviceMotionEventInit : EventInit {
 495 |     DeviceMotionEventAccelerationInit acceleration;
 496 |     DeviceMotionEventAccelerationInit accelerationIncludingGravity;
 497 |     DeviceMotionEventRotationRateInit rotationRate;
 498 |     double interval = 0;
 499 | };
 500 |
501 | 502 | The ondevicemotion attribute is an [=event handler IDL attribute=] for the ondevicemotion [=event handler=], whose [=event handler event type=] is devicemotion. 503 | 504 | 507 | 508 | The acceleration attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to null. It represents the device's linear acceleration. 509 | 510 | The accelerationIncludingGravity attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to null. It represents the device's acceleration with gravity. 511 | 512 | The rotationRate attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to null. It represents the device's [=rotation rate=]. 513 | 514 | The interval attribute must return the value it was initialized to. It represents the interval at which data is obtained from the underlying hardware and must be expressed in milliseconds (ms). It is constant to simplify filtering of the data by the Web application. 515 | 516 |
517 | The requestPermission() method steps are: 518 | 519 | 1. Let |global| be the [=current global object=]. 520 | 1. Let |hasTransientActivation| be true if [=this=]'s [=relevant global object=] has [=transient activation=], and false otherwise. 521 | 1. Let |result| be [=a new promise=] in [=this=]'s [=relevant Realm=]. 522 | 1. Run these steps in parallel: 523 | 1. Let |permissions| be « "accelerometer", "gyroscope" ». 524 | 1. [=list/For each=] |name| of |permissions|: 525 | 1. If |name|'s permission state is "{{PermissionState/prompt}}" and |hasTransientActivation| is false: 526 | 1. [=Queue a global task=] on the [=device motion and orientation task source=] given |global| to [=reject=] |result| with a "{{NotAllowedError}}" {{DOMException}}. 527 | 1. Return. 528 | 1. Let |permissionState| be "{{PermissionState/granted}}". 529 | 1. [=list/For each=] |name| of |permissions|: 530 | 531 | Note: There is no algorithm for requesting multiple permissions at once. However, user agents are encouraged to bundle concurrent requests for different kinds of media into a single user-facing permission prompt. 532 | 533 | 1. If the result of requesting permission to use |name| is not "{{PermissionState/granted}}": 534 | 1. Set |permissionState| to "{{PermissionState/denied}}". 535 | 1. [=Break=]. 536 | 1. [=Queue a global task=] on the [=device motion and orientation task source=] given |global| to [=resolve=] |result| with |permissionState|. 537 | 1. Return |result|. 538 | 539 |
540 | 541 |
542 | At an [=implementation-defined=] interval |interval|, the user agent must execute the following steps on a [=/navigable=]'s [=navigable/active window=] |window|: 543 | 544 | 1. Let |document| be |window|'s [=associated Document=]. 545 | 1. If |document|'s [=Document/visibility state=] is not "`visible`", return. 546 | 1. [=list/For each=] |policy| of « "accelerometer", "gyroscope" »: 547 | 1. If |document| is not [=allowed to use=] the [=policy-controlled feature=] named |policy|, return. 548 | 1. Let |topLevelTraversable| be |window|'s [=Window/navigable=]'s [=navigable/top-level traversable=]. 549 | 1. Let |platformLinearAcceleration| be null. 550 | 1. If |topLevelTraversable|'s [=virtual sensor mapping=] [=map/contains=] "`linear-acceleration`": 551 | 1. Let |virtualSensor| be |topLevelTraversable|'s [=virtual sensor mapping=]["`linear-acceleration`"]. 552 | 1. If |virtualSensor|'s [=can provide readings flag=] is true, then set |platformLinearAcceleration| to the latest readings provided to |virtualSensor|. 553 | 1. Otherwise, if the implementation is able to provide [=linear acceleration=]: 554 | 1. Set |platformLinearAcceleration| to the device's [=linear acceleration=] along the X, Y and Z axes. 555 | 1. Let |acceleration| be null. 556 | 1. If |platformLinearAcceleration| is not null: 557 | 1. Set |acceleration| to a [=new=] {{DeviceMotionEventAcceleration}} created in |window|'s [=global object/realm=]. 558 | 1. Set |acceleration|'s [=DeviceMotionEventAcceleration/x axis acceleration=] to |platformLinearAcceleration|'s value along the X axis, or null if it cannot be provided. 559 | 1. If |acceleration|'s [=DeviceMotionEventAcceleration/x axis acceleration=] is not null, limit its precision to no more than 0.1 m/s2. 560 | 1. Set |acceleration|'s [=DeviceMotionEventAcceleration/y axis acceleration=] to |platformLinearAcceleration|'s value along the Y axis, or null if it cannot be provided. 561 | 1. If |acceleration|'s [=DeviceMotionEventAcceleration/y axis acceleration=] is not null, limit its precision to no more than 0.1 m/s2. 562 | 1. Set |acceleration|'s [=DeviceMotionEventAcceleration/z axis acceleration=] to |platformLinearAcceleration|'s value along the Z axis, or null if it cannot be provided. 563 | 1. If |acceleration|'s [=DeviceMotionEventAcceleration/z axis acceleration=] is not null, limit its precision to no more than 0.1 m/s2. 564 | 1. Let |platformAccelerationIncludingGravity| be null. 565 | 1. If |topLevelTraversable|'s [=virtual sensor mapping=] [=map/contains=] "`accelerometer`": 566 | 1. Let |virtualSensor| be |topLevelTraversable|'s [=virtual sensor mapping=]["`accelerometer`"]. 567 | 1. If |virtualSensor|'s [=can provide readings flag=] is true, then set |platformAccelerationIncludingGravity| to the latest readings provided to |virtualSensor|. 568 | 1. Otherwise, if the implementation is able to provide [=acceleration with gravity=]: 569 | 1. Set |platformAccelerationIncludingGravity| to the device's [=linear acceleration=] along the X, Y and Z axes. 570 | 1. Let |accelerationIncludingGravity| be null. 571 | 1. If |platformAccelerationIncludingGravity| is not null: 572 | 1. Set |accelerationIncludingGravity| to a [=new=] {{DeviceMotionEventAcceleration}} created in |window|'s [=global object/realm=]. 573 | 1. Set |accelerationIncludingGravity|'s [=DeviceMotionEventAcceleration/x axis acceleration=] to |platformAccelerationIncludingGravity|'s value along the X axis, or null if it cannot be provided. 574 | 1. If |accelerationIncludingGravity|'s [=DeviceMotionEventAcceleration/x axis acceleration=] is not null, limit its precision to no more than 0.1 m/s2. 575 | 1. Set |accelerationIncludingGravity|'s [=DeviceMotionEventAcceleration/y axis acceleration=] to |platformAccelerationIncludingGravity|'s value along the Y axis, or null if it cannot be provided. 576 | 1. If |accelerationIncludingGravity|'s [=DeviceMotionEventAcceleration/y axis acceleration=] is not null, limit its precision to no more than 0.1 m/s2. 577 | 1. Set |accelerationIncludingGravity|'s [=DeviceMotionEventAcceleration/z axis acceleration=] to |platformAccelerationIncludingGravity|'s value along the Z axis, or null if it cannot be provided. 578 | 1. If |accelerationIncludingGravity|'s [=DeviceMotionEventAcceleration/z axis acceleration=] is not null, limit its precision to no more than 0.1 m/s2. 579 | 1. Let |platformRotationRate| be null. 580 | 1. If |topLevelTraversable|'s [=virtual sensor mapping=] [=map/contains=] "`gyroscope`": 581 | 1. Let |virtualSensor| be |topLevelTraversable|'s [=virtual sensor mapping=]["`gyroscope`"]. 582 | 1. If |virtualSensor|'s [=can provide readings flag=] is true, then set |platformRotationRate| to the latest readings provided to |virtualSensor|. 583 | 1. Otherwise, if the implementation is able to provide [=rotation rate=]: 584 | 1. Set |platformRotationRate| to the device's [=rotation rate=] about the X, Y and Z axes. 585 | 1. Let |rotationRate| be null. 586 | 1. If |platformRotationRate| is not null: 587 | 1. Set |rotationRate| to a [=new=] {{DeviceMotionEventRotationRate}} created in |window|'s [=global object/realm=]. 588 | 1. Set |rotationRate|'s [=DeviceMotionEventRotationRate/x axis rotation rate=] to |platformRotationRate|'s value about the X axis, or null if it cannot be provided. 589 | 1. If |rotationRate|'s [=DeviceMotionEventRotationRate/x axis rotation rate=] is not null, limit its precision to no more than 0.1 deg/s. 590 | 1. Set |rotationRate|'s [=DeviceMotionEventRotationRate/y axis rotation rate=] to |platformRotationRate|'s value about the Y axis, or null if it cannot be provided. 591 | 1. If |rotationRate|'s [=DeviceMotionEventRotationRate/y axis rotation rate=] is not null, limit its precision to no more than 0.1 deg/s. 592 | 1. Set |rotationRate|'s [=DeviceMotionEventRotationRate/z axis rotation rate=] to |platformRotationRate|'s value about the Z axis, or null if it cannot be provided. 593 | 1. If |rotationRate|'s [=DeviceMotionEventRotationRate/z axis rotation rate=] is not null, limit its precision to no more than 0.1 deg/s. 594 | 1. Let |environment| be |window|'s [=relevant settings object=]. 595 | 1. Run these steps [=in parallel=]: 596 | 1. [=list/For each=] |permission| in « "accelerometer", "gyroscope" »: 597 | 1. Let |state| be the result of [=getting the current permission state=] with |permission| and |environment|. 598 | 1. If |state| is not "{{PermissionState/granted}}", return. 599 | 1. [=Queue a global task=] on the [=device motion and orientation task source=] given |window| to run the following steps: 600 | 1. [=Fire an event=] named "devicemotion" at |window|, using {{DeviceMotionEvent}}, with the {{DeviceMotionEvent/acceleration}} attribute initialized to |acceleration|, the {{DeviceMotionEvent/accelerationIncludingGravity}} attribute initialized to |accelerationIncludingGravity|, the {{DeviceMotionEvent/rotationRate}} attribute initialized to |rotationRate|, and the {{DeviceMotionEvent/interval}} attribute initialized to |interval|. 601 | 602 |
603 | 604 | 608 | If an implementation can never provide motion information, the event should be fired with the {{DeviceMotionEvent/acceleration}}, {{DeviceMotionEvent/accelerationIncludingGravity}} and {{DeviceMotionEvent/rotationRate}} attributes set to null. 609 | 610 | Security and privacy considerations {#security-and-privacy} 611 | =========================================================== 612 | 613 | The API defined in this specification can be used to obtain information from hardware sensors, such as accelerometer, gyroscope and magnetometer. Provided data may be considered as sensitive and could become a subject of attack from malicious web pages. The calibration of accelerometers, gyroscopes and magnetometers may reveal persistent details about the particular sensor hardware [[SENSORID]]. The main attack vectors can be categorized into following categories: 614 | 615 | * Monitoring of a user input [[TOUCH]] 616 | * Location tracking [[INDOORPOS]] 617 | * User identification [[FINGERPRINT]] 618 | 619 | In light of that, implementations may consider visual indicators to signify the use of sensors by the web page. Additionally, this specification requires users to give express permission for the user agent to provide device motion and/or orientation data via the requestPermission() API calls. 620 | 621 | Furthermore, to minimize privacy risks, the chance of fingerprinting and other attacks the implementations must: 622 | 623 | * fire events only when a [=/navigable=]'s [=navigable/active document=]'s [=visibility state=] is "visible", 624 | * implement [[#permissions-integration]] so that events are fired on [=child navigables=] (including but not restricted to cross-origin ones) only if allowed by the [=/top-level traversable=], 625 | * fire events on a [=/navigable=]'s [=navigable/active windows=] only when its [=relevant settings object=] is a [=secure context=], 626 | * limit precision of attribute values as described in the previous sections. 627 | 628 | Additionally, implementing these items may also have a beneficial impact on the battery life of mobile devices. 629 | 630 | Issue: Further implementation experience is being gathered to inform the limit for the maximum sampling frequency cap. 631 | 632 | Accessibility considerations {#a11y} 633 | =========================================================== 634 | 635 | DeviceOrientation events provide opportunities for novel forms of input, which can open up novel interactions for users. In order to ensure that as many people as possible will be able to interact with the experiences you build, please consider the following: 636 | 637 | * It is important for alternative means of providing input to be available, so that people who cannot make the required gestures have another way to interact. Examples may include people with dexterity-related disabilities, or people who use eye gaze, or head-tracking input. 638 | - For games, consider supporting either game controller, keyboard or mouse input as alternative interaction methods. 639 | - For web apps, consider providing UI, such as a button, menu command, and/or keyboard shortcut, to perform the function. 640 | 641 | * It is essential that users can undo any accidental input - this may be particularly relevant for people with tremors. 642 | 643 | There are two user needs that can arise, which would likely be managed by the user agent, or underlying operating system. However, it can be helpful to bear these considerations in mind, as they represent ways that your content or app may be used. 644 | 645 | * It is important that the user is able to disable the use of gesture or motion-based input. The web app should provide an appropriate accessible means for the user to supply this input, such as a button. 646 | - For example: whilst the shake-to-undo feature can provide a natural and thoughtful interaction for some, for people with tremors, it may present a barrier. This could be managed by declining permission, or more likely by changing a browser or OS setting, coupled with the web app providing alternative input means. 647 | * It is also important that the device's orientation can be locked - a primary use case being someone who is interacting with a touch device, such as a phone, non-visually. They may have built up 'muscle memory' as to where elements are on the screen in a given orientation, and having the layout shift would break their ability to navigate. Again, this would most likely be done at the operating system level. 648 | 649 | Automation {#automation} 650 | ========== 651 | 652 |
653 | This feature is [=at risk=] due to limited implementation experience. 654 |
655 | 656 | This specification can pose a challenge to test authors, as the events defined here depend on the presence of physical hardware whose readings cannot be easily controlled. 657 | 658 | To address this challenge, this document builds upon the [[WEBDRIVER2]] extension commands and infrastructure laid out by [[GENERIC-SENSOR#automation]]. This was chosen over the option of developing completely new and independent infrastructure with separate extension commands because there is significant overlap between the two specifications: not only does testing the [[GENERIC-SENSOR]] specification present similar challenges, but many derived APIs (e.g. [[GYROSCOPE]]) obtain and provide similar information. 659 | 660 | This specification only requires implementations to support the [[GENERIC-SENSOR#automation]] section of the [[GENERIC-SENSOR]] specification, not its interfaces and events. 661 | 662 | Device Orientation Automation {#device-orientation-automation} 663 | ----------------------------- 664 | 665 | Automation support for the deviceorientation event is built upon virtual sensors that represent accelerometers, gyroscopes and, optionally, magnetometers. 666 | 667 | Orientation data retrieved from the platform by the user agent comes from accelerometers, gyroscopes and, optionally, magnetometers. Contrary to motion data, however, these lower-level readings must be transformed into Euler angles in the formation described in [[#device-orientation-model]]. Furthermore, the platform might provide extra APIs to the user agent that already perform some of those conversions from raw acceleration and rotation data. 668 | 669 | Therefore, instead of requiring implementations (and automation users) to provide orientation readings via lower-level virtual sensors which use different units of measurement, this specification defines extra virtual sensor types for relative and orientation data in the format used by this specification. 670 | 671 | ### Parse orientation reading data algorithm ### {#parse-orientation-data-reading-algorithm} 672 | 673 |
674 | To perform the parse orientation data reading algorithm, given a JSON {{Object}} |parameters|: 675 | 676 | 1. Let |alpha| be the result of invoking [=get a property=] from |parameters| with "alpha". 677 | 1. If |alpha| is not a {{Number}}, or its value is NaN, +∞, or −∞, return `undefined`. 678 | 1. If |alpha| is not in the range [0, 360), then return `undefined`. 679 | 1. Let |beta| be the result of invoking [=get a property=] from |parameters| with "beta". 680 | 1. If |beta| is not a {{Number}}, or its value is NaN, +∞, or −∞, return `undefined`. 681 | 1. If |beta| is not in the range [-180, 180), then return `undefined`. 682 | 1. Let |gamma| be the result of invoking [=get a property=] from |parameters| with "gamma". 683 | 1. If |gamma| is not a {{Number}}, or its value is NaN, +∞, or −∞, return `undefined`. 684 | 1. If |gamma| is not in the range [-90, 90), then return `undefined`. 685 | 1. Return a new [=ordered map=] «[ "alpha" → |alpha|, "beta" → |beta|, "gamma" → |gamma| ]». 686 | 687 | Note: The return value is a [=ordered map=] to prevent a dependency on the [=sensor reading=] concept from the [[GENERIC-SENSOR]] specification. They should be interchangeable for the purposes of the algorithm above. 688 | 689 |
690 | 691 | ### The "absolute-orientation" virtual sensor type ### {#absolute-orientation-virtual-sensors} 692 | 693 | The [=per-type virtual sensor metadata=] [=map=] must have the following [=map/entry=]: 694 | : 695 | : [=map/Key=] 696 | :: "absolute-orientation" 697 | : [=map/Value=] 698 | :: A virtual sensor metadata whose reading parsing algorithm is parse orientation data reading. 699 | 700 | ### The "relative-orientation" virtual sensor type ### {#relative-orientation-virtual-sensors} 701 | 702 | The [=per-type virtual sensor metadata=] [=map=] must have the following [=map/entry=]: 703 | : 704 | : [=map/Key=] 705 | :: "relative-orientation" 706 | : [=map/Value=] 707 | :: A virtual sensor metadata whose reading parsing algorithm is parse orientation data reading. 708 | 709 | Device Motion Automation {#device-motion-automation} 710 | ------------------------ 711 | 712 | The motion data retrieved from the platform by the user agent comes from accelerometers and gyroscopes. This specification defines certain [=per-type virtual sensor metadata=] entries that are shared with the [[ACCELEROMETER]] and [[GYROSCOPE]] specifications. 713 | 714 | Accelerometer virtual sensors are used to provide acceleration with gravity data to the platform. Linear Acceleration virtual sensors are used to provide linear acceleration data to the platform. Gyroscope virtual sensors are used to provide [=rotation rate=] data to the platform. 715 | 716 | ### The "accelerometer" virtual sensor type ### {#accelerometer-virtual-sensors} 717 | 718 | The [=per-type virtual sensor metadata=] [=map=] must have the following [=map/entry=]: 719 | 720 | : [=map/Key=] 721 | :: "accelerometer" 722 | : [=map/Value=] 723 | :: A virtual sensor metadata whose reading parsing algorithm is parse xyz reading. 724 | 725 | ### The "linear-acceleration" virtual sensor type ### {#linear-acceleration-virtual-sensors} 726 | 727 | The [=per-type virtual sensor metadata=] [=map=] must have the following [=map/entry=]: 728 | 729 | : [=map/Key=] 730 | :: "linear-acceleration" 731 | : [=map/Value=] 732 | :: A virtual sensor metadata whose reading parsing algorithm is parse xyz reading. 733 | 734 | ### The "gyroscope" virtual sensor type ### {#gyroscope-virtual-sensors} 735 | 736 | The [=per-type virtual sensor metadata=] [=map=] must have the following [=map/entry=]: 737 | 738 | : [=map/Key=] 739 | :: "gyroscope" 740 | : [=map/Value=] 741 | :: A virtual sensor metadata whose reading parsing algorithm is parse xyz reading. 742 | 743 |

A Examples

744 | This section is non-normative. 745 | 746 |

A.1 Calculating compass heading

747 | 748 | This section is non-normative. 749 | 750 | The following worked example is intended as an aid to users of the DeviceOrientation event. 751 | 752 | [[#introduction|Introduction]] section provided an example of using the DeviceOrientation event to obtain a compass heading when the device is held with the screen horizontal. This example shows how to determine the compass heading that the user is facing when holding the device with the screen approximately vertical in front of them. An application of this is an augmented-reality system. 753 | 754 | More precisely, we wish to determine the compass heading of the horizontal component of a vector which is orthogonal to the device's screen and pointing out of the back of the screen. 755 | 756 | If v represents this vector in the rotated device body frame xyz, then v is as follows. 757 | 758 | 759 | v = [0; 0; -1] 760 | 761 | 762 | The transformation of v due to the rotation about the z axis can be represented by the following rotation matrix. 763 | 764 | 765 | Z = [cos(alpha) -sin(alpha) 0; sin(alpha) cos(alpha) 0; 0 0 1] 766 | 767 | 768 | The transformation of v due to the rotation about the x axis can be represented by the following rotation matrix. 769 | 770 | 771 | X = [1 0 0; 0 cos(beta) -sin(beta); 0 sin(beta) cos(beta)] 772 | 773 | 774 | The transformation of v due to the rotation about the y axis can be represented by the following rotation matrix. 775 | 776 | 777 | Y = [cos(gamma) 0 sin(gamma); 0 1 0; -sin(gamma) 0 cos(gamma)] 778 | 779 | 780 | If R represents the full rotation matrix of the device in the earth frame XYZ, then since the initial body frame is aligned with the earth, R is as follows. 781 | 782 | 783 | R = ZXY = [[cos(alpha) cos(gamma)-sin(alpha) sin(beta) sin(gamma), -cos(beta) sin(alpha), cos(gamma) sin(alpha) sin(beta)+cos(alpha) sin(gamma)], [cos(gamma) sin(alpha)+cos(alpha) sin(beta) sin(gamma), cos(alpha) cos(beta), sin(alpha) sin(gamma)-cos(alpha) cos(gamma) sin(beta)], [-cos(beta) sin(gamma), sin(beta), cos(beta) cos(gamma)]] 784 | 785 | 786 | If v' represents the vector v in the earth frame XYZ, then since the initial body frame is aligned with the earth, v' is as follows. 787 | 788 | 789 | v' = Rv 790 | 791 | 792 | v' = [-cos(alpha)sin(gamma)-sin(alpha)sin(beta)cos(gamma); -sin(alpha)sin(gamma)+cos(alpha)sin(beta)cos(gamma); -cos(beta)cos(gamma)] 793 | 794 | 795 | The compass heading θ is given by 796 | 797 | 798 | theta = atan((v'_x)/(v'_y)) = atan((-cos(alpha)sin(gamma)-sin(alpha)sin(beta)cos(gamma))/(-sin(alpha)sin(gamma)+cos(alpha)sin(beta)cos(gamma))) 799 | 800 | 801 | provided that β and γ are not both zero. 802 | 803 |
804 | 805 | The compass heading calculation above can be represented in JavaScript as follows to return the correct compass heading when the provided parameters are defined, not null and represent {{DeviceOrientationEvent/absolute}} values. 806 | 807 | 
 808 | var degtorad = Math.PI / 180; // Degree-to-Radian conversion
 809 | 
 810 | function compassHeading( alpha, beta, gamma ) {
 811 | 
 812 |   var _x = beta  ? beta  * degtorad : 0; // beta value
 813 |   var _y = gamma ? gamma * degtorad : 0; // gamma value
 814 |   var _z = alpha ? alpha * degtorad : 0; // alpha value
 815 | 
 816 |   var cX = Math.cos( _x );
 817 |   var cY = Math.cos( _y );
 818 |   var cZ = Math.cos( _z );
 819 |   var sX = Math.sin( _x );
 820 |   var sY = Math.sin( _y );
 821 |   var sZ = Math.sin( _z );
 822 | 
 823 |   // Calculate Vx and Vy components
 824 |   var Vx = - cZ * sY - sZ * sX * cY;
 825 |   var Vy = - sZ * sY + cZ * sX * cY;
 826 | 
 827 |   // Calculate compass heading
 828 |   var compassHeading = Math.atan( Vx / Vy );
 829 | 
 830 |   // Convert compass heading to use whole unit circle
 831 |   if( Vy < 0 ) {
 832 |     compassHeading += Math.PI;
 833 |   } else if( Vx < 0 ) {
 834 |     compassHeading += 2 * Math.PI;
 835 |   }
 836 | 
 837 |   return compassHeading * ( 180 / Math.PI ); // Compass Heading (in degrees)
 838 | 
 839 | }
 840 |
841 |
842 | 843 | As a consistency check, if we set γ = 0, then 844 | 845 | 846 | theta = atan(-sin(alpha)sin(beta)/cos(alpha)sin(beta)) = -alpha 847 | 848 | 849 | as expected. 850 | 851 | Alternatively, if we set β = 90, then 852 | 853 | 854 | theta = atan((-cos(alpha)sin(gamma)-sin(alpha)cos(gamma))/(-sin(alpha)sin(gamma)+cos(alpha)cos(gamma))) 855 | 856 | 857 | theta = atan(-sin(alpha+gamma)/cos(alpha+gamma)) = -(alpha+gamma) 858 | 859 | 860 | as expected. 861 | 862 |

A.2 Alternate device orientation representations

863 | 864 | This section is non-normative. 865 | 866 | Describing orientation using Tait-Bryan angles can have some disadvantages such as introducing gimbal lock [[GIMBALLOCK]]. Depending on the intended application it can be useful to convert the Device Orientation values to other rotation representations. 867 | 868 | The first alternate orientation representation uses rotation matrices. By combining the component rotation matrices provided in the [[#worked-example|worked example]] above we can represent the orientation of the device body frame as a combined rotation matrix. 869 | 870 | If R represents the rotation matrix of the device in the earth frame XYZ, then since the initial body frame is aligned with the earth, R is as follows. 871 | 872 | 873 | R = ZXY = [[cos(alpha) cos(gamma)-sin(alpha) sin(beta) sin(gamma), -cos(beta) sin(alpha), cos(gamma) sin(alpha) sin(beta)+cos(alpha) sin(gamma)], [cos(gamma) sin(alpha)+cos(alpha) sin(beta) sin(gamma), cos(alpha) cos(beta), sin(alpha) sin(gamma)-cos(alpha) cos(gamma) sin(beta)], [-cos(beta) sin(gamma), sin(beta), cos(beta) cos(gamma)]] 874 | 875 | 876 |
877 | The above combined rotation matrix can be represented in JavaScript as follows provided passed parameters are defined, not null and represent {{DeviceOrientationEvent/absolute}} values. 878 | 
 879 | var degtorad = Math.PI / 180; // Degree-to-Radian conversion
 880 | 
 881 | function getRotationMatrix( alpha, beta, gamma ) {
 882 | 
 883 |   var _x = beta  ? beta  * degtorad : 0; // beta value
 884 |   var _y = gamma ? gamma * degtorad : 0; // gamma value
 885 |   var _z = alpha ? alpha * degtorad : 0; // alpha value
 886 | 
 887 |   var cX = Math.cos( _x );
 888 |   var cY = Math.cos( _y );
 889 |   var cZ = Math.cos( _z );
 890 |   var sX = Math.sin( _x );
 891 |   var sY = Math.sin( _y );
 892 |   var sZ = Math.sin( _z );
 893 | 
 894 |   //
 895 |   // ZXY rotation matrix construction.
 896 |   //
 897 | 
 898 |   var m11 = cZ * cY - sZ * sX * sY;
 899 |   var m12 = - cX * sZ;
 900 |   var m13 = cY * sZ * sX + cZ * sY;
 901 | 
 902 |   var m21 = cY * sZ + cZ * sX * sY;
 903 |   var m22 = cZ * cX;
 904 |   var m23 = sZ * sY - cZ * cY * sX;
 905 | 
 906 |   var m31 = - cX * sY;
 907 |   var m32 = sX;
 908 |   var m33 = cX * cY;
 909 | 
 910 |   return [
 911 |     m11,    m12,    m13,
 912 |     m21,    m22,    m23,
 913 |     m31,    m32,    m33
 914 |   ];
 915 | 
 916 | };
 917 |
918 |
919 | 920 | Another alternate representation of device orientation data is as Quaternions. [[QUATERNIONS]] 921 | 922 | If q represents the unit quaternion of the device in the earth frame XYZ, then since the initial body frame is aligned with the earth, q is as follows. 923 | 924 | 925 | q = [[q_w], [q_x], [q_y], [q_z]] = [[cos(beta)cos(gamma)cos(alpha) - sin(beta)sin(gamma)sin(alpha)], [sin(beta)cos(gamma)cos(alpha) - cos(beta)sin(gamma)sin(alpha)], [cos(beta)sin(gamma)cos(alpha) + sin(beta)cos(gamma)sin(alpha)], [cos(beta)cos(gamma)sin(alpha) + sin(beta)sin(gamma)cos(alpha)]] 926 | 927 | 928 |
929 | The above quaternion can be represented in JavaScript as follows provided the passed parameters are defined, are {{DeviceOrientationEvent/absolute}} values and those parameters are not null. 930 | 
 931 | var degtorad = Math.PI / 180; // Degree-to-Radian conversion
 932 | 
 933 | function getQuaternion( alpha, beta, gamma ) {
 934 | 
 935 |   var _x = beta  ? beta  * degtorad : 0; // beta value
 936 |   var _y = gamma ? gamma * degtorad : 0; // gamma value
 937 |   var _z = alpha ? alpha * degtorad : 0; // alpha value
 938 | 
 939 |   var cX = Math.cos( _x/2 );
 940 |   var cY = Math.cos( _y/2 );
 941 |   var cZ = Math.cos( _z/2 );
 942 |   var sX = Math.sin( _x/2 );
 943 |   var sY = Math.sin( _y/2 );
 944 |   var sZ = Math.sin( _z/2 );
 945 | 
 946 |   //
 947 |   // ZXY quaternion construction.
 948 |   //
 949 | 
 950 |   var w = cX * cY * cZ - sX * sY * sZ;
 951 |   var x = sX * cY * cZ - cX * sY * sZ;
 952 |   var y = cX * sY * cZ + sX * cY * sZ;
 953 |   var z = cX * cY * sZ + sX * sY * cZ;
 954 | 
 955 |   return [ w, x, y, z ];
 956 | 
 957 | }
 958 |
959 |
960 | 961 | We can check that a Unit Quaternion has been constructed correctly using Lagrange's four-square theorem 962 | 963 | 964 | q_w^2 * q_x^2 * q_y^2 * q_z^2 = 1 965 | 966 | 967 | as expected. 968 | 969 |

Acknowledgments

970 | 971 | The Device Orientation and Motion specification, originally published as a Candidate Recommendation in August 2016 under the title DeviceOrientation Event Specification, was initially developed by the [Geolocation Working Group](https://www.w3.org/2008/geolocation/). After the group was closed in 2017, the specification was temporarily retired. Revitalized in 2019 by the [Devices and Sensors Working Group](https://www.w3.org/groups/wg/das/), this document has undergone significant enhancements including improvements in interoperability, test automation, privacy, and editorial content (see [[#changes]] section). 972 | 973 | In 2024, the Devices and Sensors Working Group partnered with the [Web Applications Working Group](https://www.w3.org/groups/wg/webapps/), making this a joint deliverable and continuing the advancement of the specification. The initial design discussions are preserved not in this GitHub repository but can be explored through the [Geolocation Working Group’s mailing list archives](https://lists.w3.org/Archives/Public/public-geolocation/). 974 | 975 | The W3C acknowledges Lars Erik Bolstad, Dean Jackson, Claes Nilsson, George Percivall, Doug Turner, Matt Womer, and Chris Dumez for their contributions. 976 | 977 | 
 978 | urlPrefix: https://html.spec.whatwg.org/multipage/
 979 |     urlPrefix: webappapis.html; type: dfn
 980 |         text: relevant settings object
 981 |
982 | 983 | 
 984 | {
 985 |     "EULERANGLES": {
 986 |         "href": "https://en.wikipedia.org/wiki/Euler_angles",
 987 |         "title": "Euler Angles"
 988 |     },
 989 |     "TOUCH": {
 990 |         "href": "https://arxiv.org/abs/1602.04115",
 991 |         "title": "TouchSignatures: Identification of User Touch Actions and PINs Based on Mobile Sensor Data via JavaScript",
 992 |         "date": "12 Feb 2016"
 993 |     },
 994 |     "INDOORPOS": {
 995 |         "authors": [
 996 |             "Shala, Ubejd",
 997 |             "Angel Rodriguez"
 998 |         ],
 999 |         "href": "http://www.diva-portal.org/smash/record.jsf?pid=diva2%3A475619&dswid=9050",
1000 |         "title": "Indoor positioning using sensor-fusion in android devices",
1001 |         "date": "2011"
1002 |     },
1003 |     "FINGERPRINT": {
1004 |         "href": "https://arxiv.org/abs/1408.1416",
1005 |         "title": "Mobile Device Identification via Sensor Fingerprinting",
1006 |         "date": "6 Aug 2014"
1007 |     },
1008 |     "GIMBALLOCK": {
1009 |         "href": "https://en.wikipedia.org/wiki/Gimbal_Lock",
1010 |         "title": "Gimbal Lock"
1011 |     },
1012 |     "PROPERACCELERATION": {
1013 |         "href": "https://en.wikipedia.org/wiki/Proper_acceleration",
1014 |         "title": "Proper acceleration"
1015 |     },
1016 |     "QUATERNIONS": {
1017 |         "href": "https://en.wikipedia.org/wiki/Quaternion",
1018 |         "title": " Quaternions"
1019 |     },
1020 |     "SENSORID": {
1021 |         "href": "https://doi.org/10.1109/SP.2019.00072",
1022 |         "title": "SensorID: Sensor Calibration Fingerprinting for Smartphones",
1023 |         "date": "2019",
1024 |         "authors": [
1025 |             "Zhang, Jiexin",
1026 |             "Beresford, Alastair R.",
1027 |             "Sheret, Ian"
1028 |         ],
1029 |         "publisher": "IEEE Symposium on Security and Privacy"
1030 |     },
1031 |     "G-FORCE": {
1032 |         "href": "https://en.wikipedia.org/wiki/G-force",
1033 |         "title": "G-Force"
1034 |     }
1035 | }
1036 |
1037 | 1038 | Changes {#changes} 1039 | =========== 1040 | 1041 | This section summarizes substantial changes and notable editorial improvements to guide review. Full details are available from the commit log. Changes since the Candidate Recommendation 2016-08-18: 1042 | 1043 | - Add Permissions Policy integration, which supersedes the previous requirement of only firing events on iframes that were same-origin with the top-level frame 1044 | - Add note to implementers about bundling permission requests 1045 | - Export powerful features Accelerometer, Gyroscope and Magnetometer 1046 | - Add Permissions API integration, start requiring requestPermission() usage 1047 | - editorial: Define API section more normatively and with more dfns 1048 | - editorial: Reorder acceleration explanation in Device Motion Model section 1049 | - editorial: Update explanations of the device rotation and motion references 1050 | - editorial: Use more precise event handling terms, modernize others 1051 | - editorial: Refer to [[SCREEN-ORIENTATION]] instead of the orientation change event 1052 | - editorial: Reword requirements in "Security and privacy considerations" 1053 | - Mark use cases and requirements and examples sections non-normative 1054 | - Remove the oncompassneedscalibration event 1055 | - Update references to "triggered by user activation", now referred to as "transient activation" 1056 | - Align with DOM phrasing on firing events 1057 | - Add a note about acceleration properties for DeviceMotionEvent 1058 | - Add a note explaining how the coordinate system differs from the CSS coordinate system 1059 | - Require no more precise than 0.1 degrees, 0.1 degrees per second, 0.1 meters per second squared to mitigate a passive fingerprinting issue 1060 | - Update constructor definition in IDL with the Web IDL 1061 | - Add explicit [Exposed] to interfaces 1062 | - Update IDL dictionaries with new dictionary defaulting setup 1063 | - Note the deviceorientationabsolute event and its ondeviceorientationabsolute event handler IDL attribute have limited implementation experience 1064 | - Add requestPermission() API static operation to both DeviceOrientationEvent and DeviceMotionEvent 1065 | - Add [SecureContext] to event handlers ondeviceorientation, ondevicemotion and ondeviceorientationabsolute 1066 | - Restrict all interfaces to secure contexts 1067 | - Remove [NoInterfaceObject] from DeviceAcceleration and DeviceRotationRate 1068 | - Make security and privacy considerations normative 1069 | - Add the ondeviceorientationabsolute event handler attribute into the IDL block (was only in prose) 1070 | - Remove '?' from dictionary members of DeviceMotionEventInit 1071 | - Use [Exposed=Window] extended attribute 1072 | -------------------------------------------------------------------------------- /security-privacy-self-assessment.md: -------------------------------------------------------------------------------- 1 | # Security and Privacy Self-Review Questionnaire for DeviceOrientation Event 2 | 3 | [Self-Review Questionnaire](https://www.w3.org/TR/security-privacy-questionnaire/) 4 | responses for the [DeviceOrientation Event](https://www.w3.org/TR/orientation-event/) specification. 5 | 6 | Related Self-Review Questionnaires: 7 | - [Generic Sensor API](https://github.com/w3c/sensors/blob/main/security-questionnaire.md) 8 | - [Orientation Sensor API](https://github.com/w3c/orientation-sensor/blob/main/security-questionnaire.md) 9 | 10 | ### 2.1 What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary? 11 | 12 | Information about the physical orientation and movement of the hosting device. See [use cases](https://www.w3.org/TR/orientation-event/#use-cases). 13 | 14 | ### 2.2 Do features in your specification expose the minimum amount of information necessary to enable their intended uses? 15 | 16 | This specification allows developers to request access to only the set of sensor data necessary, either a "device motion" event for motion-controlled applications or a "device orientation" event for orientation control. Since absolute orientation exposes more information, a "relative orientation" option is available if the compass heading is unnecessary. 17 | 18 | The data precision is normatively limited to resist fingerprinting (see 2.6). 19 | 20 | ### 2.3 How do the features in your specification deal with personal information, personally-identifiable information (PII), or information derived from them? 21 | 22 | This specification does not deal with PII directly, however identifiable information such as gait can be determined from monitoring sensor readings over time. The specification requires users to give express permission for the user agent to provide device motion and/or orientation data. Furthermore, all interfaces are restricted to secure contexts to protect against both active and passive network attackers. 23 | 24 | ### 2.4 How do the features in your specification deal with sensitive information? 25 | 26 | See 2.3. 27 | 28 | ### 2.5 Do the features in your specification introduce new state for an origin that persists across browsing sessions? 29 | 30 | This specification defines new [permissions](https://www.w3.org/TR/orientation-event/#permissions-api-integration) for which user agents may persist the user's decision to grant access to a site between browsing sessions. Otherwise, sensors are completely stateless. 31 | 32 | ### 2.6 Do the features in your specification expose information about the underlying platform to origins? 33 | 34 | Minor manufacturing imperfections and differences unique to the underlying platform and the sensor hardware in the hosting device might be detected through readings over time. 35 | 36 | The specification mitigates this type of passive fingerprinting by normatively limiting rotation and acceleration precision to at most 0.1 degrees, 0.1 degrees per second or 0.1 meters per second squared as appropriate. More context is available in a [paper](https://github.com/JensenPaul/sensor-fingerprint-mitigation). 37 | 38 | ### 2.7 Does this specification allow an origin to send data to the underlying platform? 39 | 40 | No. 41 | 42 | ### 2.8 Do features in this specification enable access to device sensors? 43 | 44 | Yes. See 2.1 and 2.2. 45 | 46 | ### 2.9 Do features in this specification enable new script execution/loading mechanisms? 47 | 48 | No. 49 | 50 | ### 2.10 Do features in this specification allow an origin to access other devices? 51 | 52 | No. 53 | 54 | ### 2.11 Do features in this specification allow an origin some measure of control over a user agent’s native UI? 55 | 56 | The specification includes a method to request the user agent display a permission prompt, the contents of which are implementation-defined. 57 | 58 | ### 2.12 What temporary identifiers do the features in this specification create or expose to the web? 59 | 60 | None. 61 | 62 | ### 2.13 How does this specification distinguish between behavior in first-party and third-party contexts? 63 | 64 | The Permissions Policy integration controls whether third-party contexts are able to receive the events defined by this specification: 65 | 66 | - The "deviceorientation" event requires the "accelerometer" and "gyroscope" features when providing relative orientation data. For the implementation to fall back to absolute orientation data, the "magnetometer" feature is also required. 67 | - The "deviceorientationabsolute" event requires the "accelerometer", "gyroscope" and "magnetometer" features. 68 | - The "devicemotion" event requires the "accelerometer" and "gyroscope" features. 69 | 70 | The default allowlist for all policy-controlled features defined by this specification ("accelerometer", "gyroscope", and "magnetometer") is `"self"`, which does not allow third-party contexts to receive the events above and have access to the corresponding sensor readings. 71 | 72 | ### 2.14 How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode? 73 | 74 | No difference to the browser's 'normal' state. 75 | 76 | ### 2.15 Does this specification have both "Security Considerations" and "Privacy Considerations" sections? 77 | 78 | Yes, combined together. 79 | 80 | ### 2.16 Do features in your specification enable origins to downgrade default security protections? 81 | 82 | No. 83 | 84 | ### 2.17 How does your feature handle non-"fully active" documents? 85 | 86 | Events are fired on active windows only. 87 | 88 | ### 2.18 What should this questionnaire have asked? 89 | 90 | That's all. Thank you for your review. 91 | -------------------------------------------------------------------------------- /spec-source-orientation.html: -------------------------------------------------------------------------------- 1 | index.html -------------------------------------------------------------------------------- /start.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/deviceorientation/70d42d5484db7fd1646e48cc17caa5ff1c9d92cb/start.png -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": 43696, 3 | "contacts": [ 4 | "himorin" 5 | ], 6 | "shortName": "orientation-event", 7 | "repo-type": "rec-track", 8 | "policy": "open" 9 | } 10 | --------------------------------------------------------------------------------