sonolus.script.vec

Vec2

Bases: Record

A 2D vector.

Usage

Vec2(x: float, y: float)

angle: float property

Calculate the angle of the vector in radians from the positive x-axis.

Returns:

Type	Description
float	The angle of the vector in radians.

magnitude: float property

Calculate the magnitude (length) of the vector.

Returns:

Type	Description
float	The magnitude of the vector.

tuple: tuple[float, float] property

Return the vector as a tuple (x, y).

Returns:

Type	Description
tuple[float, float]	A tuple representation of the vector.

__add__(other: Vec2) -> Vec2

Add this vector to another vector and return a new vector.

Parameters:

Name	Type	Description	Default
other	Vec2	The vector to add.	required

Returns:

Type	Description
Vec2	A new vector resulting from the addition.

__mul__(other: Vec2 | float) -> Vec2

Multiply this vector by another vector or a scalar and return a new vector.

Parameters:

Name	Type	Description	Default
other	Vec2 | float	The vector or scalar to multiply by.	required

Returns:

Type	Description
Vec2	A new vector resulting from the multiplication.

__neg__() -> Vec2

Negate the vector (invert the direction) and return a new vector.

Returns:

Type	Description
Vec2	A new vector with inverted direction.

__sub__(other: Vec2) -> Vec2

Subtract another vector from this vector and return a new vector.

Parameters:

Name	Type	Description	Default
other	Vec2	The vector to subtract.	required

Returns:

Type	Description
Vec2	A new vector resulting from the subtraction.

__truediv__(other: Vec2 | float) -> Vec2

Divide this vector by another vector or a scalar and return a new vector.

Parameters:

Name	Type	Description	Default
other	Vec2 | float	The vector or scalar to divide by.	required

Returns:

Type	Description
Vec2	A new vector resulting from the division.

dot(other: Vec2) -> float

Calculate the dot product of this vector with another vector.

Parameters:

Name	Type	Description	Default
other	Vec2	The other vector to calculate the dot product with.	required

Returns:

Type	Description
float	The dot product of the two vectors.

down() -> Vec2 classmethod

Return a vector pointing downwards (x=0, y=-1).

Returns:

Type	Description
Vec2	A new vector pointing downwards.

left() -> Vec2 classmethod

Return a vector pointing to the left (x=-1, y=0).

Returns:

Type	Description
Vec2	A new vector pointing to the left.

normalize() -> Vec2

Normalize the vector (set the magnitude to 1) and return a new vector.

If the vector is a zero vector, an assertion error is raised if runtime checks are enabled.

Returns:

Type	Description
Vec2	A new vector with magnitude 1.

normalize_or_zero() -> Vec2

Normalize the vector (set the magnitude to 1) and return a new vector.

If the vector is a zero vector, return a zero vector.

Returns:

Type	Description
Vec2	A new vector with magnitude 1, or a zero vector if the original vector is zero.

one() -> Vec2 classmethod

Return a vector with x and y set to 1.

Returns:

Type	Description
Vec2	A new vector with x=1 and y=1.

orthogonal() -> Vec2

Return a vector orthogonal to this vector.

The orthogonal vector is rotated 90 degrees counter-clockwise from this vector.

Returns:

Type	Description
Vec2	A new vector orthogonal to this vector.

right() -> Vec2 classmethod

Return a vector pointing to the right (x=1, y=0).

Returns:

Type	Description
Vec2	A new vector pointing to the right.

rotate(angle: float) -> Vec2

Rotate the vector by a given angle in radians and return a new vector.

Parameters:

Name	Type	Description	Default
angle	float	The angle to rotate the vector by, in radians. Positive angles rotate counterclockwise.	required

Returns:

Type	Description
Vec2	A new vector rotated by the given angle.

rotate_about(angle: float, pivot: Vec2) -> Vec2

Rotate the vector about a pivot by a given angle in radians and return a new vector.

Parameters:

Name	Type	Description	Default
angle	float	The angle to rotate the vector by, in radians. Positive angles rotate counterclockwise.	required
pivot	Vec2	The pivot point to rotate about.	required

Returns:

Type	Description
Vec2	A new vector rotated about the pivot by the given angle.

unit(angle: float) -> Vec2 classmethod

Return a unit vector (magnitude 1) at a given angle in radians.

Parameters:

Name	Type	Description	Default
angle	float	The angle in radians.	required

Returns:

Type	Description
Vec2	A new unit vector at the specified angle.

up() -> Vec2 classmethod

Return a vector pointing upwards (x=0, y=1).

Returns:

Type	Description
Vec2	A new vector pointing upwards.

zero() -> Vec2 classmethod

Return a vector with x and y set to 0.

Returns:

Type	Description
Vec2	A new vector with x=0 and y=0.

angle_diff(a: float, b: float) -> float

Return the smallest absolute difference between two angles in radians.

The result is in the range [0, π].

pnpoly(vertices: ArrayLike[Vec2] | tuple[Vec2, ...], test: Vec2) -> bool

Check if a point is inside a polygon.

No guaranteed behavior for points on the edges or very close to the edges.

Parameters:

Name	Type	Description	Default
vertices	ArrayLike[Vec2] | tuple[Vec2, ...]	The vertices of the polygon.	required
test	Vec2	The point to test.	required

Returns:

Type	Description
bool	Whether the point is inside the polygon.

signed_angle_diff(a: float, b: float) -> float

Return the signed smallest difference between two angles in radians.

The result is in the range [-π, π). A positive result means a is counter-clockwise from b. A negative result means a is clockwise from b.

If the two angles are exactly opposite, the result will be -π, but this should not be relied upon.