Skip to content

Image

A container for image data.

Parameters:

Name Type Description Default
image_tensor Tensor

The image data as tensor.

required
Source code in src/safeds/data/image/containers/_image.py
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
class Image:
    """
    A container for image data.

    Parameters
    ----------
    image_tensor:
        The image data as tensor.
    """

    _filter_edges_kernel_cache: Tensor | None = None

    @staticmethod
    def _filter_edges_kernel() -> Tensor:
        import torch

        if Image._filter_edges_kernel_cache is None:
            Image._filter_edges_kernel_cache = (
                torch.tensor([[-1.0, -1.0, -1.0], [-1.0, 8.0, -1.0], [-1.0, -1.0, -1.0]])
                .unsqueeze(dim=0)
                .unsqueeze(dim=0)
                .to(_get_device())
            )

        return Image._filter_edges_kernel_cache

    @staticmethod
    def from_file(path: str | Path, device: Device = None) -> Image:
        """
        Create an image from a file.

        Parameters
        ----------
        path:
            The path to the image file.
        device:
            The device where the tensor will be saved on. Defaults to the default device

        Returns
        -------
        image:
            The image.

        Raises
        ------
        FileNotFoundError
            If the file of the path cannot be found
        """
        from PIL.Image import open as pil_image_open
        from torchvision.transforms.functional import pil_to_tensor

        if device is None:
            device = _get_device()

        return Image(image_tensor=pil_to_tensor(pil_image_open(path)), device=device)

    @staticmethod
    def from_bytes(data: bytes, device: Device = None) -> Image:
        """
        Create an image from bytes.

        Parameters
        ----------
        data:
            The data of the image.
        device:
            The device where the tensor will be saved on. Defaults to the default device

        Returns
        -------
        image:
            The image.
        """
        import torch
        import torchvision

        if device is None:
            device = _get_device()

        with warnings.catch_warnings():
            warnings.filterwarnings(
                "ignore",
                message="The given buffer is not writable, and PyTorch does not support non-writable tensors.",
            )
            input_tensor = torch.frombuffer(data, dtype=torch.uint8)

        return Image(image_tensor=torchvision.io.decode_image(input_tensor), device=device)

    def __init__(self, image_tensor: Tensor, device: Device = None) -> None:
        if device is None:
            device = _get_device()

        self._image_tensor: Tensor = image_tensor.to(device)

    def __eq__(self, other: object) -> bool:
        """
        Compare two images.

        Parameters
        ----------
        other:
            The image to compare to.

        Returns
        -------
        equals:
            Whether the two images contain equal pixel data.
        """
        import torch

        if not isinstance(other, Image):
            return NotImplemented
        return (
            self._image_tensor.size() == other._image_tensor.size()
            and torch.all(torch.eq(self._image_tensor, other._set_device(self.device)._image_tensor)).item()
        )

    def __hash__(self) -> int:
        """
        Return a deterministic hash value for this image.

        Returns
        -------
        hash:
            The hash value.
        """
        return _structural_hash(self.width, self.height, self.channel)

    def __sizeof__(self) -> int:
        """
        Return the complete size of this object.

        Returns
        -------
        size:
            Size of this object in bytes.
        """
        return sys.getsizeof(self._image_tensor) + self._image_tensor.element_size() * self._image_tensor.nelement()

    def _repr_jpeg_(self) -> bytes | None:
        """
        Return a JPEG image as bytes.

        If the image has an alpha channel return None.

        Returns
        -------
        jpeg:
            The image as JPEG.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2
        from torchvision.utils import save_image

        if self.channel == 4:
            return None
        buffer = io.BytesIO()
        if self.channel == 1:
            func2.to_pil_image(self._image_tensor, mode="L").save(buffer, format="jpeg")
        else:
            save_image(self._image_tensor.to(torch.float32) / 255, buffer, format="jpeg")
        buffer.seek(0)
        return buffer.read()

    def _repr_png_(self) -> bytes:
        """
        Return a PNG image as bytes.

        Returns
        -------
        png:
            The image as PNG.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2
        from torchvision.utils import save_image

        buffer = io.BytesIO()
        if self.channel == 1:
            func2.to_pil_image(self._image_tensor, mode="L").save(buffer, format="png")
        else:
            save_image(self._image_tensor.to(torch.float32) / 255, buffer, format="png")
        buffer.seek(0)
        return buffer.read()

    def _set_device(self, device: Device) -> Image:
        """
        Set the device where the image will be saved on.

        Returns
        -------
        result:
            The image on the given device
        """
        return Image(self._image_tensor, device)

    # ------------------------------------------------------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------------------------------------------------------

    @property
    def width(self) -> int:
        """
        Get the width of the image in pixels.

        Returns
        -------
        width:
            The width of the image.
        """
        return self._image_tensor.size(dim=2)

    @property
    def height(self) -> int:
        """
        Get the height of the image in pixels.

        Returns
        -------
        height:
            The height of the image.
        """
        return self._image_tensor.size(dim=1)

    @property
    def channel(self) -> int:
        """
        Get the number of channels of the image.

        Returns
        -------
        channel:
            The number of channels of the image.
        """
        return self._image_tensor.size(dim=0)

    @property
    def device(self) -> Device:
        """
        Get the device where the image is saved on.

        Returns
        -------
        device:
            The device of the image
        """
        return self._image_tensor.device

    # ------------------------------------------------------------------------------------------------------------------
    # Conversion
    # ------------------------------------------------------------------------------------------------------------------

    def to_jpeg_file(self, path: str | Path) -> None:
        """
        Save the image as a JPEG file.

        Parameters
        ----------
        path:
            The path to the JPEG file.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2
        from torchvision.utils import save_image

        if self.channel == 4:
            raise IllegalFormatError("png")
        Path(path).parent.mkdir(parents=True, exist_ok=True)
        if self.channel == 1:
            func2.to_pil_image(self._image_tensor, mode="L").save(path, format="jpeg")
        else:
            save_image(self._image_tensor.to(torch.float32) / 255, path, format="jpeg")

    def to_png_file(self, path: str | Path) -> None:
        """
        Save the image as a PNG file.

        Parameters
        ----------
        path:
            The path to the PNG file.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2
        from torchvision.utils import save_image

        Path(path).parent.mkdir(parents=True, exist_ok=True)
        if self.channel == 1:
            func2.to_pil_image(self._image_tensor, mode="L").save(path, format="png")
        else:
            save_image(self._image_tensor.to(torch.float32) / 255, path, format="png")

    # ------------------------------------------------------------------------------------------------------------------
    # Transformations
    # ------------------------------------------------------------------------------------------------------------------

    def change_channel(self, channel: int) -> Image:
        """
        Return a new `Image` that has the given number of channels.

        The original image is not modified.

        Parameters
        ----------
        channel:
            The new number of channels. 1 will result in a grayscale image.

        Returns
        -------
        result:
            The image with the given number of channels.

        Raises
        ------
        ValueError
            if the given channel is not a valid channel option
        """
        import torch

        if self.channel == channel:
            image_tensor = self._image_tensor
        elif self.channel == 1 and channel == 3:
            image_tensor = torch.cat([self._image_tensor, self._image_tensor, self._image_tensor], dim=0)
        elif self.channel == 1 and channel == 4:
            image_tensor = torch.cat(
                [
                    self._image_tensor,
                    self._image_tensor,
                    self._image_tensor,
                    torch.full(self._image_tensor.size(), 255).to(self.device),
                ],
                dim=0,
            )
        elif self.channel in (3, 4) and channel == 1:
            image_tensor = self.convert_to_grayscale()._image_tensor[0:1]
        elif self.channel == 3 and channel == 4:
            image_tensor = torch.cat(
                [self._image_tensor, torch.full(self._image_tensor[0:1].size(), 255).to(self.device)],
                dim=0,
            )
        elif self.channel == 4 and channel == 3:
            image_tensor = self._image_tensor[0:3]
        else:
            raise ValueError(f"Channel {channel} is not a valid channel option. Use either 1, 3 or 4")
        return Image(image_tensor, device=self._image_tensor.device)

    def resize(self, new_width: int, new_height: int) -> Image:
        """
        Return a new `Image` that has been resized to a given size.

        The original image is not modified.

        Parameters
        ----------
        new_width:
            the new width of the image
        new_height:
            the new height of the image

        Returns
        -------
        result:
            The image with the given width and height.

        Raises
        ------
        OutOfBoundsError
            If new_width or new_height are below 1
        """
        from torchvision.transforms import InterpolationMode
        from torchvision.transforms.v2 import functional as func2

        _check_resize_errors(new_width, new_height)
        return Image(
            func2.resize(self._image_tensor, size=[new_height, new_width], interpolation=InterpolationMode.NEAREST),
            device=self._image_tensor.device,
        )

    def convert_to_grayscale(self) -> Image:
        """
        Return a new `Image` that is converted to grayscale.

        The original image is not modified.

        Returns
        -------
        result:
            The grayscale image.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2

        if self.channel == 4:
            return Image(
                torch.cat(
                    [
                        func2.rgb_to_grayscale(self._image_tensor[0:3], num_output_channels=3),
                        self._image_tensor[3].unsqueeze(dim=0),
                    ],
                ),
                device=self.device,
            )
        else:
            return Image(func2.rgb_to_grayscale(self._image_tensor[0:3], num_output_channels=3), device=self.device)

    def crop(self, x: int, y: int, width: int, height: int) -> Image:
        """
        Return a new `Image` that has been cropped to a given bounding rectangle.

        The original image is not modified.

        Parameters
        ----------
        x:
            the x coordinate of the top-left corner of the bounding rectangle
        y:
            the y coordinate of the top-left corner of the bounding rectangle
        width:
            the width of the bounding rectangle
        height:
            the height of the bounding rectangle

        Returns
        -------
        result:
            The cropped image.

        Raises
        ------
        OutOfBoundsError
            If x or y are below 0 or if width or height are below 1
        """
        from torchvision.transforms.v2 import functional as func2

        _check_crop_errors_and_warnings(x, y, width, height, self.width, self.height, plural=False)
        return Image(func2.crop(self._image_tensor, y, x, height, width), device=self.device)

    def flip_vertically(self) -> Image:
        """
        Return a new `Image` that is flipped vertically (horizontal axis, flips up-down and vice versa).

        The original image is not modified.

        Returns
        -------
        result:
            The flipped image.
        """
        from torchvision.transforms.v2 import functional as func2

        return Image(func2.vertical_flip(self._image_tensor), device=self.device)

    def flip_horizontally(self) -> Image:
        """
        Return a new `Image` that is flipped horizontally (vertical axis, flips left-right and vice versa).

        The original image is not modified.

        Returns
        -------
        result:
            The flipped image.
        """
        from torchvision.transforms.v2 import functional as func2

        return Image(func2.horizontal_flip(self._image_tensor), device=self.device)

    def adjust_brightness(self, factor: float) -> Image:
        """
        Return a new `Image` with an adjusted brightness.

        The original image is not modified.

        Parameters
        ----------
        factor:
            The brightness factor.
            1.0 will not change the brightness.
            Below 1.0 will result in a darker image.
            Above 1.0 will resolut in a brighter image.
            Has to be bigger than or equal to 0 (black).

        Returns
        -------
        result:
            The Image with adjusted brightness.

        Raises
        ------
        OutOfBoundsError
            If factor is smaller than 0.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2

        _check_adjust_brightness_errors_and_warnings(factor, plural=False)
        if self.channel == 4:
            return Image(
                torch.cat(
                    [
                        func2.adjust_brightness(self._image_tensor[0:3], factor * 1.0),
                        self._image_tensor[3].unsqueeze(dim=0),
                    ],
                ),
                device=self.device,
            )
        else:
            return Image(func2.adjust_brightness(self._image_tensor, factor * 1.0), device=self.device)

    def add_noise(self, standard_deviation: float) -> Image:
        """
        Return a new `Image` with noise added to the image.

        The original image is not modified.

        Parameters
        ----------
        standard_deviation:
            The standard deviation of the normal distribution. Has to be bigger than or equal to 0.

        Returns
        -------
        result:
            The image with added noise.

        Raises
        ------
        OutOfBoundsError
            If standard_deviation is smaller than 0.
        """
        import torch

        _check_add_noise_errors(standard_deviation)
        return Image(
            self._image_tensor + torch.normal(0, standard_deviation, self._image_tensor.size()).to(self.device) * 255,
            device=self.device,
        )

    def adjust_contrast(self, factor: float) -> Image:
        """
        Return a new `Image` with adjusted contrast.

        The original image is not modified.

        Parameters
        ----------
        factor:
            If factor > 1, increase contrast of image.
            If factor = 1, no changes will be made.
            If factor < 1, make image greyer.
            Has to be bigger than or equal to 0 (gray).

        Returns
        -------
        image:
            New image with adjusted contrast.

        Raises
        ------
        OutOfBoundsError
            If factor is smaller than 0.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2

        _check_adjust_contrast_errors_and_warnings(factor, plural=False)
        if self.channel == 4:
            return Image(
                torch.cat(
                    [
                        func2.adjust_contrast(self._image_tensor[0:3], factor * 1.0),
                        self._image_tensor[3].unsqueeze(dim=0),
                    ],
                ),
                device=self.device,
            )
        else:
            return Image(func2.adjust_contrast(self._image_tensor, factor * 1.0), device=self.device)

    def adjust_color_balance(self, factor: float) -> Image:
        """
        Return a new `Image` with adjusted color balance.

        The original image is not modified.

        Parameters
        ----------
        factor:
            Has to be bigger than or equal to 0.
            If 0 <= factor < 1, make image greyer.
            If factor = 1, no changes will be made.
            If factor > 1, increase color balance of image.

        Returns
        -------
        image:
            The new, adjusted image.

        Raises
        ------
        OutOfBoundsError
            If factor is smaller than 0.
        """
        _check_adjust_color_balance_errors_and_warnings(factor, self.channel, plural=False)
        return Image(
            self.convert_to_grayscale()._image_tensor * (1.0 - factor * 1.0) + self._image_tensor * (factor * 1.0),
            device=self.device,
        )

    def blur(self, radius: int) -> Image:
        """
        Return a blurred version of the image.

        The original image is not modified.

        Parameters
        ----------
        radius:
             Radius is directly proportional to the blur value. The radius is equal to the amount of pixels united in
             each direction. A radius of 1 will result in a united box of 9 pixels.

        Returns
        -------
        result:
            The blurred image.

        Raises
        ------
        OutOfBoundsError
            If radius is smaller than 0 or equal or greater than the smaller size of the image.
        """
        from torchvision.transforms.v2 import functional as func2

        _check_blur_errors_and_warnings(radius, min(self.width, self.height), plural=False)
        return Image(func2.gaussian_blur(self._image_tensor, [radius * 2 + 1, radius * 2 + 1]), device=self.device)

    def sharpen(self, factor: float) -> Image:
        """
        Return a sharpened version of the image.

        The original image is not modified.

        Parameters
        ----------
        factor:
            If factor > 1, increase the sharpness of the image.
            If factor = 1, no changes will be made.
            If factor < 1, blur the image.
            Has to be bigger than or equal to 0 (blurred).

        Returns
        -------
        result:
            The image sharpened by the given factor.

        Raises
        ------
        OutOfBoundsError
            If factor is smaller than 0.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2

        _check_sharpen_errors_and_warnings(factor, plural=False)
        if self.channel == 4:
            return Image(
                torch.cat(
                    [
                        func2.adjust_sharpness(self._image_tensor[0:3], factor * 1.0),
                        self._image_tensor[3].unsqueeze(dim=0),
                    ],
                ),
                device=self.device,
            )
        else:
            return Image(func2.adjust_sharpness(self._image_tensor, factor * 1.0), device=self.device)

    def invert_colors(self) -> Image:
        """
        Return a new `Image` with colors inverted.

        The original image is not modified.

        Returns
        -------
        result:
            The image with inverted colors.
        """
        import torch
        from torchvision.transforms.v2 import functional as func2

        if self.channel == 4:
            return Image(
                torch.cat([func2.invert(self._image_tensor[0:3]), self._image_tensor[3].unsqueeze(dim=0)]),
                device=self.device,
            )
        else:
            return Image(func2.invert(self._image_tensor), device=self.device)

    def rotate_right(self) -> Image:
        """
        Return a new `Image` that is rotated 90 degrees clockwise.

        The original image is not modified.

        Returns
        -------
        result:
            The image rotated 90 degrees clockwise.
        """
        from torchvision.transforms.v2 import functional as func2

        return Image(func2.rotate(self._image_tensor, -90, expand=True), device=self.device)

    def rotate_left(self) -> Image:
        """
        Return a new `Image` that is rotated 90 degrees counter-clockwise.

        The original image is not modified.

        Returns
        -------
        result:
            The image rotated 90 degrees counter-clockwise.
        """
        from torchvision.transforms.v2 import functional as func2

        return Image(func2.rotate(self._image_tensor, 90, expand=True), device=self.device)

    def find_edges(self) -> Image:
        """
        Return a grayscale version of the image with the edges highlighted.

        The original image is not modified.

        Returns
        -------
        result:
            The image with edges found.
        """
        import torch

        kernel = (
            Image._filter_edges_kernel()
            if self.device.type == _get_device()
            else Image._filter_edges_kernel().to(self.device)
        )
        edges_tensor = torch.clamp(
            torch.nn.functional.conv2d(
                self.convert_to_grayscale()._image_tensor.float()[0].unsqueeze(dim=0),
                kernel,
                padding="same",
            ).squeeze(dim=1),
            0,
            255,
        ).to(torch.uint8)
        if self.channel == 3:
            return Image(edges_tensor.repeat(3, 1, 1), device=self.device)
        elif self.channel == 4:
            return Image(
                torch.cat([edges_tensor.repeat(3, 1, 1), self._image_tensor[3].unsqueeze(dim=0)]),
                device=self.device,
            )
        else:
            return Image(edges_tensor, device=self.device)

