Matrix Manual (Classic)

About

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 elements.
  • Matrix64: A matrix composed of Vector64 elements.
  • Matrix: Defined as Matrix64.

See also Vector Manual (Classic).

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

Access

To retrieve and modify Matrix 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 Matrix objects stored in a BaseContainer respectively use:

See also BaseContainer Manual.

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

See also GeData Manual.

// This example reads a Matrix userdata parameter from the given object
// and creates a new cube using that Matrix.
GeData data;
// read the user data parameter 1
if (object->GetParameter(id, data, DESCFLAGS_GET::NONE))
{
const Matrix mg = data.GetMatrix();
if (cube != nullptr)
{
cube->SetMg(mg);
doc->InsertObject(cube, nullptr, nullptr);
}
}

Components

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 Matrix 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 Vector* const points = pointObject->GetPointR();
const Int32 pointCount = pointObject->GetPointCount();
const Matrix mg = pointObject->GetMg();
for (Int32 i = 0; i < pointCount; ++i)
{
if (points)
{
const Vector point = points[i];
const Vector worldSpacePosition = mg * point;
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:

// This example calculates the position of objectB in the local space of objectA.
const Matrix mgA = objectA->GetMg();
const Matrix inverse = ~mgA;
const Vector worldSpacePos = objectB->GetMg().off;
const Vector 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);

Compare

Two matrices can be compared using the usual operators:

Note
For save comparison of floating point values see Compare.

Disc I/O

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

// This example writes the Matrix into a new BaseFile.
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->Close();
}
// This example reads a Matrix form the given BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to read
if (bf->Open(filename, FILEOPEN::READ, FILEDIALOG::ANY))
{
Matrix matrix;
bf->ReadMatrix64(&matrix);
// This example writes the Matrix into a new HyperFile.
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->Close();
}
// This example reads a Matrix from the given HyperFile.
if (hf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open HyperFile to read
if (hf->Open('matr', filename, FILEOPEN::READ, FILEDIALOG::ANY))
{
Matrix matrix;
hf->ReadMatrix(&matrix);

See also BaseFile Manual on Matrix and HyperFile Manual on Matrix.

Utility Functions

Several utility functions can be used to easily create matrices:

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

Note
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 Vector vec { 100, 100, 100 };
const Vector rotation = VectorToHPB(vec);
const Matrix mg = HPBToMatrix(rotation, ROTATIONORDER::DEFAULT);
object->SetMg(mg);

Further Reading

BaseFile::Close
Bool Close()
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
HyperFile::WriteMatrix
Bool WriteMatrix(const Matrix &v)
HPBToMatrix
Matrix HPBToMatrix(const Vector &hpb, ROTATIONORDER rot_order)
VectorToHPB
Vector VectorToHPB(const Vector &p)
BaseObject
Definition: c4d_baseobject.h:224
maxon::Mat3< maxon::Vector64 >
DescID
Definition: lib_description.h:328
FILEDIALOG::ANY
@ ANY
Show an error dialog for any error.
DTYPE_SUBCONTAINER
@ DTYPE_SUBCONTAINER
Sub-container.
Definition: lib_description.h:58
BaseFile::WriteMatrix64
Bool WriteMatrix64(const Matrix64 &v)
maxon::String
Definition: string.h:1213
GeData::GetMatrix
const Matrix & GetMatrix(void) const
Definition: c4d_gedata.h:457
BaseObject::SetMg
void SetMg(const Matrix &m)
Definition: c4d_baseobject.h:488
DTYPE_MATRIX
@ DTYPE_MATRIX
Matrix
Definition: lib_description.h:71
Ocube
#define Ocube
Cube.
Definition: ge_prepass.h:1047
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
BaseFile::Open
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')
ID_USERDATA
#define ID_USERDATA
User data ID.
Definition: lib_description.h:25
HyperFile::Open
Bool Open(Int32 ident, const Filename &filename, FILEOPEN mode, FILEDIALOG error_dialog)
Osphere
#define Osphere
Sphere.
Definition: ge_prepass.h:1048
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 >
DescLevel
Represents a level within a DescID.
Definition: lib_description.h:287
GeData
Definition: c4d_gedata.h:82
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
MatrixMove
Matrix MatrixMove(const Vector &t)
FILEOPEN::READ
@ 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.
Definition: matrix.h:279
AutoAlloc
Definition: ge_autoptr.h:36
DESCFLAGS_GET::NONE
@ NONE
None.
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)