simetri.image.image

  1from typing import Any, Optional, Union, Callable, Tuple, Dict, List, Sequence
  2
  3from PIL import Image as PIL_Image
  4from ..graphics.core import Base
  5
  6
  7def supported_formats() -> List[str]:
  8    """Generates a list of supported image formats available in your system.
  9        Returns:
 10            List[str]: A list of supported image formats available in your system.
 11    """
 12
 13    exts = PIL_Image.registered_extensions()
 14    supported = {ex for ex, f in exts.items() if f in PIL_Image.OPEN}
 15
 16    return sorted(supported)
 17
 18from PIL import Image
 19
 20def convert_png_to_ico(png_path, ico_path, sizes=None):
 21    """Converts a PNG image to an ICO file.
 22
 23    Args:
 24        png_path: Path to the input PNG image.
 25        ico_path: Path to save the output ICO file.
 26        sizes: A list of tuples specifying the sizes to include in the ICO file,
 27               e.g., [(16, 16), (32, 32), (48, 48)]. If None, defaults to [(32, 32)].
 28    """
 29    if sizes is None:
 30      sizes = [(32, 32)]
 31
 32    img = Image.open(png_path)
 33
 34    icon_sizes = []
 35    for size in sizes:
 36      icon_sizes.append(size)
 37
 38    img.save(ico_path, sizes=icon_sizes)
 39
 40    # Example usage:
 41    convert_png_to_ico("input.png", "output.ico", sizes=[(16, 16), (32, 32)])
 42
 43class Image(PIL_Image.Image, Base):
 44    """
 45    A class that extends the PIL Image class to add additional functionality.
 46    """
 47
 48    def __init__(self, *args, **kwargs):
 49        """
 50        Initialize an Image object.
 51
 52        Args:
 53            *args: Variable length argument list.
 54            **kwargs: Arbitrary keyword arguments.
 55        """
 56        super().__init__(*args, **kwargs)
 57
 58    def __repr__(self):
 59        """
 60        Return a string representation of the Image object.
 61
 62        Returns:
 63            str: A string representation of the Image object.
 64        """
 65        return f"Image({self.size}, {self.mode})"
 66
 67    def __str__(self):
 68        """
 69        Return a human-readable string representation of the Image object.
 70
 71        Returns:
 72            str: A human-readable string representation of the Image object.
 73        """
 74        return f"Image of size {self.size} and mode {self.mode}"
 75
 76    @property
 77    def filename(self) -> str:
 78        """
 79        The filename of the image, if available.
 80
 81        Returns:
 82            str: The filename of the image or None if not set.
 83        """
 84        return self.info.get("filename", None)
 85
 86    @property
 87    def format(self) -> str:
 88        """
 89        The format of the image, if available.
 90
 91        Returns:
 92            str: The format of the image (e.g., "JPEG", "PNG") or None if not set.
 93        """
 94        return super().format
 95
 96    @property
 97    def mode(self) -> str:
 98        """
 99        The mode of the image.
100
101        Returns:
102            str: The mode of the image (e.g., "RGB", "L").
103        """
104        return super().mode
105
106    @property
107    def size(self) -> tuple:
108        """
109        The size of the image.
110
111        Returns:
112            tuple: A tuple (width, height) representing the dimensions of the image in pixels.
113        """
114        return super().size
115
116    @property
117    def width(self) -> int:
118        """
119        The width of the image.
120
121        Returns:
122            int: The width of the image in pixels.
123        """
124        return self.size[0]
125
126    @property
127    def height(self) -> int:
128        """
129        The height of the image.
130
131        Returns:
132            int: The height of the image in pixels.
133        """
134        return self.size[1]
135
136    @property
137    def info(self) -> dict:
138        """
139        A dictionary containing miscellaneous information about the image.
140
141        Returns:
142            dict: A dictionary of metadata associated with the image.
143        """
144        return super().info
145
146    @property
147    def palette(self):
148        """
149        The palette of the image, if available.
150
151        Returns:
152            ImagePalette: The palette of the image or None if not applicable.
153        """
154        return super().palette
155
156    @property
157    def category(self) -> str:
158        """
159        The category of the image.
160
161        Returns:
162            str: The category of the image (e.g., "image").
163        """
164        return super().category
165
166    @property
167    def readonly(self) -> bool:
168        """
169        Whether the image is read-only.
170
171        Returns:
172            bool: True if the image is read-only, False otherwise.
173        """
174        return super().readonly
175
176    @property
177    def decoderconfig(self) -> tuple:
178        """
179        The decoder configuration of the image.
180
181        Returns:
182            tuple: A tuple containing the decoder configuration.
183        """
184        return super().decoderconfig
185
186    @property
187    def decodermaxblock(self) -> int:
188        """
189        The maximum block size used by the decoder.
190
191        Returns:
192            int: The maximum block size in bytes.
193        """
194        return super().decodermaxblock
195
196    def alpha_composite(self, im: 'Image', dest: Sequence[int] = (0, 0),
197                                    source: Sequence[int] = (0, 0)) -> 'Image':
198        """
199        Blend two images together using alpha compositing.
200        This method is a wrapper around the PIL alpha_composite method.
201
202        Args:
203            im (Image): The source image to composite with.
204            dest (Sequence[int], optional): The destination coordinates. Defaults to (0, 0).
205            source (Sequence[int], optional): The source coordinates. Defaults to (0, 0).
206
207        Returns:
208            Image: The resulting image after alpha compositing.
209        """
210        return super().alpha_composite(im, dest, source)
211
212    def apply_transparency(self) -> None:
213        """
214        Apply transparency to the image.
215
216        This method is a wrapper around the PIL apply_transparency method.
217        """
218        return super().apply_transparency()
219
220    def convert(self, mode=None, matrix=None, dither=None, palette=0, colors=256):
221        """
222        Converts an image to a different mode.
223
224        Args:
225            mode (str, optional): The requested mode. See: :ref:`concept-modes`.
226            matrix (list, optional): An optional conversion matrix.
227            dither (int, optional): Dithering method, used when converting from mode "RGB" to "P" or from "RGB" or "L" to "1".
228            palette (int, optional): Palette to use when converting from mode "RGB" to "P".
229            colors (int, optional): Number of colors to use for the palette.
230
231        Returns:
232            Image: An Image object.
233        """
234        return super().convert(mode, matrix, dither, palette, colors)
235
236    def copy(self):
237        """
238        Copies this image. Use this method if you wish to paste things into an image, but still retain the original.
239
240        Returns:
241            Image: An Image object.
242        """
243        return super().copy()
244
245    def crop(self, box=None):
246        """
247        Returns a rectangular region from this image. The box is a 4-tuple defining the left, upper, right, and lower pixel coordinate.
248
249        Args:
250            box (tuple, optional): The crop rectangle, as a (left, upper, right, lower)-tuple.
251
252        Returns:
253            Image: An Image object.
254        """
255        return super().crop(box)
256
257    def draft(self, mode, size):
258        """
259        Configures the image file loader so it returns a version of the image that as closely as possible matches the given mode and size.
260
261        Args:
262            mode (str): The requested mode.
263            size (tuple): The requested size.
264
265        Returns:
266            None
267        """
268        return super().draft(mode, size)
269
270    def effect_spread(self, distance):
271        """
272        Randomly spreads pixels in an image.
273
274        Args:
275            distance (int): Distance to spread pixels.
276
277        Returns:
278            Image: An Image object.
279        """
280        return super().effect_spread(distance)
281
282    def filter(self, filter):
283        """
284        Applies the given filter to this image.
285
286        Args:
287            filter (Filter): Filter kernel.
288
289        Returns:
290            Image: An Image object.
291        """
292        return super().filter(filter)
293
294    def getbands(self):
295        """
296        Returns a tuple containing the name of each band in this image. For example, "RGB" returns ("R", "G", "B").
297
298        Returns:
299            tuple: A tuple containing band names.
300        """
301        return super().getbands()
302
303    def getbbox(self):
304        """
305        Calculates the bounding box of the non-zero regions in the image.
306
307        Returns:
308            tuple: The bounding box is returned as a 4-tuple defining the left, upper, right, and lower pixel coordinate.
309        """
310        return super().getbbox()
311
312    def getcolors(self, maxcolors=256):
313        """
314        Returns a list of colors used in this image.
315
316        Args:
317            maxcolors (int, optional): Maximum number of colors. If this number is exceeded, this method stops counting and returns None.
318
319        Returns:
320            list: A list of (count, pixel) values.
321        """
322        return super().getcolors(maxcolors)
323
324    def getdata(self, band=None):
325        """
326        Returns the contents of this image as a sequence object containing pixel values.
327
328        Args:
329            band (int, optional): What band to return. Default is None.
330
331        Returns:
332            Sequence: Pixel values.
333        """
334        return super().getdata(band)
335
336    def getextrema(self):
337        """
338        Gets the minimum and maximum pixel values for each band in the image.
339
340        Returns:
341            tuple: A tuple containing one (min, max) tuple for each band.
342        """
343        return super().getextrema()
344
345    def getpixel(self, xy):
346        """
347        Returns the pixel value at a given position.
348
349        Args:
350            xy (tuple): The coordinate, given as (x, y).
351
352        Returns:
353            Pixel: The pixel value.
354        """
355        return super().getpixel(xy)
356
357    def histogram(self, mask=None, extrema=None):
358        """
359        Returns a histogram for the image.
360
361        Args:
362            mask (Image, optional): A mask image.
363            extrema (tuple, optional): A tuple of manually-specified extrema.
364
365        Returns:
366            list: A list containing pixel counts.
367        """
368        return super().histogram(mask, extrema)
369
370    def paste(self, im, box=None, mask=None):
371        """
372        Pastes another image into this image.
373
374        Args:
375            im (Image or tuple): The source image or pixel value.
376            box (tuple, optional): A 2-tuple giving the upper left corner, or a 4-tuple defining the left, upper, right, and lower pixel coordinate.
377            mask (Image, optional): A mask image.
378
379        Returns:
380            None
381        """
382        return super().paste(im, box, mask)
383
384    def resize(self, size, resample=None, box=None, reducing_gap=None):
385        """
386        Returns a resized copy of this image.
387
388        Args:
389            size (tuple): The requested size in pixels, as a 2-tuple.
390            resample (int, optional): An optional resampling filter.
391            box (tuple, optional): A box to define the region to resize.
392            reducing_gap (float, optional): Apply optimization by resizing the image in two steps.
393
394        Returns:
395            Image: An Image object.
396        """
397        return super().resize(size, resample, box, reducing_gap)
398
399    def rotate(self, angle, resample=0, expand=0, center=None, translate=None, fillcolor=None):
400        """
401        Returns a rotated copy of this image.
402
403        Args:
404            angle (float): The angle to rotate the image.
405            resample (int, optional): An optional resampling filter.
406            expand (int, optional): Optional expansion flag.
407            center (tuple, optional): Optional center of rotation.
408            translate (tuple, optional): An optional post-rotate translation.
409            fillcolor (tuple, optional): Optional fill color for the area outside the rotated image.
410
411        Returns:
412            Image: An Image object.
413        """
414        return super().rotate(angle, resample, expand, center, translate, fillcolor)
415
416    def save(self, fp, format=None, **params):
417        """
418        Saves this image under the given filename.
419
420        Args:
421            fp (str or file object): A filename (string) or file object.
422            format (str, optional): Optional format override.
423            **params: Extra parameters to the image writer.
424
425        Returns:
426            None
427        """
428        return super().save(fp, format, **params)
429
430    def show(self, title=None, command=None):
431        """
432        Displays this image.
433
434        Args:
435            title (str, optional): Optional title for the image window.
436            command (str, optional): Command used to show the image.
437
438        Returns:
439            None
440        """
441        return super().show(title, command)
442
443    def split(self):
444        """
445        Splits this image into individual bands.
446
447        Returns:
448            tuple: A tuple containing individual bands as Image objects.
449        """
450        return super().split()
451
452    def transpose(self, method):
453        """
454        Transposes this image.
455
456        Args:
457            method (int): One of the transpose methods.
458
459        Returns:
460            Image: An Image object.
461        """
462        return super().transpose(method)
463
464open = PIL_Image.open
465alpha_composite = PIL_Image.alpha_composite
466blend = PIL_Image.blend
467composite = PIL_Image.composite
468eval = PIL_Image.eval
469merge = PIL_Image.merge
470new = PIL_Image.new
471# fromarrow = PIL_Image.fromarrow
472frombytes = PIL_Image.frombytes
473frombuffer = PIL_Image.frombuffer
474fromarray = PIL_Image.fromarray
475effect_mandelbrot = PIL_Image.effect_mandelbrot
476effect_noise = PIL_Image.effect_noise
477linear_gradient = PIL_Image.linear_gradient
478radial_gradient = PIL_Image.radial_gradient
479register_open = PIL_Image.register_open
480register_mime = PIL_Image.register_mime
481register_save = PIL_Image.register_save
482register_save_all = PIL_Image.register_save_all
483register_extension = PIL_Image.register_extension
484register_extensions = PIL_Image.register_extensions
485registered_extensions = PIL_Image.registered_extensions
486register_decoder = PIL_Image.register_decoder
487register_encoder = PIL_Image.register_encoder