Vector Manual (Classic)

A vector is a structure composed of three floating-point values. Such a vector is typically used to represent a position in 3D space, a direction, normals, a rotation or a color value.

The vector classes available:

Warning
A description of MAXON API vector classes can also be found here: Vectors. The MAXON API also includes dedicated classes for colors like maxon::Color.
// This example reads the position of the points of the given spline object
// and creates null objects at these positions.
const Vector* const splinePoints = spline->GetPointR();
const Int32 splinePointCount = spline->GetPointCount();
const Matrix splineMg = spline->GetMg();
for (Int i = 0; i < splinePointCount; ++i)
{
BaseObject* const nullObj = BaseObject::Alloc(Onull);
if (nullObj && splinePoints)
{
// get world space position
const Vector worldSpacePoint = splineMg * splinePoints[i];
Matrix mg;
mg.off = worldSpacePoint;
nullObj->SetMg(mg);
doc->InsertObject(nullObj, nullptr, nullptr);
}
else
{
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
}
}
Py_ssize_t i
Definition: abstract.h:645
Definition: c4d_baseobject.h:225
void SetMg(const Matrix &m)
Definition: c4d_baseobject.h:488
static BaseObject * Alloc(Int32 type)
maxon::Int32 Int32
Definition: ge_sys_math.h:60
maxon::Int Int
Definition: ge_sys_math.h:64
#define Onull
Null.
Definition: ge_prepass.h:1062
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
const char * doc
Definition: pyerrors.h:226
V off
The translation vector.
Definition: matrix.h:263

# Access

Vector objects can be created on demand or can be obtained from other entities.

Access Vector objects stored in a BaseContainer:

Access Vector objects stored in a GeData object (GeData type is DA_VECTOR):

Vectors are also the building blocks of Matrix objects. Especially the `off` component of a Matrix is often accessed:

Vectors are used to represent the position of points of a PointObject like a SplineObject or PolygonObject:

In a GeDialog the float values of three gadgets can be read as a Vector:

// This example reads the "Size" parameter of the given Cube object.
GeData data;
if (cube->GetParameter(DescID { PRIM_CUBE_LEN }, data, DESCFLAGS_GET::NONE))
{
const Vector size = data.GetVector();
ApplicationOutput("Cube Size: @"_s, size);
}
Definition: lib_description.h:330
Definition: c4d_gedata.h:83
const Vector & GetVector(void) const
Definition: c4d_gedata.h:451
Py_ssize_t size
Definition: bytesobject.h:86
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210

# Components

A Vector is made up of three components, which can be accessed directly:

Alternatively the subscript operator can be used:

// This example reads the color of the given material
// and converts the components to integer values.
GeData data;
if (mat->GetParameter(DescID { MATERIAL_COLOR_COLOR }, data, DESCFLAGS_GET::NONE))
{
const Vector color = data.GetVector();
// convert to 0 - 255 integer
const Int32 colorR = SAFEINT32(color.x * COLORTOINT_MULTIPLIER);
const Int32 colorG = SAFEINT32(color.y * COLORTOINT_MULTIPLIER);
const Int32 colorB = SAFEINT32(color.z * COLORTOINT_MULTIPLIER);
ApplicationOutput("Color: @ : @ : @"_s, colorR, colorG, colorB);
}
static const Float COLORTOINT_MULTIPLIER
Constant to convert from vectors color components to integers.
Definition: c4d_tools.h:25
Int32 SAFEINT32(Float32 x)
Definition: apibasemath.h:266
T y
Definition: vec.h:40
T x
Definition: vec.h:39
T z
Definition: vec.h:41

# Vector Maths

## Vector Properties

Several functions are available to calculate properties of a Vector object:

// This example compares the distance of one object to two other objects.
const Matrix mgA = objectA->GetMg();
const Matrix mgB = objectB->GetMg();
const Matrix mgC = objectC->GetMg();
const Vector AB = mgB.off - mgA.off;
const Vector AC = mgC.off - mgA.off;
const Float sqrDistanceAB = AB.GetSquaredLength();
const Float sqrDistanceAC = AC.GetSquaredLength();
const maxon::String objAName { objectA->GetName() };
const maxon::String objBName { objectB->GetName() };
const maxon::String objCName { objectC->GetName() };
if (sqrDistanceAB > sqrDistanceAC)
ApplicationOutput("Object @ is closer to object @ than object @"_s, objAName, objCName, objBName);
else
ApplicationOutput("Object @ is closer to object @ than object @"_s, objAName, objBName, objCName);
Definition: string.h:1235
maxon::Float Float
Definition: ge_sys_math.h:66
constexpr T GetSquaredLength() const
Returns the squared length of the vector.
Definition: vec.h:466

## Vector Operators

Basic mathematical operations to handle vectors and vectors with scalars are implemented as operators:

## Vector Normalization

// This example normalizes the given vector.
const Vector vec { 10, 20, 30 };
const Vector normalized = vec.GetNormalized();
ApplicationOutput("Vector: @ / Normalized Vector: @"_s, vec, normalized);
Unstrided GetNormalized() const
Returns a normalized vector, so that GetLength(vector)==1.0.
Definition: vec.h:472

## Vector Operations

Basic vector based mathematical operations are available as global functions:

Note
To calculate the normal of a polygon use CalcFaceNormal().
// This example calculates the angle between the given vectors.
const Vector a { 100, 0, 0 };
const Vector b { 100, 100, 0 };
const Float angle = GetAngle(a, b);
const String formattedString = FormatNumber(angle, FORMAT_DEGREE, 0);
ApplicationOutput("Angle: @"_s, maxon::String { formattedString });
String FormatNumber(const GeData &val, Int32 format, Int32 fps, Bool bUnit=true)
Definition: c4d_string.h:39
@ FORMAT_DEGREE
Floating point with degree sign. Measured in radians, displayed in degrees.
Definition: c4d_gui.h:47

## Zero

These functions an be used to check if the components of a vector are zero:

# Compare

Two vectors can be compared using a dedicated function or the usual operators:

• Vector::IsEqual(): Compares the given vectors component-wise using the given epsilon.
• Vector::operator==(): Returns true if the given vectors are equal or if the components equal the given scalar.
• Vector::operator!=(): Returns true if the given vectors are not equal or if the components are not equal to the given scalar.
Note
For safe comparison of floating point values see Compare.

# Disc I/O

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

// This example writes the Vector into a new BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to write
{
bf->WriteVector64(vector);
bf->Close();
}
PyCompilerFlags const char * filename
Definition: ast.h:15
Definition: ge_autoptr.h:37
@ ANY
Show an error dialog for any error.
// This example reads a Vector from the given BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
{
Vector vector;
// This example writes the Vector into a new HyperFile.
if (hf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open HyperFile to write
if (hf->Open('vect', filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
{
hf->WriteVector(vector);
hf->Close();
}
// This example reads a Vector from the given HyperFile.
if (hf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
{
Vector vector;

# Utility Functions

Further utility functions are available:

• ReflectRay(): Returns the ray vector after a reflection on a surface normal.
• String::VectorToString(): Converts the given vector to a string.
• GetOptimalAngle(): Returns the optimal angle so that the "distance" of the given new rotation to the old rotation is at minimum.
• VectorToHPB(): Calculates Euler angles from a direction vector.

# Color Functions

The Vector class is also used to represent colors in different color spaces:

• RGBToHSV(): Converts a RGB color value into the HSV color space.
• HSVToRGB(): Converts a HSV color value into the RGB color space.
• RGBToHSL(): Converts a RGB color value into the HSL color space.
• HSLtoRGB(): Converts a HSL color value into the RGB color space.