Skip to content

sonolus.script.transform

InvertibleTransform2d

Bases: Record

A transformation matrix for 2D points that can be inverted.

Usage 
InvertibleTransform2d.new()

compose(other)

Compose with another invertible transform which is applied after this transform and return a new transform.

Parameters:

Name Type Description Default
other Self

The other invertible transform to compose with.

 required

Returns:

Type Description
Self

A new invertible transform resulting from the composition.

compose_before(other)

Compose with another invertible transform which is applied before this transform and return a new transform.

Parameters:

Name Type Description Default
other Self

The other invertible transform to compose with.

 required

Returns:

Type Description
Self

A new invertible transform resulting from the composition.

inverse_transform_quad(quad)

Inverse transform a Quad and return a new Quad.

Parameters:

Name Type Description Default
quad QuadLike

The quad to inverse transform.

 required

Returns:

Type Description
Quad

A new inverse transformed quad.

inverse_transform_vec(v)

Inverse transform a Vec2 and return a new Vec2.

Parameters:

Name Type Description Default
v Vec2

The vector to inverse transform.

 required

Returns:

Type Description
Vec2

A new inverse transformed vector.

new() classmethod

Create a new identity transform.

Returns:

Type Description
Self

A new identity transform.

normalize()

Normalize the transform to have a 1 in the bottom right corner and return a new transform.

This may fail in some special cases involving perspective transformations where the bottom right corner is 0.

Returns:

Type Description
Self

A new normalized invertible transform.

perspective_x(foreground_x, vanishing_point)

Apply a perspective transformation along the x-axis and return a new transform.

Parameters:

Name Type Description Default
foreground_x float

The foreground x-coordinate.

 required
vanishing_point Vec2

The vanishing point vector.

 required

Returns:

Type Description
Self

A new invertible transform after applying perspective.

perspective_y(foreground_y, vanishing_point)

Apply a perspective transformation along the y-axis and return a new transform.

Parameters:

Name Type Description Default
foreground_y float

The foreground y-coordinate.

 required
vanishing_point Vec2

The vanishing point vector.

 required

Returns:

Type Description
Self

A new invertible transform after applying perspective.

rotate(angle)

Rotate about the origin and return a new transform.

Parameters:

Name Type Description Default
angle float

The angle of rotation in radians.

 required

Returns:

Type Description
Self

A new invertible transform after rotation.

rotate_about(angle, /, pivot)

Rotate about the pivot and return a new transform.

Parameters:

Name Type Description Default
angle float

The angle of rotation in radians.

 required
pivot Vec2

The pivot point for rotation.

 required

Returns:

Type Description
Self

A new invertible transform after rotation.

scale(factor)

Scale about the origin and return a new transform.

Parameters:

Name Type Description Default
factor Vec2

The scale factor vector.

 required

Returns:

Type Description
Self

A new invertible transform after scaling.

scale_about(factor, /, pivot)

Scale about the pivot and return a new transform.

Parameters:

Name Type Description Default
factor Vec2

The scale factor vector.

 required
pivot Vec2

The pivot point for scaling.

 required

Returns:

Type Description
Self

A new invertible transform after scaling.

shear_x(m)

Shear along the x-axis and return a new transform.

Parameters:

Name Type Description Default
m float

The shear factor along the x-axis.

 required

Returns:

Type Description
Self

A new invertible transform after shearing.

shear_y(m)

Shear along the y-axis and return a new transform.

Parameters:

Name Type Description Default
m float

The shear factor along the y-axis.

 required

Returns:

Type Description
Self

A new invertible transform after shearing.

simple_perspective_x(x)

Apply perspective along the x-axis with vanishing point at the given x coordinate and return a new transform.

Parameters:

Name Type Description Default
x float

The x coordinate of the vanishing point.

 required

Returns:

Type Description
Self

A new invertible transform after applying perspective.

simple_perspective_y(y)

Apply perspective along the y-axis with vanishing point at the given y coordinate and return a new transform.

Parameters:

Name Type Description Default
y float

The y coordinate of the vanishing point.

 required

Returns:

Type Description
Self

A new invertible transform after applying perspective.

transform_quad(quad)

Transform a Quad and return a new Quad.

Parameters:

Name Type Description Default
quad QuadLike

The quad to transform.

 required

Returns:

Type Description
Quad

A new transformed quad.

transform_vec(v)

Transform a Vec2 and return a new Vec2.

Parameters:

Name Type Description Default
v Vec2

The vector to transform.

 required

Returns:

Type Description
Vec2

A new transformed vector.

translate(translation)

Translate along the x and y axes and return a new transform.

Parameters:

Name Type Description Default
translation Vec2

The translation vector.

 required

Returns:

Type Description
Self

A new invertible transform after translation.

Transform2d

Bases: Record

A transformation matrix for 2D points.

Usage 
Transform2d.new()

compose(other)

Compose with another transform which is applied after this transform and return a new transform.

Parameters:

Name Type Description Default
other Self

The other transform to compose with.

 required

Returns:

Type Description
Self

A new transform resulting from the composition.

