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

Vector.x¶

X component of the vector.

Type: float

Vector.y¶

Y component of the vector.

Type: float

Vector.z¶

Z component of the vector.

Type: float

Methods Signatures

`Vector.__init__()`	Initializes a new `Vector`.
`Vector.__str__()`	Returns a string representation of the vector.
`Vector.__hash__()`	Returns the hash code of the vector used for hash maps and comparisons.
`Vector.__getitem__()`	Retrieves the value of the x, y or z component of the vector.
`Vector.__setitem__()`	Assigns a value to the x, y or z component of the vector.
`Vector.__del__()`	Not implemented.
`Vector.__add__()`	Adds an operand to the vector.
`Vector.__radd__()`	Adds the vector to an operand.
`Vector.__sub__()`	Subtracts an operand from the vector.
`Vector.__rsub__()`	Subtracts the vector from an operand.
`Vector.__mul__()`	Calculates the product of the vector and an left-side operand.
`Vector.__rmul__()`	Calculates the product of the vector and a right-side operand.
`Vector.__div__()`	Divides each vector component by a scalar.
`Vector.__rdiv__()`	Not implemented.
`Vector.__mod__()`	Calculates the cross product of the vector and an operand.
`Vector.__xor__()`	Calculates an alternative product operation of the vector and a left-side operand.
`Vector.__rxor__()`	Not implemented.
`Vector.__abs__()`	Returns a vector with the absolute (positive) value of each component.
`Vector.__neg__()`	Returns the inverse of the vector.
`Vector.__invert__()`	Returns the normalized vector.
`Vector.__eq__()`	Checks if two vectors are equal.
`Vector.__ne__()`	Check if two vectors are not equal.
`Vector.__ge__()`	Not implemented.
`Vector.__gt__()`	Not implemented.
`Vector.__le__()`	Not implemented.
`Vector.__lt__()`	Not implemented.

`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.
`Vector.GetAverage()`	Calculates the average value of ‘x’, ‘y’ and ‘z’.
`Vector.GetSum()`	Calculates the sum of ‘x’, ‘y’ and ‘z’.
`Vector.ClampMin()`	Set the minimum of each component.
`Vector.ClampMax()`	Set the maximum of each component.
`Vector.Clamp01()`	Returns a vector that is clamped to the range [0.0 .. 1.0].
`Vector.GetLength()`	Calculates the length of the vector.
`Vector.GetLengthSquared()`	Calculates the squared length of the vector.
`Vector.GetSquaredLength()`	Returns the squared length of the vector.
`Vector.GetNormalized()`	Calculates the normalized vector, so that `GetLength()` returns 1.0.
`Vector.Normalize()`	Normalizes the vector, so that `GetLength()` returns 1.0.
`Vector.GetMin()`	Returns the minimum of ‘x’, ‘y’ and ‘z’.
`Vector.GetMax()`	Returns the maximum of ‘x’, ‘y’ and ‘z’.
`Vector.GetRightRotated()`	Returns a vector where the components have been rotated to the right (in the usual (x, y, z)-representation).
`Vector.Dot()`	Calculates the dot product of the vector and vector v2.
`Vector.Abs()`	Returns the vector with absolute value for each entry
`Vector.Min()`	Calculates the minimum of each component.
`Vector.Max()`	Calculates the maximum of each component.
`Vector.SetMin()`	Set the minimum of each component.
`Vector.SetMax()`	Set the maximum of each component.
`Vector.GetAngle()`	Calculates angle (in radians) between v1 and v2.
`Vector.Cross()`	Calculates the cross product of the vector and vector v2.

Static Methods Signatures

c4d.Vector.GetDistance()

Retrieve the distance between two vectors.

Methods Documentation

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.__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.__hash__(self)¶

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

New in version S26.

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

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.__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.__del__(self)¶

Not implemented.

Note

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

Raise: TypeError.

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.__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.__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.__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.__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.__mul__() is the operator implementation for the primary 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))

>>> # Computes the component-wise product of u and v.
>>> u ^ v
Vector(2, 0, 0)

>>> # Transforms u by M, excluding translations. 
>>> u ^ M
Vector(0, 1, 0)

Parameters: other (Union[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.__rxor__(self, other)¶

Not implemented.

Raise: TypeError.

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.__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.__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.__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.__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.__ge__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__gt__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__le__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.__lt__(self, other)¶

Not implemented.

Raise: TypeError.

Vector.GetHashCode(self)¶

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

New in version S26.

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 S26.

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 S26.

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 S26.

Vector.GetAverage(self)¶

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

New in version S26.

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

Vector.GetSum(self)¶

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

New in version S26.

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

Vector.ClampMin(self, other)¶

Set the minimum of each component.

New in version S26.

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

Vector.ClampMax(self, other)¶

Set the maximum of each component.

New in version S26.

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

Vector.Clamp01(self)¶

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

New in version S26.

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

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 S26.000: Use Vector.GetSquaredLength() instead.

Return type: float
Returns: The squared length.

Vector.GetSquaredLength(self)¶

Returns the squared length of the vector.

New in version S26.

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

Vector.GetNormalized(self)¶

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

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

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

Vector.GetMin(self)¶

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

New in version S26.

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

Vector.GetMax(self)¶

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

New in version S26.

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

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 S26.

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

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.Abs(self)¶

Returns the vector with absolute value for each entry

New in version S26.

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

Vector.Min(self, other)¶

Calculates the minimum of each component.

New in version S26.

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

Vector.Max(self, other)¶

Calculates the maximum of each component.

New in version S26.

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

Vector.SetMin(self, other)¶

Set the minimum of each component.

New in version S26.

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

Vector.SetMax(self, other)¶

Set the maximum of each component.

New in version S26.

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

Vector.GetAngle(self, other)¶

Calculates angle (in radians) between v1 and v2.

New in version S26.

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

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.

Static Methods Documentation

static c4d.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