Vector Manual (Classic)

About

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:

See also Primitive Data Types Manual (Classic).

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:248
void SetMg(const Matrix &m)
Definition: c4d_baseobject.h:516
static BaseObject * Alloc(Int32 type)
maxon::Int32 Int32
Definition: ge_sys_math.h:56
maxon::Int Int
Definition: ge_sys_math.h:60
#define Onull
Null.
Definition: ge_prepass.h:1078
#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:

See also BaseContainer Manual.

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

See also GeData Manual.

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

See also Matrix Manual (Classic).

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;
// read "Size" parameter
if (cube->GetParameter(ConstDescID(DescLevel(PRIM_CUBE_LEN)), data, DESCFLAGS_GET::NONE))
{
const Vector size = data.GetVector();
ApplicationOutput("Cube Size: @"_s, size);
}
Definition: c4d_gedata.h:83
const Vector & GetVector() const
Definition: c4d_gedata.h:486
Py_ssize_t size
Definition: bytesobject.h:86
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
#define ConstDescID(...)
Definition: lib_description.h:594
@ PRIM_CUBE_LEN
Definition: ocube.h:6
Represents a level within a DescID.
Definition: lib_description.h:298

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;
// read "Color" parameter
{
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:275
@ MATERIAL_COLOR_COLOR
Definition: mmaterial.h:56
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:1237
maxon::Float Float
Definition: ge_sys_math.h:62
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:41
@ FORMAT_DEGREE
Floating point with degree sign. Measured in radians, displayed in degrees.
Definition: c4d_gui.h:48

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);
// open BaseFile to read
{
Vector vector;
bf->ReadVector64(&vector);
@ READ
Open the file for reading.
// 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);
// open HyperFile to read
if (hf->Open('vect', filename, FILEOPEN::READ, FILEDIALOG::ANY))
{
Vector vector;
hf->ReadVector(&vector);

See also BaseFile Manual on Vector and HyperFile Manual on 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.

See also Color Functions Manual.

Further Reading