channel: int property

Get the number of channels of the image.

Returns:

Name Type Description
channel int

The number of channels of the image.

device: Device property

Get the device where the image is saved on.

Returns:

Name Type Description
device Device

The device of the image

height: int property

Get the height of the image in pixels.

Returns:

Name Type Description
height int

The height of the image.

width: int property

Get the width of the image in pixels.

Returns:

Name Type Description
width int

The width of the image.

__eq__(other)

Compare two images.

Parameters:

Name Type Description Default
other object

The image to compare to.

required

Returns:

Name Type Description
equals bool

Whether the two images contain equal pixel data.

Source code in src/safeds/data/image/containers/_image.py
def __eq__(self, other: object) -> bool:
    """
    Compare two images.

    Parameters
    ----------
    other:
        The image to compare to.

    Returns
    -------
    equals:
        Whether the two images contain equal pixel data.
    """
    import torch

    if not isinstance(other, Image):
        return NotImplemented
    return (
        self._image_tensor.size() == other._image_tensor.size()
        and torch.all(torch.eq(self._image_tensor, other._set_device(self.device)._image_tensor)).item()
    )

__hash__()

Return a deterministic hash value for this image.

Returns:

Name Type Description
hash int

The hash value.

Source code in src/safeds/data/image/containers/_image.py
def __hash__(self) -> int:
    """
    Return a deterministic hash value for this image.

    Returns
    -------
    hash:
        The hash value.
    """
    return _structural_hash(self.width, self.height, self.channel)

