legacy-libs/google-proto-files/google/type/quaternion.proto

   1 // Copyright 2019 Google LLC.
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14 //
  15
  16 syntax = "proto3";
  17
  18 package google.type;
  19
  20 option cc_enable_arenas = true;
  21 option go_package = "google.golang.org/genproto/googleapis/type/quaternion;quaternion";
  22 option java_multiple_files = true;
  23 option java_outer_classname = "QuaternionProto";
  24 option java_package = "com.google.type";
  25 option objc_class_prefix = "GTP";
  26
  27
  28 // A quaternion is defined as the quotient of two directed lines in a
  29 // three-dimensional space or equivalently as the quotient of two Euclidean
  30 // vectors (https://en.wikipedia.org/wiki/Quaternion).
  31 //
  32 // Quaternions are often used in calculations involving three-dimensional
  33 // rotations (https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation),
  34 // as they provide greater mathematical robustness by avoiding the gimbal lock
  35 // problems that can be encountered when using Euler angles
  36 // (https://en.wikipedia.org/wiki/Gimbal_lock).
  37 //
  38 // Quaternions are generally represented in this form:
  39 //
  40 //   w + xi + yj + zk
  41 //
  42 // where x, y, z, and w are real numbers, and i, j, and k are three imaginary
  43 // numbers.
  44 //
  45 // Our naming choice (x, y, z, w) comes from the desire to avoid confusion for
  46 // those interested in the geometric properties of the quaternion in the 3D
  47 // Cartesian space. Other texts often use alternative names or subscripts, such
  48 // as (a, b, c, d), (1, i, j, k), or (0, 1, 2, 3), which are perhaps better
  49 // suited for mathematical interpretations.
  50 //
  51 // To avoid any confusion, as well as to maintain compatibility with a large
  52 // number of software libraries, the quaternions represented using the protocol
  53 // buffer below *must* follow the Hamilton convention, which defines ij = k
  54 // (i.e. a right-handed algebra), and therefore:
  55 //
  56 //   i^2 = j^2 = k^2 = ijk = −1
  57 //   ij = −ji = k
  58 //   jk = −kj = i
  59 //   ki = −ik = j
  60 //
  61 // Please DO NOT use this to represent quaternions that follow the JPL
  62 // convention, or any of the other quaternion flavors out there.
  63 //
  64 // Definitions:
  65 //
  66 //   - Quaternion norm (or magnitude): sqrt(x^2 + y^2 + z^2 + w^2).
  67 //   - Unit (or normalized) quaternion: a quaternion whose norm is 1.
  68 //   - Pure quaternion: a quaternion whose scalar component (w) is 0.
  69 //   - Rotation quaternion: a unit quaternion used to represent rotation.
  70 //   - Orientation quaternion: a unit quaternion used to represent orientation.
  71 //
  72 // A quaternion can be normalized by dividing it by its norm. The resulting
  73 // quaternion maintains the same direction, but has a norm of 1, i.e. it moves
  74 // on the unit sphere. This is generally necessary for rotation and orientation
  75 // quaternions, to avoid rounding errors:
  76 // https://en.wikipedia.org/wiki/Rotation_formalisms_in_three_dimensions
  77 //
  78 // Note that (x, y, z, w) and (-x, -y, -z, -w) represent the same rotation, but
  79 // normalization would be even more useful, e.g. for comparison purposes, if it
  80 // would produce a unique representation. It is thus recommended that w be kept
  81 // positive, which can be achieved by changing all the signs when w is negative.
  82 //
  83 //
  84 // Next available tag: 5
  85 message Quaternion {
  86   // The x component.
  87   double x = 1;
  88
  89   // The y component.
  90   double y = 2;
  91
  92   // The z component.
  93   double z = 3;
  94
  95   // The scalar component.
  96   double w = 4;
  97 }