c4d.Vector¶

class c4d.Vector¶

Single precision vector mathematics.

A vector class represents a point, a color, a direction, an HPB-angle or a simple coordinate in a 3D space using the Cartesian
coordinates x, y and z. The values are stored in the members x, y and z.

For example, positions are stored in the order (X position; Y position; Z position) and rotations in the order (H angle; P angle; B angle).

Cinema 4D also uses vectors to store colors and their values of an RGB (Red, Green, Blue) color model.
The vector class can also represent a direction, an arrow pointing from the origin of the coordinates, such as (0,0,0), to an endpoint3.

Note

Cinema 4D uses a left-handed coordinate system.

Warning

The Vector type does not support the function copy.copy(), please use the Vector copy constructor instead.

>>> import c4d
>>> import copy

>>> # A vector and its Python object id.
>>> vec = c4d.Vector(1)
>>> id(vec), vec
(1331515356992, Vector(1, 1, 1))

>>> # We are only creating a reference to the same object.
>>> ref = vec
>>> id(ref), ref
(1331515356992, Vector(1, 1, 1))

>>> # Cinema's types usually do not work with Python's copy module.
>>> copy.deepcopy(vec)
...
TypeError: can't pickle c4d.Vector objects.

>>> # But we can copy objects via copy constructors.
>>> copy = c4d.Vector(vec)
>>> id(copy), copy
(1331515387904, Vector(1, 1, 1))

Attributes

c4d.Vector.x¶

X component of the vector.

Type: float

c4d.Vector.y¶

Y component of the vector.

Type: float

c4d.Vector.z¶

Z component of the vector.

Type: float

Overview¶

Vector.GetDistance()

Retrieve the distance between two vectors.

Comparison And State
`Vector.GetHashCode()`	Returns the hash code of the vector used for hash maps and comparisons.
`Vector.IsEqual()`	Tests component-wise if the difference is no bigger than ‘epsilon’.
`Vector.IsZero()`	Checks if each component is zero.
`Vector.SetZero()`	Sets all components to zero.
Component Aggregates
`Vector.GetAverage()`	Calculates the average value of ‘x’, ‘y’ and ‘z’.
`Vector.GetMax()`	Returns the maximum of ‘x’, ‘y’ and ‘z’.
`Vector.GetMin()`	Returns the minimum of ‘x’, ‘y’ and ‘z’.
`Vector.GetSum()`	Calculates the sum of ‘x’, ‘y’ and ‘z’.
Component Operations
`Vector.Abs()`	Returns the vector with absolute value for each entry
`Vector.Clamp01()`	Returns a vector that is clamped to the range [0.0 .. 1.0].
`Vector.ClampMax()`	Set the maximum of each component.
`Vector.ClampMin()`	Set the minimum of each component.
`Vector.Max()`	Calculates the maximum of each component.
`Vector.Min()`	Calculates the minimum of each component.
`Vector.SetMax()`	Set the maximum of each component.
`Vector.SetMin()`	Set the minimum of each component.
Magic Methods
`Vector.__abs__()`	Returns a vector with the absolute (positive) value of each component.
`Vector.__add__()`	Adds an operand to the vector.
`Vector.__del__()`	Not implemented.
`Vector.__div__()`	Divides each vector component by a scalar.
`Vector.__eq__()`	Checks if two vectors are equal.
`Vector.__ge__()`	Not implemented.
`Vector.__getitem__()`	Retrieves the value of the x, y or z component of the vector.
`Vector.__gt__()`	Not implemented.
`Vector.__hash__()`	Returns the hash code of the vector used for hash maps and comparisons.
`Vector.__init__()`	Initializes a new `Vector`.
`Vector.__invert__()`	Returns the normalized vector.
`Vector.__le__()`	Not implemented.
`Vector.__lt__()`	Not implemented.
`Vector.__mod__()`	Calculates the cross product of the vector and an operand.
`Vector.__mul__()`	Calculates the product of the vector and an left-side operand.
`Vector.__ne__()`	Check if two vectors are not equal.
`Vector.__neg__()`	Returns the inverse of the vector.
`Vector.__radd__()`	Adds the vector to an operand.
`Vector.__rdiv__()`	Not implemented.
`Vector.__rmul__()`	Calculates the product of the vector and a right-side operand.
`Vector.__rsub__()`	Subtracts the vector from an operand.
`Vector.__rxor__()`	Not implemented.
`Vector.__setitem__()`	Assigns a value to the x, y or z component of the vector.
`Vector.__str__()`	Returns a string representation of the vector.
`Vector.__sub__()`	Subtracts an operand from the vector.
`Vector.__xor__()`	Calculates an alternative product operation of the vector and a left-side operand.
Magnitude And Normalization
`Vector.GetLength()`	Calculates the length of the vector.
`Vector.GetLengthSquared()`	Calculates the squared length of the vector.
`Vector.GetNormalized()`	Calculates the normalized vector, so that `GetLength()` returns 1.0.
`Vector.GetSquaredLength()`	Returns the squared length of the vector.
`Vector.Normalize()`	Normalizes the vector, so that `GetLength()` returns 1.0.
Spatial Operations
`Vector.Cross()`	Calculates the cross product of the vector and vector v2.
`Vector.Dot()`	Calculates the dot product of the vector and vector v2.
`Vector.GetAngle()`	Calculates angle (in radians) between v1 and v2.
`Vector.GetRightRotated()`	Returns a vector where the components have been rotated to the right (in the usual (x, y, z)-representation).

