editorial: Add a separate section describing model, rewrite contents #117
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This gets rid of a lot of tags that we do not need to care about. While at it, use the `<figure>` tag to group the images and their descriptions.
…rence coordinates The goal is to make it easier to understand what DeviceOrientationEvent represents and better explain the difference between relative and absolute orientation. - Stop saying relative orientation is relative to the "Earth coordinate frame". Relative orientation is relative to an arbitrary reference frame that varies across platforms. - Refer to the "device coordinate system" defined in the Accelerometer spec, which is the same coordinate system we were defining here. The text there also contains a helpful image besides the textual explanation. - Provide links to different absolute and relative orientation sensor resources in native platforms. - For absolute orientation, refer to Orientation Sensor's "Earth's reference coordinate system", which is basically the "Earth coordinate frame" we had in this specification but with the Y axis pointing to the magnetic North, not True North. The previous version of the text was very vague when it came to explaining what "absolute" meant; this version reflects what Gecko, WebKit and Blink use when providing absolute orientation values. - Remove the "Earth coordinate frame" explanation altogether, as nothing references it anymore.
reillyeon
reviewed
Nov 8, 2023
|
|
||
| This specification expresses a device's physical orientation as a series of rotations relative to an <a>implementation-defined</a> reference coordinate frame. | ||
|
|
||
| The sequence of rotation steps is a set of intrinsic Tait-Bryan angles of type Z - X' - Y'' ([[EULERANGLES]]) that are applied on the <a>device coordinate system</a> defined in [[!ACCELEROMETER]] and summarized below: |
There was a problem hiding this comment.
I'm nervous about referencing a definition from a specification that is less far along the standards track than this one. I am curious for @anssiko's opinion here.
There was a problem hiding this comment.
I assume this is about the device coordinate system definition. We can use these three factors to assess the associated risk for referencing this definition: stability, schedule and licensing (from the normative references guide):
- Stability:
- Stability of the referenced document: The WG believes the specification is stable and has demonstrated it is implementable but awaits further implementation experience before advancing to a Proposed Rec.
- Stability of the referenced part(s): This definition refers to an established coordinate system, a Cartesian coordinate system, and the right-hand rule, a common convention for the orientation of axes in 3D space.
- Nature of the dependency: A coordinate system convention.
- Status of implementations: Chromium implementations, automated tests.
- Schedule: The Accelerometer specification is a Candidate Recommendation Draft.
- Licensing: The Accelerometer specification uses a permissive document license, the same as this specification.
Considering these three factors, I think it is appropriate to incorporate this device coordinate system definition as a reference. If this definition would go away for some reason, it would be relatively easy to copy-paste this definition into this specification without delaying possible future transition significantly.
@himorin, let us know if you think otherwise.
There was a problem hiding this comment.
Thanks for the link to that guide. I think given the nature of the reference (definitions of sensor concepts, rather than anything specific to the Generic Sensor API) this is fine.
…odel" section The idea is to have the more general discussion about what is being measured and how in one section separate from the section that covers the API, each event's attributes and security requirements. The device orientation contents in particular were quite long and mixed with normative IDL descriptions and requirements that made the text confusing to follow. The new "device orientation model" section has separated the description of the rotation steps from the discussion of different reference frames. The new "device motion model" section has some of the old content, but more text has been added along with references to the MOTION-SENSORS, ACCELEROMETER and GYROSCOPE specs which not only implement the same functionality but also have more in-depth content about the same topics.
rakuco
force-pushed
the
editorial-improvements-to-model-explanation
branch
from
06c1e8a
to
7db68d7
Compare
reillyeon
approved these changes
Nov 9, 2023
github-actions bot
added a commit
that referenced
this pull request
Nov 9, 2023
…anation SHA: cc5abc7 Reason: push, by rakuco Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
github-actions bot
added a commit
that referenced
this pull request
Nov 10, 2023
…anation SHA: cc5abc7 Reason: push, by rakuco Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The 3 changes here are related but I feel like they should be separate commits.
The idea is to 1) make the spec easier to read by not mixing explanations about the motion and orientation models with descriptions of IDL attributes 2) make the explanations easier to understand by clarifying some concepts, especially the Device Orientation-related ones.
Preview | Diff