Geometry

Module: terminaltexteffects.utils.geometry

Utility functions for geometric calculations and operations.

The purpose of these functions is to find terminal coordinates that fall within certain regions or along certain paths. These functions are used by effects to enable more complex animations and movement paths.

Functions:

Name	Description
find_coords_on_circle	Finds points on a circle given the origin, radius, and number of points.
find_coords_in_circle	Finds coordinates within an ellipse given the center and major axis length.
find_coords_in_rect	Finds coordinates within a rectangle given the origin and distance.
find_coord_at_distance	Finds the coordinate at a given distance along a line defined by two coordinates.
find_coord_on_bezier_curve	Finds points on a bezier curve.
find_coord_on_line	Finds points on a line.
find_length_of_bezier_curve	Finds the length of a quadratic or cubic bezier curve.
find_length_of_line	Finds the length of a line intersecting two coordinates.
find_normalized_distance_from_center	Returns the normalized distance from the center of the Canvas.

find_coord_at_distance = functools.wraps(find_coord_at_distance)(functools.lru_cache(maxsize=8192)(find_coord_at_distance)) module-attribute

Find the coordinate at the given distance along the line defined by the origin and target coordinates.

The coordinate returned is approximately [distance] units away from the target coordinate, away from the origin coordinate.

Parameters:

Name	Type	Description	Default
origin	Coord	origin coordinate (a)	required
target	Coord	target coordinate (b)	required
distance	float	distance from the target coordinate (b), away from the origin coordinate (a)	required

Returns:

Name	Type	Description
Coord	Coord	Coordinate at the given distance (c).

find_coord_on_bezier_curve = functools.wraps(find_coord_on_bezier_curve)(functools.lru_cache(maxsize=16384)(find_coord_on_bezier_curve)) module-attribute

Find points on a bezier curve of any degree.

Parameters:

Name	Type	Description	Default
start	Coord	The starting coordinate of the curve.	required
control	tuple[Coord, ...]	The control points of the curve.	required
end	Coord	The ending coordinate of the curve.	required
t	float	The distance factor between the start and end coordinates.	required

Returns:

Name	Type	Description
Coord	Coord	The coordinate on the bezier curve corresponding to the given parameter value.

find_coord_on_line = functools.wraps(find_coord_on_line)(functools.lru_cache(maxsize=16384)(find_coord_on_line)) module-attribute

Find points on a line.

Parameters:

Name	Type	Description	Default
start	Coord	The starting coordinate of the line.	required
end	Coord	The ending coordinate of the line.	required
t	float	The distance factor between the start and end coordinates.	required

Returns:

Name	Type	Description
Coord	Coord	The coordinate on the line corresponding to the given parameter value.

find_coords_in_circle = functools.wraps(find_coords_in_circle)(functools.lru_cache(maxsize=8192)(find_coords_in_circle)) module-attribute

Find the coordinates within a circle with the given center and diameter.

The actual shape calculated is an ellipse with a major axis of length diameter, however the terminal cell height/width ratio creates a circle visually.

Parameters:

Name	Type	Description	Default
center	Coord	The center coordinate of the circle.	required
diameter	int	The length of the major axis of the circle.	required

Returns:

Type	Description
list[Coord]	list[Coord]: A list of coordinates within the circle.

find_coords_in_rect = functools.wraps(find_coords_in_rect)(functools.lru_cache(maxsize=8192)(find_coords_in_rect)) module-attribute

Find coords that fall within a rectangle.

Distance specifies the number of units in each direction from the origin. Final width = 2 * distance + 1, final height = 2 * distance + 1.

Parameters:

Name	Type	Description	Default
origin	Coord	center of the rectangle	required
distance	int	distance from the origin	required

Returns:

Type	Description
list[Coord]	list[Coord]: list of Coord points in the rectangle

find_coords_on_circle = functools.wraps(find_coords_on_circle)(functools.lru_cache(maxsize=8192)(find_coords_on_circle)) module-attribute

Find points on a circle.

Parameters:

Name	Type	Description	Default
origin	Coord	origin of the circle	required
radius	int	radius of the circle	required
coords_limit	int	limit the number of coords returned, if 0, the number of points is calculated based on the circumference of the circle	required
unique	bool	whether to remove duplicate points. Defaults to True.	required

Returns:

Name	Type	Description
list	Coord	list of Coord points on the circle

find_length_of_bezier_curve = functools.wraps(find_length_of_bezier_curve)(functools.lru_cache(maxsize=4096)(find_length_of_bezier_curve)) module-attribute

Find the length of a bezier curve.

Parameters:

Name	Type	Description	Default
start	Coord	The starting coordinate of the curve.	required
control	tuple[Coord, ...] | Coord	The control point(s) of the curve.	required
end	Coord	The ending coordinate of the curve.	required

Returns:

Name	Type	Description
float	float	The length of the bezier curve.

find_length_of_line = functools.wraps(find_length_of_line)(functools.lru_cache(maxsize=8192)(find_length_of_line)) module-attribute

Return the length of the line intersecting coord1 and coord2.

If double_row_diff is True, the distance is doubled to account for the terminal character height/width ratio.

Parameters:

Name	Type	Description	Default
coord1	Coord	first coordinate.	required
coord2	Coord	second coordinate.	required
double_row_diff	bool	whether to double the row difference to account for terminal character height/width ratio. Defaults to False.	required

Returns:

Name	Type	Description
float	float	length of the line

find_normalized_distance_from_center = functools.wraps(find_normalized_distance_from_center)(functools.lru_cache(maxsize=8192)(find_normalized_distance_from_center)) module-attribute

Return the normalized distance from the center of a rectangle on the Canvas as a float between 0 and 1.

The distance is calculated using the Pythagorean theorem and accounts for the aspect ratio of the terminal.

Parameters:

Name	Type	Description	Default
bottom	int	Bottom row of the rectangle on the Canvas.	required
top	int	Top row of the rectangle on the Canvas.	required
left	int	Left column of the rectangle on the Canvas.	required
right	int	Right column of the rectangle on the Canvas.	required
other_coord	Coord	Other coordinate from which to calculate the distance to the center of the rectangle.	required

Returns:

Name	Type	Description
float	float	Normalized distance from the center of the rectangle on the Canvas, float between 0 and 1.

Coord dataclass

A coordinate with row and column values.

Parameters:

Name	Type	Description	Default
column	int	column value	required
row	int	row value	required

Source code in terminaltexteffects/utils/geometry.py

@dataclass(eq=True, frozen=True)
class Coord:
    """A coordinate with row and column values.

    Args:
        column (int): column value
        row (int): row value

    """

    column: int
    row: int