Matrix Manual (Classic)

内容表

关于
Access
组件
Functionality
- Apply Transformation
- Edit Matrix
比较
Disc I/O
Utility Functions
延伸阅读

关于

In 3D graphics a matrix is used to represent the transformation from one coordinate system to another. The typical use case is the transformation matrix that defines the position, rotation and scale of an object in 3D space.

The classic matrix classes available:

Matrix32 : A matrix composed of Vector32 元素。
Matrix64 : A matrix composed of Vector64 元素。
矩阵 : Defined as Matrix64 .

另请参阅 Vector Manual (Classic) .

警告: A description of MAXON API matrix classes can be found here: Matrices .

Access

To retrieve and modify 矩阵 objects stored in a BaseObject respectively use:

BaseObject::GetMg() : Returns the world (global) matrix representing the object's position, scale and rotation.
BaseObject::SetMg() : Sets the world (global) matrix representing the object's position, scale and rotation.

For more object related matrices see BaseObject .

To retrieve and modify 矩阵 objects stored in a BaseContainer respectively use:

BaseContainer::GetMatrix() ：返回矩阵 stored at the given ID.
BaseContainer::SetMatrix() : Sets the 矩阵 stored at the given ID.

另请参阅 BaseContainer Manual .

To retrieve and modify 矩阵 objects stored in a GeData object ( GeData type is DA_MATRIX ) respectively use:

GeData::GetMatrix() ：返回矩阵对象。
GeData::SetMatrix() : Stores the 矩阵对象。

另请参阅 GeData Manual .

// This example reads a Matrix userdata parameter from the given object // and creates a new cube using that Matrix.

const DescID id { DescLevel { ID_USERDATA , DTYPE_SUBCONTAINER , 0 }, DescLevel { 1, DTYPE_MATRIX , 0 } };

GeData data;

// read the user data parameter 1 if (object-> GetParameter ( id , data, DESCFLAGS_GET::NONE )) { const 矩阵 mg = data. GetMatrix (); BaseObject * const cube = BaseObject::Alloc ( Ocube ); if (cube != nullptr ) { cube-> SetMg (mg); doc-> InsertObject (cube, nullptr , nullptr ); } }

组件

A matrix is composed of four vector components:

Matrix::off : The translation vector.
Matrix::sqmat::v1: The X-axis coordinate in a left-handed coordinate system of a transformed X-axis aligned unit-vector.
Matrix::sqmat::v2: The Y-axis coordinate in a left-handed coordinate system of a transformed Y-axis aligned unit-vector.
Matrix::sqmat::v3: The Z-axis coordinate in a left-handed coordinate system of a transformed Z-axis aligned unit-vector.

// This example prints the world space position of the given object. const 矩阵 mg = object ->GetMg(); ApplicationOutput ( "World Space Position: @" _s, mg. off );

Functionality

Apply Transformation

A matrix is typically used to transform a given vector.

Matrix::operator*() const: Transforms the given vector.

// This example loops through all points of the given point object. // For each point the coordinates are transferred into world space // and a sphere is created at that location. const 向量 * const points = pointObject->GetPointR(); const Int32 pointCount = pointObject->GetPointCount(); const 矩阵 mg = pointObject->GetMg(); for ( Int32 i = 0; i < pointCount; ++i) { if (points) { const 向量 point = points[i]; const 向量 worldSpacePosition = mg * point; BaseObject * const sphere = BaseObject::Alloc ( Osphere ); if (sphere != nullptr ) { sphere-> SetMg ( MatrixMove (worldSpacePosition)); doc-> InsertObject (sphere, nullptr , nullptr ); } } }

Edit Matrix

Basic operations to edit a matrix are done using operators or special functions:

Matrix::operator~() : Inverts the matrix.
Matrix::operator/() : Divides each vector in matrix with the given scalar.

// This example calculates the position of objectB in the local space of objectA. const 矩阵 mgA = objectA->GetMg(); const 矩阵 inverse = ~mgA; const 向量 worldSpacePos = objectB->GetMg().off; const 向量 localSpacePos = inverse * worldSpacePos; const maxon::String objectBName { objectB->GetName() }; const maxon::String objectAName { objectA->GetName() }; ApplicationOutput ( "Object " _s + objectBName); ApplicationOutput ( "Position @ in the local space of @" _s, localSpacePos, objectAName);

比较

Two matrices can be compared using the usual operators:

Matrix::operator==() : Returns true if the two matrices are equal.
Matrix::operator!=() : Returns true if the two matrices are not equal.

注意: For save comparison of floating point values see 比较 .

Disc I/O

Matrix objects can be stored in a BaseFile 或 HyperFile using:

BaseFile::ReadMatrix32() : Reads the Matrix32 from the BaseFile .
BaseFile::WriteMatrix32() : Writes the Matrix32 to the BaseFile .
BaseFile::ReadMatrix64() : Reads the Matrix64 from the BaseFile .
BaseFile::WriteMatrix64() : Writes the Matrix64 to the BaseFile .

// This example writes the Matrix into a new BaseFile. AutoAlloc<BaseFile> bf; if (bf == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// open BaseFile to write if (bf-> Open (filename, FILEOPEN::WRITE , FILEDIALOG::ANY )) { bf-> WriteMatrix64 (matrix); bf-> 关闭 (); }

// This example reads a Matrix form the given BaseFile. AutoAlloc<BaseFile> bf; if (bf == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// open BaseFile to read if (bf-> Open (filename, FILEOPEN::READ , FILEDIALOG::ANY )) { 矩阵 matrix; bf-> ReadMatrix64 (&matrix);

