HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
matrix4f.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_MATRIX4F_H
12 #define PXR_BASE_GF_MATRIX4F_H
13 
14 /// \file gf/matrix4f.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/vec4f.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/vec3f.h"
27 #include "pxr/base/tf/hash.h"
28 
29 #include <iosfwd>
30 #include <vector>
31 
33 
34 template <>
35 struct GfIsGfMatrix<class GfMatrix4f> { static const bool value = true; };
36 
37 class GfMatrix4d;
38 class GfMatrix4f;
39 class GfQuatf;
40 class GfRotation;
41 class GfMatrix3f;
42 
43 /// \class GfMatrix4f
44 /// \ingroup group_gf_LinearAlgebra
45 ///
46 /// Stores a 4x4 matrix of \c float 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 GfMatrix4f 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 float 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  GfMatrix4f() = default;
80 
81  /// Constructor. Initializes the matrix from 16 independent
82  /// \c float values, specified in row-major order. For example,
83  /// parameter \e m10 specifies the value in row 1 and column 0.
84  GfMatrix4f(float m00, float m01, float m02, float m03,
85  float m10, float m11, float m12, float m13,
86  float m20, float m21, float m22, float m23,
87  float m30, float m31, float m32, float 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 float values, specified in row-major order.
96  GfMatrix4f(const float m[4][4]) {
97  Set(m);
98  }
99 
100  /// Constructor. Explicitly initializes the matrix to \e s times the
101  /// identity matrix.
102  explicit GfMatrix4f(float 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 GfMatrix4f(const GfVec4f& 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 GfMatrix4f(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 GfMatrix4f(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 GfMatrix4f(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 GfMatrix4f(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 GfVec3f& translate);
159 
160  /// Constructor. Initializes a transformation matrix to perform the
161  /// indicated rotation and translation.
162  GF_API
163  GfMatrix4f(const GfMatrix3f& rotmx,
164  const GfVec3f& translate);
165  /// This explicit constructor converts a "double" matrix to a "float" matrix.
166  GF_API
167  explicit GfMatrix4f(const class GfMatrix4d& m);
168 
169  /// Sets a row of the matrix from a Vec4.
170  void SetRow(int i, const GfVec4f & 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 GfVec4f & 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  GfVec4f GetRow(int i) const {
187  return GfVec4f(_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  GfVec4f GetColumn(int i) const {
192  return GfVec4f(_mtx[0][i], _mtx[1][i], _mtx[2][i], _mtx[3][i]);
193  }
194 
195  /// Sets the matrix from 16 independent \c float values,
196  /// specified in row-major order. For example, parameter \e m10 specifies
197  /// the value in row 1 and column 0.
198  GfMatrix4f& Set(float m00, float m01, float m02, float m03,
199  float m10, float m11, float m12, float m13,
200  float m20, float m21, float m22, float m23,
201  float m30, float m31, float m32, float 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 float
210  /// values, specified in row-major order.
211  GfMatrix4f& Set(const float 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  GfMatrix4f& SetDiagonal(float s);
244 
245  /// Sets the matrix to have diagonal (<c>v[0], v[1], v[2], v[3]</c>).
246  GF_API
247  GfMatrix4f& SetDiagonal(const GfVec4f&);
248 
249  /// Fills a 4x4 array of \c float values with the values in
250  /// the matrix, specified in row-major order.
251  GF_API
252  float* Get(float m[4][4]) const;
253 
254  /// Returns raw access to components of matrix as an array of
255  /// \c float values. Components are in row-major order.
256  float* data() {
257  return _mtx.GetData();
258  }
259 
260  /// Returns const raw access to components of matrix as an array of
261  /// \c float values. Components are in row-major order.
262  const float* data() const {
263  return _mtx.GetData();
264  }
265 
266  /// Returns vector components as an array of \c float values.
267  float* GetArray() {
268  return _mtx.GetData();
269  }
270 
271  /// Returns vector components as a const array of \c float values.
272  const float* 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  /// float values so that standard indexing (such as <c>m[0][1]</c>)
278  /// works correctly.
279  float* operator [](int i) { return _mtx[i]; }
280 
281  /// Accesses an indexed row \e i of the matrix as an array of 4 \c
282  /// float values so that standard indexing (such as <c>m[0][1]</c>)
283  /// works correctly.
284  const float* operator [](int i) const { return _mtx[i]; }
285 
286  /// Hash.
287  friend inline size_t hash_value(GfMatrix4f 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  GfMatrix4f 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  GfMatrix4f 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 GfVec3f & 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  GfVec3f GetRow3(int i) const {
356  return GfVec3f(_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  GfVec3f 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  GfMatrix4f 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  GfMatrix4f& operator *=(const GfMatrix4f& m);
414 
415  /// Multiplies the matrix by a float.
416  GF_API
417  GfMatrix4f& operator *=(double);
418 
419  /// Returns the product of a matrix and a float.
420  friend GfMatrix4f operator *(const GfMatrix4f& m1, double d)
421  {
422  GfMatrix4f m = m1;
423  return m *= d;
424  }
425 
426  ///
427  // Returns the product of a matrix and a float.
428  friend GfMatrix4f operator *(double d, const GfMatrix4f& m)
429  {
430  return m * d;
431  }
432 
433  /// Adds matrix \e m to this matrix.
434  GF_API
435  GfMatrix4f& operator +=(const GfMatrix4f& m);
436 
437  /// Subtracts matrix \e m from this matrix.
438  GF_API
439  GfMatrix4f& operator -=(const GfMatrix4f& m);
440 
441  /// Returns the unary negation of matrix \e m.
442  GF_API
443  friend GfMatrix4f operator -(const GfMatrix4f& m);
444 
445  /// Adds matrix \e m2 to \e m1
446  friend GfMatrix4f operator +(const GfMatrix4f& m1, const GfMatrix4f& m2)
447  {
448  GfMatrix4f tmp(m1);
449  tmp += m2;
450  return tmp;
451  }
452 
453  /// Subtracts matrix \e m2 from \e m1.
454  friend GfMatrix4f operator -(const GfMatrix4f& m1, const GfMatrix4f& m2)
455  {
456  GfMatrix4f tmp(m1);
457  tmp -= m2;
458  return tmp;
459  }
460 
461  /// Multiplies matrix \e m1 by \e m2.
462  friend GfMatrix4f operator *(const GfMatrix4f& m1, const GfMatrix4f& m2)
463  {
464  GfMatrix4f 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 GfMatrix4f operator /(const GfMatrix4f& m1, const GfMatrix4f& 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 GfVec4f operator *(const GfMatrix4f& m, const GfVec4f& vec) {
477  return GfVec4f(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 GfVec4f operator *(const GfVec4f &vec, const GfMatrix4f& m) {
485  return GfVec4f(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  GfMatrix4f& SetScale(float 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  GfMatrix4f& SetRotate(const GfQuatf &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  GfMatrix4f& SetRotate(const GfMatrix3f &mx);
528 
529  /// Sets the matrix to specify a rotation equivalent to \e mx,
530  /// without clearing the translation.
531  GF_API
532  GfMatrix4f& SetRotateOnly(const GfMatrix3f &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  GfMatrix4f& SetScale(const GfVec3f &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 GfVec3f& translate);
554 
555  /// Sets matrix to specify a rotation by \e rotmx and a
556  /// translation by \e translate.
557  GF_API
558  GfMatrix4f& SetTransform(const GfMatrix3f& rotmx,
559  const GfVec3f& 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  GfMatrix4f& SetLookAt(const GfVec3f &eyePoint,
568  const GfVec3f &centerPoint,
569  const GfVec3f &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  GfMatrix4f& SetLookAt(const GfVec3f &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(GfMatrix4f* r, GfVec3f* s, GfMatrix4f* u,
596  GfVec3f* t, GfMatrix4f* p,
597  float eps = 1e-5) const;
598 
599  /// Returns the translation part of the matrix, defined as the first three
600  /// elements of the last row.
602  return GfVec3f(_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  GfVec3f DecomposeRotation(const GfVec3f &axis0,
628  const GfVec3f &axis1,
629  const GfVec3f &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 the row vector \e vec by the matrix, returning the result.
651  /// This treats the vector as a 4-component vector whose fourth component
652  /// is 1. This is an overloaded method; it differs from the other version
653  /// in that it returns a different value type.
654  GfVec3f Transform(const GfVec3f &vec) const {
655  return (GfProject(GfVec4f(
656  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0],
657  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1],
658  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2],
659  vec[0] * _mtx[0][3] + vec[1] * _mtx[1][3] + vec[2] * _mtx[2][3] + _mtx[3][3])));
660  }
661 
662  /// Transforms row vector \e vec by the matrix, returning the result. This
663  /// treats the vector as a direction vector, so the translation
664  /// information in the matrix is ignored. That is, it treats the vector as
665  /// a 4-component vector whose fourth component is 0.
666  GfVec3d TransformDir(const GfVec3d &vec) const {
667  return GfVec3d(
668  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0],
669  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1],
670  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2]);
671  }
672 
673  /// Transforms row vector \e vec by the matrix, returning the result. This
674  /// treats the vector as a direction vector, so the translation
675  /// information in the matrix is ignored. That is, it treats the vector as
676  /// a 4-component vector whose fourth component is 0. This is an
677  /// overloaded method; it differs from the other version in that it
678  /// returns a different value type.
679  GfVec3f TransformDir(const GfVec3f &vec) const {
680  return GfVec3f(
681  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0],
682  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1],
683  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2]);
684  }
685 
686  /// Transforms the row vector \e vec by the matrix, returning the result.
687  /// This treats the vector as a 4-component vector whose fourth component
688  /// is 1 and ignores the fourth column of the matrix (i.e. assumes it is
689  /// (0, 0, 0, 1)).
690  GfVec3d TransformAffine(const GfVec3d &vec) const {
691  return GfVec3d(
692  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0],
693  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1],
694  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2]);
695  }
696 
697  /// Transforms the row vector \e vec by the matrix, returning the result.
698  /// This treats the vector as a 4-component vector whose fourth component
699  /// is 1 and ignores the fourth column of the matrix (i.e. assumes it is
700  /// (0, 0, 0, 1)).
701  GfVec3f TransformAffine(const GfVec3f &vec) const {
702  return GfVec3f(
703  vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0],
704  vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1],
705  vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2]);
706  }
707  /// @}
708 
709 private:
710  /// Returns the determinant of the 3x3 submatrix specified by the three
711  /// given row and column indices (0-3 for each).
712  GF_API
713  double _GetDeterminant3(size_t row1, size_t row2, size_t row3,
714  size_t col1, size_t col2, size_t col3) const;
715 
716  /// Diagonalizes the upper 3x3 matrix of a matrix known to be symmetric.
717  void _Jacobi3(GfVec3d *eigenvalues, GfVec3d eigenvectors[3]) const;
718 
719  /// Set the 3x3 submatrix to the rotation given by a quaternion,
720  /// defined by the real component \p r and imaginary components \p i.
721  void _SetRotateFromQuat(float r, const GfVec3f& i);
722 
723 
724 private:
725  /// Matrix storage, in row-major order.
727 
728  // Friend declarations
729  friend class GfMatrix4d;
730 };
731 
732 
733 /// Tests for equality within a given tolerance, returning \c true if the
734 /// difference between each component of the matrix is less than or equal
735 /// to \p tolerance, or false otherwise.
736 GF_API
737 bool GfIsClose(GfMatrix4f const &m1, GfMatrix4f const &m2, double tolerance);
738 
739 /// Output a GfMatrix4f
740 /// \ingroup group_gf_DebuggingOutput
741 GF_API std::ostream& operator<<(std::ostream &, GfMatrix4f const &);
742 
744 
745 #endif // PXR_BASE_GF_MATRIX4F_H
bool HasOrthogonalRows3() const
Definition: matrix4f.h:369
GfVec3f GfProject(const GfVec4f &v)
Definition: homogeneous.h:48
GF_API GfVec3f DecomposeRotation(const GfVec3f &axis0, const GfVec3f &axis1, const GfVec3f &axis2) const
GfVec4f GetRow(int i) const
Gets a row of the matrix as a Vec4.
Definition: matrix4f.h:186
GF_API std::ostream & operator<<(std::ostream &, GfMatrix4f const &)
GfVec3f TransformDir(const GfVec3f &vec) const
Definition: matrix4f.h:679
GF_API friend GfMatrix4f operator-(const GfMatrix4f &m)
Returns the unary negation of matrix m.
static const size_t numRows
Definition: matrix4f.h:75
GF_API GfMatrix4f & operator*=(const GfMatrix4f &m)
Post-multiplies matrix m into this matrix.
GF_API GfMatrix4f & SetDiagonal(float s)
Sets the matrix to s times the identity matrix.
friend GfMatrix4f operator+(const GfMatrix4f &m1, const GfMatrix4f &m2)
Adds matrix m2 to m1.
Definition: matrix4f.h:446
*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
bool IsLeftHanded() const
Definition: matrix4f.h:407
GF_API GfMatrix4f & operator+=(const GfMatrix4f &m)
Adds matrix m to this matrix.
float * data()
Definition: matrix4f.h:256
const GLdouble * v
Definition: glcorearb.h:837
GLsizei const GLfloat * value
Definition: glcorearb.h:824
GF_API GfMatrix4f & SetRotate(const GfQuatf &rot)
GA_API const UT_StringHolder rot
GF_API GfMatrix4f & SetRotateOnly(const GfQuatf &rot)
Definition: vec3f.h:45
GLdouble s
Definition: glad.h:3009
Definition: vec4d.h:45
GfVec3d TransformDir(const GfVec3d &vec) const
Definition: matrix4f.h:666
GfVec4f GetColumn(int i) const
Gets a column of the matrix as a Vec4.
Definition: matrix4f.h:191
GF_API GfQuatf ExtractRotationQuat() const
GF_API GfMatrix3f ExtractRotationMatrix() const
double GfAbs(double f)
Definition: math.h:222
Definition: quatf.h:42
GF_API GfMatrix4f & SetTranslateOnly(const GfVec3f &t)
void SetRow3(int i, const GfVec3f &v)
Definition: matrix4f.h:348
GF_API GfMatrix4f GetInverse(double *det=NULL, double eps=0) const
GF_API GfMatrix4f RemoveScaleShear() const
GF_API bool Orthonormalize(bool issueWarning=true)
void SetColumn(int i, const GfVec4f &v)
Sets a column of the matrix from a Vec4.
Definition: matrix4f.h:178
bool IsRightHanded() const
Definition: matrix4f.h:401
friend GfMatrix4f operator*(const GfMatrix4f &m1, double d)
Returns the product of a matrix and a float.
Definition: matrix4f.h:420
GF_API float * Get(float m[4][4]) const
GfMatrix4f & Set(float m00, float m01, float m02, float m03, float m10, float m11, float m12, float m13, float m20, float m21, float m22, float m23, float m30, float m31, float m32, float m33)
Definition: matrix4f.h:198
GF_API GfMatrix4f & SetScale(float scaleFactor)
Sets matrix to specify a uniform scaling by scaleFactor.
GF_API GfMatrix4f & SetTransform(const GfRotation &rotate, const GfVec3f &translate)
GfVec3d Transform(const GfVec3d &vec) const
Definition: matrix4f.h:642
double GetDeterminant3() const
Definition: matrix4f.h:362
T * GetData()
Return a pointer to the start of all the data.
Definition: matrixData.h:33
GA_API const UT_StringHolder trans
GfVec3f GetRow3(int i) const
Gets a row of the matrix as a Vec3.
Definition: matrix4f.h:355
friend size_t hash_value(GfMatrix4f const &m)
Hash.
Definition: matrix4f.h:287
GF_API double GetHandedness() const
GF_API bool Factor(GfMatrix4f *r, GfVec3f *s, GfMatrix4f *u, GfVec3f *t, GfMatrix4f *p, float eps=1e-5) const
float * operator[](int i)
Definition: matrix4f.h:279
GfMatrix4f & SetZero()
Sets the matrix to zero.
Definition: matrix4f.h:237
GF_API bool operator==(const GfMatrix4d &m) const
float ScalarType
Definition: matrix4f.h:73
double GfDot(const GfDualQuatd &dq1, const GfDualQuatd &dq2)
Return the dot (inner) product of two dual quaternions.
Definition: dualQuatd.h:260
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
GfMatrix4f(const GfVec4f &v)
Definition: matrix4f.h:108
Definition: vec4f.h:45
GfMatrix4f & SetIdentity()
Sets the matrix to the identity matrix.
Definition: matrix4f.h:232
GF_API GfMatrix4f GetTranspose() const
Returns the transpose of the matrix.
GF_API GfMatrix4f & SetTranslate(const GfVec3f &trans)
GF_API GfMatrix4f & SetLookAt(const GfVec3f &eyePoint, const GfVec3f &centerPoint, const GfVec3f &upDirection)
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
GfMatrix4f & Set(const float m[4][4])
Definition: matrix4f.h:211
GfMatrix4f(const float m[4][4])
Definition: matrix4f.h:96
friend GfMatrix4f operator/(const GfMatrix4f &m1, const GfMatrix4f &m2)
Divides matrix m1 by m2 (that is, m1 * inv(m2)).
Definition: matrix4f.h:470
GF_API double GetDeterminant() const
Returns the determinant of the matrix.
GF_API bool GfIsClose(GfMatrix4f const &m1, GfMatrix4f const &m2, double tolerance)
GfVec3f ExtractTranslation() const
Definition: matrix4f.h:601
Definition: vec3d.h:45
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
GfMatrix4f()=default
Default constructor. Leaves the matrix component values undefined.
GfVec3f TransformAffine(const GfVec3f &vec) const
Definition: matrix4f.h:701
GfMatrix4f(float m00, float m01, float m02, float m03, float m10, float m11, float m12, float m13, float m20, float m21, float m22, float m23, float m30, float m31, float m32, float m33)
Definition: matrix4f.h:84
GF_API GfRotation ExtractRotation() const
GfVec3f Transform(const GfVec3f &vec) const
Definition: matrix4f.h:654
GLboolean r
Definition: glcorearb.h:1222
PUGI__FN char_t * translate(char_t *buffer, const char_t *from, const char_t *to, size_t to_length)
Definition: pugixml.cpp:8574
static const size_t numColumns
Definition: matrix4f.h:76
GfMatrix4f(float s)
Definition: matrix4f.h:102
GF_API GfMatrix4f & operator-=(const GfMatrix4f &m)
Subtracts matrix m from this matrix.
GfVec3d TransformAffine(const GfVec3d &vec) const
Definition: matrix4f.h:690
void SetRow(int i, const GfVec4f &v)
Sets a row of the matrix from a Vec4.
Definition: matrix4f.h:170
GF_API GfMatrix4f GetOrthonormalized(bool issueWarning=true) const
Returns an orthonormalized copy of the matrix.
#define GF_MIN_ORTHO_TOLERANCE
Definition: limits.h:22
const float * data() const
Definition: matrix4f.h:262
#define GF_API
Definition: api.h:23
float * GetArray()
Returns vector components as an array of float values.
Definition: matrix4f.h:267
bool operator!=(const GfMatrix4d &m) const
Definition: matrix4f.h:320
const float * GetArray() const
Returns vector components as a const array of float values.
Definition: matrix4f.h:272