__init__(image_tensor, device=None)

Source code in src/safeds/data/image/containers/_image.py
def __init__(self, image_tensor: Tensor, device: Device = None) -> None:
    if device is None:
        device = _get_device()

    self._image_tensor: Tensor = image_tensor.to(device)

__sizeof__()

Return the complete size of this object.

Returns:

Name Type Description
size int

Size of this object in bytes.

Source code in src/safeds/data/image/containers/_image.py
def __sizeof__(self) -> int:
    """
    Return the complete size of this object.

    Returns
    -------
    size:
        Size of this object in bytes.
    """
    return sys.getsizeof(self._image_tensor) + self._image_tensor.element_size() * self._image_tensor.nelement()

add_noise(standard_deviation)

Return a new Image with noise added to the image.

The original image is not modified.

Parameters:

Name Type Description Default
standard_deviation float

The standard deviation of the normal distribution. Has to be bigger than or equal to 0.

required

Returns:

Name Type Description
result Image

The image with added noise.

Raises:

Type Description
OutOfBoundsError

If standard_deviation is smaller than 0.

Source code in src/safeds/data/image/containers/_image.py
def add_noise(self, standard_deviation: float) -> Image:
    """
    Return a new `Image` with noise added to the image.

    The original image is not modified.

    Parameters
    ----------
    standard_deviation:
        The standard deviation of the normal distribution. Has to be bigger than or equal to 0.

    Returns
    -------
    result:
        The image with added noise.

    Raises
    ------
    OutOfBoundsError
        If standard_deviation is smaller than 0.
    """
    import torch

    _check_add_noise_errors(standard_deviation)
    return Image(
        self._image_tensor + torch.normal(0, standard_deviation, self._image_tensor.size()).to(self.device) * 255,
        device=self.device,
    )

