Canvas

Module: terminaltexteffects.engine.terminal

Represent the canvas in the terminal.

The canvas is the area defined by the dimensions of the input data, unless specified otherwise in the TerminalConfig.

This class provides methods for working with the canvas, such as checking if a coordinate is within the canvas, getting random coordinates within the canvas, and getting a random coordinate outside the canvas.

This class also provides attributes for the dimensions of the canvas, the extents of the text within the canvas, and the center of the canvas.

Parameters:

Name	Type	Description	Default
top	int	top row of the canvas	required
right	int	right column of the canvas	required
bottom	int	bottom row of the canvas. Defaults to 1.	1
left	int	left column of the canvas. Defaults to 1.	1

Attributes:

Name	Type	Description
top	int	top row of the canvas
right	int	right column of the canvas
bottom	int	bottom row of the canvas
left	int	left column of the canvas
center_row	int	row of the center of the canvas
center_column	int	column of the center of the canvas
center	Coord	coordinate of the center of the canvas
width	int	width of the canvas
height	int	height of the canvas
text_left	int	left column of the text within the canvas
text_right	int	right column of the text within the canvas
text_top	int	top row of the text within the canvas
text_bottom	int	bottom row of the text within the canvas
text_width	int	width of the text within the canvas
text_height	int	height of the text within the canvas
text_center_row	int	row of the center of the text within the canvas
text_center_column	int	column of the center of the text within the canvas

Methods:

Name	Description
coord_is_in_canvas	Checks whether a coordinate is within the canvas.
coord_is_in_text	Checks whether a coordinate is within the text boundary of the canvas.
random_column	Get a random column position within the canvas.
random_row	Get a random row position within the canvas.
random_coord	Get a random coordinate within or outside the canvas.

Source code in terminaltexteffects/engine/terminal.py

