Copyright © 2011 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.
This
specification
defines
several
new
DOM
events
event
types
that
provide
information
about
the
physical
orientation
and
motion
of
a
hosting
device.
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 W3C technical reports index at http://www.w3.org/TR/.
This
document
was
published
by
the
Geolocation
Working
Group
as
a
Last
Call
Working
Draft.
.
If
you
wish
to
make
comments
regarding
this
document,
please
send
them
to
public-geolocation@w3.org
(
subscribe
,
archives
).
The
Last
Call
period
ends
on
@@
30
November
2011
@@.
All feedback is welcome.
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.
This
is
the
Last
Call
First
Public
Working
draft
of
this
specification.
It
should
not
be
considered
stable.
When
providing
feedback,
please
first
refer
to
the
Editor's
Draft
and
confirm
that
the
issue
has
not
been
addressed
already.
If
the
issue
has
not
been
addressed,
please
describe
it
report
the
issue
on
the
public
mailing
list
.
The
Last
Call
period
ends
@@
30
November
2011
@@
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures 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 Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
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.
The key words "MUST", "MUST NOT", "REQUIRED", "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. [RFC2119]
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.
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.)
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.
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. [WEBIDL]
The events introduced by this specification implement the Event interface defined in the DOM Level 2 Events Specification, [DOMEVENTS] . Implementations must therefore support this specification.
This section is non-normative.
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
is
agnostic
to
of
the
underlying
source
of
information.
Common
sources
of
information
include
gyroscopes,
compasses
and
accelerometers.
The
first
DOM
event
provided
by
the
specification,
deviceorientation
,
supplies
the
physical
orientation
of
the
device,
expressed
specified
as
a
series
of
rotations
from
a
local
coordinate
frame.
The
second
DOM
event
provided
by
this
specification,
devicemotion
,
supplies
the
acceleration
of
the
device,
expressed
specified
in
Cartesian
cartesian
coordinates
in
relative
to
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.
Finally,
the
specification
provides
a
compassneedscalibration
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.
The following code extracts illustrate basic use of the events.
Registering
to
receive
deviceorientation
events:
window.addEventListener("deviceorientation", function(event) { // process event.alpha, event.beta and event.gamma }, true);
A device lying flat on a horizontal surface with the top of the screen pointing West has the following orientation:
{alpha: 90, beta: 0, gamma: 0};
To
get
the
compass
heading,
one
would
simply
subtract
alpha
from
360
degrees.
As
the
device
is
turned
on
the
horizontal
surface,
the
compass
heading
is
(360
-
alpha
).
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
beta
is
90,
irrespective
of
what
alpha
and
gamma
are.
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:
{alpha: 270 - alpha, beta: 0, gamma: 90};
Showing custom UI to instruct the user to calibrate the compass:
window.addEventListener("compassneedscalibration", function(event) { alert('Your compass needs calibrating! Wave your device in a figure-eight motion'); event.preventDefault(); }, true);
Registering
to
receive
devicemotion
events:
window.addEventListener("devicemotion", function(event) { // Process event.acceleration, event.accelerationIncludingGravity, // event.rotationRate and event.interval }, true);
A
device
lying
flat
on
a
horizontal
surface
with
the
screen
upmost
has
an
acceleration
of
zero
and
the
following
value
for
accelerationIncludingGravity
:
{x: 0, y: 0, z: 9.81};
A
device
in
free-fall,
with
the
screen
horizontal
and
upmost,
has
an
accelerationIncludingGravity
of
zero
and
the
following
value
for
acceleration
:
{x: 0, y: 0, z: -9.81};
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
acceleration
and
accelerationIncludingGravity
.
The
device
also
records
a
negative
value
for
rotationRate.gamma
:
{acceleration: {x: v^2/r, y: 0, z: 0},{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} };
This section is non-normative.
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 Section 5.2 . 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.
User
agents
implementing
this
specification
must
provide
allow
a
new
DOM
event,
event
type,
named
deviceorientation
.
The
corresponding
event
must
be
of
type
DeviceOrientationEvent
and
must
fire
on
the
window
object.
Registration
for,
and
firing
of
the
deviceorientation
event
must
follow
the
usual
behavior
of
DOM
Level
2
Events,
[DOMEVENTS]
.
User
agents
must
also
provide
an
event
handler
IDL
attribute
[HTML5]
named
ondeviceorientation
on
the
window
object.
The
type
of
this
event
handler
must
be
DeviceOrientationEvent
.
interface DeviceOrientationEvent : 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); }
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.
The
alpha
,
beta
and
gamma
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.
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 [WGS84] , at the user's location.
For
a
mobile
device
such
as
a
phone
or
tablet,
the
device
coordinate
frame
is
defined
relative
to
the
screen
in
its
standard
orientation,
orientation
of
the
screen,
typically
portrait.
This
means
that
portrait,
when
slide-out
elements
such
as
keyboards
are
not
deployed,
and
swiveling
elements
such
as
displays
are
folded
to
their
default
position.
deployed.
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
orientationchange
event.
For
a
laptop
computer,
the
device
coordinate
frame
is
defined
relative
to
the
integrated
keyboard.
The transformation from the Earth coordinate frame to the device coordinate frame must use the following system of rotations.
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:
Rotate
the
device
frame
around
its
z
axis
by
alpha
degrees,
with
alpha
in
[0,
360).
Rotate
the
device
frame
around
its
x
axis
by
beta
degrees,
with
beta
in
[-180,
180).
Rotate
the
device
frame
around
its
y
axis
by
gamma
degrees,
with
gamma
in
[-90,
90).
Thus
the
angles
alpha
,
beta
and
gamma
form
a
set
of
intrinsic
Tait-Bryan
angles
of
type
Z-X'-Y''.
[EULERANGLES]
Note
that
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.
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
absolute
property
must
be
set
to
false
.
Otherwise,
the
absolute
property
must
be
set
to
true
.
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
absolute
property
must
be
set
appropriately.
If
an
implementation
can
never
provide
orientation
information,
the
event
should
be
fired
with
all
properties
set
to
null.
User
agents
implementing
this
specification
must
provide
allow
a
new
DOM
event,
named
compassneedscalibration
that
uses
the
Event
interface
defined
in
the
DOM
Level
2
Events
specification
[DOMEVENTS]
.
This
event
must
fire
on
the
window
object.
Registration
for,
and
firing
of
the
compassneedscalibration
event
must
follow
the
usual
behavior
of
DOM
Level
2
Events
Events,
[DOMEVENTS]
.
User
agents
must
also
provide
an
event
handler
IDL
attribute
[HTML5]
named
oncompassneedscalibration
on
the
window
object.
The
type
of
this
event
handler
must
be
Event
.
This
event
must
only
be
fired
when
one
or
more
event
listeners
are
registered
for
the
deviceorientation
event
and
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
deviceorientation
event.
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.
User
agents
implementing
this
specification
must
provide
allow
a
new
DOM
event,
event
type,
named
devicemotion
.
The
corresponding
event
must
be
of
type
DeviceMotionEvent
and
must
fire
on
the
window
object.
Registration
for,
and
firing
of
the
devicemotion
event
must
follow
the
usual
behavior
of
DOM
Level
2
Events,
[DOMEVENTS]
.
User
agents
must
also
provide
an
event
handler
IDL
attribute
[HTML5]
named
ondevicemotion
on
the
window
object.
The
type
of
this
event
handler
must
be
DeviceMotionEvent
.
[Callback, NoInterfaceObject]interface {interface Acceleration { readonly attribute double? x; readonly attribute double? y; readonly attribute double? z; } [Callback, NoInterfaceObject]interface {interface RotationRate { readonly attribute double? alpha; readonly attribute double? beta; readonly attribute double? gamma; } interface DeviceMotionEvent : Event {readonly attribute DeviceAcceleration? acceleration; readonly attribute DeviceAcceleration? accelerationIncludingGravity; readonly attribute DeviceRotationRate? rotationRate;readonly attribute Acceleration? acceleration; readonly attribute Acceleration? accelerationIncludingGravity; readonly attribute RotationRate? 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 Acceleration? acceleration, in Acceleration? accelerationIncludingGravity, in RotationRate? rotationRate, in double? interval); }
The
event
must
fire
at
regular
intervals
and
the
interval
property
must
provide
this
interval
in
milliseconds.
The
acceleration
property
must
provide
the
acceleration
of
the
hosting
device
relative
to
the
Earth
frame,
expressed
in
the
body
frame,
as
frame
defined
in
section
4.1
.
The
acceleration
and
must
be
expressed
in
m/s^2.
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
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
section
4.1
and
must
be
expressed
in
m/s^2.
accelerationIncludingGravity
accelerationInclusingGravity
The
rotationRate
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
section
4.1
and
must
be
expressed
in
deg/s.
The
interval
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.
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.
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.
A
Web
application
monitors
the
device's
acceleration
and
applies
signal
processing
in
order
to
recognize
recognise
certain
specific
gestures.
For
example,
using
a
shaking
gesture
to
clear
a
web
form.
A mapping Web application uses the device's orientation to correctly align the map with reality.
This
section
is
non-normative.
The
following
worked
example
is
intended
as
an
aid
to
users
of
the
DeviceOrientation
event.
Section
2
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.
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.
If
r
represents
this
vector
in
the
rotated
device
body
frame
xyz,
then
r
is
as
follows.
The
transformation
of
r
due
to
the
rotation
about
the
z
axis
can
be
represented
by
the
following
rotation
matrix.
The
transformation
of
r
due
to
the
rotation
about
the
x
axis
can
be
represented
by
the
following
rotation
matrix.
The
transformation
of
r
due
to
the
rotation
about
the
y
axis
can
be
represented
by
the
following
rotation
matrix.
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.
The
compass
heading
θ
is
given
by
Lars
Erik
Bolstad,
Dean
Jackson,
Claes
Nilsson,
George
Percivall,
Doug
Turner,
Matt
Womer