Members¶

Spatial Operations¶

static Vector.GetDistance(v1, v2)¶

Retrieve the distance between two vectors.

Parameters

v1 (c4d.Vector) – The first vector.
v2 (c4d.Vector) – The second vector.

Returns

the distance from v1 to v2.

Return type

float

Comparison And State¶

Vector.GetHashCode(self)¶

Returns the hash code of the vector used for hash maps and comparisons.

New in version R26.

Returns: The vector’s hash code.
Return type: int

Vector.IsEqual(self, other, epsilon)¶

Tests component-wise if the difference is no bigger than ‘epsilon’.

New in version R26.

Parameters

other (c4d.Vector) – The other vector to test.
epsilon (float) – The threshold value.

Returns

True if other is in the range of epsilon, False otherwise.

Return type

bool

Vector.IsZero(self, epsilon=1e-10)¶

Checks if each component is zero.

New in version R26.

Parameters: epsilon (float) – The threshold value.
Returns: False if one or more component are bigger than epsilon, otherwise True.
Return type: bool

Vector.SetZero(self)¶: Sets all components to zero.

New in version R26.

Component Aggregates¶

Vector.GetAverage(self)¶

Calculates the average value of ‘x’, ‘y’ and ‘z’.

New in version R26.

Returns: The average value of ‘x’, ‘y’ and ‘z’.
Return type: float

Vector.GetMax(self)¶

Returns the maximum of ‘x’, ‘y’ and ‘z’.

New in version R26.

Returns: A new float with the maximum of ‘x’, ‘y’ and ‘z’.
Return type: float

Vector.GetMin(self)¶

Returns the minimum of ‘x’, ‘y’ and ‘z’.

New in version R26.

Returns: A new float with the minimum of ‘x’, ‘y’ and ‘z’.
Return type: float

Vector.GetSum(self)¶

Calculates the sum of ‘x’, ‘y’ and ‘z’.

New in version R26.

Returns: The sum value of ‘x’, ‘y’ and ‘z’.
Return type: float

Component Operations¶

Vector.Abs(self)¶

Returns the vector with absolute value for each entry

New in version R26.

Returns: A new absolute vector.
Return type: c4d.Vector

Vector.Clamp01(self)¶

Returns a vector that is clamped to the range [0.0 .. 1.0].

New in version R26.

Returns: The clamped vector.
Return type: c4d.Vector

Vector.ClampMax(self, other)¶

Set the maximum of each component.

New in version R26.

Parameters: other (c4d.Vector) – The maximum value of ‘x’, ‘y’ and ‘z’.

