You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
711 lines
34 KiB
711 lines
34 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
<html lang=en>
|
|
<head>
|
|
<title>DeviceOrientation Event Specification</title>
|
|
<meta content="text/html;charset=utf-8" http-equiv=Content-Type>
|
|
|
|
<style type="text/css">
|
|
dt, dfn { font-weight: bold; font-style: normal; }
|
|
img.extra { float: right; }
|
|
body ins, body del { display: block; }
|
|
body * ins, body * del { display: inline; }
|
|
pre, code { color: black; background: transparent; font-size: inherit; font-family: monospace; }
|
|
pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
|
|
pre em { font-weight: bolder; font-style: normal; }
|
|
pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
|
|
pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em; }
|
|
table { border-collapse: collapse; border-style: hidden hidden none hidden; }
|
|
table thead { border-bottom: solid; }
|
|
table tbody th:first-child { border-left: solid; }
|
|
table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
|
|
ul.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
|
|
ul.toc li ul { margin-bottom: 0.75em; }
|
|
ul.toc li ul li ul { margin-bottom: 0.25em; }
|
|
var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
|
|
@media screen { code { color: rgb(255, 69, 0); background: transparent; } }
|
|
code :link, code :visited { color: inherit; background: transparent; }
|
|
.example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 1em; padding-left: 1em; }
|
|
.issue, .big-issue { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
|
|
.issue > :first-child, .big-issue > :first-child { margin-top: 0; }
|
|
p .big-issue { line-height: 3em; }
|
|
.note { color: green; background: transparent; }
|
|
.note { font-family: sans-serif; }
|
|
p.note:before { content: 'Note: '; }
|
|
.warning { color: red; background: transparent; }
|
|
.warning:before { font-style: normal; }
|
|
p.warning:before { content: '\26A0 Warning! '; }
|
|
.note, .warning { font-weight: bolder; font-style: italic; padding: 0.5em 2em; }
|
|
.copyright { margin: 0.25em 0; }
|
|
img { max-width: 100%; }
|
|
h4 + .element { margin-top: -2.5em; padding-top: 2em; }
|
|
h4 + p + .element { margin-top: -5em; padding-top: 4em; }
|
|
.element { background: #EEEEFF; color: black; margin: 0 0 1em -1em; padding: 0 1em 0.25em 0.75em; border-left: solid #9999FF 0.25em; }
|
|
table.matrix, table.matrix td { border: none; text-align: right; }
|
|
table.matrix { margin-left: 2em; }
|
|
ol#rotations li div { display: inline-block; width: 350px; margin-right: 20px; font-size: small; }
|
|
ol#rotations li div img { width: 350px; }
|
|
object.equation {display: block; height: 140px; width: 100%; margin: 20px 20px -60px; }
|
|
</style>
|
|
<link href="http://www.w3.org/StyleSheets/TR/W3C-WD.css" rel=stylesheet type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
<div class=head> <!--begin-logo-->
|
|
<p><a href="http://www.w3.org/"><img alt="W3C" height="48"
|
|
src="http://www.w3.org/Icons/w3c_home" width=72></a> <!--end-logo-->
|
|
|
|
<h1 id="title_heading">DeviceOrientation Event Specification</h1>
|
|
|
|
<h2 class="no-num no-toc" id="draft_date">W3C Working Draft 1 December 2011</h2>
|
|
|
|
<dl>
|
|
<dt>This Version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/2011/WD-orientation-event-20111201/">http://www.w3.org/TR/2011/WD-orientation-event-20111201/</a></dd>
|
|
|
|
<dt>Latest Published Version:</dt>
|
|
|
|
<dd><a
|
|
href="http://www.w3.org/TR/orientation-event/">http://www.w3.org/TR/orientation-event/</a></dd>
|
|
|
|
<dt>Previous version:</dt>
|
|
<dd><a
|
|
href="http://www.w3.org/TR/2011/WD-orientation-event-20110628/">http://www.w3.org/TR/2011/WD-orientation-event-20110628/</a></dd>
|
|
<dt>Latest Editor's Draft:
|
|
|
|
<dd><a
|
|
href="http://dev.w3.org/geo/api/spec-source-orientation.html">http://dev.w3.org/geo/api/spec-source-orientation.html</a></dd>
|
|
|
|
|
|
<dt>Editors:</dt>
|
|
|
|
<dd>Steve Block, Google, Inc</dd>
|
|
<dd>Andrei Popescu, Google, Inc</dd>
|
|
</dl>
|
|
|
|
<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p>
|
|
|
|
<hr>
|
|
</div>
|
|
|
|
<h2 class="no-num no-toc" id="abstract">Abstract</h2>
|
|
|
|
<p>This specification defines several new DOM events that provide
|
|
information about the physical orientation and motion of a hosting device.</p>
|
|
|
|
<h2 class="no-num no-toc" id="status">Status of This Document</h2>
|
|
<!-- intro boilerplate (required) -->
|
|
<p><em>This section describes the status of this document at the time
|
|
of its publication. Other documents may supersede this document. A
|
|
list of current W3C publications and the latest revision of this
|
|
technical report can be found in
|
|
the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
|
|
http://www.w3.org/TR/.</em></p>
|
|
|
|
<!-- where to send feedback (required) -->
|
|
|
|
<p>This document was published by the <a
|
|
href="http://www.w3.org/2008/geolocation/">Geolocation Working Group</a> as a Last Call Working Draft.
|
|
When providing feedback, please first refer to the <a href="http://dev.w3.org/geo/api/spec-source-orientation.html">Editor's Draft</a> and confirm that the issue has not been addressed already. If the issue has not been addressed, please send it to the <a
|
|
href="mailto:public-geolocation@w3.org">public-geolocation@w3.org</a> (<a
|
|
href="mailto:public-geolocation-request@w3.org?subject=subscribe">subscribe</a>,
|
|
<a
|
|
href="http://lists.w3.org/Archives/Public/public-geolocation/">archives</a>) mailing list. The Last Call period ends 15 January 2012. For a list of changes, please see the <a href="orientation-fpwd-lc-diff.html">changes since the First Public Working Draft</a> diff document.</p>
|
|
<p>All feedback is welcome.</p>
|
|
<!-- stability (required) -->
|
|
|
|
<p>Publication as a Working Draft does not imply endorsement by the
|
|
W3C Membership. This is a draft document and may be updated, replaced
|
|
or obsoleted by other documents at any time. It is inappropriate to
|
|
cite this document as other than work in progress.</p>
|
|
|
|
<!-- required patent boilerplate -->
|
|
|
|
<p> This document was produced by a group operating under the <a
|
|
href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
|
|
2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42891/status" rel="disclosure">public list of any patent disclosures</a>
|
|
made in connection with the deliverables of the group; that page also
|
|
includes instructions for disclosing a patent. An individual who has
|
|
actual knowledge of a patent which the individual believes contains <a
|
|
href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
|
|
Claim(s)</a> must disclose the information in accordance with <a
|
|
href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
|
|
6 of the W3C Patent Policy</a>.
|
|
|
|
<h2 class="no-num no-toc" id="contents">Table of Contents</h2>
|
|
<!--begin-toc-->
|
|
<ul class=toc>
|
|
<li><a href="#conformance-requirements"><span class=secno>1 </span>Conformance requirements</a>
|
|
<li><a href="#introduction"><span class=secno>2 </span>Introduction</a>
|
|
<li><a href="#scope"><span class=secno>3 </span>Scope</a>
|
|
<li><a href="#description"><span class=secno>4 </span>Description</a>
|
|
<ul class=toc>
|
|
<li><a href="#deviceorientation"><span class=secno>4.1 </span>deviceorientation Event</a>
|
|
<li><a href="#compassneedscalibration"><span class=secno>4.2 </span>compassneedscalibration Event</a>
|
|
<li><a href="#devicemotion"><span class=secno>4.3 </span>devicemotion Event</a>
|
|
</ul>
|
|
<li><a href="#use-cases-and-requirements"><span class=secno>5 </span>Use-Cases and Requirements</a>
|
|
<ul class=toc>
|
|
<li><a href="#use-cases"><span class=secno>5.1 </span>Use-Cases</a>
|
|
<li><a href="#requirements"><span class=secno>5.2 </span>Requirements</a>
|
|
</ul>
|
|
<li><a href="#worked-example"><span class=secno>6 </span>Worked Example</a>
|
|
<li><a href="#acknowledgments">Acknowledgments</a>
|
|
<li><a href="#references">References</a>
|
|
</ul>
|
|
<!--end-toc-->
|
|
|
|
<h2 id="conformance-requirements"><span class=secno>1 </span>Conformance requirements</h2>
|
|
|
|
<p>All diagrams, examples, and notes in this specification are
|
|
non-normative, as are all sections explicitly marked non-normative.
|
|
Everything else in this specification is normative.
|
|
|
|
<p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
|
|
NOT",-->
|
|
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the
|
|
normative parts of this document are to be interpreted as described in
|
|
RFC2119. For readability, these words do not appear in all uppercase
|
|
letters in this specification. <a href="#ref-rfc2119">[RFC2119]</a></p>
|
|
<!-- XXX but they should be
|
|
marked up -->
|
|
|
|
<p>Requirements phrased in the imperative as part of algorithms (such as
|
|
"strip any leading space characters" or "return false and abort these
|
|
steps") are to be interpreted with the meaning of the key word ("must",
|
|
"should", "may", etc) used in introducing the algorithm.
|
|
|
|
<p>Conformance requirements phrased as algorithms or specific steps may be
|
|
implemented in any manner, so long as the end result is equivalent. (In
|
|
particular, the algorithms defined in this specification are intended to
|
|
be easy to follow, and not intended to be performant.)
|
|
|
|
<p id="hardwareLimitations">User agents may impose implementation-specific
|
|
limits on otherwise unconstrained inputs, e.g. to prevent denial of
|
|
service attacks, to guard against running out of memory, or to work around
|
|
platform-specific limitations.
|
|
|
|
<p>Implementations that use ECMAScript to implement the APIs defined in
|
|
this specification must implement them in a manner consistent with the
|
|
ECMAScript Bindings defined in the Web IDL specification, as this
|
|
specification uses that specification's terminology. <a
|
|
href="#ref-webidl">[WEBIDL]</a>
|
|
|
|
<p>The events introduced by this specification implement the Event interface
|
|
defined in the DOM Level 2 Events Specification,
|
|
<a href="#ref-domevents">[DOMEVENTS]</a>.
|
|
Implementations must therefore support this specification.
|
|
|
|
<h2 id="introduction"><span class=secno>2 </span>Introduction</h2>
|
|
|
|
<p><em>This section is non-normative.</em>
|
|
|
|
<p>This specification provides several 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.
|
|
|
|
<p>The first DOM event provided by the specification,
|
|
<code>deviceorientation</code>, supplies the physical orientation of the
|
|
device, expressed as a series of rotations from a local coordinate frame.
|
|
|
|
<p>The second DOM event provided by this specification,
|
|
<code>devicemotion</code>, supplies 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.
|
|
|
|
<p>Finally, the specification provides a <code>compassneedscalibration</code>
|
|
DOM event, which is used to inform Web sites that a compass being used to
|
|
provide data for one of the above events is in need of calibration.
|
|
|
|
<p>The following code extracts illustrate basic use of the events.
|
|
|
|
<div class=example>
|
|
<p>Registering to receive
|
|
<a href="#deviceorientation"><code>deviceorientation</code></a>
|
|
events:</p>
|
|
<pre>
|
|
window.addEventListener("deviceorientation", function(event) {
|
|
// process event.alpha, event.beta and event.gamma
|
|
}, true);
|
|
</pre>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>A device lying flat on a horizontal surface with the top of the
|
|
screen pointing West has the following orientation:</p>
|
|
<pre>
|
|
{alpha: 90,
|
|
beta: 0,
|
|
gamma: 0};
|
|
</pre>
|
|
<p> To get the compass heading, one would simply
|
|
subtract <code>alpha</code> from 360 degrees. As the device is
|
|
turned on the horizontal surface, the compass heading is (360
|
|
- <code>alpha</code>).</p>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>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 <code>beta</code> is 90, irrespective of
|
|
what <code>alpha</code> and <code>gamma</code> are.</p>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>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:</p>
|
|
<pre>
|
|
{alpha: 270 - alpha,
|
|
beta: 0,
|
|
gamma: 90};
|
|
</pre>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>Showing custom UI to instruct the user to calibrate the compass:</p>
|
|
<pre>
|
|
window.addEventListener("compassneedscalibration", function(event) {
|
|
alert('Your compass needs calibrating! Wave your device in a figure-eight motion');
|
|
event.preventDefault();
|
|
}, true);
|
|
</pre>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>Registering to receive
|
|
<a href="#devicemotion"><code>devicemotion</code></a> events:</p>
|
|
<pre>
|
|
window.addEventListener("devicemotion", function(event) {
|
|
// Process event.acceleration, event.accelerationIncludingGravity,
|
|
// event.rotationRate and event.interval
|
|
}, true);
|
|
</pre>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>A device lying flat on a horizontal surface with the screen upmost has
|
|
an <code>acceleration</code> of zero and the following value for
|
|
<code>accelerationIncludingGravity</code>:</p>
|
|
<pre>
|
|
{x: 0,
|
|
y: 0,
|
|
z: 9.81};
|
|
</pre>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>A device in free-fall, with the screen horizontal and upmost, has an
|
|
<code>accelerationIncludingGravity</code> of zero and the following value
|
|
for <code>acceleration</code>:</p>
|
|
<pre>
|
|
{x: 0,
|
|
y: 0,
|
|
z: -9.81};
|
|
</pre>
|
|
</div>
|
|
|
|
<div class=example>
|
|
<p>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 <code>acceleration</code>
|
|
and <code>accelerationIncludingGravity</code>. The device also records a
|
|
negative value for <code>rotationRate.gamma</code>:</p>
|
|
<pre>
|
|
{acceleration: {x: v^2/r, y: 0, z: 0},
|
|
accelerationIncludingGravity: {x: v^2/r, y: 0, z: 9.81},
|
|
rotationRate: {alpha: 0, beta: 0, gamma: -v/r*180/pi} };
|
|
</pre>
|
|
</div>
|
|
|
|
<h2 id="scope"><span class=secno>3 </span>Scope</h2>
|
|
|
|
<p><em>This section is non-normative.</em>
|
|
|
|
<p>This specification is limited to providing DOM events for retrieving
|
|
information describing the physical orientation and motion of the hosting
|
|
device. The intended purpose of this API is to enable simple use cases such
|
|
as those in <a href="#use-cases">Section 5.1</a>.
|
|
|
|
The scope of this specification does not include providing utilities to
|
|
manipulate this data, such as transformation libraries. Nor does it include
|
|
providing access to low sensor data, or direct control of these sensors.
|
|
|
|
<h2 id="description"><span class=secno>4 </span>Description</h2>
|
|
|
|
<h3 id="deviceorientation"><span class=secno>4.1 </span>deviceorientation Event</h3>
|
|
|
|
<p>User agents implementing this specification must provide a new DOM event,
|
|
named <code>deviceorientation</code>. The corresponding event must be of
|
|
type <code>DeviceOrientationEvent</code> and must fire on the
|
|
<code>window</code> object. Registration for, and firing of the
|
|
<code>deviceorientation</code> event must follow the usual behavior of DOM
|
|
Level 2 Events, <a href="#ref-domevents">[DOMEVENTS]</a>.
|
|
|
|
<p>User agents must also provide an event handler IDL attribute
|
|
<a href="#ref-html5">[HTML5]</a> named <code>ondeviceorientation</code> on the
|
|
<code>window</code> object. The type of this event handler must be
|
|
<code>DeviceOrientationEvent</code>.
|
|
|
|
<pre class=idl>
|
|
interface <dfn id="deviceorientation_event">DeviceOrientationEvent</dfn> : Event {
|
|
readonly attribute double? alpha;
|
|
readonly attribute double? beta;
|
|
readonly attribute double? gamma;
|
|
readonly attribute boolean absolute;
|
|
void initDeviceOrientationEvent(in DOMString type,
|
|
in boolean bubbles,
|
|
in boolean cancelable,
|
|
in double? alpha,
|
|
in double? beta,
|
|
in double? gamma,
|
|
in boolean absolute);
|
|
}
|
|
</pre>
|
|
|
|
<p>The event should fire whenever a significant change in orientation occurs.
|
|
The definition of a significant change in this context is left to the
|
|
implementation. In addition, when a new listener registers for the event,
|
|
implementations should fire the event as soon as sufficiently fresh data is
|
|
available.</p>
|
|
|
|
<p>The <code>alpha</code>, <code>beta</code> and <code>gamma</code> properties
|
|
of the event must specify the orientation of the device in terms of the
|
|
transformation from a coordinate frame fixed on the Earth to a
|
|
coordinate frame fixed in the device. The coordinate frames must be oriented
|
|
as described below.</p>
|
|
|
|
<p>The Earth coordinate frame is a 'East, North, Up' frame at the user's
|
|
location. It has the following 3 axes, where the ground plane is tangent to
|
|
the spheriod of the World Geodetic System 1984
|
|
<a href="#ref-wgs84">[WGS84]</a>, at the user's location.
|
|
|
|
<ul>
|
|
<li>East (X) is in the ground plane, perpendicular to the North axis and positive towards the East.</li>
|
|
<li>North (Y) is in the ground plane and positive towards True North (towards the North Pole).</li>
|
|
<li>Up (Z) is perpendicular to the ground plane and positive upwards.</li>
|
|
</ul>
|
|
|
|
<p>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. 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. Users wishing to detect these changes in screen
|
|
orientation may be able to do so with the existing
|
|
<code>orientationchange</code> event.
|
|
For a laptop computer, the device coordinate frame is defined relative to the
|
|
integrated keyboard.
|
|
|
|
<ul>
|
|
<li>x is in the plane of the screen or keyboard and is positive towards the right hand side of the screen or keyboard.</li>
|
|
<li>y is in the plane of the screen or keyboard and is positive towards the top of the screen or keyboard.</li>
|
|
<li>z is perpendicular to the screen or keyboard, positive out of the screen or keyboard.</li>
|
|
</ul>
|
|
|
|
<p>The transformation from the Earth coordinate frame to the device coordinate
|
|
frame must use the following system of rotations.
|
|
|
|
<p>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. Starting with the two frames aligned, the rotations are applied in the
|
|
following order:</p>
|
|
|
|
<ol id="rotations">
|
|
<li>
|
|
<p>Rotate the device frame around its z axis by <code>alpha</code> degrees, with <code>alpha</code> in [0, 360).</p>
|
|
<div>
|
|
<img src="start.png" alt="start orientation">
|
|
<div>Device in the initial position, with Earth (XYZ) and body (xyz) frames aligned.</div>
|
|
</div>
|
|
<div>
|
|
<img src="c-rotation.png" alt="rotation about z axis">
|
|
<div>Device rotated through angle alpha about z axis, with previous locations of x and y axes shown as x<sub>0</sub> and y<sub>0</sub>.</div>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Rotate the device frame around its x axis by <code>beta</code> degrees, with <code>beta</code> in [-180, 180).</p>
|
|
<div>
|
|
<img src="a-rotation.png" alt="rotation about x axis">
|
|
<div>Device rotated through angle beta about new x axis, with previous locations of y and z axes shown as y<sub>0</sub> and z<sub>0</sub>.</div>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Rotate the device frame around its y axis by <code>gamma</code> degrees, with <code>gamma</code> in [-90, 90).</p>
|
|
<div>
|
|
<img src="b-rotation.png" alt="rotation about y axis">
|
|
<div>Device rotated through angle gamma about new y axis, with previous locations of x and z axes shown as x<sub>0</sub> and z<sub>0</sub>.</div>
|
|
</div>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>Thus the angles <code>alpha</code>, <code>beta</code> and
|
|
<code>gamma</code> form a set of intrinsic Tait-Bryan angles of type Z-X'-Y''.
|
|
<a href="#ref-eulerangles">[EULERANGLES]</a>
|
|
Note that this choice of angles follows mathematical convention, but means
|
|
that <code>alpha</code> 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.</p>
|
|
|
|
<p> Implementations that are unable to provide absolute values for the three
|
|
angles may instead provide values relative to some arbitrary orientation, as
|
|
this may still be of utility. In this case, the <code>absolute</code> property
|
|
must be set to <code>false</code>. Otherwise, the <code>absolute</code>
|
|
property must be set to <code>true</code>.</p>
|
|
|
|
<p> Implementations that are unable to provide all three angles must
|
|
set the values of the unknown angles to null. If any angles are provided, the
|
|
<code>absolute</code> property must be set appropriately. If an implementation
|
|
can never provide orientation information, the event should be fired
|
|
with all properties set to null.</p>
|
|
|
|
<h3 id="compassneedscalibration"><span class=secno>4.2 </span>compassneedscalibration Event</h3>
|
|
|
|
<p>User agents implementing this specification must provide a new DOM event,
|
|
named <code>compassneedscalibration</code> that uses the <code>Event</code>
|
|
interface defined in the DOM Level 2 Events specification
|
|
<a href="#ref-domevents">[DOMEVENTS]</a>. This event must fire on the
|
|
<code>window</code> object. Registration for, and firing of the
|
|
<code>compassneedscalibration</code> event must follow the usual behavior of
|
|
DOM Level 2 Events <a href="#ref-domevents">[DOMEVENTS]</a>.
|
|
|
|
<p>User agents must also provide an event handler IDL attribute
|
|
<a href="#ref-html5">[HTML5]</a> named <code>oncompassneedscalibration</code>
|
|
on the <code>window</code> object. The type of this event handler must be
|
|
<code>Event</code>.
|
|
|
|
<p>This event must be fired when the user agent determines that a compass used
|
|
to obtain orientation data is in need of calibration. Furthermore, user agents
|
|
should only fire the event if calibrating the compass will increase the
|
|
accuracy of the data provided by the
|
|
<code><a href="#deviceorientation">deviceorientation</a></code> event.
|
|
|
|
<p>The default action of this event should be for the user agent to present the
|
|
user with details of how to calibrate the compass. The event must be
|
|
cancelable, so that web sites can provide their own alternative calibration
|
|
UI.
|
|
|
|
<h3 id="devicemotion"><span class=secno>4.3 </span>devicemotion Event</h3>
|
|
|
|
<p>User agents implementing this specification must provide a new DOM event,
|
|
named <code>devicemotion</code>. The corresponding event must be of type
|
|
<code>DeviceMotionEvent</code> and must fire on the <code>window</code>
|
|
object.
|
|
Registration for, and firing of the <code>devicemotion</code>
|
|
event must follow the usual behavior of DOM Level 2 Events,
|
|
<a href="#ref-domevents">[DOMEVENTS]</a>.
|
|
|
|
<p>User agents must also provide an event handler IDL attribute
|
|
<a href="#ref-html5">[HTML5]</a> named <code>ondevicemotion</code>
|
|
on the <code>window</code> object. The type of this event handler must be
|
|
<code>DeviceMotionEvent</code>.
|
|
|
|
<pre class=idl>
|
|
[Callback, NoInterfaceObject]
|
|
interface <dfn id="device_acceleration">DeviceAcceleration</dfn> {
|
|
readonly attribute double? x;
|
|
readonly attribute double? y;
|
|
readonly attribute double? z;
|
|
}
|
|
|
|
[Callback, NoInterfaceObject]
|
|
interface <dfn id="device_rotation_rate">DeviceRotationRate</dfn> {
|
|
readonly attribute double? alpha;
|
|
readonly attribute double? beta;
|
|
readonly attribute double? gamma;
|
|
}
|
|
|
|
interface <dfn id="devicemotion_event">DeviceMotionEvent</dfn> : Event {
|
|
readonly attribute DeviceAcceleration? acceleration;
|
|
readonly attribute DeviceAcceleration? accelerationIncludingGravity;
|
|
readonly attribute DeviceRotationRate? rotationRate;
|
|
readonly attribute double? interval;
|
|
void initAccelerometerEvent(in DOMString type,
|
|
in boolean bubbles,
|
|
in boolean cancelable,
|
|
in DeviceAcceleration? acceleration,
|
|
in DeviceAcceleration? accelerationIncludingGravity,
|
|
in DeviceRotationRate? rotationRate,
|
|
in double? interval);
|
|
}
|
|
</pre>
|
|
|
|
<p>The <code>acceleration</code> property must provide the acceleration of the
|
|
hosting device relative to the Earth frame, expressed in the body frame, as
|
|
defined in <a href="#deviceorientation">section 4.1</a>. The acceleration must
|
|
be expressed in m/s^2.
|
|
|
|
<p>Implementations that are unable to provide acceleration data without the
|
|
effect of gravity (due, for example, to the lack of a gyroscope) may instead
|
|
supply the acceleration including the effect of gravity. This is less useful
|
|
in many applications but is provided as a means of providing best-effort
|
|
support. In this case, the <code>accelerationIncludingGravity</code> property
|
|
must provide the acceleration of the hosting device, plus an acceleration
|
|
equal and opposite to the acceleration due to gravity. Again, the acceleration
|
|
must be given in the body frame defined in
|
|
<a href="#deviceorientation">section 4.1</a> and must be expressed in m/s^2.
|
|
|
|
<p>The <code>rotationRate</code> property must provide the rate of rotation of
|
|
the hosting device in space. It must be expressed as the rate of change of
|
|
the angles of the defined in <a href="#deviceorientation">section 4.1</a> and
|
|
must be expressed in deg/s.
|
|
|
|
<p>The <code>interval</code> property must provide the interval at which
|
|
data is obtained from the underlying hardware and must be expressed in
|
|
milliseconds. It must be a constant, to simplify filtering of the data by the
|
|
Web application.
|
|
|
|
<p>Implementations that are unable to provide all properties must
|
|
set the values of the unknown properties to null. If an implementation
|
|
can never provide motion information, the event should be fired
|
|
with all properties set to null.
|
|
|
|
<h2 id="use-cases-and-requirements"><span class=secno>5 </span>Use-Cases and Requirements</h2>
|
|
|
|
<h3 id="use-cases"><span class=secno>5.1 </span>Use-Cases</h3>
|
|
|
|
<h4 id="controlling-a-game"><span class=secno>5.1.1 </span>Controlling a game</h4>
|
|
<p>A gaming Web application monitors the device's orientation and interprets
|
|
tilting in a certain direction as a means to control an on-screen sprite.
|
|
|
|
<h4 id="gesture-recognition"><span class=secno>5.1.2 </span>Gesture recognition</h4>
|
|
<p>A Web application monitors the device's acceleration and applies signal
|
|
processing in order to recognize certain specific gestures. For example, using
|
|
a shaking gesture to clear a web form.
|
|
|
|
<h4 id="mapping"><span class=secno>5.1.3 </span>Mapping</h4>
|
|
<p>A mapping Web application uses the device's orientation to correctly align
|
|
the map with reality.
|
|
|
|
<h3 id="requirements"><span class=secno>5.2 </span>Requirements</h3>
|
|
|
|
<h4 id="requirement-orientation"><span class=secno>5.2.1 </span>The specification must provide data that describes the physical orientation in space of the device.</h4>
|
|
<h4 id="requirement-motion"><span class=secno>5.2.2 </span>The specification must provide data that describes the motion in space of the device.</h4>
|
|
<h4 id="requirement-changes"><span class=secno>5.2.3 </span>The specification must allow Web applications to register for changes in the device's orientation.</h4>
|
|
<h4 id="requirement-agnostic"><span class=secno>5.2.4 </span>The specification must be agnostic to the underlying sources of orientation and motion data.</h4>
|
|
<h4 id="requirement-use-dom"><span class=secno>5.2.5 </span>The specification must use the existing DOM event framework.</h4>
|
|
|
|
<h2 id="worked-example">Worked Example</h2>
|
|
|
|
<p><em>This section is non-normative.</em>
|
|
|
|
<p>The following worked example is intended as an aid to users of the
|
|
DeviceOrientation event.
|
|
|
|
<p><a href="#introduction">Section 2</a> 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.
|
|
|
|
<p>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.
|
|
|
|
<p>If r represents this vector in the rotated device body frame xyz, then r
|
|
is as follows.
|
|
|
|
<object class="equation" data="equation1.xhtml" type="application/mathml+xml">
|
|
<p><img src="equation1.gif">
|
|
</object>
|
|
|
|
<p>The transformation of r due to the rotation about the z axis can be
|
|
represented by the following rotation matrix.
|
|
|
|
<object class="equation" data="equation2.xhtml" type="application/mathml+xml">
|
|
<img src="equation2.gif">
|
|
</object>
|
|
|
|
<p>The transformation of r due to the rotation about the x axis can be
|
|
represented by the following rotation matrix.
|
|
|
|
<object class="equation" data="equation3.xhtml" type="application/mathml+xml">
|
|
<img src="equation3.gif">
|
|
</object>
|
|
|
|
<p>The transformation of r due to the rotation about the y axis can be
|
|
represented by the following rotation matrix.
|
|
|
|
<object class="equation" data="equation4.xhtml" type="application/mathml+xml">
|
|
<img src="equation4.gif">
|
|
</object>
|
|
|
|
<p>If R resresents the vector r in the earth frame XYZ, then since the inital
|
|
body frame is aligned with the earth, R is as follows.
|
|
|
|
<object class="equation" data="equation5a.xhtml" type="application/mathml+xml">
|
|
<img src="equation5a.gif">
|
|
</object>
|
|
<object class="equation" data="equation5b.xhtml" type="application/mathml+xml">
|
|
<img src="equation5b.gif">
|
|
</object>
|
|
<object class="equation" data="equation5c.xhtml" type="application/mathml+xml">
|
|
<img src="equation5c.gif">
|
|
</object>
|
|
<object class="equation" data="equation5d.xhtml" type="application/mathml+xml">
|
|
<img src="equation5d.gif">
|
|
</object>
|
|
<object class="equation" data="equation5e.xhtml" type="application/mathml+xml">
|
|
<img src="equation5e.gif">
|
|
</object>
|
|
|
|
<p>The compass heading θ is given by
|
|
|
|
<object class="equation" data="equation6.xhtml" type="application/mathml+xml">
|
|
<img src="equation6.gif">
|
|
</object>
|
|
|
|
<p>provided that β and γ are not both zero.
|
|
|
|
<p>As a consistency check, if we set γ = 0, then
|
|
|
|
<object class="equation" data="equation7.xhtml" type="application/mathml+xml">
|
|
<img src="equation7.gif">
|
|
</object>
|
|
|
|
<p>as expected.
|
|
|
|
<p>Alternatively, if we set β = 90, then
|
|
|
|
<object class="equation" data="equation8a.xhtml" type="application/mathml+xml">
|
|
<img src="equation8a.gif">
|
|
</object>
|
|
<object class="equation" data="equation8b.xhtml" type="application/mathml+xml">
|
|
<img src="equation8b.gif">
|
|
</object>
|
|
|
|
<p>as expected.
|
|
|
|
<h2 class=no-num id="acknowledgments">Acknowledgments</h2>
|
|
|
|
<p>Lars Erik Bolstad, Dean Jackson, Claes Nilsson, George Percivall, Doug Turner, Matt Womer
|
|
|
|
<h2 class=no-num id="references">References</h2>
|
|
|
|
<dl>
|
|
<dt><a id="ref-domevents">[DOMEVENTS]</a></dt>
|
|
<dd><cite><a href="http://www.w3.org/TR/DOM-Level-2-Events/">DOM Level 2 Events</a></cite>, See http://www.w3.org/TR/DOM-Level-2-Events/</dd>
|
|
<dt><a id="ref-eulerangles">[EULERANGLES]</a></dt>
|
|
<dd><em>(Non-normative)</em> <cite><a href="http://en.wikipedia.org/wiki/Euler_angles">Euler Angles</a></cite>, See http://en.wikipedia.org/wiki/Euler_angles</dd>
|
|
<dt><a id="ref-html5">[HTML5]</a></dt>
|
|
<dd><cite><a href="http://dev.w3.org/html5/spec/Overview.html">HTML5</a></cite>, See http://dev.w3.org/html5/spec/Overview.html</dd>
|
|
<dt><a id=ref-rfc2119>[RFC2119]</a></dt>
|
|
<dd><cite><a href="http://www.ietf.org/rfc/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a></cite>, Scott Bradner. Internet Engineering Task Force, March 1997. See http://www.ietf.org/rfc/rfc2119.txt</dd>
|
|
<dt><a id=ref-webidl>[WEBIDL]</a></dt>
|
|
<dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, Cameron McCormack, Editor. World Wide Web Consortium, 19 December 2008. See http://dev.w3.org/2006/webapi/WebIDL</dd>
|
|
<dt><a id="ref-wgs84">[WGS84]</a></dt>
|
|
<dd><cite><a href="http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf">National Imagery and Mapping Agency Technical Report 8350.2, Third Edition</a></cite>. National Imagery and Mapping Agency, 3 January 2000. See http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf</dd>
|
|
</dl>
|
|
</body>
|
|
</html>
|