adjust_brightness(factor)

Return a new Image with an adjusted brightness.

The original image is not modified.

Parameters:

Name Type Description Default
factor float

The brightness factor. 1.0 will not change the brightness. Below 1.0 will result in a darker image. Above 1.0 will resolut in a brighter image. Has to be bigger than or equal to 0 (black).

required

Returns:

Name Type Description
result Image

The Image with adjusted brightness.

Raises:

Type Description
OutOfBoundsError

If factor is smaller than 0.

Source code in src/safeds/data/image/containers/_image.py
def adjust_brightness(self, factor: float) -> Image:
    """
    Return a new `Image` with an adjusted brightness.

    The original image is not modified.

    Parameters
    ----------
    factor:
        The brightness factor.
        1.0 will not change the brightness.
        Below 1.0 will result in a darker image.
        Above 1.0 will resolut in a brighter image.
        Has to be bigger than or equal to 0 (black).

    Returns
    -------
    result:
        The Image with adjusted brightness.

    Raises
    ------
    OutOfBoundsError
        If factor is smaller than 0.
    """
    import torch
    from torchvision.transforms.v2 import functional as func2

    _check_adjust_brightness_errors_and_warnings(factor, plural=False)
    if self.channel == 4:
        return Image(
            torch.cat(
                [
                    func2.adjust_brightness(self._image_tensor[0:3], factor * 1.0),
                    self._image_tensor[3].unsqueeze(dim=0),
                ],
            ),
            device=self.device,
        )
    else:
        return Image(func2.adjust_brightness(self._image_tensor, factor * 1.0), device=self.device)