@dataclass
class Canvas:
    """Represent the canvas in the terminal.

    The canvas is the area defined by the dimensions of the input data, unless specified otherwise
    in the TerminalConfig.

    This class provides methods for working with the canvas, such as checking if a coordinate is within the canvas,
    getting random coordinates within the canvas, and getting a random coordinate outside the canvas.

    This class also provides attributes for the dimensions of the canvas, the extents of the text within the canvas,
    and the center of the canvas.

    Args:
        top (int): top row of the canvas
        right (int): right column of the canvas
        bottom (int): bottom row of the canvas. Defaults to 1.
        left (int): left column of the canvas. Defaults to 1.

    Attributes:
        top (int): top row of the canvas
        right (int): right column of the canvas
        bottom (int): bottom row of the canvas
        left (int): left column of the canvas
        center_row (int): row of the center of the canvas
        center_column (int): column of the center of the canvas
        center (Coord): coordinate of the center of the canvas
        width (int): width of the canvas
        height (int): height of the canvas
        text_left (int): left column of the text within the canvas
        text_right (int): right column of the text within the canvas
        text_top (int): top row of the text within the canvas
        text_bottom (int): bottom row of the text within the canvas
        text_width (int): width of the text within the canvas
        text_height (int): height of the text within the canvas
        text_center_row (int): row of the center of the text within the canvas
        text_center_column (int): column of the center of the text within the canvas

    Methods:
        coord_is_in_canvas:
            Checks whether a coordinate is within the canvas.
        coord_is_in_text:
            Checks whether a coordinate is within the text boundary of the canvas.
        random_column:
            Get a random column position within the canvas.
        random_row:
            Get a random row position within the canvas.
        random_coord:
            Get a random coordinate within or outside the canvas.

    """

    top: int
    """int: top row of the canvas"""
    right: int
    """int: right column of the canvas"""
    bottom: int = 1
    """int: bottom row of the canvas"""
    left: int = 1
    """int: left column of the canvas"""

    def __post_init__(self) -> None:
        """After initialization, calculate the center, width, height, and text dimensions of the canvas."""
        self.center_row = max(self.top // 2, self.bottom)
        """int: row of the center of the canvas"""
        if self.top % 2 and self.top > 1:
            self.center_row += 1
        self.center_column = max(self.right // 2, self.left)
        """int: column of the center of the canvas"""
        if self.right % 2 and self.right > 1:
            self.center_column += 1
        self.center = Coord(self.center_column, self.center_row)
        """Coord: coordinate of the center of the canvas"""
        self.width = self.right
        """int: width of the canvas"""
        self.height = self.top
        """int: height of the canvas"""
        self.text_left = 0
        """int: left column of the text within the canvas"""
        self.text_right = 0
        """int: right column of the text within the canvas"""
        self.text_top = 0
        """int: top row of the text within the canvas"""
        self.text_bottom = 0
        """int: bottom row of the text within the canvas"""
        self.text_width = 0
        """int: width of the text within the canvas"""
        self.text_height = 0
        """int: height of the text within the canvas"""
        self.text_center_row = 0
        """int: row of the center of the text within the canvas"""
        self.text_center_column = 0
        """int: column of the center of the text within the canvas"""

    def _anchor_text(
        self,
        characters: list[EffectCharacter],
        anchor: Literal["n", "ne", "e", "se", "s", "sw", "w", "nw", "c"],
    ) -> list[EffectCharacter]:
        """Anchors the text within the canvas based on the specified anchor point.

        Args:
            characters (list[EffectCharacter]): _description_
            anchor (Literal["n", "ne", "e", "se", "s", "sw", "w", "nw", "c"]): Anchor point for the text
                within the Canvas.

        Returns:
            list[EffectCharacter]: List of characters anchored within the canvas. Only returns characters with
            coordinates within the canvas after anchoring.

        """
        # translate coordinate based on anchor within the canvas
        input_width = max([character._input_coord.column for character in characters])
        input_height = max([character._input_coord.row for character in characters])

        column_delta = row_delta = 0
        if input_width != self.width:
            if anchor in ("s", "n", "c"):
                column_delta = self.center_column - (input_width // 2)
            elif anchor in ("se", "e", "ne"):
                column_delta = self.right - input_width
            elif anchor in ("sw", "w", "nw"):
                column_delta = self.left - 1
        if input_height != self.height:
            if anchor in ("w", "e", "c"):
                row_delta = self.center_row - (input_height // 2)
            elif anchor in ("nw", "n", "ne"):
                row_delta = self.top - input_height
            elif anchor in ("sw", "s", "se"):
                row_delta = self.bottom - 1

        for character in characters:
            current_coord = character.input_coord
            anchored_coord = Coord(current_coord.column + column_delta, current_coord.row + row_delta)
            character._input_coord = anchored_coord
            character.motion.set_coordinate(anchored_coord)

        characters = [character for character in characters if self.coord_is_in_canvas(character.input_coord)]

        # get text dimensions, centers, and extents
        self.text_left = min([character.input_coord.column for character in characters])
        self.text_right = max([character.input_coord.column for character in characters])
        self.text_top = max([character.input_coord.row for character in characters])
        self.text_bottom = min([character.input_coord.row for character in characters])
        self.text_width = max(self.text_right - self.text_left + 1, 1)
        self.text_height = max(self.text_top - self.text_bottom + 1, 1)
        self.text_center_row = self.text_bottom + ((self.text_top - self.text_bottom) // 2)
        self.text_center_column = self.text_left + ((self.text_right - self.text_left) // 2)

        return characters

    def coord_is_in_canvas(self, coord: Coord) -> bool:
        """Check whether a coordinate is within the canvas.

        Args:
            coord (Coord): coordinate to check

        Returns:
            bool: whether the coordinate is within the canvas

        """
        return self.left <= coord.column <= self.right and self.bottom <= coord.row <= self.top

    def coord_is_in_text(self, coord: Coord) -> bool:
        """Check whether a coordinate is within the text boundary.

        Args:
            coord (Coord): coordinate to check

        Returns:
            bool: whether the coordinate is within the text boundary

        """
        return self.text_left <= coord.column <= self.text_right and self.text_bottom <= coord.row <= self.text_top

    def random_column(self, *, within_text_boundary: bool = False) -> int:
        """Get a random column position within the canvas.

        Args:
            within_text_boundary (bool, optional): If True, the column will be limited to the text boundary. Otherwise,
                it can be anywhere within the canvas. Defaults to False.

        Returns:
            int: a random column position within the canvas

        """
        if within_text_boundary:
            return random.randint(self.text_left, self.text_right)
        return random.randint(self.left, self.right)

    def random_row(self, *, within_text_boundary: bool = False) -> int:
        """Get a random row position within the canvas.

        Args:
            within_text_boundary (bool, optional): If True, the row will be limited to the text boundary. Otherwise,
                it can be anywhere within the canvas. Defaults to False.

        Returns:
            int: a random row position within the canvas

        """
        if within_text_boundary:
            return random.randint(self.text_bottom, self.text_top)
        return random.randint(self.bottom, self.top)

    def random_coord(self, *, outside_scope: bool = False, within_text_boundary: bool = False) -> Coord:
        """Get a random coordinate. Coordinate is within the canvas unless outside_scope is True.

        `outside_scope` takes precedence over `within_text_boundary`, they are functionally mutually exclusive.

        Args:
            outside_scope (bool, optional): whether the coordinate should fall outside the canvas. Defaults to False.
            within_text_boundary (bool, optional): If True, the coordinate will be limited to the text boundary.
                Otherwise, it can be anywhere within the canvas. Defaults to False.

        Returns:
            Coord: a random coordinate . Coordinate is within the canvas unless outside_scope is True.

        """
        if outside_scope is True:
            random_coord_above = Coord(self.random_column(), self.top + 1)
            random_coord_below = Coord(self.random_column(), self.bottom - 1)
            random_coord_left = Coord(self.left - 1, self.random_row())
            random_coord_right = Coord(self.right + 1, self.random_row())
            return random.choice([random_coord_above, random_coord_below, random_coord_left, random_coord_right])
        return Coord(
            self.random_column(within_text_boundary=within_text_boundary),
            self.random_row(within_text_boundary=within_text_boundary),
        )

bottom = 1 class-attribute instance-attribute

int: bottom row of the canvas

left = 1 class-attribute instance-attribute

int: left column of the canvas

right instance-attribute

int: right column of the canvas

top instance-attribute

int: top row of the canvas

__post_init__()

After initialization, calculate the center, width, height, and text dimensions of the canvas.

Source code in terminaltexteffects/engine/terminal.py

def __post_init__(self) -> None:
    """After initialization, calculate the center, width, height, and text dimensions of the canvas."""
    self.center_row = max(self.top // 2, self.bottom)
    """int: row of the center of the canvas"""
    if self.top % 2 and self.top > 1:
        self.center_row += 1
    self.center_column = max(self.right // 2, self.left)
    """int: column of the center of the canvas"""
    if self.right % 2 and self.right > 1:
        self.center_column += 1
    self.center = Coord(self.center_column, self.center_row)
    """Coord: coordinate of the center of the canvas"""
    self.width = self.right
    """int: width of the canvas"""
    self.height = self.top
    """int: height of the canvas"""
    self.text_left = 0
    """int: left column of the text within the canvas"""
    self.text_right = 0
    """int: right column of the text within the canvas"""
    self.text_top = 0
    """int: top row of the text within the canvas"""
    self.text_bottom = 0
    """int: bottom row of the text within the canvas"""
    self.text_width = 0
    """int: width of the text within the canvas"""
    self.text_height = 0
    """int: height of the text within the canvas"""
    self.text_center_row = 0
    """int: row of the center of the text within the canvas"""
    self.text_center_column = 0
    """int: column of the center of the text within the canvas"""

coord_is_in_canvas(coord)

Check whether a coordinate is within the canvas.

Parameters:

Name	Type	Description	Default
coord	Coord	coordinate to check	required

Returns:

Name	Type	Description
bool	bool	whether the coordinate is within the canvas

Source code in terminaltexteffects/engine/terminal.py

def coord_is_in_canvas(self, coord: Coord) -> bool:
    """Check whether a coordinate is within the canvas.

    Args:
        coord (Coord): coordinate to check

    Returns:
        bool: whether the coordinate is within the canvas

    """
    return self.left <= coord.column <= self.right and self.bottom <= coord.row <= self.top

coord_is_in_text(coord)

Check whether a coordinate is within the text boundary.

Parameters:

Name	Type	Description	Default
coord	Coord	coordinate to check	required

Returns:

Name	Type	Description
bool	bool	whether the coordinate is within the text boundary

Source code in terminaltexteffects/engine/terminal.py

def coord_is_in_text(self, coord: Coord) -> bool:
    """Check whether a coordinate is within the text boundary.

    Args:
        coord (Coord): coordinate to check

    Returns:
        bool: whether the coordinate is within the text boundary

    """
    return self.text_left <= coord.column <= self.text_right and self.text_bottom <= coord.row <= self.text_top

random_column(*, within_text_boundary=False)

Get a random column position within the canvas.

Parameters:

Name	Type	Description	Default
within_text_boundary	bool	If True, the column will be limited to the text boundary. Otherwise, it can be anywhere within the canvas. Defaults to False.	False

Returns:

Name	Type	Description
int	int	a random column position within the canvas

Source code in terminaltexteffects/engine/terminal.py

def random_column(self, *, within_text_boundary: bool = False) -> int:
    """Get a random column position within the canvas.

    Args:
        within_text_boundary (bool, optional): If True, the column will be limited to the text boundary. Otherwise,
            it can be anywhere within the canvas. Defaults to False.

    Returns:
        int: a random column position within the canvas

    """
    if within_text_boundary:
        return random.randint(self.text_left, self.text_right)
    return random.randint(self.left, self.right)

random_coord(*, outside_scope=False, within_text_boundary=False)

Get a random coordinate. Coordinate is within the canvas unless outside_scope is True.

outside_scope takes precedence over within_text_boundary, they are functionally mutually exclusive.

Parameters:

Name	Type	Description	Default
outside_scope	bool	whether the coordinate should fall outside the canvas. Defaults to False.	False
within_text_boundary	bool	If True, the coordinate will be limited to the text boundary. Otherwise, it can be anywhere within the canvas. Defaults to False.	False

Returns:

Name	Type	Description
Coord	Coord	a random coordinate . Coordinate is within the canvas unless outside_scope is True.

Source code in terminaltexteffects/engine/terminal.py

def random_coord(self, *, outside_scope: bool = False, within_text_boundary: bool = False) -> Coord:
    """Get a random coordinate. Coordinate is within the canvas unless outside_scope is True.

    `outside_scope` takes precedence over `within_text_boundary`, they are functionally mutually exclusive.

    Args:
        outside_scope (bool, optional): whether the coordinate should fall outside the canvas. Defaults to False.
        within_text_boundary (bool, optional): If True, the coordinate will be limited to the text boundary.
            Otherwise, it can be anywhere within the canvas. Defaults to False.

    Returns:
        Coord: a random coordinate . Coordinate is within the canvas unless outside_scope is True.

    """
    if outside_scope is True:
        random_coord_above = Coord(self.random_column(), self.top + 1)
        random_coord_below = Coord(self.random_column(), self.bottom - 1)
        random_coord_left = Coord(self.left - 1, self.random_row())
        random_coord_right = Coord(self.right + 1, self.random_row())
        return random.choice([random_coord_above, random_coord_below, random_coord_left, random_coord_right])
    return Coord(
        self.random_column(within_text_boundary=within_text_boundary),
        self.random_row(within_text_boundary=within_text_boundary),
    )

random_row(*, within_text_boundary=False)

Get a random row position within the canvas.

Parameters:

Name	Type	Description	Default
within_text_boundary	bool	If True, the row will be limited to the text boundary. Otherwise, it can be anywhere within the canvas. Defaults to False.	False

Returns:

Name	Type	Description
int	int	a random row position within the canvas

Source code in terminaltexteffects/engine/terminal.py

def random_row(self, *, within_text_boundary: bool = False) -> int:
    """Get a random row position within the canvas.

    Args:
        within_text_boundary (bool, optional): If True, the row will be limited to the text boundary. Otherwise,
            it can be anywhere within the canvas. Defaults to False.

    Returns:
        int: a random row position within the canvas

    """
    if within_text_boundary:
        return random.randint(self.text_bottom, self.text_top)
    return random.randint(self.bottom, self.top)