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