Vector Manual (Cinema API)

Table of Contents

• About
• Access
• Components
• Vector Maths
  • Vector Properties
  • Vector Operators
  • Vector Normalization
  • Vector Operations
  • Zero
• Compare
• Disc I/O
• Utility Functions
• Color Functions
• Further Reading

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:

• ::Vector32: A vector composed of ::Float32 values.
• ::Vector64: A vector composed of ::Float64 values.
• ::Vector: Defined as ::Vector64.

See also Primitive Data Types Manual (Cinema API).

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:

• BaseContainer::GetVector(): Returns the ::Vector stored at the given ID.
• BaseContainer::SetVector(): Sets the ::Vector stored at the given ID.

See also BaseContainer Manual.

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

• GeData::GetVector(): Returns the ::Vector object.
• GeData::SetVector(): Stores the ::Vector object.

See also GeData Manual.

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

• Matrix::off: The translation/offset vector.

See also Matrix Manual (Cinema API).

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

• PointObject::GetPointR(): Returns the start of the read-only points array.
• PointObject::GetPointW(): Returns the start of the writeable points array.

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

• GeDialog::GetVector(): Retrieves the value of three float fields at the same time 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);
  }

Components

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

• Vector::x: The x component.
• Vector::y: The y component.
• Vector::z: The z component.

Alternatively the subscript operator can be used:

• Vector::operator[](): Sets a vector component.

  // This example reads the color of the given material
  // and converts the components to integer values.
 
  GeData data;
 
  // read "Color" parameter
  if (mat->GetParameter(ConstDescID(DescLevel(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);
  }

Vector Maths

Vector Properties

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

• Vector::GetAverage(): Calculates the average value of the three components. May be used for a cheap grayscale result.
• Vector::GetSum(): Calculates the sum of the three components.
• Vector::GetMin(): Calculates the minimum value of the three components.
• Vector::GetMax(): Calculates the maximum value of the three components.
• Vector::GetLength(): Calculates the length of the vector.
• Vector::GetSquaredLength(): Calculates the squared length of the vector.

  // 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::operator+=(): Adds a vector to a vector or a scalar to each component.
• Vector::operator-=(): Subtracts a vector from a vector or a scalar from each component.
• Vector::operator*=(): Multiplies each component with the given scalar or the components of the given vector.
• Vector::operator/=(): Divides each component with the given scalar.
• Vector::operator*(): Multiplies each component with the given scalar or the components of the given vector.
• Vector::operator/(): Divides each component with the given scalar.
• Vector::operator+(): Adds a vector to a vector or a scalar to each component.
• Vector::operator-(): Subtracts a vector from a vector or a scalar from each component.

Vector Normalization

• Vector::Clamp01(): Returns the vector clamped to the range [0.0 .. 1.0].
• Vector::GetNormalized(): Calculates the normalized vector.
• Vector::operator!(): Calculates the normalized vector.
• Vector::Normalize(): Normalizes the vector.

    // 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:

• Vector::GetAngle(): Calculates the angle (in radians) between the given vectors.
• Vector::Dot(): Calculates the dot product of the given vectors.
• Vector::Cross(): Calculates the cross product the given vectors.

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:

• Vector::IsZero(): Returns true if all components of the vector are zero.
• Vector::SetZero(): Sets all components of the vector to 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:

• BaseFile::ReadVector32(): Reads a Vector32 from the BaseFile.
• BaseFile::WriteVector32(): Writes a Vector32 to the BaseFile.
• BaseFile::ReadVector64(): Reads a Vector64 from the BaseFile.
• BaseFile::WriteVector64(): Writes a Vector64 to the BaseFile.

  // This example writes the Vector 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->WriteVector64(vector);
    bf->Close();
  }

  // This example reads a Vector from 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))
  {
    Vector vector;
    bf->ReadVector64(&vector);

• HyperFile::ReadVector(): Reads a ::Vector from the HyperFile.
• HyperFile::WriteVector(): Writes a ::Vector to the HyperFile.
• HyperFile::ReadVector32(): Reads a Vector32 from the HyperFile.
• HyperFile::WriteVector32(): Writes a Vector32 to the HyperFile.
• HyperFile::ReadVector64(): Reads a Vector64 from the HyperFile.
• HyperFile::WriteVector64(): Writes a Vector64 to the HyperFile.

  // This example writes the Vector into a new HyperFile.
 
  AutoAlloc<HyperFile> hf;
  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.
 
  AutoAlloc<HyperFile> hf;
  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

• GeData Manual
• BaseContainer Manual
• Primitive Data Types Manual (Cinema API)
• Matrix Manual (Cinema API)