- From: vecnathewhisperd via GitHub <sysbot+gh@w3.org>
- Date: Sun, 15 Oct 2023 07:37:10 +0000
- To: public-device-apis-log@w3.org
vecnathewhisperd has just created a new issue for https://github.com/w3c/sensors:
== sensors ==
if ('Accelerometer' in window) {
// The `Accelerometer` interface is supported by the browser.
// Does the device have an accelerometer, though?
}
For an actually meaningful feature detection result, you need to try to connect to the sensor, too. This example illustrates how to do that.
let accelerometer = null;
try {
accelerometer = new Accelerometer({ frequency: 10 });
accelerometer.onerror = (event) => {
// Handle runtime errors.
if (event.error.name === 'NotAllowedError') {
console.log('Permission to access sensor was denied.');
} else if (event.error.name === 'NotReadableError') {
console.log('Cannot connect to the sensor.');
}
};
accelerometer.onreading = (e) => {
console.log(e);
};
accelerometer.start();
} catch (error) {
// Handle construction errors.
if (error.name === 'SecurityError') {
console.log('Sensor construction was blocked by the Permissions Policy.');
} else if (error.name === 'ReferenceError') {
console.log('Sensor is not supported by the User Agent.');
} else {
throw error;
}
}
[#](https://developer.chrome.com/articles/generic-sensor/#polyfill)
Polyfill
For browsers that do not support the Generic Sensor API, a [polyfill](https://github.com/kenchris/sensor-polyfills) is available. The polyfill allows you to load only the relevant sensors' implementations.
// Import the objects you need.
import { Gyroscope, AbsoluteOrientationSensor } from './src/motion-sensors.js';
// And they're ready for use!
const gyroscope = new Gyroscope({ frequency: 15 });
const orientation = new AbsoluteOrientationSensor({ frequency: 60 });
[#](https://developer.chrome.com/articles/generic-sensor/#what-are-sensors-how-to-use-them)
What are all these sensors? How can I use them?
Sensors is an area that might need a brief introduction. If you are familiar with sensors, you can jump right to the [hands-on coding section](https://developer.chrome.com/articles/generic-sensor/#lets-code). Otherwise, let's look at each supported sensor in detail.
[#](https://developer.chrome.com/articles/generic-sensor/#acceleration-and-linear-accelerometer-sensor)
Accelerometer and linear acceleration sensor
Accelerometer sensor measurements
The [Accelerometer](https://developer.mozilla.org/docs/Web/API/Accelerometer) sensor measures acceleration of a device hosting the sensor on three axes (X, Y, and Z). This sensor is an inertial sensor, meaning that when the device is in linear free fall, the total measured acceleration would be 0 m/s2, and when a device lying flat on a table, the acceleration in upwards direction (Z axis) will be equal to the Earth's gravity, i.e. g ≈ +9.8 m/s2 as it is measuring the force of the table pushing the device upwards. If you push the device to the right, acceleration on the X axis would be positive, or negative if the device is accelerated from the right toward the left.
Accelerometers can be used for things like: step counting, motion sensing, or simple device orientation. Quite often, accelerometer measurements are combined with data from other sources to create fusion sensors, such as, orientation sensors.
The [LinearAccelerationSensor](https://developer.mozilla.org/docs/Web/API/LinearAccelerationSensor) measures acceleration that is applied to the device hosting the sensor, excluding the contribution of gravity. When a device is at rest, for instance lying flat on the table, the sensor would measure ≈ 0 m/s2 acceleration on three axes.
[#](https://developer.chrome.com/articles/generic-sensor/#gravity-sensor)
Gravity sensor
It is already possible for users to manually derive readings close to those of a gravity sensor by manually inspecting Accelerometer and LinearAccelerometer readings, but this can be cumbersome and depend on the accuracy of the values provided by those sensors. Platforms such as Android can provide gravity readings as part of the operating system, which should be cheaper in terms of computation, provide more accurate values depending on the user's hardware, and be easier to use in terms of API ergonomics. The [GravitySensor](https://w3c.github.io/accelerometer/#gravitysensor-interface) returns the effect of acceleration along the device's X, Y, and Z axis due to gravity.
[#](https://developer.chrome.com/articles/generic-sensor/#gyroscope-sensor)
Gyroscope
Gyroscope sensor measurements
The [Gyroscope](https://developer.mozilla.org/docs/Web/API/Gyroscope) sensor measures angular velocity in radians per second around the device's local X, Y, and Z axis. Most consumer devices have mechanical ([MEMS](https://en.wikipedia.org/wiki/Microelectromechanical_systems)) gyroscopes, which are inertial sensors that measure rotation rate based on [inertial Coriolis force](https://en.wikipedia.org/wiki/Coriolis_force). MEMS gyroscopes are prone to drift that is caused by the sensor's gravitational sensitivity which deforms the sensor's internal mechanical system. Gyroscopes oscillate at relative high frequencies, e.g., 10s of kHz, and therefore, might consume more power compared to other sensors.
[#](https://developer.chrome.com/articles/generic-sensor/#orientation-sensors)
Orientation sensors
Absolute orientation sensor measurements
The [AbsoluteOrientationSensor](https://developer.mozilla.org/docs/Web/API/AbsoluteOrientationSensor) is a fusion sensor that measures rotation of a device in relation to the Earth's coordinate system, while the [RelativeOrientationSensor](https://developer.mozilla.org/docs/Web/API/RelativeOrientationSensor) provides data representing rotation of a device hosting motion sensors in relation to a stationary reference coordinate system.
All modern 3D JavaScript frameworks support [quaternions](https://en.wikipedia.org/wiki/Quaternion) and [rotation matrices](https://en.wikipedia.org/wiki/Rotation_matrix) to represent rotation; however, if you use WebGL directly, the OrientationSensor conveniently has both a [quaternion property](https://developer.mozilla.org/docs/Web/API/OrientationSensor/quaternion) and a [populateMatrix() method](https://developer.mozilla.org/docs/Web/API/OrientationSensor/populateMatrix). Here are few snippets:
[three.js](https://threejs.org/docs/index.html#api/core/Object3D.quaternion)
let torusGeometry = new THREE.TorusGeometry(7, 1.6, 4, 3, 6.3);
let material = new THREE.MeshBasicMaterial({ color: 0x0071c5 });
let torus = new THREE.Mesh(torusGeometry, material);
scene.add(torus);
// Update mesh rotation using quaternion.
const sensorAbs = new AbsoluteOrientationSensor();
sensorAbs.onreading = () => torus.quaternion.fromArray(sensorAbs.quaternion);
sensorAbs.start();
// Update mesh rotation using rotation matrix.
const sensorRel = new RelativeOrientationSensor();
let rotationMatrix = new Float32Array(16);
sensor_rel.onreading = () => {
sensorRel.populateMatrix(rotationMatrix);
torus.matrix.fromArray(rotationMatrix);
};
sensorRel.start();
[BABYLON](https://doc.babylonjs.com/typedoc/classes/babylon.abstractmesh#rotationquaternion)
const mesh = new BABYLON.Mesh.CreateCylinder('mesh', 0.9, 0.3, 0.6, 9, 1, scene);
const sensorRel = new RelativeOrientationSensor({ frequency: 30 });
sensorRel.onreading = () => mesh.rotationQuaternion.FromArray(sensorRel.quaternion);
sensorRel.start();
[WebGL](https://www.khronos.org/registry/webgl/specs/latest/2.0/)
// Initialize sensor and update model matrix when new reading is available.
let modMatrix = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
const sensorAbs = new AbsoluteOrientationSensor({ frequency: 60 });
sensorAbs.onreading = () => sensorAbs.populateMatrix(modMatrix);
sensorAbs.start();
// Somewhere in rendering code, update vertex shader attribute for the model
gl.uniformMatrix4fv(modMatrixAttr, false, modMatrix);
Orientation sensors enable various use cases, such as immersive gaming, augmented and virtual reality.
For more information about motion sensors, advanced use cases, and requirements, check out the [motion sensors explainer](https://w3c.github.io/motion-sensors/) document.
[#](https://developer.chrome.com/articles/generic-sensor/#synchronization-with-screen-coordinates)
Synchronization with screen coordinates
By default, [spatial sensors'](https://w3c.github.io/sensors/#spatial-sensor) readings are resolved in a local coordinate system that is bound to the device and does not take screen orientation into account.
Device coordinate system
Device coordinate system
However, many use cases like games or augmented and virtual reality require sensor readings to be resolved in a coordinate system that is instead bound to the screen orientation.
Screen coordinate system
Screen coordinate system
Previously, remapping of sensor readings to screen coordinates had to be implemented in JavaScript. This approach is inefficient and it also quite significantly increases the complexity of the web application code; the web application must watch screen orientation changes and perform coordinates transformations for sensor readings, which is not a trivial thing to do for Euler angles or quaternions.
The Generic Sensor API provides a much simpler and reliable solution! The local coordinate system is configurable for all defined spatial sensor classes: Accelerometer, Gyroscope, LinearAccelerationSensor, AbsoluteOrientationSensor, RelativeOrientationSensor, and Magnetometer. By passing the referenceFrame option to the sensor object constructor, the user defines whether the returned readings will be resolved in [device](https://w3c.github.io/accelerometer/#device-coordinate-system) or [screen](https://w3c.github.io/accelerometer/#screen-coordinate-system) coordinates.
// Sensor readings are resolved in the Device coordinate system by default.
// Alternatively, could be RelativeOrientationSensor({referenceFrame: "device"}).
const sensorRelDevice = new RelativeOrientationSensor();
// Sensor readings are resolved in the Screen coordinate system. No manual remapping is required!
const sensorRelScreen = new RelativeOrientationSensor({ referenceFrame: 'screen' });
[#](https://developer.chrome.com/articles/generic-sensor/#lets-code)
Let's code!
The Generic Sensor API is very simple and easy-to-use! The Sensor interface has [start()](https://w3c.github.io/sensors/#sensor-start) and [stop()](https://w3c.github.io/sensors/#sensor-stop) methods to control sensor state and several event handlers for receiving notifications about sensor activation, errors and newly available readings. The concrete sensor classes usually add their specific reading attributes to the base class.
[#](https://developer.chrome.com/articles/generic-sensor/#development-environment)
Development environment
During development you'll be able to use sensors through localhost. If you are developing for mobile devices, set up [port forwarding](https://developer.chrome.com/docs/devtools/remote-debugging/local-server/) for your local server, and you are ready to rock!
When your code is ready, deploy it on a server that supports HTTPS. [GitHub Pages](https://pages.github.com/) are served over HTTPS, making it a great place to share your demos.
[#](https://developer.chrome.com/articles/generic-sensor/#3d-model-rotation)
3D model rotation
In this simple example, we use the data from an absolute orientation sensor to modify the rotation quaternion of a 3D model. The model is a three.js [Object3D](https://threejs.org/docs/index.html#api/core/Object3D) class instance that has a [quaternion](https://threejs.org/docs/index.html#api/core/Object3D.quaternion) property. The following code snippet from the [orientation phone](https://github.com/intel/generic-sensor-demos/tree/master/orientation-phone) demo, illustrates how the absolute orientation sensor can be used to rotate a 3D model.
function initSensor() {
sensor = new AbsoluteOrientationSensor({ frequency: 60 });
sensor.onreading = () => model.quaternion.fromArray(sensor.quaternion);
sensor.onerror = (event) => {
if (event.error.name == 'NotReadableError') {
console.log('Sensor is not available.');
}
};
sensor.start();
}
The device's orientation will be reflected in 3D model rotation within the WebGL scene.
Sensor updates 3D model's orientation
Sensor updates orientation of a 3D model
[#](https://developer.chrome.com/articles/generic-sensor/#punchmeter)
Punchmeter
The following code snippet is extracted from the [punchmeter demo](https://github.com/intel/generic-sensor-demos/tree/master/punchmeter), illustrating how the linear acceleration sensor can be used to calculate the maximum velocity of a device under the assumption that it is initially laying still.
this.maxSpeed = 0;
this.vx = 0;
this.ax = 0;
this.t = 0;
/* … */
this.accel.onreading = () => {
let dt = (this.accel.timestamp - this.t) * 0.001; // In seconds.
this.vx += ((this.accel.x + this.ax) / 2) * dt;
let speed = Math.abs(this.vx);
if (this.maxSpeed < speed) {
this.maxSpeed = speed;
}
this.t = this.accel.timestamp;
this.ax = this.accel.x;
};
The current velocity is calculated as an approximation to the integral of the acceleration function.
Demo web application for punch speed measurement
Measurement of a punch speed
[#](https://developer.chrome.com/articles/generic-sensor/#debugging-and-sensor-overriding-with-chrome-devtools)
Debugging and sensor overriding with Chrome DevTools
In some cases you don't need a physical device to play with the Generic Sensor API. Chrome DevTools has great support for [simulating device orientation](https://developer.chrome.com/docs/devtools/device-mode/orientation/).
Chrome DevTools used to override the custom orientation data of a virtual phone
Simulating device orientation with Chrome DevTools
[#](https://developer.chrome.com/articles/generic-sensor/#privacy-and-security)
Privacy and security
Sensor readings are sensitive data which can be subject to various attacks from malicious web pages. Implementations of Generic Sensor APIs enforce a few limitations to mitigate the possible security and privacy risks. These limitations must be taken into account by developers who intend to use the API, so let's briefly list them.
[#](https://developer.chrome.com/articles/generic-sensor/#only-https)
Only HTTPS
Because Generic Sensor API is a powerful feature, the browser only allows it on secure contexts. In practice it means that to use Generic Sensor API you'll need to access your page through HTTPS. During development you can do so via http://localhost/ but for production you'll need to have HTTPS on your server. See the [Safe and secure](https://web.dev/articles/secure) collection for best practices and guidelines.
[#](https://developer.chrome.com/articles/generic-sensor/#permissions-policy-integration)
Permissions Policy integration
The [Permissions Policy integration](https://developer.chrome.com/docs/privacy-sandbox/permissions-policy/) in Generic Sensor API controls access to sensors data for a frame.
By default the Sensor objects can be created only within a main frame or same-origin subframes, thus preventing cross-origin iframes from unsanctioned reading of sensor data. This default behavior can be modified by explicitly enabling or disabling of the corresponding [policy-controlled features](https://w3c.github.io/webappsec-permissions-policy/#features).
The snippet below illustrates granting accelerometer data access to a cross-origin iframe, meaning that now Accelerometer or LinearAccelerationSensor objects can be created there.
<iframe src="https://third-party.com" allow="accelerometer" />
[#](https://developer.chrome.com/articles/generic-sensor/#sensor-readings-delivery-can-be-suspended)
Sensor readings delivery can be suspended
Sensor readings are only accessible by a visible web page, i.e., when the user is actually interacting with it. Moreover, sensor data would not be provided to the parent frame if the user focus changes to a cross-origin subframe. This prevents the parent frame infering user input.
[#](https://developer.chrome.com/articles/generic-sensor/#whats-next)
What's next?
There is a set of already specified sensor classes to be implemented in the near future such as [Ambient Light Sensor](https://w3c.github.io/ambient-light/) or [Proximity Sensor](https://w3c.github.io/proximity/); however, thanks to the great extensibility of Generic Sensor framework we can anticipate appearance of even more new classes representing various sensor types.
Another important area for future work is improving the Generic Sensor API itself, the Generic Sensor specification is currently a Candidate Recommendation, which means that there is still time to make fixes and bring new functionality that developers need.
[#](https://developer.chrome.com/articles/generic-sensor/#you-can-help)
You can help!
The sensor specifications reached [Candidate Recommendation](https://www.w3.org/Consortium/Process/Process-19991111/tr.html#RecsCR) maturity level, hence, the feedback from web and browser developers is highly appreciated. Let us know what features would be great to add or if there is something you would like to modify in the current API.
Please feel free to file [specification issues](https://github.com/w3c/sensors/issues/new) as well as [bugs](https://bugs.chromium.org/p/chromium/issues/entry) for the Chrome implementation.
[#](https://developer.chrome.com/articles/generic-sensor/#resources)
Resources
Demo projects: https://intel.github.io/generic-sensor-demos/
Generic Sensor API specification: https://w3c.github.io/sensors/
Specification issues: https://github.com/w3c/sensors/issues
W3C working group mailing list: [public-device-apis@w3.org](mailto:public-device-apis@w3.org)
Chrome Feature Status: https://www.chromestatus.com/feature/5698781827825664
Implementation bugs: [http://crbug.com?q=component:Blink>Sensor](http://crbug.com/?q=component:Blink%3ESensor)
Please view or discuss this issue at https://github.com/w3c/sensors/issues/472 using your GitHub account
--
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config
Received on Sunday, 15 October 2023 07:37:13 UTC