This
specification
defines
several
new
DOM
events
that
provide
information
about
the
physical
orientation
and
motion
of
a
hosting
device.
Status
of
This
Document
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/.
https://www.w3.org/TR/.
This
document
was
published
by
the
Geolocation
Working
Group
as
a
Last
Call
Working
Draft.
When
providing
feedback,
please
first
refer
to
the
Editor's
Draft
and
confirm
that
the
issue
has
not
been
addressed
already.
Candidate
Recommendation.
If
the
issue
has
not
been
addressed,
you
wish
to
make
comments
regarding
this
document,
please
send
it
them
to
the
public-geolocation@w3.org
(
subscribe
,
archives
)
mailing
list.
The
Last
Call
period
ends
).
All
feedback
is
welcome.
A
diff-marked
version
of
this
document
from
the
previous
draft
is
available
for
comparison
purposes.
W3C
publishes
a
Candidate
Recommendation
to
indicate
that
the
document
is
believed
to
be
stable
and
to
encourage
implementation
by
the
developer
community.
This
Candidate
Recommendation
is
expected
to
advance
to
Proposed
Recommendation
no
earlier
than
15
January
2012.
September
2016.
For
a
list
of
changes,
please
see
this
specification
to
exit
the
changes
since
Candidate
Recommendation
stage,
two
independent
implementations
will
be
required
to
pass
each
test
in
the
First
Public
Working
Draft
diff
document.
DeviceOrientation
test
suite
.
Publication
as
a
Working
Draft
Candidate
Recommendation
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.
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
DOM4
Specification,
[DOMEVENTS]
[DOM4]
.
Implementations
must
therefore
support
this
specification.
2
Introduction
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
agnostic
to
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
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
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.
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.
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);
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
:
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.1
6.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.
4
Description
4.1
deviceorientation
Event
User
agents
implementing
this
specification
must
provide
a
new
DOM
event,
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
DOM4
Events,
[DOMEVENTS]
[DOM4]
.
User
agents
must
also
provide
an
event
handler
IDL
attribute
[HTML5]
named
ondeviceorientation
on
the
window
object.
The
type
of
this
the
corresponding
event
handler
event
type
must
be
DeviceOrientationEvent
deviceorientation
.
The
alpha
attribute
must
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
null.
The
beta
attribute
must
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
null.
The
gamma
attribute
must
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
null.
The
absolute
attribute
must
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
false.
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
implementation,
though
a
new
listener
registers
maximum
threshold
for
the
event,
implementations
should
change
of
one
degree
is
recommended.
Implementations
may
also
fire
the
event
as
soon
as
if
they
have
reason
to
believe
that
the
page
does
not
have
sufficiently
fresh
data
is
available.
data.
The
alpha
,
beta
and
gamma
properties
attributes
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.
East
(X)
is
in
the
ground
plane,
perpendicular
to
the
North
axis
and
positive
towards
the
East.
North
(Y)
is
in
the
ground
plane
and
positive
towards
True
North
(towards
the
North
Pole).
Up
(Z)
is
perpendicular
to
the
ground
plane
and
positive
upwards.
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
orientationchange
event.
For
a
laptop
computer,
the
device
coordinate
frame
is
defined
relative
to
the
integrated
keyboard.
x
is
in
the
plane
of
the
screen
or
keyboard
and
is
positive
towards
the
right
hand
side
of
the
screen
or
keyboard.
y
is
in
the
plane
of
the
screen
or
keyboard
and
is
positive
towards
the
top
of
the
screen
or
keyboard.
z
is
perpendicular
to
the
screen
or
keyboard,
positive
out
of
the
screen
or
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).
Device
in
the
initial
position,
with
Earth
(XYZ)
and
body
(xyz)
frames
aligned.
Device
rotated
through
angle
alpha
about
z
axis,
with
previous
locations
of
x
and
y
axes
shown
as
x
0
and
y
0
.
Rotate
the
device
frame
around
its
x
axis
by
beta
degrees,
with
beta
in
[-180,
180).
Device
rotated
through
angle
beta
about
new
x
axis,
with
previous
locations
of
y
and
z
axes
shown
as
y
0
and
z
0
.
Rotate
the
device
frame
around
its
y
axis
by
gamma
degrees,
with
gamma
in
[-90,
90).
Device
rotated
through
angle
gamma
about
new
y
axis,
with
previous
locations
of
x
and
z
axes
shown
as
x
0
and
z
0
.
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
The
deviceorientation
event
tries
to
provide
absolute
relative
values
for
the
three
angles
may
instead
provide
values
relative
(relative
to
some
arbitrary
orientation,
as
this
may
orientation),
based
on
just
the
accelerometer
and
the
gyroscope.
The
implementation
can
still
be
of
utility.
decide
to
provide
absolute
orientation
if
relative
is
not
available
or
the
resulting
data
is
more
accurate.
In
this
either
case,
the
absolute
property
must
be
set
accordingly
to
false
.
Otherwise,
reflect
the
absolute
property
must
be
set
to
true
.
choice.
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
the
alpha
,
beta
and
gamma
attributes
set
to
null.
4.2
deviceorientationabsolute
Event
User
agents
implementing
this
specification
must
provide
a
new
DOM
event,
named
deviceorientationabsolute
.
The
corresponding
event
must
be
of
type
DeviceOrientationEvent
and
must
fire
on
the
window
object.
Registration
for,
and
firing
of
the
deviceorientationabsolute
event
must
follow
the
usual
behavior
of
DOM4
Events,
[DOM4]
.
User
agents
must
also
provide
an
event
handler
IDL
attribute
[HTML5]
named
ondeviceorientationabsolute
on
the
window
object.
The
type
of
the
corresponding
event
handler
event
type
must
be
deviceorientationabsolute
.
The
deviceorientationabsolute
event
is
completely
analogous
to
the
deviceorientation
event,
except
additional
sensors
like
the
magnetometer
can
be
used
to
provide
an
absolute
orientation.
The
absolute
property
must
be
set
to
true
.
If
an
implementation
can
never
provide
absolute
orientation
information,
the
event
should
be
fired
with
the
alpha
,
beta
and
gamma
attributes
set
to
null.
4.3
compassneedscalibration
Event
User
agents
implementing
this
specification
must
provide
a
new
DOM
event,
named
compassneedscalibration
that
uses
the
Event
interface
defined
in
the
DOM
Level
2
DOM4
Events
specification
[DOMEVENTS]
[DOM4]
.
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
DOM4
Events
[DOMEVENTS]
[DOM4]
.
User
agents
must
also
provide
an
event
handler
IDL
attribute
[HTML5]
named
oncompassneedscalibration
on
the
window
object.
The
type
of
this
the
corresponding
event
handler
must
be
Event
compassneedscalibration
.
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
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.
4.3
4.4
devicemotion
Event
User
agents
implementing
this
specification
must
provide
a
new
DOM
event,
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
DOM4
Events,
[DOMEVENTS]
[DOM4]
.
User
agents
must
also
provide
an
event
handler
IDL
attribute
[HTML5]
named
ondevicemotion
on
the
window
object.
The
type
of
this
the
corresponding
event
handler
event
type
must
be
DeviceMotionEvent
devicemotion
.
The
acceleration
property
attribute
must
provide
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
null.
The
accelerationIncludingGravity
attribute
must
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
null.
The
rotationRate
attribute
must
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
null.
The
interval
attribute
must
return
the
value
it
was
initialized
to.
When
the
object
is
created,
this
attribute
must
be
initialized
to
0.
In
the
DeviceMotionEvent
events
fired
by
the
user
agent,
the
following
requirements
must
apply:
The
acceleration
attribute
must
be
initialized
with
the
acceleration
of
the
hosting
device
relative
to
the
Earth
frame,
expressed
in
the
body
frame,
as
defined
in
section
4.1
.
The
acceleration
must
be
expressed
in
m/s^2.
meters
per
second
squared
(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
accelerationIncludingGravity
property
attribute
must
provide
be
initialized
with
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.
meters
per
second
squared
(m/s
2
).
The
rotationRate
property
attribute
must
provide
be
initialized
with
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.
degrees
per
second
(deg/s).
The
interval
property
attribute
must
provide
be
initialized
with
the
interval
at
which
data
is
obtained
from
the
underlying
hardware
and
must
be
expressed
in
milliseconds.
milliseconds
(ms).
It
must
be
a
constant,
to
simplify
filtering
of
the
data
by
the
Web
application.
Implementations
that
are
unable
to
provide
all
properties
attributes
must
set
initialize
the
values
of
the
unknown
properties
attributes
to
null.
If
an
implementation
can
never
provide
motion
information,
the
event
should
be
fired
with
all
properties
attributes
set
to
null.
5
Security
and
privacy
considerations
This
section
is
non-normative.
The
API
defined
in
this
specification
can
be
used
to
obtain
information
from
hardware
sensors
like
accelerometer,
gyroscope,
etc.
The
provided
information
is
currently
considered
not
sensitive
enough
to
warrant
specific
sensor
permission
grants.
However
there
have
been
academic
efforts
to
exploit
hardware
specific
sensor
bias
for
fingerprinting
purposes
[FINGERPRINT]
.
Some
researchers
claim
to
be
able
to
detect
user
touch
actions
with
some
reliability
from
sensor
data
[TOUCH]
.
In
light
of
that
implementations
may
consider
permissions
or
visual
indicators
to
signify
the
use
of
sensors
by
the
page.
Furthermore
to
minimize
privacy
risks,
the
chance
of
fingerprinting
and
other
attacks
the
implementations
should
take
into
consideration
the
following
suggestions:
do
not
fire
events
on
invisible
or
backgrounded
pages,
limit
the
frequency
of
events
(typically
60Hz
seems
to
be
sufficient).
Additionally,
implementing
these
items
will
also
have
a
beneficial
impact
on
the
battery
life
of
mobile
devices.
6
Use-Cases
and
Requirements
5.1
6.1
Use-Cases
5.1.1
6.1.1
Controlling
a
game
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.
5.1.2
6.1.2
Gesture
recognition
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.
5.1.3
6.1.3
Mapping
A
mapping
Web
application
uses
the
device's
orientation
to
correctly
align
the
map
with
reality.
5.2
6.2
Requirements
5.2.1
6.2.1
The
specification
must
provide
data
that
describes
the
physical
orientation
in
space
of
the
device.
5.2.2
6.2.2
The
specification
must
provide
data
that
describes
the
motion
in
space
of
the
device.
5.2.3
6.2.3
The
specification
must
allow
Web
applications
to
register
for
changes
in
the
device's
orientation.
5.2.4
6.2.4
The
specification
must
be
agnostic
to
the
underlying
sources
of
orientation
and
motion
data.
5.2.5
6.2.5
The
specification
must
use
the
existing
DOM
event
framework.
Worked
Example
A.
Examples
A.1
Calculating
compass
heading
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
v
represents
this
vector
in
the
rotated
device
body
frame
xyz,
then
r
v
is
as
follows.
The
transformation
of
r
v
due
to
the
rotation
about
the
z
axis
can
be
represented
by
the
following
rotation
matrix.
The
transformation
of
r
v
due
to
the
rotation
about
the
x
axis
can
be
represented
by
the
following
rotation
matrix.
The
transformation
of
r
v
due
to
the
rotation
about
the
y
axis
can
be
represented
by
the
following
rotation
matrix.
If
R
resresents
represents
the
vector
r
full
rotation
matrix
of
the
device
in
the
earth
frame
XYZ,
then
since
the
inital
initial
body
frame
is
aligned
with
the
earth,
R
is
as
follows.
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.
The
compass
heading
θ
θ
is
given
by
provided
that
β
β
and
γ
γ
are
not
both
zero.
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
absolute
values.
var degtorad = Math.PI / 180; // Degree-to-Radian conversion
function compassHeading( alpha, beta, gamma ) {
var _x = beta ? beta * degtorad : 0; // beta value
var _y = gamma ? gamma * degtorad : 0; // gamma value
var _z = alpha ? alpha * degtorad : 0; // alpha value
var cX = Math.cos( _x );
var cY = Math.cos( _y );
var cZ = Math.cos( _z );
var sX = Math.sin( _x );
var sY = Math.sin( _y );
var sZ = Math.sin( _z );
// Calculate Vx and Vy components
var Vx = - cZ * sY - sZ * sX * cY;
var Vy = - sZ * sY + cZ * sX * cY;
// Calculate compass heading
var compassHeading = Math.atan( Vx / Vy );
// Convert compass heading to use whole unit circle
if( Vy < 0 ) {
compassHeading += Math.PI;
} else if( Vx < 0 ) {
compassHeading += 2 * Math.PI;
}
return compassHeading * ( 180 / Math.PI ); // Compass Heading (in degrees)
}
As
a
consistency
check,
if
we
set
γ
γ
=
0,
then
as
expected.
Alternatively,
if
we
set
β
β
=
90,
then
as
expected.
A.2
Alternate
device
orientation
representations
This
section
is
non-normative.
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.
The
first
alternate
orientation
representation
uses
rotation
matrices.
By
combining
the
component
rotation
matrices
provided
in
the
worked
example
above
we
can
represent
the
orientation
of
the
device
body
frame
as
a
combined
rotation
matrix.
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.
The
above
combined
rotation
matrix
can
be
represented
in
JavaScript
as
follows
provided
passed
parameters
are
defined,
not
null
and
represent
absolute
values.
var degtorad = Math.PI / 180; // Degree-to-Radian conversion
function getRotationMatrix( alpha, beta, gamma ) {
var _x = beta ? beta * degtorad : 0; // beta value
var _y = gamma ? gamma * degtorad : 0; // gamma value
var _z = alpha ? alpha * degtorad : 0; // alpha value
var cX = Math.cos( _x );
var cY = Math.cos( _y );
var cZ = Math.cos( _z );
var sX = Math.sin( _x );
var sY = Math.sin( _y );
var sZ = Math.sin( _z );
//
// ZXY rotation matrix construction.
//
var m11 = cZ * cY - sZ * sX * sY;
var m12 = - cX * sZ;
var m13 = cY * sZ * sX + cZ * sY;
var m21 = cY * sZ + cZ * sX * sY;
var m22 = cZ * cX;
var m23 = sZ * sY - cZ * cY * sX;
var m31 = - cX * sY;
var m32 = sX;
var m33 = cX * cY;
return [
m11, m12, m13,
m21, m22, m23,
m31, m32, m33
];
};
Another
alternate
representation
of
device
orientation
data
is
as
Quaternions.
[QUATERNIONS]
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.
The
above
quaternion
can
be
represented
in
JavaScript
as
follows
provided
the
passed
parameters
are
defined,
are
absolute
values
and
those
parameters
are
not
null.
var degtorad = Math.PI / 180; // Degree-to-Radian conversion
function getQuaternion( alpha, beta, gamma ) {
var _x = beta ? beta * degtorad : 0; // beta value
var _y = gamma ? gamma * degtorad : 0; // gamma value
var _z = alpha ? alpha * degtorad : 0; // alpha value
var cX = Math.cos( _x/2 );
var cY = Math.cos( _y/2 );
var cZ = Math.cos( _z/2 );
var sX = Math.sin( _x/2 );
var sY = Math.sin( _y/2 );
var sZ = Math.sin( _z/2 );
//
// ZXY quaternion construction.
//
var w = cX * cY * cZ - sX * sY * sZ;
var x = sX * cY * cZ - cX * sY * sZ;
var y = cX * sY * cZ + sX * cY * sZ;
var z = cX * cY * sZ + sX * sY * cZ;
return [ w, x, y, z ];
}
We
can
check
that
a
Unit
Quaternion
has
been
constructed
correctly
using
Lagrange's
four-square
theorem
as
expected.
Acknowledgments
Lars
Erik
Bolstad,
Dean
Jackson,
Claes
Nilsson,
George
Percivall,
Doug
Turner,
Matt
Womer