adjust_color_balance(factor)

Return a new Image with adjusted color balance.

The original image is not modified.

Parameters:

Name Type Description Default
factor float

Has to be bigger than or equal to 0. If 0 <= factor < 1, make image greyer. If factor = 1, no changes will be made. If factor > 1, increase color balance of image.

required

Returns:

Name Type Description
image Image

The new, adjusted image.

Raises:

Type Description
OutOfBoundsError

If factor is smaller than 0.

Source code in src/safeds/data/image/containers/_image.py
def adjust_color_balance(self, factor: float) -> Image:
    """
    Return a new `Image` with adjusted color balance.

    The original image is not modified.

    Parameters
    ----------
    factor:
        Has to be bigger than or equal to 0.
        If 0 <= factor < 1, make image greyer.
        If factor = 1, no changes will be made.
        If factor > 1, increase color balance of image.

    Returns
    -------
    image:
        The new, adjusted image.

    Raises
    ------
    OutOfBoundsError
        If factor is smaller than 0.
    """
    _check_adjust_color_balance_errors_and_warnings(factor, self.channel, plural=False)
    return Image(
        self.convert_to_grayscale()._image_tensor * (1.0 - factor * 1.0) + self._image_tensor * (factor * 1.0),
        device=self.device,
    )

adjust_contrast(factor)

Return a new Image with adjusted contrast.

The original image is not modified.

Parameters:

Name Type Description Default
factor float

If factor > 1, increase contrast of image. If factor = 1, no changes will be made. If factor < 1, make image greyer. Has to be bigger than or equal to 0 (gray).

required

Returns:

Name Type Description
image Image

New image with adjusted contrast.

Raises:

Type Description
OutOfBoundsError

If factor is smaller than 0.

Source code in src/safeds/data/image/containers/_image.py
def adjust_contrast(self, factor: float) -> Image:
    """
    Return a new `Image` with adjusted contrast.

    The original image is not modified.

    Parameters
    ----------
    factor:
        If factor > 1, increase contrast of image.
        If factor = 1, no changes will be made.
        If factor < 1, make image greyer.
        Has to be bigger than or equal to 0 (gray).

    Returns
    -------
    image:
        New image with adjusted contrast.

    Raises
    ------
    OutOfBoundsError
        If factor is smaller than 0.
    """
    import torch
    from torchvision.transforms.v2 import functional as func2

    _check_adjust_contrast_errors_and_warnings(factor, plural=False)
    if self.channel == 4:
        return Image(
            torch.cat(
                [
                    func2.adjust_contrast(self._image_tensor[0:3], factor * 1.0),
                    self._image_tensor[3].unsqueeze(dim=0),
                ],
            ),
            device=self.device,
        )
    else:
        return Image(func2.adjust_contrast(self._image_tensor, factor * 1.0), device=self.device)

blur(radius)

Return a blurred version of the image.

The original image is not modified.

Parameters:

Name Type Description Default
radius int

Radius is directly proportional to the blur value. The radius is equal to the amount of pixels united in each direction. A radius of 1 will result in a united box of 9 pixels.

