pyxora.wrapper.image

  1from .functions import vector
  2
  3from typing import Union,Tuple
  4
  5import pygame
  6
  7class Image:
  8    """The Image class that includes methods for drawing, moving, and scaling images on a Pygame surface."""
  9    def __init__(self,image: pygame.Surface,pos: Tuple[int | float, int | float] | pygame.math.Vector2 | pygame.math.Vector3,
 10        shape_type:int="rect",align: str= "topleft",custom_size=None) -> None:
 11        """Initializes an Image object with the given position, image, shape type, and custom size.
 12
 13        Args:
 14            image (pygame.Surface): The image surface.
 15            pos (pos: Tuple[int | float, int | float] | pygame.math.Vector2 | pygame.math.Vector3): The position of the image.
 16            shape_type (int): The shape type of the image. Default = rect
 17            align (str): The alignment of the image. Default = topleft
 18            custom_size (tuple): The custom size of the image. Optional
 19
 20        Note:
 21            Available Shape Types: rect,circle (more will be added in the future, along with shapes.py)
 22            Available Alignments: topleft, topright, midtop, midleft, center, midright, bottomleft, midbottom, bottomright
 23        """
 24        self._surface = image
 25        self._pos = vector(*pos)
 26        self._size = self.rect.size
 27
 28        # custom_size = scale
 29        if custom_size:
 30            self._surface = pygame.transform.smoothscale(image, custom_size)
 31
 32        if custom_size:
 33            self._size = custom_size
 34
 35        self._scale = 1.0
 36        self._scale_surface = None
 37
 38        shape_type == 2 and self.__apply_circular_mask()
 39
 40        # change the position of the text based on the alignment
 41        self.__apply_alignment(align)
 42
 43    @property
 44    def position(self) -> pygame.math.Vector2 | pygame.math.Vector3:
 45        """
 46        Get a copy of the position of the text.
 47
 48        Returns:
 49            pygame.math.Vector2 or pygame.math.Vector3: The position of the text.
 50        """
 51        return self._pos.copy()
 52
 53    @property
 54    def size(self) -> tuple:
 55        """
 56        Get a the size of the image.
 57
 58        Returns:
 59            tuple: the image size
 60        """
 61        return tuple(self._size)
 62
 63    @property
 64    def shape(self) -> str:
 65        """
 66        Get a the shape of the image.
 67
 68        Returns:
 69            str: the image shape
 70        """
 71        return self._shape
 72
 73    @property
 74    def value(self) -> pygame.Surface:
 75        """
 76        Get a copy of the surface image.
 77
 78        Returns:
 79            pygame.Surface: the image copy surface
 80        """
 81        return self._surface.copy()
 82
 83    @property
 84    def rect(self) -> pygame.Rect:
 85        """
 86        Returns the rectangle of the image.
 87
 88        Returns:
 89            pygame.Rect: The rectangle of the image.
 90        """
 91        _rect = self._surface.get_rect()
 92        _rect.x = self._pos[0]
 93        _rect.y = self._pos[1]
 94        return _rect
 95
 96    @property
 97    def memory(self) -> int:
 98        """
 99        Returns the memory size of the image in bytes.
100
101        Returns:
102            int: The memory size of the image surface.
103        """
104        bytes_per_pixel = self._surface.get_bytesize()
105        width,height = self._surface.get_size()
106        return width * height * bytes_per_pixel
107
108    def move(self,pos: Tuple[int | float, int | float] | pygame.math.Vector2 | pygame.math.Vector3) -> None:
109        """
110        Moves the image by the given offset.
111
112        Args:
113            pos (Tuple[int | float, int | float] | Vector2 | Vector3):
114                The amount to move the image by, relative to its current position.
115        """
116        self._pos.x += pos[0]
117        self._pos.y += pos[1]
118
119    def move_at(self,pos: Tuple[int | float, int | float] | pygame.math.Vector2 | pygame.math.Vector3) -> None:
120        """
121        Moves the image to a position.
122
123        Args:
124            pos (Tuple[int | float, int | float] | Vector2 | Vector3):
125                The new position for the image.
126        """
127        self._pos.x = pos[0]
128        self._pos.y = pos[1]
129
130    def draw(self,surf: pygame.Surface,scale: float) -> None:
131        """
132        Draws the image on the given surface.
133
134        Args:
135            surf (pygame.Surface):
136                The surface to draw the image on.
137            scale (float):
138                The scale factor to apply to the image.
139        """
140        if scale == 1:
141            surf.blit(self._surface, self._pos)
142            return
143
144        if not self._scale == scale:
145            self._scale_surface = pygame.transform.smoothscale_by(self._surface, scale)
146            self._scale = scale
147
148        surf.blit(self._scale_surface, self._pos)
149
150    def __apply_circular_mask(self) -> None:
151        """Applies a circular alpha mask to the surface."""
152        mask = pygame.Surface(self._size, pygame.SRCALPHA)
153        radius = self._size[0] // 2
154        center = (radius, radius)
155        pygame.draw.circle(mask, (255, 255, 255), center, radius)
156        self.surface.blit(mask, (0, 0), special_flags=pygame.BLEND_RGBA_MULT)
157
158    def __apply_alignment(self, align: str):
159        """
160        Adjusts position based on alignment keywords.
161
162        Supported alignments:
163        'topleft', 'topright', 'midtop', 'midleft', 'center', 'midright',
164        'bottomleft', 'midbottom', 'bottomright'
165        """
166        align = align.lower().strip()
167        rect = self.rect
168
169        # Horizontal adjustment
170        if "left" in align:
171            self._pos.x -= 0
172        elif "center" in align or "mid" in align:
173            self._pos.x -= rect.width / 2
174        elif "right" in align:
175            self._pos.x -= rect.width
176        else:
177            raise ValueError(f"Invalid horizontal alignment in: {align}")
178
179        # Vertical adjustment
180        if "top" in align:
181            self._pos.y -= 0
182        elif "center" in align or "mid" in align:
183            self._pos.y -= rect.height / 2
184        elif "bottom" in align:
185            self._pos.y -= rect.height
186        else:
187            raise ValueError(f"Invalid vertical alignment in: {align}")