Vector.ClampMin(self, other)¶

Set the minimum of each component.

New in version R26.

Parameters: other (c4d.Vector) – The minimum value of ‘x’, ‘y’ and ‘z’.

Vector.Max(self, other)¶

Calculates the maximum of each component.

New in version R26.

Parameters: other (c4d.Vector) – The other vector.
Returns: The vector containing the maximum of each component.
Return type: c4d.Vector

Vector.Min(self, other)¶

Calculates the minimum of each component.

New in version R26.

Parameters: other (c4d.Vector) – The other vector.
Returns: The vector containing the minimum of each component.
Return type: c4d.Vector

Vector.SetMax(self, other)¶

Set the maximum of each component.

New in version R26.

Parameters: other (c4d.Vector) – The other vector.

Vector.SetMin(self, other)¶

Set the minimum of each component.

New in version R26.

Parameters: other (c4d.Vector) – The other vector.

Magic Methods¶

Vector.__abs__(self)¶

Returns a vector with the absolute (positive) value of each component.

>>> abs(c4d.Vector(-1, -2, -3))
Vector(1,2,3)

Return type: c4d.Vector
Returns: The absolute vector.

Vector.__add__(self, other)¶

Adds an operand to the vector.

>>> c4d.Vector(1, 2, 3) + 1
Vector(2,3,4)

>>> c4d.Vector(1, 2, 3) + c4d.Vector(2, 3, 4)
Vector(3,5,7)

Parameters: other (Union[c4d.Vector, int, float]) – The other operand.
Return type: c4d.Vector
Returns: The resulting vector.

Vector.__del__(self)¶

Not implemented.

Note

The Vector does not support item deletion, e.g., by calling del(v[0]).

Raise: TypeError.

Vector.__div__(self, other)¶

Divides each vector component by a scalar.

>>> c4d.Vector(1, 2, 3) / 5
Vector(0.2, 0.4, 0.6)

Parameters: other (Union[int, float]) – The other operand.
Return type: c4d.Vector
Returns: The resulting vector.

Vector.__eq__(self, other)¶

Checks if two vectors are equal.

Parameters: other (c4d.Vector) – The other vector.
Return type: bool
Returns: True if both vectors are equal.

Vector.__ge__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__getitem__(self, key)¶

Retrieves the value of the x, y or z component of the vector.

The component is identified by an index in the interval [0, 2].

New in version R14.014.

>>> v = c4d.Vector(1, 2, 3)
>>> v[0]
1.0
>>> v[1]
2.0
>>> v[2]
3.0

Parameters: key (int) – The component index.
Raises: IndexError – When key does not satisfy 0 <= key < 2.
Return type: float
Returns: The vector component.

Vector.__gt__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__hash__(self)¶

Returns the hash code of the vector used for hash maps and comparisons.

New in version R26.

Returns: The vector’s hash code.
Return type: int

Vector.__init__(self, x=0.0, y=0.0, z=0.0)¶

Initializes a new Vector.

All arguments are optional so it is possible to create a new vector without any arguments. All components are simply 0.
Otherwise x can be a Vector so all components of the passed vector will be copied to the new vector.
If only a number is passed, all components will be set to this.

>>> c4d.Vector()
Vector(0,0,0)

>>> c4d.Vector(100)
Vector(100,100,100)

>>> v = c4d.Vector(100, 100, 100)
>>> c4d.Vector(v)
Vector(100,100,100)

>>> c4d.Vector(1, 2, 3)
Vector(1,2,3)

Parameters

x (Optional[Union[int, float, c4d.Vector]]) – If x is a number and is the only passed argument, set this to all components. If x is a vector, clone it. Otherwise set the X component.
y (Optional[Union[int, float]]) – Set the Y component.
z (Optional[Union[int, float]]) – Set the Z component.

Vector.__invert__(self)¶

Returns the normalized vector.

>>> ~c4d.Vector(1, 2, 3)
Vector(0.267,0.535,0.802)

Return type: c4d.Vector
Returns: The normalized vector.

Vector.__le__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__lt__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__mod__(self, other)¶

