[x3d-public] Add quaternion utility methods to X3D SFRotation programming-language standards?
Andreas Plesch
andreasplesch at gmail.com
Mon Jul 22 11:35:20 PDT 2024
Thanks, Don.
x3dom has a number of utility methods for quaternions (see below). Other
than adopting the existing SFRotation methods (
https://www.web3d.org/documents/specifications/19777-1/V3.3/Part1/functions.html#SFRotationFunctions
) for quaternions, the most useful ones are:
Quaternion.prototype.multiply = function ( that ) // exists also for
SFRotation but not clearly defined for SFRotation
Quaternion.prototype.toMatrix = function () // get rotation matrix
Quaternion.prototype.setValue = function ( matrix ) // set from rotation
matrix
Quaternion.normalize = function ( that )
Quaternion.rotateFromTo = function ( fromVec, toVec ) // this is a
constructor variation for SFRotation
Quaternion.prototype.copy = function ()
Quaternion.prototype.equals = function ( that, eps ) // requires .dot
method as well
Source code is in https://github.com/x3dom/x3dom/blob/master/src/fields.js
but I suppose the idea would be that there would be a new Quaternion SAI
data type, with methods which are provided by the X3D browser.
SFRotation.slerp and SFRotation(from, to) would be implemented often by
using quaternions internally in the first place.
SFRotation.multiply is not well defined since axis angle tuples are not a
mathematical concept. The method only really makes sense if the
multiplication is inferred to mean the multiplication of the corresponding
quaternions, or perhaps of corresponding rotation matrices.
Since most SFRotation operations need quaternions, x3dom tries to avoid
conversions by representing SFRotations internally as quaternions
exclusively. This is why it has all the Quaternion methods. In fact,
support for SFRotation SAI methods was only recently added, by treating
them as a proxy to Quaternion methods.
Given that most/all X3D browsers would use quaternions internally, it seems
possible for them to support standardized SAI quaternion methods as well.
I think the main use case other than use of external libraries may be
optimization, eg. avoiding SFRotation to quaternion and back type
conversions, in animations and other scripts called in each frame.
In terms of Java X3DJSAIL and Python X3DPSAIL, eg. scene construction prior
to live scene access, the getQuaternion and setQuaternion for SFRotation
may be sufficient since other functionality may be out of scope for the
libraries and can be achieved with external libraries.
-Andreas
PS: The links to tables in
https://www.web3d.org/documents/specifications/19777-1/V3.3/Part1/functions.html#SFRotationDescription
are off but that had likely been reported and may be fixed already.
/**
* Sets the components of this quaternion from another quaternion, and
returns
* this modified quaternion.
*
* @param {x3dom.fields.Quaternion} that - the quaternion to copy from
* @returns {x3dom.fields.Quaternion} this modified quaternion
*/
x3dom.fields.Quaternion.prototype.setValues
/**
* Returns a copy of this quaternion.
*
* @returns {x3dom.fields.Quaternion} a copy of this quaternion
*/
x3dom.fields.Quaternion.prototype.copy = function ()
/**
* Returns the product obtained by multiplying this vector with
* another one.
*
* @param {x3dom.fields.Quaternion} that - the right (multiplicand)
* quaternion
* @returns {x3dom.fields.Quaternion} the product of this quaternion
* and the other one
*/
x3dom.fields.Quaternion.prototype.multiply = function ( that )
/**
* Sets this quaternion's components from an array of numbers.
*
* @param {Number[]} array - an array of at least four numbers, the first
* four of which will be used to set this
* quaternion's x-, y-, z-, and w-components
* @returns {x3dom.fields.Quaternion} this modified quaternion
*/
x3dom.fields.Quaternion.prototype.fromArray = function ( array )
/**
* Returns a rotation matrix representation of this quaternion.
*
* @returns {x3dom.fields.SFMatrix4} a new rotation matrix representing
* this quaternion's rotation
*/
x3dom.fields.Quaternion.prototype.toMatrix = function ()
/**
* Returns this quaternion's rotation angle in radians.
*
* @returns {Number} this quaternion's rotation angle in radians
*/
x3dom.fields.Quaternion.prototype.angle = function ()
/**
* Sets this quaternion's components from the supplied rotation matrix,
* and returns the quaternion itself.
*
* @param {x3dom.fields.SFMatrix4f} matrix - the rotation matrix whose
* rotation shall be copied
* into this quaternion
* @returns {x3dom.fields.Quaternion} this modified quaternion
*/
x3dom.fields.Quaternion.prototype.setValue = function ( matrix )
/**
* Sets this quaternion from the Euler angles representation, and
* returns this quaternion.
*
* @param {Number} alpha - the rotation angle in radians about the
* first axis
* @param {Number} beta - the rotation angle in radians about the
* second axis
* @param {Number} gamma - the rotation angle in radians about the
* third axis
* @returns {x3dom.fields.Quaternion} the modified quaternion
*/
x3dom.fields.Quaternion.prototype.setFromEuler = function ( alpha, beta,
gamma )
/**
* Returns the dot product of this quaternion and another one.
*
* @param {x3dom.fields.Quaternion} that - the right quaternion
* @returns {Number} the production of this quaternion and the other one
*/
x3dom.fields.Quaternion.prototype.dot = function ( that )
/**
* Returns a new quaternion obtained by adding to this quaternion
* the components of another one.
*
* @param {x3dom.fields.Quaternion} that - the quaternion to add to this
* one
* @returns {x3dom.fields.Quaternion} a new quaternion representing the
* sum of this and the other quaternion
*/
x3dom.fields.Quaternion.prototype.add = function ( that )
/**
* Returns a new quaternion as the difference between this quaternion
* and another one subtracted from it.
*
* @param {x3dom.fields.Quaternion} that - the quaternion to deduct
* from this one
* @returns {x3dom.fields.Quaternion} a new quaternion holding the
* difference
*/
x3dom.fields.Quaternion.prototype.subtract = function ( that )
/**
* Sets this quaternion's components from another quaternion, and
* returns this quaternion.
*
* @param {x3dom.fields.Quaternion} that - the quaternion to copy from
* @returns {x3dom.fields.Quaternion} this modified quaternion
*/
x3dom.fields.Quaternion.prototype.setValues = function ( that )
/**
* Checks whether this quaternion equals another one.
*
* @param {x3dom.fields.Quaternion} that - the quaternion to juxtapose
* with this one
* @param {Number} eps - the tolerance of deviation
* within which not exactly equal
* components are still considered
* equal
* @returns {Boolean} ``true'' if both quaternions are equal
* or approximately equal, ``false'' otherwise
*/
x3dom.fields.Quaternion.prototype.equals = function ( that, eps )
/**
* Returns a scaled version of this quaternion.
*
* @param {Number} s - the scalar scale factor
* @returns {x3dom.fields.Quaternion} a scaled version of this quaternion
*/
x3dom.fields.Quaternion.prototype.multScalar = function ( s )
/**
* Normalizes a quaternion and returns it.
*
* @param {x3dom.fields.Quaternion} that - the quaternion to be
* normalized
* @returns {x3dom.fields.Quaternion} the normalized input quaternion
*/
x3dom.fields.Quaternion.normalize = function ( that )
/**
* Returns a negated version of this quaternion.
*
* The negation of a quaternion negates all of its components.
*
* @returns {x3dom.fields.Quaternion} the negated version of this
* quaternion
*/
x3dom.fields.Quaternion.prototype.negate = function ()
/**
* Returns an inverted version of this quaternion.
*
* The conjugate or inverse quaternion negates the x-, y-, and
* z-components, while retaining the w-coordinate's signum.
*
* @returns {x3dom.fields.Quaternion} the inverted version of this
* quaternion
*/
x3dom.fields.Quaternion.prototype.inverse = function ()
/**
* Returns the result of performing a spherical linear interpolation,
* or slerp, between this quaternion and another one as defined
* by the supplied ratio.
*
* @param {x3dom.fields.Quaternion} that - the opposite end of the
* interpolation
* @param {Number} t - the ratio of the interpolation
* between the two quaternions,
* usually as a floating-point
* value in the [0.0, 1.0]
* @returns {x3dom.fields.Quaternion} a new quaternion which represents
* the interpolated value between
* this and the opposite quaternion
* at the given ratio
*/
x3dom.fields.Quaternion.prototype.slerp = function ( that, t )
/**
* Computes and returns a quaternion representing the rotation necessary
* to reach align the first vector with the second one.
*
* @param {x3dom.fields.SFVec3f} fromVec - the start vector which shall
* be construed as being
* intended to be aligned with
* the ``toVec''
* @param {x3dom.fields.SFVec3f} toVec - the vector whose orientation
* shall be reached by the
* ``fromVec''
* @returns {x3dom.fields.Quaternion} the quaternion which represents
* the rotation necessary to align
* the ``fromVec'' with the
* ``toVec''
*/
x3dom.fields.Quaternion.rotateFromTo = function ( fromVec, toVec )
/**
* Parses the axis-angle representation of a rotation from a string
* and sets this quaternion's rotation from it, finally returning this
* quaternion itself.
*
* @param {String} str - the string to parse the axis-angle data from
* @returns {x3dom.fields.Quaternion} this modified quaternion
*/
x3dom.fields.Quaternion.prototype.setValueByStr = function ( str )
On Sun, Jul 21, 2024 at 6:00 PM Brutzman, Donald (Don) (CIV) <
brutzman at nps.edu> wrote:
> Interesting to see in the online issue discussion below that X3DOM
> includes quaternion methods.
>
> The SFRotation representation has some similarity to quaternions, but they
> are of course mathematically distinct. Quaternions have long been a
> suggested alternative for X3D, with SFRotation remaining the primary
> representation since it is much more reviewable and editable (among other
> reasons). Nevertheless, for programmers, additional flexibility can be
> considered without conflict. This may encourage X3D API usage with other
> 3D programming libraries.
>
> Please consider and advise whether quaternion-based accessor (get and set)
> utility methods ought to be added to the X3D specifications for SFRotation
> data type. Specifically they might become required in X3D Scene Access
> Interface (SAI), along with all of the future corresponding version 4.0
> revisions to X3D programming-language bindings (ECMAScript/JavaScript,
> Java, C/C++/C#, Python).
>
>
> - X3D Scene Access Interface (SAI), version 4.0 draft
> - https://web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-2v4.0-WD1
>
>
> If so, please list what utility methods seem most broadly valuable. Based
> on responses, Dick and I will work on crafting a Mantis issue and draft
> specification prose for further review.
>
> At that point, once reasonably well defined, am also willing to add
> convenience methods in Java X3DJSAIL and Python X3DPSAIL (x3d.py) libraries
> for testing. Contributions of exemplar source code for those libraries
> will also be welcome, if anyone wants.
>
> Further interesting is the possibility that we are not only supporting
> future X3D programmers, but potentially also supporting Metaverse
> requirements for 3D Web Interoperability.
>
> For those wanting additional background, more information about X3D data
> types and SFRotation (plus further links) can be found at
>
>
> - X3D Tooltips 4.0: field types
> - https://www.web3d.org/x3d/tooltips/X3dTooltips.html#type
> - https://www.web3d.org/x3d/tooltips/X3dTooltips.html#FieldTypesTable
> - https://www.web3d.org/x3d/tooltips/X3dTooltips.html#SFRotation
>
>
> Thanks in advance for considering the possibilities and all feedback.
>
>
> all the best, Don
>
> --
>
> Don Brutzman Naval Postgraduate School, Code USW/Br
> brutzman at nps.edu
>
> Watkins 270, MOVES Institute, Monterey CA 93943-5000 USA
> +1.831.656.2149
> X3D graphics, virtual worlds, Navy robotics
> https://faculty.nps.edu/brutzman
> ------------------------------
> *From:* Andreas Plesch <notifications at github.com>
> *Sent:* Wednesday, June 26, 2024 11:03 AM
> *To:* x3dom/x3dom <x3dom at noreply.github.com>
> *Cc:* Subscribed <subscribed at noreply.github.com>
> *Subject:* Re: [x3dom/x3dom] SFMatrix4f() documentation for setRotation
> and translation (Issue #1322)
>
> SFRotation field methods are also available but less well tested.
>
> SAI code may look like this:
>
> SFRot90 = x3dom.fields.SFRotation(1, 0, 0, 1.57);
> locR = SFRot90.multiVec(hitP);
> trans = new x3dom.fields.SFVec3f(440000, 3670000, 0);
> locT = locR.add(trans);
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/x3dom/x3dom/issues/1322#issuecomment-2192318975>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AB23BYDQOLK25VKQG3TBTJ3ZJL65PAVCNFSM6AAAAABJRIL4AOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCOJSGMYTQOJXGU>
> .
> You are receiving this because you are subscribed to this thread.Message
> ID: <x3dom/x3dom/issues/1322/2192318975 at github.com>
>
--
Andreas Plesch
Waltham, MA 02453
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20240722/4c480048/attachment-0001.html>
More information about the x3d-public
mailing list