compose_before(other)

Compose with another transform which is applied before this transform and return a new transform.

Parameters:

Name Type Description Default
other Self

The other transform to compose with.

 required

Returns:

Type Description
Self

A new transform resulting from the composition.

inverse_perspective_x(foreground_x, vanishing_point)

Apply the inverse of a perspective transformation along the x-axis and return a new transform.

Parameters:

Name Type Description Default
foreground_x float

The foreground x-coordinate.

 required
vanishing_point Vec2

The vanishing point vector.

 required

Returns:

Type Description
Self

A new transform after applying the inverse perspective.

inverse_perspective_y(foreground_y, vanishing_point)

Apply the inverse of a perspective transformation along the y-axis and return a new transform.

Parameters:

Name Type Description Default
foreground_y float

The foreground y-coordinate.

 required
vanishing_point Vec2

The vanishing point vector.

 required

Returns:

Type Description
Self

A new transform after applying the inverse perspective.

new() classmethod

Create a new identity transform.

Returns:

Type Description
Self

A new identity transform.

normalize()

Normalize the transform to have a 1 in the bottom right corner and return a new transform.

This may fail in some special cases involving perspective transformations where the bottom right corner is 0.

Returns:

Type Description
Self

A new normalized transform.

perspective_x(foreground_x, vanishing_point)

Apply a perspective transformation along the x-axis and return a new transform.

Parameters:

Name Type Description Default
foreground_x float

The foreground x-coordinate.

 required
vanishing_point Vec2

The vanishing point vector.

 required

Returns:

Type Description
Self

A new transform after applying perspective.

perspective_y(foreground_y, vanishing_point)

Apply a perspective transformation along the y-axis and return a new transform.

Parameters:

Name Type Description Default
foreground_y float

The foreground y-coordinate.

 required
vanishing_point Vec2

The vanishing point vector.

 required

Returns:

Type Description
Self

A new transform after applying perspective.

rotate(angle)

Rotate about the origin and return a new transform.

Parameters:

Name Type Description Default
angle float

The angle of rotation in radians.

 required

Returns:

Type Description
Self

A new transform after rotation.

rotate_about(angle, /, pivot)

Rotate about the pivot and return a new transform.

Parameters:

Name Type Description Default
angle float

The angle of rotation in radians.

 required
pivot Vec2

The pivot point for rotation.

 required

Returns:

Type Description
Self

A new transform after rotation.

scale(factor)

Scale about the origin and return a new transform.

Parameters:

Name Type Description Default
factor Vec2

The scale factor vector.

 required

Returns:

Type Description
Self

A new transform after scaling.

scale_about(factor, /, pivot)

Scale about the pivot and return a new transform.

Parameters:

Name Type Description Default
factor Vec2

The scale factor vector.

 required
pivot Vec2

The pivot point for scaling.

 required

Returns:

Type Description
Self

A new transform after scaling.

shear_x(m)

Shear along the x-axis and return a new transform.

Parameters:

Name Type Description Default
m float

The shear factor along the x-axis.

 required

Returns:

Type Description
Self

A new transform after shearing.

shear_y(m)

Shear along the y-axis and return a new transform.

Parameters:

Name Type Description Default
m float

The shear factor along the y-axis.

 required

Returns:

Type Description
Self

A new transform after shearing.

simple_perspective_x(x)

Apply perspective along the x-axis with vanishing point at the given x coordinate and return a new transform.

Parameters:

Name Type Description Default
x float

The x coordinate of the vanishing point.

 required

Returns:

Type Description
Self

A new transform after applying perspective.

simple_perspective_y(y)

Apply perspective along the y-axis with vanishing point at the given y coordinate and return a new transform.

Parameters:

Name Type Description Default
y float

The y coordinate of the vanishing point.

 required

Returns:

Type Description
Self

A new transform after applying perspective.

transform_quad(quad)

Transform a Quad and return a new Quad.

Parameters:

Name Type Description Default
quad QuadLike

The quad to transform.

 required

Returns:

Type Description
Quad

A new transformed quad.

transform_vec(v)

Transform a Vec2 and return a new Vec2.

Parameters:

Name Type Description Default
v Vec2

The vector to transform.

 required

Returns:

Type Description
Vec2

A new transformed vector.

translate(translation)

Translate along the x and y axes and return a new transform.

Parameters:

Name Type Description Default
translation Vec2

The translation vector.

 required

Returns:

Type Description
Self

A new transform after translation.

perspective_approach(distance_ratio, progress)

Calculate the perspective correct approach curve given the initial distance, target distance, and progress.

For typical engines with stage tilt, distance_ratio is the displayed width of a lane at the judge line divided by the displayed width of a lane at note spawn. For flat stages, this will be 1.0, and this function would simply return progress unchanged.

Parameters:

Name Type Description Default
distance_ratio float

The ratio of the distance at note spawn to the distance at the judge line.

 required
progress float

The progress value, where 0 corresponds to note spawn and 1 corresponds to the judge line.

 required

Returns:

Type Description
float

The perspective-corrected progress value.