Calculates the cross product of the vector and an operand.

>>> c4d.Vector(1, 0, 0) % c4d.Vector(0, 1, 0)
Vector(0, 0, 1)

Parameters: other (c4d.Vector) – The other operand.
Return type: c4d.Vector
Returns: The resulting vector.

Vector.__mul__(self, other)¶

Calculates the product of the vector and an left-side operand.

If other is a float, it multiplies each vector component by the scalar.
If other is a vector, calculates the dot product of the vectors.
If other is a matrix, the vector is transformed by it, including translations.

See also

Vector.__xor__() is the operator implementation for alternative product operations.

>>> u = c4d.Vector(1, 0, 0)
>>> v = c4d.Vector(2, 0, 0)

>>> # A transform rotating by 90° ccw and translating by 100 units on v3 (i.e., the 
>>> # z-axis, the basis vector k).
>>> M = c4d.Matrix(v1=c4d.Vector( 0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector( 0, 0, 1),
                   off=c4d.Vector(0, 0, 100))

>>> # Calculates the dot product of u and v.
>>> u * v
2.0

>>> # Scales u by the factor of 5.
>>> u * 5.
Vector(5, 0, 0)

>>> # Transforms u by M, including translations.
>>> u * M
Vector(0, 1, 100)

Parameters: other (Union[int, float, c4d.Vector, c4d.Matrix]) – The other operand.
Return type: Union[c4d.Vector, float]
Returns: A float, if other is of type Vector. | A vector, if other is of type float or Matrix.

Vector.__ne__(self, other)¶

Check if two vectors are not equal.

Parameters: other (c4d.Vector) – The other vector.
Return type: bool
Returns: True if both vectors are not equal.

Vector.__neg__(self)¶

Returns the inverse of the vector.

>>> -c4d.Vector(1, 2, 3)
Vector(-1,-2,-3)

Return type: c4d.Vector
Returns: The inverse vector.

Vector.__radd__(self, other)¶

Adds the vector to an operand.

>>> 1 + c4d.Vector(1, 2, 3)
Vector(2,3,4)

>>> c4d.Vector(1, 2, 3) + c4d.Vector(2, 3, 4)
Vector(3,5,7)

Parameters: other (Union[c4d.Vector, int, float]) – The other operand.
Return type: c4d.Vector
Returns: The resulting vector.

Vector.__rdiv__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__rmul__(self, other)¶

Calculates the product of the vector and a right-side operand.

If other is a float, it multiplies each vector component by the scalar.
If other is a matrix, the vector is transformed by it, including translations.

>>> u = c4d.Vector(1, 0, 0)
>>> v = c4d.Vector(2, 0, 0)

>>> # A transform rotating by 90° ccw and translating by 100 units on v3 (i.e., the 
>>> # z-axis, the basis vector k).
>>> M = c4d.Matrix(v1=c4d.Vector( 0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector( 0, 0, 1),
                   off=c4d.Vector(0, 0, 100))

>>> # Calculates the dot product of u and v.
>>> u * v
2.0

>>> # Scales u by the factor of 5.
>>> 5. * u
Vector(5, 0, 0)

>>> # Transforms u by M, including translations.
>>> M * u
Vector(0, 1, 100)

Parameters: other (Union[int, float, c4d.Vector, c4d.Matrix]) – The other operand.
Return type: Union[c4d.Vector, float]
Returns: A float, if other is of type Vector. | A vector, if other is of type float or Matrix.

Vector.__rsub__(self, other)¶

Subtracts the vector from an operand.

>>> 1 - c4d.Vector(1, 2, 3)
Vector(0,-1,-2)

>>> c4d.Vector(1, 2, 3) - c4d.Vector(2, 3, 4)
Vector(-1,-1,-1)

Parameters: other (Union[c4d.Vector, int, float]) – The other operand.
Return type: c4d.Vector
Returns: The resulting vector.

Vector.__rxor__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__setitem__(self, key, value)¶

Assigns a value to the x, y or z component of the vector.

The component is identified by an index in the interval [0, 2].

New in version R14.014.

>>> v = c4d.Vector(1, 2, 3)
>>> v[0] = 0
>>> v
Vector(0, 2, 3)

Parameters

key (int) – The component index.
value (Union[float, int]) – The new vector component.

Raises

IndexError – When key does not satisfy 0 <= key < 2.

Vector.__str__(self)¶

Returns a string representation of the vector.

Called if str() is invoked on a vector object. See object.__str__() for more information on Python’s data model.

>>> c4d.Vector(30, 40, 2)
Vector(30.0, 40.0, 2.0)

Return type: str
Returns: The Vector as string.

Vector.__sub__(self, other)¶

Subtracts an operand from the vector.

>>> c4d.Vector(1, 2, 3) - 1
Vector(0,1,2)

c4d.Vector(1, 2, 3) - c4d.Vector(2, 3, 4)
Vector(-1,-1,-1)

Parameters: other (Union[c4d.Vector, int, float]) – The other operand.
Return type: c4d.Vector
Returns: The resulting vector.

Vector.__xor__(self, other)¶

Calculates an alternative product operation of the vector and a left-side operand.

If other is a vector, calculates the component-wise product of the vectors.
If other is a matrix, the vector is transformed by it, excluding translations.

Magnitude And Normalization¶

Vector.GetLength(self)¶

Calculates the length of the vector.

Return type: float
Returns: The length.

Vector.GetLengthSquared(self)¶

Calculates the squared length of the vector.

Deprecated since version R26.000: Use Vector.GetSquaredLength() instead.

Return type: float
Returns: The squared length.

Vector.GetNormalized(self)¶

Calculates the normalized vector, so that GetLength() returns 1.0.

Return type: c4d.Vector
Returns: The normalized vector.

Vector.GetSquaredLength(self)¶

Returns the squared length of the vector.

New in version R26.

Returns: The squared length of the vector.
Return type: float

Vector.Normalize(self)¶: Normalizes the vector, so that GetLength() returns 1.0.

Spatial Operations¶

Vector.Cross(self, v2)¶

Calculates the cross product of the vector and vector v2.

Parameters: v2 (c4d.Vector) – The other vector.
Return type: c4d.Vector
Returns: The result.

Vector.Dot(self, v2)¶

Calculates the dot product of the vector and vector v2.

Parameters: v2 (c4d.Vector) – The second vector.
Return type: float
Returns: The dot product.

Vector.GetAngle(self, other)¶

Calculates angle (in radians) between v1 and v2.

New in version R26.

Parameters: other (c4d.Vector) – The other vector.
Returns: The angle.
Return type: float

Vector.GetRightRotated(self, rots)¶

Returns a vector where the components have been rotated to the right (in the usual (x, y, z)-representation). E.g., with a value of 1 for rots, the result will be (z, x, y).

New in version R26.

Parameters: rots (int) – Number of rotations, may be negative. The result depends only on the number modulo 3.
Returns: A new rotated vector.
Return type: c4d.Vector

Category	Option	Description
Query	Words and phrases	Search is case-insensitive. Put a phrase in quotes for an exact match. Quoted phrases require every word and disable fuzzy matching.
Terms	OR / AND	Choose whether to match any term or require all terms.
Fuzzy	On / Off	Toggle approximate and prefix matches. Quoted phrases always use strict matching.
Results	Sparse / Dense	Sparse groups multiple hits for one entity and hides its owned API members when the class or module itself matches. Dense lists each match separately.
Sort by	Type / Relevance	Group results by entity type then rank within each group, or rank all results by relevance.
Content	All / API / Manuals / Examples / Resources	Search all documentation, API documentation, manuals, the examples index, or the resources index. Code examples embedded in other sections retain their own content area.
Entity	All / Page / Module / Class / Function / Attribute / Description / Node / Symbol / Icon	Page covers results without a specific entity type. Resource entity types are available with All or Resources; API entity types are available with All or API.
Location	All / Text / Code / Name / Signature	Text covers everything outside code, names, and signatures. Name and Signature are available with All or API.