required

Returns:

Name Type Description
result Image

The blurred image.

Raises:

Type Description
OutOfBoundsError

If radius is smaller than 0 or equal or greater than the smaller size of the image.

Source code in src/safeds/data/image/containers/_image.py
def blur(self, radius: int) -> Image:
    """
    Return a blurred version of the image.

    The original image is not modified.

    Parameters
    ----------
    radius:
         Radius is directly proportional to the blur value. The radius is equal to the amount of pixels united in
         each direction. A radius of 1 will result in a united box of 9 pixels.

    Returns
    -------
    result:
        The blurred image.

    Raises
    ------
    OutOfBoundsError
        If radius is smaller than 0 or equal or greater than the smaller size of the image.
    """
    from torchvision.transforms.v2 import functional as func2

    _check_blur_errors_and_warnings(radius, min(self.width, self.height), plural=False)
    return Image(func2.gaussian_blur(self._image_tensor, [radius * 2 + 1, radius * 2 + 1]), device=self.device)

change_channel(channel)

Return a new Image that has the given number of channels.

The original image is not modified.

Parameters:

Name Type Description Default
channel int

The new number of channels. 1 will result in a grayscale image.

required

Returns:

Name Type Description
result Image

The image with the given number of channels.

Raises:

Type Description
ValueError

if the given channel is not a valid channel option

Source code in src/safeds/data/image/containers/_image.py
def change_channel(self, channel: int) -> Image:
    """
    Return a new `Image` that has the given number of channels.

    The original image is not modified.

    Parameters
    ----------
    channel:
        The new number of channels. 1 will result in a grayscale image.

    Returns
    -------
    result:
        The image with the given number of channels.

    Raises
    ------
    ValueError
        if the given channel is not a valid channel option
    """
    import torch

    if self.channel == channel:
        image_tensor = self._image_tensor
    elif self.channel == 1 and channel == 3:
        image_tensor = torch.cat([self._image_tensor, self._image_tensor, self._image_tensor], dim=0)
    elif self.channel == 1 and channel == 4:
        image_tensor = torch.cat(
            [
                self._image_tensor,
                self._image_tensor,
                self._image_tensor,
                torch.full(self._image_tensor.size(), 255).to(self.device),
            ],
            dim=0,
        )
    elif self.channel in (3, 4) and channel == 1:
        image_tensor = self.convert_to_grayscale()._image_tensor[0:1]
    elif self.channel == 3 and channel == 4:
        image_tensor = torch.cat(
            [self._image_tensor, torch.full(self._image_tensor[0:1].size(), 255).to(self.device)],
            dim=0,
        )
    elif self.channel == 4 and channel == 3:
        image_tensor = self._image_tensor[0:3]
    else:
        raise ValueError(f"Channel {channel} is not a valid channel option. Use either 1, 3 or 4")
    return Image(image_tensor, device=self._image_tensor.device)

convert_to_grayscale()

Return a new Image that is converted to grayscale.

The original image is not modified.

Returns:

Name Type Description
result Image

The grayscale image.

Source code in src/safeds/data/image/containers/_image.py
def convert_to_grayscale(self) -> Image:
    """
    Return a new `Image` that is converted to grayscale.

    The original image is not modified.

    Returns
    -------
    result:
        The grayscale image.
    """
    import torch
    from torchvision.transforms.v2 import functional as func2

    if self.channel == 4:
        return Image(
            torch.cat(
                [
                    func2.rgb_to_grayscale(self._image_tensor[0:3], num_output_channels=3),
                    self._image_tensor[3].unsqueeze(dim=0),
                ],
            ),
            device=self.device,
        )
    else:
        return Image(func2.rgb_to_grayscale(self._image_tensor[0:3], num_output_channels=3), device=self.device)

crop(x, y, width, height)

Return a new Image that has been cropped to a given bounding rectangle.

The original image is not modified.

Parameters:

Name Type Description Default
x int

the x coordinate of the top-left corner of the bounding rectangle

required
y int

the y coordinate of the top-left corner of the bounding rectangle

required
width int

the width of the bounding rectangle

required
height int

the height of the bounding rectangle

required

Returns:

Name Type Description
result Image

The cropped image.

Raises:

Type Description
OutOfBoundsError

If x or y are below 0 or if width or height are below 1

Source code in src/safeds/data/image/containers/_image.py
def crop(self, x: int, y: int, width: int, height: int) -> Image:
    """
    Return a new `Image` that has been cropped to a given bounding rectangle.

    The original image is not modified.

    Parameters
    ----------
    x:
        the x coordinate of the top-left corner of the bounding rectangle
    y:
        the y coordinate of the top-left corner of the bounding rectangle
    width:
        the width of the bounding rectangle
    height:
        the height of the bounding rectangle

    Returns
    -------
    result:
        The cropped image.

    Raises
    ------
    OutOfBoundsError
        If x or y are below 0 or if width or height are below 1
    """
    from torchvision.transforms.v2 import functional as func2

    _check_crop_errors_and_warnings(x, y, width, height, self.width, self.height, plural=False)
    return Image(func2.crop(self._image_tensor, y, x, height, width), device=self.device)

find_edges()

Return a grayscale version of the image with the edges highlighted.