HyperFile::ReadMatrix() : Reads the 矩阵从 HyperFile .
HyperFile::WriteMatrix() : Writes the 矩阵到 HyperFile .
HyperFile::ReadMatrix32() : Reads the Matrix32 from the HyperFile .
HyperFile::WriteMatrix32() : Writes the Matrix32 to the HyperFile .
HyperFile::ReadMatrix64() : Reads the Matrix64 from the HyperFile .
HyperFile::WriteMatrix64() : Writes the Matrix64 to the HyperFile .

// This example writes the Matrix into a new HyperFile. AutoAlloc<HyperFile> hf; if (hf == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// open HyperFile to write if (hf-> Open ( 'matr' , filename, FILEOPEN::WRITE , FILEDIALOG::ANY )) { hf-> WriteMatrix (matrix); hf-> 关闭 (); }

// This example reads a Matrix from the given HyperFile. AutoAlloc<HyperFile> hf; if (hf == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// open HyperFile to read if (hf-> Open ( 'matr' , filename, FILEOPEN::READ , FILEDIALOG::ANY )) { 矩阵 matrix; hf-> ReadMatrix (&matrix);

另请参阅 BaseFile Manual on 矩阵 and HyperFile Manual on 矩阵 .

Utility Functions

Several utility functions can be used to easily create matrices:

MatrixMove() : Creates a translation matrix.
MatrixScale() : Creates a scaling matrix.
MatrixRotX() : Creates a rotation matrix on the X axis.
MatrixRotY() : Creates a rotation matrix on the Y axis.
MatrixRotZ() : Creates a rotation matrix on the Z axis.

Matrices also represent rotations. Several functions can be used to change and obtain the rotation stored in a matrix:

MatrixToHPB() : Calculates Euler angles from the given 矩阵
Matrix64ToHPB() : Calculates Euler angles from the given Matrix64 .
HPBToMatrix() : Constructs a matrix from Euler angles.
LHPBToMatrix() : A double precision version of HPBToMatrix() .
MatrixToRotAxis() : Calculates rotation axis and angle from a matrix.
RotAxisToMatrix() : Calculates matrix from rotation axis and angle.

注意: Rotations are represented by vectors, see also Vector Manual (Classic) .

Matrix utility:

RebuildMatrix() : Recalculates a matrix making it orthogonal if one or more of its vectors is collapsed

// This example creates a rotation matrix based on a direction vector // and applies it to the given object. const 向量 vec { 100, 100, 100 }; const 向量 rotation = VectorToHPB (vec); const 矩阵 mg = HPBToMatrix (rotation, ROTATIONORDER::DEFAULT ); object ->SetMg(mg);

延伸阅读

BaseFile::Close

Bool Close()

BaseDocument::InsertObject

void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)

HyperFile::WriteMatrix

Bool WriteMatrix(const Matrix &v)

Matrix HPBToMatrix(const Vector &hpb, ROTATIONORDER rot_order)

Vector VectorToHPB(const Vector &p)

定义： c4d_baseobject.h:224

maxon::Mat3< maxon::Vector64 >

定义： lib_description.h:327

FILEDIALOG::ANY

@ ANY

Show an error dialog for any error.

DTYPE_SUBCONTAINER

@ DTYPE_SUBCONTAINER

Sub-container.

定义： lib_description.h:58

BaseFile::WriteMatrix64

Bool WriteMatrix64(const Matrix64 &v)

定义： string.h:1197

GeData::GetMatrix

const Matrix & GetMatrix(void) const

定义： c4d_gedata.h:457

BaseObject::SetMg

void SetMg(const Matrix &m)

定义： c4d_baseobject.h:488

@ DTYPE_MATRIX

矩阵

定义： lib_description.h:71

#define Ocube

Cube.

定义： ge_prepass.h:1040

MAXON_SOURCE_LOCATION

#define MAXON_SOURCE_LOCATION

定义： memoryallocationbase.h:66

Bool Open(const Filename &name, FILEOPEN mode=FILEOPEN::READ, FILEDIALOG error_dialog=FILEDIALOG::IGNOREOPEN, BYTEORDER order=BYTEORDER::V_MOTOROLA, Int32 type='C4DC', Int32 creator='C4D1')

#define ID_USERDATA

User data ID.

定义： lib_description.h:25

HyperFile::Open

Bool Open(Int32 ident, const Filename &filename, FILEOPEN mode, FILEDIALOG error_dialog)

#define Osphere

Sphere.

定义： ge_prepass.h:1041

BaseFile::ReadMatrix64

Bool ReadMatrix64(Matrix64 *v)

ROTATIONORDER::DEFAULT

@ DEFAULT

Default order (HPB).

FILEOPEN::WRITE

@ WRITE

HyperFile::ReadMatrix

Bool ReadMatrix(Matrix *v)

maxon::Vec3< maxon::Float64, 1 >

Represents a level within a DescID.

定义： lib_description.h:286

定义： c4d_gedata.h:82

maxon::Int32 Int32

定义： ge_sys_math.h:58

ApplicationOutput

#define ApplicationOutput(formatString,...)

定义： debugdiagnostics.h:207

Matrix MatrixMove(const Vector &t)

@ READ

Open the file for reading.

BaseObject::Alloc

static BaseObject * Alloc(Int32 type)

HyperFile::Close

Bool Close()

maxon::Mat3::off

V off

The translation vector.

定义： matrix.h:279

定义： ge_autoptr.h:36

DESCFLAGS_GET::NONE

@ NONE

None.

C4DAtom::GetParameter

Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)