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);
}
}

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
{
const Vector size = data.GetVector();
ApplicationOutput("Cube Size: @"_s, size);
}

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);
}

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);

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);

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));

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)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to write
if (bf->Open(filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
{
bf->WriteVector64(vector);
bf->Close();
}
// This example reads a Vector from the given BaseFile.
if (!bf)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to read
if (bf->Open(filename, FILEOPEN::READ, FILEDIALOG::ANY))
{
Vector vector;
bf->ReadVector64(&vector);
// This example writes the Vector into a new HyperFile.
if (!hf)
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)
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