The original image is not modified.

Returns:

Name Type Description
result Image

The image with edges found.

Source code in src/safeds/data/image/containers/_image.py
def find_edges(self) -> Image:
    """
    Return a grayscale version of the image with the edges highlighted.

    The original image is not modified.

    Returns
    -------
    result:
        The image with edges found.
    """
    import torch

    kernel = (
        Image._filter_edges_kernel()
        if self.device.type == _get_device()
        else Image._filter_edges_kernel().to(self.device)
    )
    edges_tensor = torch.clamp(
        torch.nn.functional.conv2d(
            self.convert_to_grayscale()._image_tensor.float()[0].unsqueeze(dim=0),
            kernel,
            padding="same",
        ).squeeze(dim=1),
        0,
        255,
    ).to(torch.uint8)
    if self.channel == 3:
        return Image(edges_tensor.repeat(3, 1, 1), device=self.device)
    elif self.channel == 4:
        return Image(
            torch.cat([edges_tensor.repeat(3, 1, 1), self._image_tensor[3].unsqueeze(dim=0)]),
            device=self.device,
        )
    else:
        return Image(edges_tensor, device=self.device)

flip_horizontally()

Return a new Image that is flipped horizontally (vertical axis, flips left-right and vice versa).

The original image is not modified.

Returns:

Name Type Description
result Image

The flipped image.

Source code in src/safeds/data/image/containers/_image.py
def flip_horizontally(self) -> Image:
    """
    Return a new `Image` that is flipped horizontally (vertical axis, flips left-right and vice versa).

    The original image is not modified.

    Returns
    -------
    result:
        The flipped image.
    """
    from torchvision.transforms.v2 import functional as func2

    return Image(func2.horizontal_flip(self._image_tensor), device=self.device)

flip_vertically()

Return a new Image that is flipped vertically (horizontal axis, flips up-down and vice versa).

The original image is not modified.

Returns:

Name Type Description
result Image

The flipped image.

Source code in src/safeds/data/image/containers/_image.py
def flip_vertically(self) -> Image:
    """
    Return a new `Image` that is flipped vertically (horizontal axis, flips up-down and vice versa).

    The original image is not modified.

    Returns
    -------
    result:
        The flipped image.
    """
    from torchvision.transforms.v2 import functional as func2

    return Image(func2.vertical_flip(self._image_tensor), device=self.device)

from_bytes(data, device=None) staticmethod

Create an image from bytes.

Parameters:

Name Type Description Default
data bytes

The data of the image.

required
device Device

The device where the tensor will be saved on. Defaults to the default device

None

Returns:

Name Type Description
image Image

The image.

Source code in src/safeds/data/image/containers/_image.py
@staticmethod
def from_bytes(data: bytes, device: Device = None) -> Image:
    """
    Create an image from bytes.

    Parameters
    ----------
    data:
        The data of the image.
    device:
        The device where the tensor will be saved on. Defaults to the default device

    Returns
    -------
    image:
        The image.
    """
    import torch
    import torchvision

    if device is None:
        device = _get_device()

    with warnings.catch_warnings():
        warnings.filterwarnings(
            "ignore",
            message="The given buffer is not writable, and PyTorch does not support non-writable tensors.",
        )
        input_tensor = torch.frombuffer(data, dtype=torch.uint8)

    return Image(image_tensor=torchvision.io.decode_image(input_tensor), device=device)

from_file(path, device=None) staticmethod

Create an image from a file.

Parameters:

Name Type Description Default
path str | Path

The path to the image file.

required
device Device

The device where the tensor will be saved on. Defaults to the default device

None

Returns:

Name Type Description
image Image

The image.

Raises:

Type Description
FileNotFoundError

If the file of the path cannot be found

Source code in src/safeds/data/image/containers/_image.py
@staticmethod
def from_file(path: str | Path, device: Device = None) -> Image:
    """
    Create an image from a file.

    Parameters
    ----------
    path:
        The path to the image file.
    device:
        The device where the tensor will be saved on. Defaults to the default device

    Returns
    -------
    image:
        The image.

    Raises
    ------
    FileNotFoundError
        If the file of the path cannot be found
    """
    from PIL.Image import open as pil_image_open
    from torchvision.transforms.functional import pil_to_tensor

    if device is None:
        device = _get_device()

    return Image(image_tensor=pil_to_tensor(pil_image_open(path)), device=device)

invert_colors()

Return a new Image with colors inverted.

The original image is not modified.

Returns:

Name Type Description
result Image

The image with inverted colors.

Source code in src/safeds/data/image/containers/_image.py
def invert_colors(self) -> Image:
    """
    Return a new `Image` with colors inverted.

    The original image is not modified.

    Returns
    -------
    result:
        The image with inverted colors.
    """
    import torch
    from torchvision.transforms.v2 import functional as func2

    if self.channel == 4:
        return Image(
            torch.cat([func2.invert(self._image_tensor[0:3]), self._image_tensor[3].unsqueeze(dim=0)]),
            device=self.device,
        )
    else:
        return Image(func2.invert(self._image_tensor), device=self.device)

resize(new_width, new_height)

Return a new Image that has been resized to a given size.

The original image is not modified.

Parameters:

Name Type Description Default
new_width int

the new width of the image

