HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
matrix4d.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 ////////////////////////////////////////////////////////////////////////
8 // This file is generated by a script. Do not edit directly. Edit the
9 // matrix4.template.h file to make changes.
10 
11 #ifndef PXR_BASE_GF_MATRIX4D_H
12 #define PXR_BASE_GF_MATRIX4D_H
13 
14 /// \file gf/matrix4d.h
15 /// \ingroup group_gf_LinearAlgebra
16 
17 #include "pxr/pxr.h"
18 #include "pxr/base/gf/api.h"
19 #include "pxr/base/gf/declare.h"
20 #include "pxr/base/gf/matrixData.h"
21 #include "pxr/base/gf/vec4d.h"
22 #include "pxr/base/gf/traits.h"
24 #include "pxr/base/gf/limits.h"
25 #include "pxr/base/gf/math.h"
26 #include "pxr/base/gf/vec3d.h"
27 #include "pxr/base/tf/hash.h"
28 
29 #include <iosfwd>
30 #include <vector>
31 
33 
34 template <>
35 struct GfIsGfMatrix<class GfMatrix4d> { static const bool value = true; };
36 
37 class GfMatrix4d;
38 class GfMatrix4f;
39 class GfQuatd;
40 class GfRotation;
41 class GfMatrix3d;
42 
43 /// \class GfMatrix4d
44 /// \ingroup group_gf_LinearAlgebra
45 ///
46 /// Stores a 4x4 matrix of \c double elements. A basic type.
47 ///
48 /// Matrices are defined to be in row-major order, so <c>matrix[i][j]</c>
49 /// indexes the element in the \e i th row and the \e j th column.
50 ///
51 /// <h3>3D Transformations</h3>
52 ///
53 /// The following methods interpret a GfMatrix4d as a 3D
54 /// transformation: SetRotate(), SetScale(), SetTranslate(), SetLookAt(),
55 /// Factor(), ExtractTranslation(), ExtractRotation(), Transform(),
56 /// TransformDir(). By convention, vectors are treated primarily as row
57 /// vectors, implying the following:
58 /// \li Transformation matrices are organized to deal with row
59 /// vectors, not column vectors. For example, the last row of a matrix
60 /// contains the translation amounts.
61 /// \li Each of the Set() methods below completely rewrites the
62 /// matrix; for example, SetTranslate() yields a matrix
63 /// which does nothing but translate.
64 /// \li When multiplying two transformation matrices, the matrix
65 /// on the left applies a more local transformation to a row
66 /// vector. For example, if R represents a rotation
67 /// matrix and T represents a translation matrix, the
68 /// product R*T will rotate a row vector, then translate
69 /// it.
71 {
72 public:
73  typedef double ScalarType;
74 
75  static const size_t numRows = 4;
76  static const size_t numColumns = 4;
77 
78  /// Default constructor. Leaves the matrix component values undefined.
79  GfMatrix4d() = default;
80 
81  /// Constructor. Initializes the matrix from 16 independent
82  /// \c double values, specified in row-major order. For example,
83  /// parameter \e m10 specifies the value in row 1 and column 0.
84  GfMatrix4d(double m00, double m01, double m02, double m03,
85  double m10, double m11, double m12, double m13,
86  double m20, double m21, double m22, double m23,
87  double m30, double m31, double m32, double m33) {
88  Set(m00, m01, m02, m03,
89  m10, m11, m12, m13,
90  m20, m21, m22, m23,
91  m30, m31, m32, m33);
92  }
93 
94  /// Constructor. Initializes the matrix from a 4x4 array
95  /// of \c double values, specified in row-major order.
96  GfMatrix4d(const double m[4][4]) {
97  Set(m);
98  }
99 
100  /// Constructor. Explicitly initializes the matrix to \e s times the
101  /// identity matrix.
102  explicit GfMatrix4d(double s) {
103  SetDiagonal(s);
104  }
105 
106  /// Constructor. Explicitly initializes the matrix to diagonal form,
107  /// with the \e i th element on the diagonal set to <c>v[i]</c>.
108  explicit GfMatrix4d(const GfVec4d& v) {
109  SetDiagonal(v);
110  }
111 
112  /// Constructor. Initialize the matrix from a vector of vectors of
113  /// double. The vector is expected to be 4x4. If it is
114  /// too big, only the first 4 rows and/or columns will be used.
115  /// If it is too small, uninitialized elements will be filled in with
116  /// the corresponding elements from an identity matrix.
117  ///
118  GF_API
119  explicit GfMatrix4d(const std::vector< std::vector<double> >& v);
120 
121  /// Constructor. Initialize the matrix from a vector of vectors of
122  /// float. The vector is expected to be 4x4. If it is
123  /// too big, only the first 4 rows and/or columns will be used.
124  /// If it is too small, uninitialized elements will be filled in with
125  /// the corresponding elements from an identity matrix.
126  ///
127  GF_API
128  explicit GfMatrix4d(const std::vector< std::vector<float> >& v);
129 
130  /// Constructor. Initialize the matrix from 4 row vectors of
131  /// double. Each vector is expected to length 4. If it is too
132  /// big, only the first 4 items will be used. If it is too small,
133  /// uninitialized elements will be filled in with the
134  /// corresponding elements from an identity matrix.
135  ///
136  GF_API
137  explicit GfMatrix4d(const std::vector<double>& r0,
138  const std::vector<double>& r1,
139  const std::vector<double>& r2,
140  const std::vector<double>& r3);
141 
142  /// Constructor. Initialize the matrix from 4 row vectors of
143  /// float. Each vector is expected to length 4. If it is too
144  /// big, only the first 4 items will be used. If it is too small,
145  /// uninitialized elements will be filled in with the
146  /// corresponding elements from an identity matrix.
147  ///
148  GF_API
149  explicit GfMatrix4d(const std::vector<float>& r0,
150  const std::vector<float>& r1,
151  const std::vector<float>& r2,
152  const std::vector<float>& r3);
153 
154  /// Constructor. Initializes a transformation matrix to perform the
155  /// indicated rotation and translation.
156  GF_API
158  const GfVec3d& translate);
159 
160  /// Constructor. Initializes a transformation matrix to perform the
161  /// indicated rotation and translation.
162  GF_API
163  GfMatrix4d(const GfMatrix3d& rotmx,
164  const GfVec3d& translate);
165  /// This explicit constructor converts a "float" matrix to a "double" matrix.
166  GF_API
167  explicit GfMatrix4d(const class GfMatrix4f& m);
168 
169  /// Sets a row of the matrix from a Vec4.
170  void SetRow(int i, const GfVec4d & v) {
171  _mtx[i][0] = v[0];
172  _mtx[i][1] = v[1];
173  _mtx[i][2] = v[2];
174  _mtx[i][3] = v[3];
175  }
176 
177  /// Sets a column of the matrix from a Vec4.
178  void SetColumn(int i, const GfVec4d & v) {
179  _mtx[0][i] = v[0];
180  _mtx[1][i] = v[1];
181  _mtx[2][i] = v[2];
182  _mtx[3][i] = v[3];
183  }
184 
185  /// Gets a row of the matrix as a Vec4.
186  GfVec4d GetRow(int i) const {
187  return GfVec4d(_mtx[i][0], _mtx[i][1], _mtx[i][2], _mtx[i][3]);
188  }
189 
190  /// Gets a column of the matrix as a Vec4.
191  GfVec4d GetColumn(int i) const {
192  return GfVec4d(_mtx[0][i], _mtx[1][i], _mtx[2][i], _mtx[3][i]);
193  }
194 
195  /// Sets the matrix from 16 independent \c double values,
196  /// specified in row-major order. For example, parameter \e m10 specifies
197  /// the value in row 1 and column 0.
198  GfMatrix4d& Set(double m00, double m01, double m02, double m03,
199  double m10, double m11, double m12, double m13,
200  double m20, double m21, double m22, double m23,
201  double m30, double m31, double m32, double m33) {
202  _mtx[0][0] = m00; _mtx[0][1] = m01; _mtx[0][2] = m02; _mtx[0][3] = m03;
203  _mtx[1][0] = m10; _mtx[1][1] = m11; _mtx[1][2] = m12; _mtx[1][3] = m13;
204  _mtx[2][0] = m20; _mtx[2][1] = m21; _mtx[2][2] = m22; _mtx[2][3] = m23;
205  _mtx[3][0] = m30; _mtx[3][1] = m31; _mtx[3][2] = m32; _mtx[3][3] = m33;
206  return *this;
207  }
208 
209  /// Sets the matrix from a 4x4 array of \c double
210  /// values, specified in row-major order.
211  GfMatrix4d& Set(const double m[4][4]) {
212  _mtx[0][0] = m[0][0];
213  _mtx[0][1] = m[0][1];
214  _mtx[0][2] = m[0][2];
215  _mtx[0][3] = m[0][3];
216  _mtx[1][0] = m[1][0];
217  _mtx[1][1] = m[1][1];
218  _mtx[1][2] = m[1][2];
219  _mtx[1][3] = m[1][3];
220  _mtx[2][0] = m[2][0];
221  _mtx[2][1] = m[2][1];
222  _mtx[2][2] = m[2][2];
223  _mtx[2][3] = m[2][3];
224  _mtx[3][0] = m[3][0];
225  _mtx[3][1] = m[3][1];
226  _mtx[3][2] = m[3][2];
227  _mtx[3][3] = m[3][3];
228  return *this;
229  }
230 
231  /// Sets the matrix to the identity matrix.
233  return SetDiagonal(1);
234  }
235 
236  /// Sets the matrix to zero.
238  return SetDiagonal(0);
239  }
240 
241  /// Sets the matrix to \e s times the identity matrix.
242  GF_API
243  GfMatrix4d& SetDiagonal(double s);
244 
245  /// Sets the matrix to have diagonal (<c>v[0], v[1], v[2], v[3]</c>).
246  GF_API
247  GfMatrix4d& SetDiagonal(const GfVec4d&);
248 
249  /// Fills a 4x4 array of \c double values with the values in
250  /// the matrix, specified in row-major order.
251  GF_API
252  double* Get(double m[4][4]) const;
253 
254  /// Returns raw access to components of matrix as an array of
255  /// \c double values. Components are in row-major order.
256  double* data() {
257  return _mtx.GetData();
258  }
259 
260  /// Returns const raw access to components of matrix as an array of
261  /// \c double values. Components are in row-major order.
262  const double* data() const {
263  return _mtx.GetData();
264  }
265 
266  /// Returns vector components as an array of \c double values.
267  double* GetArray() {
268  return _mtx.GetData();
269  }
270 
271  /// Returns vector components as a const array of \c double values.
272  const double* GetArray() const {
273  return _mtx.GetData();
274  }
275 
276  /// Accesses an indexed row \e i of the matrix as an array of 4 \c
277  /// double values so that standard indexing (such as <c>m[0][1]</c>)
278  /// works correctly.
279  double* operator [](int i) { return _mtx[i]; }
280 
281  /// Accesses an indexed row \e i of the matrix as an array of 4 \c
282  /// double values so that standard indexing (such as <c>m[0][1]</c>)
283  /// works correctly.
284  const double* operator [](int i) const { return _mtx[i]; }
285 
286  /// Hash.
287  friend inline size_t hash_value(GfMatrix4d const &m) {
288  return TfHash::Combine(
289  m._mtx[0][0],
290  m._mtx[0][1],
291  m._mtx[0][2],
292  m._mtx[0][3],
293  m._mtx[1][0],
294  m._mtx[1][1],
295  m._mtx[1][2],
296  m._mtx[1][3],
297  m._mtx[2][0],
298  m._mtx[2][1],
299  m._mtx[2][2],
300  m._mtx[2][3],
301  m._mtx[3][0],
302  m._mtx[3][1],
303  m._mtx[3][2],
304  m._mtx[3][3]
305  );
306  }
307 
308  /// Tests for element-wise matrix equality. All elements must match
309  /// exactly for matrices to be considered equal.
310  GF_API
311  bool operator ==(const GfMatrix4d& m) const;
312 
313  /// Tests for element-wise matrix equality. All elements must match
314  /// exactly for matrices to be considered equal.
315  GF_API
316  bool operator ==(const GfMatrix4f& m) const;
317 
318  /// Tests for element-wise matrix inequality. All elements must match
319  /// exactly for matrices to be considered equal.
320  bool operator !=(const GfMatrix4d& m) const {
321  return !(*this == m);
322  }
323 
324  /// Tests for element-wise matrix inequality. All elements must match
325  /// exactly for matrices to be considered equal.
326  bool operator !=(const GfMatrix4f& m) const {
327  return !(*this == m);
328  }
329 
330  /// Returns the transpose of the matrix.
331  GF_API
332  GfMatrix4d GetTranspose() const;
333 
334  /// Returns the inverse of the matrix, or FLT_MAX * SetIdentity() if the
335  /// matrix is singular. (FLT_MAX is the largest value a \c float can have,
336  /// as defined by the system.) The matrix is considered singular if the
337  /// determinant is less than or equal to the optional parameter \e eps. If
338  /// \e det is non-null, <c>*det</c> is set to the determinant.
339  GF_API
340  GfMatrix4d GetInverse(double* det = NULL, double eps = 0) const;
341 
342  /// Returns the determinant of the matrix.
343  GF_API
344  double GetDeterminant() const;
345 
346  /// Sets a row of the matrix from a Vec3.
347  /// The fourth element of the row is ignored.
348  void SetRow3(int i, const GfVec3d & v) {
349  _mtx[i][0] = v[0];
350  _mtx[i][1] = v[1];
351  _mtx[i][2] = v[2];
352  }
353 
354  /// Gets a row of the matrix as a Vec3.
355  GfVec3d GetRow3(int i) const {
356  return GfVec3d(_mtx[i][0], _mtx[i][1], _mtx[i][2]);
357  }
358 
359  /// Returns the determinant of the upper 3x3 matrix. This method is useful
360  /// when the matrix describes a linear transformation such as a rotation or
361  /// scale because the other values in the 4x4 matrix are not important.
362  double GetDeterminant3() const {
363  return _GetDeterminant3(0, 1, 2, 0, 1, 2);
364  }
365 
366  /// Returns true, if the row vectors of the upper 3x3 matrix form an
367  /// orthogonal basis. Note they do not have to be unit length for this
368  /// test to return true.
369  bool HasOrthogonalRows3() const {
370  // XXX Should add GfAreOrthogonal(v0, v1, v2) (which also
371  // GfRotation::Decompose() could use).
372  GfVec3d axis0(GetRow3(0)), axis1(GetRow3(1)), axis2(GetRow3(2));
373  return (GfAbs(GfDot(axis0, axis1)) < GF_MIN_ORTHO_TOLERANCE &&
374  GfAbs(GfDot(axis0, axis2)) < GF_MIN_ORTHO_TOLERANCE &&
375  GfAbs(GfDot(axis1, axis2)) < GF_MIN_ORTHO_TOLERANCE);
376  }
377 
378  /// Makes the matrix orthonormal in place. This is an iterative method
379  /// that is much more stable than the previous cross/cross method. If the
380  /// iterative method does not converge, a warning is issued.
381  ///
382  /// Returns true if the iteration converged, false otherwise. Leaves any
383  /// translation part of the matrix unchanged. If \a issueWarning is true,
384  /// this method will issue a warning if the iteration does not converge,
385  /// otherwise it will be silent.
386  GF_API
387  bool Orthonormalize(bool issueWarning=true);
388 
389  /// Returns an orthonormalized copy of the matrix.
390  GF_API
391  GfMatrix4d GetOrthonormalized(bool issueWarning=true) const;
392 
393  /// Returns the sign of the determinant of the upper 3x3 matrix, i.e. 1
394  /// for a right-handed matrix, -1 for a left-handed matrix, and 0 for a
395  /// singular matrix.
396  GF_API
397  double GetHandedness() const;
398 
399  /// Returns true if the vectors in the upper 3x3 matrix form a
400  /// right-handed coordinate system.
401  bool IsRightHanded() const {
402  return GetHandedness() == 1.0;
403  }
404 
405  /// Returns true if the vectors in the upper 3x3 matrix form a left-handed
406  /// coordinate system.
407  bool IsLeftHanded() const {
408  return GetHandedness() == -1.0;
409  }
410 
411  /// Post-multiplies matrix \e m into this matrix.
412  GF_API
413  GfMatrix4d& operator *=(const GfMatrix4d& m);
414 
415  /// Multiplies the matrix by a double.
416  GF_API
417  GfMatrix4d& operator *=(double);
418 
419  /// Returns the product of a matrix and a double.
420  friend GfMatrix4d operator *(const GfMatrix4d& m1, double d)
421  {
422  GfMatrix4d m = m1;
423  return m *= d;
424  }
425 
426  ///
427  // Returns the product of a matrix and a double.
428  friend GfMatrix4d operator *(double d, const GfMatrix4d& m)
429  {
430  return m * d;
431  }
432 
433  /// Adds matrix \e m to this matrix.
434  GF_API
435  GfMatrix4d& operator +=(const GfMatrix4d& m);
436 
437  /// Subtracts matrix \e m from this matrix.
438  GF_API
439  GfMatrix4d& operator -=(const GfMatrix4d& m);
440 
441  /// Returns the unary negation of matrix \e m.
442  GF_API
443  friend GfMatrix4d operator -(const GfMatrix4d& m);
444 
445  /// Adds matrix \e m2 to \e m1
446  friend GfMatrix4d operator +(const GfMatrix4d& m1, const GfMatrix4d& m2)
447  {
448  GfMatrix4d tmp(m1);
449  tmp += m2;
450  return tmp;
451  }
452 
453  /// Subtracts matrix \e m2 from \e m1.
454  friend GfMatrix4d operator -(const GfMatrix4d& m1, const GfMatrix4d& m2)
455  {
456  GfMatrix4d tmp(m1);
457  tmp -= m2;
458  return tmp;
459  }
460 
461  /// Multiplies matrix \e m1 by \e m2.
462  friend GfMatrix4d operator *(const GfMatrix4d& m1, const GfMatrix4d& m2)
463  {
464  GfMatrix4d tmp(m1);
465  tmp *= m2;
466  return tmp;
467  }
468 
469  /// Divides matrix \e m1 by \e m2 (that is, <c>m1 * inv(m2)</c>).
470  friend GfMatrix4d operator /(const GfMatrix4d& m1, const GfMatrix4d& m2)
471  {
472  return(m1 * m2.GetInverse());
473  }
474 
475  /// Returns the product of a matrix \e m and a column vector \e vec.
476  friend inline GfVec4d operator *(const GfMatrix4d& m, const GfVec4d& vec) {
477  return GfVec4d(vec[0] * m._mtx[0][0] + vec[1] * m._mtx[0][1] + vec[2] * m._mtx[0][2] + vec[3] * m._mtx[0][3],
478  vec[0] * m._mtx[1][0] + vec[1] * m._mtx[1][1] + vec[2] * m._mtx[1][2] + vec[3] * m._mtx[1][3],
479  vec[0] * m._mtx[2][0] + vec[1] * m._mtx[2][1] + vec[2] * m._mtx[2][2] + vec[3] * m._mtx[2][3],
480  vec[0] * m._mtx[3][0] + vec[1] * m._mtx[3][1] + vec[2] * m._mtx[3][2] + vec[3] * m._mtx[3][3]);
481  }
482 
483  /// Returns the product of row vector \e vec and a matrix \e m.
484  friend inline GfVec4d operator *(const GfVec4d &vec, const GfMatrix4d& m) {
485  return GfVec4d(vec[0] * m._mtx[0][0] + vec[1] * m._mtx[1][0] + vec[2] * m._mtx[2][0] + vec[3] * m._mtx[3][0],
486  vec[0] * m._mtx[0][1] + vec[1] * m._mtx[1][1] + vec[2] * m._mtx[2][1] + vec[3] * m._mtx[3][1],
487  vec[0] * m._mtx[0][2] + vec[1] * m._mtx[1][2] + vec[2] * m._mtx[2][2] + vec[3] * m._mtx[3][2],
488  vec[0] * m._mtx[0][3] + vec[1] * m._mtx[1][3] + vec[2] * m._mtx[2][3] + vec[3] * m._mtx[3][3]);
489  }
490 
491  /// Sets matrix to specify a uniform scaling by \e scaleFactor.
492  GF_API
493  GfMatrix4d& SetScale(double scaleFactor);
494 
495  /// Returns the matrix with any scaling or shearing removed,
496  /// leaving only the rotation and translation.
497  /// If the matrix cannot be decomposed, returns the original matrix.
498  GF_API
500 
501  /// \name 3D Transformation Utilities
502  /// @{
503 
504  /// Sets the matrix to specify a rotation equivalent to \e rot,
505  /// and clears the translation.
506  GF_API
507  GfMatrix4d& SetRotate(const GfQuatd &rot);
508 
509  /// Sets the matrix to specify a rotation equivalent to \e rot,
510  /// without clearing the translation.
511  GF_API
513 
514  /// Sets the matrix to specify a rotation equivalent to \e rot,
515  /// and clears the translation.
516  GF_API
518 
519  /// Sets the matrix to specify a rotation equivalent to \e rot,
520  /// without clearing the translation.
521  GF_API
523 
524  /// Sets the matrix to specify a rotation equivalent to \e mx,
525  /// and clears the translation.
526  GF_API
527  GfMatrix4d& SetRotate(const GfMatrix3d &mx);
528 
529  /// Sets the matrix to specify a rotation equivalent to \e mx,
530  /// without clearing the translation.
531  GF_API
532  GfMatrix4d& SetRotateOnly(const GfMatrix3d &mx);
533 
534  /// Sets the matrix to specify a nonuniform scaling in x, y, and z by
535  /// the factors in vector \e scaleFactors.
536  GF_API
537  GfMatrix4d& SetScale(const GfVec3d &scaleFactors);
538 
539  /// Sets matrix to specify a translation by the vector \e trans,
540  /// and clears the rotation.
541  GF_API
543 
544  /// Sets matrix to specify a translation by the vector \e trans,
545  /// without clearing the rotation.
546  GF_API
548 
549  /// Sets matrix to specify a rotation by \e rotate and a
550  /// translation by \e translate.
551  GF_API
553  const GfVec3d& translate);
554 
555  /// Sets matrix to specify a rotation by \e rotmx and a
556  /// translation by \e translate.
557  GF_API
558  GfMatrix4d& SetTransform(const GfMatrix3d& rotmx,
559  const GfVec3d& translate);
560 
561  /// Sets the matrix to specify a viewing matrix from parameters
562  /// similar to those used by <c>gluLookAt(3G)</c>. \e eyePoint
563  /// represents the eye point in world space. \e centerPoint
564  /// represents the world-space center of attention. \e upDirection
565  /// is a vector indicating which way is up.
566  GF_API
567  GfMatrix4d& SetLookAt(const GfVec3d &eyePoint,
568  const GfVec3d &centerPoint,
569  const GfVec3d &upDirection);
570 
571  /// Sets the matrix to specify a viewing matrix from a world-space
572  /// \e eyePoint and a world-space rotation that rigidly rotates the
573  /// orientation from its canonical frame, which is defined to be
574  /// looking along the <c>-z</c> axis with the <c>+y</c> axis as the up
575  /// direction.
576  GF_API
577  GfMatrix4d& SetLookAt(const GfVec3d &eyePoint,
578  const GfRotation &orientation);
579 
580  /// Factors the matrix into 5 components:
581  /// \li <c>\e M = r * s * -r * u * t</c>
582  /// where
583  /// \li \e t is a translation.
584  /// \li \e u and \e r are rotations, and \e -r is the transpose
585  /// (inverse) of \e r. The \e u matrix may contain shear
586  /// information.
587  /// \li \e s is a scale.
588  /// Any projection information could be returned in matrix \e p,
589  /// but currently p is never modified.
590  ///
591  /// Returns \c false if the matrix is singular (as determined by \e eps).
592  /// In that case, any zero scales in \e s are clamped to \e eps
593  /// to allow computation of \e u.
594  GF_API
595  bool Factor(GfMatrix4d* r, GfVec3d* s, GfMatrix4d* u,
596  GfVec3d* t, GfMatrix4d* p,
597  double eps = 1e-10) const;
598 
599  /// Returns the translation part of the matrix, defined as the first three
600  /// elements of the last row.
602  return GfVec3d(_mtx[3][0], _mtx[3][1], _mtx[3][2]);
603  }
604 
605  /// Returns the rotation corresponding to this matrix. This works well
606  /// only if the matrix represents a rotation.
607  ///
608  /// For good results, consider calling Orthonormalize() before calling
609  /// this method.
610  GF_API
611  GfRotation ExtractRotation() const;
612 
613  /// Return the rotation corresponding to this matrix as a quaternion.
614  /// This works well only if the matrix represents a rotation.
615  ///
616  /// For good results, consider calling Orthonormalize() before calling
617  /// this method.
618  GF_API
620 
621  /// Decompose the rotation corresponding to this matrix about 3 orthogonal
622  /// axes. If the axes are not orthogonal, warnings will be spewed.
623  ///
624  /// This is a convenience method that is equivalent to calling
625  /// ExtractRotation().Decompose().
626  GF_API
627  GfVec3d DecomposeRotation(const GfVec3d &axis0,
628  const GfVec3d &axis1,
629  const GfVec3d &axis2) const;
630 
631  /// Returns the rotation corresponding to this matrix. This works well
632  /// only if the matrix represents a rotation.
633  ///
634  /// For good results, consider calling Orthonormalize() before calling
635  /// this method.
636  GF_API
638 
639  /// Transforms the row vector \e vec by the matrix, returning the result.
640  /// This treats the vector as a 4-component vector whose fourth component
641  /// is 1.
642  GfVec3d Transform(const GfVec3d &vec) const {
643  return GfProject(GfVec4d(
644  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0],
645  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1],
646  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2],
647  vec[0] * _mtx[0][3] + vec[1] * _mtx[1][3] + vec[2] * _mtx[2][3] + _mtx[3][3]));
648  }
649 
650  /// Transforms row vector \e vec by the matrix, returning the result. This
651  /// treats the vector as a direction vector, so the translation
652  /// information in the matrix is ignored. That is, it treats the vector as
653  /// a 4-component vector whose fourth component is 0.
654  GfVec3d TransformDir(const GfVec3d &vec) const {
655  return GfVec3d(
656  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0],
657  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1],
658  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2]);
659  }
660 
661  /// Transforms the row vector \e vec by the matrix, returning the result.
662  /// This treats the vector as a 4-component vector whose fourth component
663  /// is 1 and ignores the fourth column of the matrix (i.e. assumes it is
664  /// (0, 0, 0, 1)).
665  GfVec3d TransformAffine(const GfVec3d &vec) const {
666  return GfVec3d(
667  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0],
668  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1],
669  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2]);
670  }
671  /// @}
672 
673 private:
674  /// Returns the determinant of the 3x3 submatrix specified by the three
675  /// given row and column indices (0-3 for each).
676  GF_API
677  double _GetDeterminant3(size_t row1, size_t row2, size_t row3,
678  size_t col1, size_t col2, size_t col3) const;
679 
680  /// Diagonalizes the upper 3x3 matrix of a matrix known to be symmetric.
681  void _Jacobi3(GfVec3d *eigenvalues, GfVec3d eigenvectors[3]) const;
682 
683  /// Set the 3x3 submatrix to the rotation given by a quaternion,
684  /// defined by the real component \p r and imaginary components \p i.
685  void _SetRotateFromQuat(double r, const GfVec3d& i);
686 
687 
688 private:
689  /// Matrix storage, in row-major order.
691 
692  // Friend declarations
693  friend class GfMatrix4f;
694 };
695 
696 
697 /// Tests for equality within a given tolerance, returning \c true if the
698 /// difference between each component of the matrix is less than or equal
699 /// to \p tolerance, or false otherwise.
700 GF_API
701 bool GfIsClose(GfMatrix4d const &m1, GfMatrix4d const &m2, double tolerance);
702 
703 /// Output a GfMatrix4d
704 /// \ingroup group_gf_DebuggingOutput
705 GF_API std::ostream& operator<<(std::ostream &, GfMatrix4d const &);
706 
708 
709 #endif // PXR_BASE_GF_MATRIX4D_H
const double * GetArray() const
Returns vector components as a const array of double values.
Definition: matrix4d.h:272
GfMatrix4d & SetIdentity()
Sets the matrix to the identity matrix.
Definition: matrix4d.h:232
GF_API GfMatrix4d & SetRotate(const GfQuatd &rot)
GfVec3f GfProject(const GfVec4f &v)
Definition: homogeneous.h:48
friend GfMatrix4d operator*(const GfMatrix4d &m1, double d)
Returns the product of a matrix and a double.
Definition: matrix4d.h:420
GF_API double * Get(double m[4][4]) const
GF_API GfMatrix4d & operator*=(const GfMatrix4d &m)
Post-multiplies matrix m into this matrix.
GF_API bool Orthonormalize(bool issueWarning=true)
GF_API bool operator==(const GfMatrix4d &m) const
bool IsRightHanded() const
Definition: matrix4d.h:401
GfMatrix4d(double m00, double m01, double m02, double m03, double m10, double m11, double m12, double m13, double m20, double m21, double m22, double m23, double m30, double m31, double m32, double m33)
Definition: matrix4d.h:84
bool IsLeftHanded() const
Definition: matrix4d.h:407
GF_API GfMatrix4d & SetScale(double scaleFactor)
Sets matrix to specify a uniform scaling by scaleFactor.
static const size_t numColumns
Definition: matrix4d.h:76
*get result *(waiting if necessary)*A common idiom is to fire a bunch of sub tasks at the and then *wait for them to all complete We provide a helper class
Definition: thread.h:632
GF_API GfMatrix4d GetInverse(double *det=NULL, double eps=0) const
friend GfMatrix4d operator+(const GfMatrix4d &m1, const GfMatrix4d &m2)
Adds matrix m2 to m1.
Definition: matrix4d.h:446
const GLdouble * v
Definition: glcorearb.h:837
GF_API GfMatrix4d & SetTranslate(const GfVec3d &trans)
GLsizei const GLfloat * value
Definition: glcorearb.h:824
GA_API const UT_StringHolder rot
void SetColumn(int i, const GfVec4d &v)
Sets a column of the matrix from a Vec4.
Definition: matrix4d.h:178
GLdouble s
Definition: glad.h:3009
GF_API GfMatrix4d & SetTransform(const GfRotation &rotate, const GfVec3d &translate)
Definition: vec4d.h:45
GF_API GfMatrix4d & operator-=(const GfMatrix4d &m)
Subtracts matrix m from this matrix.
GF_API GfMatrix4d GetOrthonormalized(bool issueWarning=true) const
Returns an orthonormalized copy of the matrix.
double * data()
Definition: matrix4d.h:256
GF_API GfMatrix4d & SetTranslateOnly(const GfVec3d &t)
GF_API GfMatrix4d & operator+=(const GfMatrix4d &m)
Adds matrix m to this matrix.
GF_API GfVec3d DecomposeRotation(const GfVec3d &axis0, const GfVec3d &axis1, const GfVec3d &axis2) const
GfVec3d Transform(const GfVec3d &vec) const
Definition: matrix4d.h:642
bool HasOrthogonalRows3() const
Definition: matrix4d.h:369
GfVec3d TransformDir(const GfVec3d &vec) const
Definition: matrix4d.h:654
double GfAbs(double f)
Definition: math.h:222
friend GfMatrix4d operator/(const GfMatrix4d &m1, const GfMatrix4d &m2)
Divides matrix m1 by m2 (that is, m1 * inv(m2)).
Definition: matrix4d.h:470
GfMatrix4d()=default
Default constructor. Leaves the matrix component values undefined.
double * operator[](int i)
Definition: matrix4d.h:279
GF_API GfMatrix4d GetTranspose() const
Returns the transpose of the matrix.
GF_API GfMatrix4d & SetDiagonal(double s)
Sets the matrix to s times the identity matrix.
GfMatrix4d & Set(const double m[4][4])
Definition: matrix4d.h:211
double ScalarType
Definition: matrix4d.h:73
GF_API GfQuatd ExtractRotationQuat() const
T * GetData()
Return a pointer to the start of all the data.
Definition: matrixData.h:33
GfMatrix4d(const double m[4][4])
Definition: matrix4d.h:96
GA_API const UT_StringHolder trans
static const size_t numRows
Definition: matrix4d.h:75
GfMatrix4d(const GfVec4d &v)
Definition: matrix4d.h:108
double GetDeterminant3() const
Definition: matrix4d.h:362
GF_API double GetDeterminant() const
Returns the determinant of the matrix.
GfVec4d GetRow(int i) const
Gets a row of the matrix as a Vec4.
Definition: matrix4d.h:186
GF_API friend GfMatrix4d operator-(const GfMatrix4d &m)
Returns the unary negation of matrix m.
GF_API double GetHandedness() const
double * GetArray()
Returns vector components as an array of double values.
Definition: matrix4d.h:267
GfVec3d TransformAffine(const GfVec3d &vec) const
Definition: matrix4d.h:665
GF_API GfRotation ExtractRotation() const
GF_API bool Factor(GfMatrix4d *r, GfVec3d *s, GfMatrix4d *u, GfVec3d *t, GfMatrix4d *p, double eps=1e-10) const
GF_API GfMatrix4d & SetLookAt(const GfVec3d &eyePoint, const GfVec3d &centerPoint, const GfVec3d &upDirection)
friend size_t hash_value(GfMatrix4d const &m)
Hash.
Definition: matrix4d.h:287
GfMatrix4d(double s)
Definition: matrix4d.h:102
double GfDot(const GfDualQuatd &dq1, const GfDualQuatd &dq2)
Return the dot (inner) product of two dual quaternions.
Definition: dualQuatd.h:260
GF_API GfMatrix3d ExtractRotationMatrix() const
ImageBuf OIIO_API rotate(const ImageBuf &src, float angle, string_view filtername=string_view(), float filterwidth=0.0f, bool recompute_roi=false, ROI roi={}, int nthreads=0)
GLdouble t
Definition: glad.h:2397
GF_API bool GfIsClose(GfMatrix4d const &m1, GfMatrix4d const &m2, double tolerance)
GF_API std::ostream & operator<<(std::ostream &, GfMatrix4d const &)
GfMatrix4d & Set(double m00, double m01, double m02, double m03, double m10, double m11, double m12, double m13, double m20, double m21, double m22, double m23, double m30, double m31, double m32, double m33)
Definition: matrix4d.h:198
static size_t Combine(Args &&...args)
Produce a hash code by combining the hash codes of several objects.
Definition: hash.h:487
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
GF_API GfMatrix4d & SetRotateOnly(const GfQuatd &rot)
const double * data() const
Definition: matrix4d.h:262
void SetRow(int i, const GfVec4d &v)
Sets a row of the matrix from a Vec4.
Definition: matrix4d.h:170
Definition: vec3d.h:45
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
GF_API GfMatrix4d RemoveScaleShear() const
void SetRow3(int i, const GfVec3d &v)
Definition: matrix4d.h:348
GLboolean r
Definition: glcorearb.h:1222
Definition: quatd.h:42
PUGI__FN char_t * translate(char_t *buffer, const char_t *from, const char_t *to, size_t to_length)
Definition: pugixml.cpp:8574
GfVec3d ExtractTranslation() const
Definition: matrix4d.h:601
GfVec4d GetColumn(int i) const
Gets a column of the matrix as a Vec4.
Definition: matrix4d.h:191
GfMatrix4d & SetZero()
Sets the matrix to zero.
Definition: matrix4d.h:237
bool operator!=(const GfMatrix4d &m) const
Definition: matrix4d.h:320
GfVec3d GetRow3(int i) const
Gets a row of the matrix as a Vec3.
Definition: matrix4d.h:355
#define GF_MIN_ORTHO_TOLERANCE
Definition: limits.h:22
#define GF_API
Definition: api.h:23