- From: Dzung Tran via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 29 Oct 2009 22:28:57 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv31411/system-info
Added Files:
compass.html
Log Message:
First cut at Compass API
--- NEW FILE: compass.html ---
<!DOCTYPE html>
<html>
<head>
<title>The Compass API</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/simple-node.js' class='remove'></script>
<script src='../ReSpec.js/js/shortcut.js' class='remove'></script>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script src='../ReSpec.js/bibref/biblio.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
shortName: "system-info-api",
// publishDate: "2009-08-06",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/system-info/",
// lcEnd: "2009-08-05",
};
</script>
<script src='../common/config.js' class='remove'></script>
</head>
<body>
<section id='abstract'>
A proposal for the Compass API. This should be part of the Geolocation API.
</section>
<section class='introductory'>
<h2>Introduction</h2>
</section>
<!--***************************************Compass***********************************************-->
<section>
<h2>Compass</h2>
This compass specification is based loosely on the Google Android Compass API, and the
W3C [[GEOLOCATION-API]]. This specification estimated estimate magnetic field at a given point on
Earth, and in particular, to compute the magnetic declination from true north.
<p>This uses the World Magnetic Model produced by the United States National Geospatial-Intelligence
Agency. More details about the model can be found at
<a href='http://www.ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml'>http://www.ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml</a>.
This class currently uses WMM-2005 which is valid until 2010, but should produce acceptable results
for several years after that. </p>
<section>
<h3>Requirements</h3>
<ul>
<li>A conforming implementation MUST provide a method to retrieve one-shot orientation information.</li>
<li>A conforming implementation MUST allow an application to register to receive
updates when the hosting device orientation changes.</li>
<li>A conforming implementation MUST allow an application to stop receiving such updates.</li>
<li>A conforming implementation SHOULD be agnostic to the underlying sources of information.</li>
<li>A conforming implementation MAY provide the ability for an application to increase
accuracy by considering geolocation data in the orienation calculation. </li>
</ul>
</section>
<section>
<h3>Use-Cases</h3>
<section>
<h4>Walking Turn-by-turn Route Navigation</h4>
A mapping application can help the user navigate along a route by providing detailed
turn-by-turn directions. The application does this by registering with
the Geolocation API to receive repeated location updates of the user's position.
The application calculates the speed and determines that the user is walking and
also registers with the Compass API to receive updates about
the user's orientation. These updates are delivered as soon as the implementing user
agent determines that the orientation of the user has changed, which allows the
application to adjust accordingly.
</section>
<section>
<h4>Show the user's Position and Orientation on a Map</h4>
A user finds herself in an unfamiliar city area and cannot determine where she is or which direction
she is facing. She wants to check her orientation so she uses her hand-held device
to navigate to a Web-based mapping application that can pinpoint her exact location
on the city map using the Geolocation API and her precise orientation using the
Compass API. She then asks the Web application to provide driving directions
from her current position to her desired destination.
</section>
<section>
<h4> Annotating Content with Orientation and Location information</h4>
A group of friends is hiking through the Scottish highlands. Some of them write
short notes and take pictures at various points throughout the journey and store
them using a Web application that can work offline on their hand-held devices.
Whenever they add new content, the application automatically tags it with location
data from the Geolocation API and orientation data from the Compass API.
Every time they reach a town or a village, and they are again within network
coverage, the application automatically uploads their notes and pictures to a
popular blogging Web site, which uses the geolocation data to construct links that
point to a mapping service. Users who follow the group's trip can click on these
links to see a satellite view of the area where the notes were written and the
pictures were taken. They can also use orientation data to determine which direction
the photographer was facing when the pictures were taken.
Another example is a life blog where a user creates content (e.g. images, video,
audio) that records her every day experiences. This content can be automatically
annotated with information such as time, geographic position, orientation,
or even the user's emotional state at the time of the recording.
</section>
</section>
<dl title='interface Compass : Object' class='idl'>
<dt>void getCurrentOrientation ( in CompassCallback successCallback, [Optional] in CompassPosition position, [Optional] in CompassErrorCallback errorCallback, [Optional] in CompassOptions options)</dt>
<dd>
The <code>getCurrentOrientation()</code> function takes one, two, three or four arguments.
When called, it must immediately return and then asynchronously acquire a new <code>
Orientation</code> object based on the values in the <code>CompassPosition</code> object. If
successful, this method must invoke its associated <code>successCallback</code> argument with
a <code>Orientation</code> object as an argument. If the attempt fails, and the method was
invoked with a non-null <code>errorCallback</code> argument, this method must invoke the
<code>errorCallback</code> with a <code>OrientationError</code> object as an argument.
<p/>If the <code>CompassPosition</code> parameter contains valid information, the
implementation SHOULD use the position of the device to increase the accuracy of the
orientation calculation.
</dd>
<dt>int watchOrientation ( in CompassCallback successCallback, [Optional] in CompassPosition position, [Optional] in CompassErrorCallback errorCallback, [Optional] in CompassOptions options)</dt>
<dd>
The <code>watchOrientation()</code> function takes one, two, three or four arguments. When
called, it must immediately return and then asynchronously start a watch process defined as
the following set of steps:
<ol>
<li>Acquire a new <code>Orientation</code> object based on the values in the <code>
CompassPosition</code> object. If successful, invoke the associated <code>
successCallback</code> with an <code>Orientation</code> object as the argument. If the
attempt fails, and the method was invoked with a non-null <code>errorCallback</code>
argument, this method must invoke the <code>errorCallback</code> with a <code>
OrientationError</code> object as an argument.</li>
<li>Invoke the appropriate callback with a new <code>Orientation</code> object every
time the implementation determines that the orientation of the hosting device has changed. </li>
</ol>
If the <code>CompassPosition</code> parameter contains valid information, the
implementation SHOULD use the position of the device to increase the accuracy of the
orientation calculation.
<p/>This method returns an integer value that uniquely identifies the watch process. When
the <code>clearWatch()</code> method is called with this identifier, the watch process MUST
stop acquiring any new position fixes and must cease invoking any callbacks. When this value
is used in a call to <code>updatePosition()</code>, the watch process SHOULD update the
position information that it is using in its orientation caluculations.
</dd>
<dt>void updatePosition ( in int watchId, in CompassPosition compassPosition )</dt>
<dd>
The <code>updatePosition()</code> function provides new position information to the
watch specified by the <code>watchId</code> parameter. The watch SHOULD use this updated
position in its orientation calculations. If this method is not called, the implementation
MUST continue to use the information provided (if any) in the original call to
<code>watchOrientation()</code>.
<p/>NOTE: I'm not sure that the watchId parameter is necessary. Is there a use case where
the caller would want to update the compass position for one watch and not any others?
</dd>
<dt>void clearWatch ( in int watchId )</dt>
<dd>
When this method is called, the implementation MUST stop calling the <code>successCallback
</code> and <code>errorCallback</code> associated with the <code>watchId</code>.
</dd>
</dl>
<section>
<h3>CompassCallback</h3>
<dl title='[Callback=FunctionOnly, NoInterfaceObject] interface CompassCallback : Object' class='idl'>
<dt>void handleEvent(in Orientation orientation)</dt>
<dd>
This function MUST be called whenever the implementation successfully retrieves orientation information as a result to a prior call to either <code>getCurrentOrientation()</code> or <code>watchOrientation()</code>. If an implementation is able to retrieve orientation information, but the information does not meet the criteria specified in the <code>OrientationOptions</code> argument, this method SHOULD NOT be called.
</dd>
</dl>
</section>
<section>
<h3>CompassErrorCallback</h3>
<dl title='[Callback=FunctionOnly, NoInterfaceObject] interface CompassErrorCallback : Object' class='idl'>
<dt>void handleEvent(in OrientationError error)</dt>
<dd>
This function MUST be called whenever the implementation is unable to retrieve orientation information as a result to a prior call to either <code>getCurrentOrientation()</code> or <code>watchOrientation()</code>. If an implementation is able to retrieve orientation information, but the information does not meet the criteria specified in the <code>OrientationOptions</code> argument, this method SHOULD be called.
</dd>
</dl>
</section>
<section>
<h3>CompassPosition</h3>
The CompassPosition object allows an implementation to provide more accurate orientation information. How this information is obtained is beyond the scope of this specification.
<dl title='interface CompassPosition : Object' class='idl'>
<dt>readonly attribute float latitude</dt>
<dd>
Degrees latitude in WGS84 geodetic coordinates -- positive is east. Values MUST be greater than -180, and less than or equal to 180.
</dd>
<dt>readonly attribute float longitude</dt>
<dd>
Degrees longitude in WGS84 geodetic coordinates -- positive is north. Values MUST be greater than -180, and less than or equal to 180.
</dd>
<dt>readonly attribute float altitudeMeteres</dt>
<dd>
Altitude in WGS84 geodetic coordinates, in meters.
</dd>
<dt>readonly attribute DOMTimeStamp timestamp</dt>
<dd>
Time at which to evaluate the declination, in milliseconds since January 1, 1970. (approximate is fine -- the declination changes very slowly).
</dd>
</dl>
</section>
<section>
<h3>CompassOptions</h3>
<dl title='[Callback, NoInterfaceObject] interface CompassOptions : Object' class='idl'>
<dt>attribute unsigned int sampleInterval</dt>
<dd>The <code>sampleInterval</code> attribute specifies in milliseconds how often
the implementation SHOULD check to see if the orientation has changed. While the
specification allows the caller to sample at very small intervals, on many
implementations, this may be wasteful because the battery device may update its
level information at a frequency significantly below the <code>sampleInterval</code>.
On implementations that are event driven, this value MAY be ignored. The caller
should be aware that setting a value too small can adversely affect the battery life.
The default value SHOULD be 1,000, or once every one second. </dd>
<dt>readonly attribute boolean enableHighAccuracy</dt>
<dd>
The <code>enableHighAccuracy</code> attribute provides a hint that the application would
like to receive the best possible results. This may result in slower response times or
increased power consumption. The user might also deny this capability, or the device might
not be able to provide more accurate results than if the flag wasn't specified.
</dd>
<dt>readonly attribute long timeout</dt>
<dd>
The <code>timeout</code> attribute denotes the maximum length of time (expressed in milliseconds) that is allowed to pass from the call to <code>getCurrentOrientation()</code> or <code>watchOrientation()</code> until the corresponding <code>successCallback</code> is invoked. If the implementation is unable to successfully acquire a new <code>Orientation</code> before the given <code>timeout</code> elapses, and no other errors have occurred in this interval, then the corresponding <code>errorCallback</code> MUST be invoked with a <code>OrientationError</code> object whose <code>code</code> attribute is set to <code>TIMEOUT</code>.
</dd>
</dl>
</section>
<section>
<h3>Orientation</h3>
<dl title='interface Orientation : Object' class='idl'>
<dt>readonly attribute DOMTimeStamp timestamp</dt>
<dd>
Time at which the orientation was calculated, in milliseconds since January 1, 1970.
</dd>
<dt>readonly attribute float declination</dt>
<dd>
The declination of the horizontal component of the magnetic field from true north, in degrees (i.e. positive means the magnetic field is rotated east that much from true north). The maximum value MUST be 180; the minumum value MUST be greater than -180.
</dd>
<dt>readonly attribute float fieldStrength</dt>
<dd>
Total field strength in nanoteslas.
</dd>
<dt>readonly attribute float horizontalStrength</dt>
<dd>
Horizontal component of the field strength in nonoteslas.
</dd>
<dt>readonly attribute float inclination</dt>
<dd>
The inclination of the magnetic field in degrees -- positive means the magnetic field is rotated downwards. The maximum value MUST be 180; the minumum value MUST be greater than -180.
</dd>
<dt>readonly attribute float x</dt>
<dd>
The X (northward?) component of the magnetic field in nanoteslas.
</dd>
<dt>readonly attribute float y</dt>
<dd>
The Y (eastward) component of the magnetic field in nanoteslas.
</dd>
<dt>readonly attribute float z</dt>
<dd>
The Z (downward) component of the magnetic field in nanoteslas.
</dd>
</dl>
</section>
<section>
<h3>OrientationError</h3>
<dl title='interface OrientationError : Object' class='idl'>
<dt>readonly attribute unsigned short UNKNOWN_ERROR</dt>
<dd>
The orientation acquisition process failed due to an error not covered by the definition of any other error code in this interface.
</dd>
<dt>readonly attribute unsigned short PERMISSION_DENIED</dt>
<dd>
The orientation acquisition process failed because the application origin does not have permission to use this <abbr title="Application Programming Interface">API</abbr>.
</dd>
<dt>readonly attribute unsigned short ORIENTATION_UNAVAILALBE</dt>
<dd>
The orientation of the device could not be determined. The implementation reported an internal error that caused the process to fail entirely.
</dd>
<dt>readonly attribute unsigned short TIMEOUT</dt>
<dd>
The specified maximum length of time has elapsed before the implementation could successfully acquire a new <code>Orientation</code> object.
</dd>
<dt>readonly attribute unsigned short INVALID_VALUE</dt>
<dd>
The implementation failed to retrieve orientation information because one or more of the values in the <code>CompassOptions</code> or <code>CompassPosition</code> parameters of the <code>getCurrentOrientation()</code> or <code>watchOrientation()</code> calls was invalid. For example, if the <code>CompassPosition</code> <code>longitude</code> attribute were set to a value of -180, the <code>CompassErrorCallback</code> must be invoked with the <code>CompassError</code> <code>code</code> attribute equal to <code>INVALID_VALUE</code> (4).
</dd>
<dt>readonly attribute unsigned short code</dt>
<dd>
The <code>code</code> attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
</dd>
<dt>readonly attribute DOMString message</dt>
<dd>
The <code>message</code> attribute must return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers should not use it directly in their application user interface.
</dd>
</dl>
</section>
</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
Many thanks to Clayne Robison and Andy Idsinga at <a href="www.intel.com">Intel Corporation</a> for their contributions to this specification.
</p>
</section>
</body>
</html>
Received on Thursday, 29 October 2009 22:29:12 UTC