required
new_height int

the new height of the image

required

Returns:

Name Type Description
result Image

The image with the given width and height.

Raises:

Type Description
OutOfBoundsError

If new_width or new_height are below 1

Source code in src/safeds/data/image/containers/_image.py
def resize(self, new_width: int, new_height: int) -> Image:
    """
    Return a new `Image` that has been resized to a given size.

    The original image is not modified.

    Parameters
    ----------
    new_width:
        the new width of the image
    new_height:
        the new height of the image

    Returns
    -------
    result:
        The image with the given width and height.

    Raises
    ------
    OutOfBoundsError
        If new_width or new_height are below 1
    """
    from torchvision.transforms import InterpolationMode
    from torchvision.transforms.v2 import functional as func2

    _check_resize_errors(new_width, new_height)
    return Image(
        func2.resize(self._image_tensor, size=[new_height, new_width], interpolation=InterpolationMode.NEAREST),
        device=self._image_tensor.device,
    )

rotate_left()

Return a new Image that is rotated 90 degrees counter-clockwise.

The original image is not modified.

Returns:

Name Type Description
result Image

The image rotated 90 degrees counter-clockwise.

Source code in src/safeds/data/image/containers/_image.py
def rotate_left(self) -> Image:
    """
    Return a new `Image` that is rotated 90 degrees counter-clockwise.

    The original image is not modified.

    Returns
    -------
    result:
        The image rotated 90 degrees counter-clockwise.
    """
    from torchvision.transforms.v2 import functional as func2

    return Image(func2.rotate(self._image_tensor, 90, expand=True), device=self.device)

rotate_right()

Return a new Image that is rotated 90 degrees clockwise.

The original image is not modified.

Returns:

Name Type Description
result Image

The image rotated 90 degrees clockwise.

Source code in src/safeds/data/image/containers/_image.py
def rotate_right(self) -> Image:
    """
    Return a new `Image` that is rotated 90 degrees clockwise.

    The original image is not modified.

    Returns
    -------
    result:
        The image rotated 90 degrees clockwise.
    """
    from torchvision.transforms.v2 import functional as func2

    return Image(func2.rotate(self._image_tensor, -90, expand=True), device=self.device)

sharpen(factor)

Return a sharpened version of the image.

The original image is not modified.

Parameters:

Name Type Description Default
factor float

If factor > 1, increase the sharpness of the image. If factor = 1, no changes will be made. If factor < 1, blur the image. Has to be bigger than or equal to 0 (blurred).

required

Returns:

Name Type Description
result Image

The image sharpened by the given factor.

Raises:

Type Description
OutOfBoundsError

If factor is smaller than 0.

Source code in src/safeds/data/image/containers/_image.py
def sharpen(self, factor: float) -> Image:
    """
    Return a sharpened version of the image.

    The original image is not modified.

    Parameters
    ----------
    factor:
        If factor > 1, increase the sharpness of the image.
        If factor = 1, no changes will be made.
        If factor < 1, blur the image.
        Has to be bigger than or equal to 0 (blurred).

    Returns
    -------
    result:
        The image sharpened by the given factor.

    Raises
    ------
    OutOfBoundsError
        If factor is smaller than 0.
    """
    import torch
    from torchvision.transforms.v2 import functional as func2

    _check_sharpen_errors_and_warnings(factor, plural=False)
    if self.channel == 4:
        return Image(
            torch.cat(
                [
                    func2.adjust_sharpness(self._image_tensor[0:3], factor * 1.0),
                    self._image_tensor[3].unsqueeze(dim=0),
                ],
            ),
            device=self.device,
        )
    else:
        return Image(func2.adjust_sharpness(self._image_tensor, factor * 1.0), device=self.device)

to_jpeg_file(path)

Save the image as a JPEG file.

Parameters:

Name Type Description Default
path str | Path

The path to the JPEG file.

required
Source code in src/safeds/data/image/containers/_image.py
def to_jpeg_file(self, path: str | Path) -> None:
    """
    Save the image as a JPEG file.

    Parameters
    ----------
    path:
        The path to the JPEG file.
    """
    import torch
    from torchvision.transforms.v2 import functional as func2
    from torchvision.utils import save_image

    if self.channel == 4:
        raise IllegalFormatError("png")
    Path(path).parent.mkdir(parents=True, exist_ok=True)
    if self.channel == 1:
        func2.to_pil_image(self._image_tensor, mode="L").save(path, format="jpeg")
    else:
        save_image(self._image_tensor.to(torch.float32) / 255, path, format="jpeg")

to_png_file(path)

Save the image as a PNG file.

Parameters:

Name Type Description Default
path str | Path

The path to the PNG file.

required
Source code in src/safeds/data/image/containers/_image.py
def to_png_file(self, path: str | Path) -> None:
    """
    Save the image as a PNG file.

    Parameters
    ----------
    path:
        The path to the PNG file.
    """
    import torch
    from torchvision.transforms.v2 import functional as func2
    from torchvision.utils import save_image

    Path(path).parent.mkdir(parents=True, exist_ok=True)
    if self.channel == 1:
        func2.to_pil_image(self._image_tensor, mode="L").save(path, format="png")
    else:
        save_image(self._image_tensor.to(torch.float32) / 255, path, format="png")