vkit.element.image

  1# Copyright 2022 vkit-x Administrator. All Rights Reserved.
  2#
  3# This project (vkit-x/vkit) is dual-licensed under commercial and SSPL licenses.
  4#
  5# The commercial license gives you the full rights to create and distribute software
  6# on your own terms without any SSPL license obligations. For more information,
  7# please see the "LICENSE_COMMERCIAL.txt" file.
  8#
  9# This project is also available under Server Side Public License (SSPL).
 10# The SSPL licensing is ideal for use cases such as open source projects with
 11# SSPL distribution, student/academic purposes, hobby projects, internal research
 12# projects without external distribution, or other projects where all SSPL
 13# obligations can be met. For more information, please see the "LICENSE_SSPL.txt" file.
 14from typing import cast, Mapping, Sequence, Tuple, Union, Optional, Iterable, List, TypeVar
 15from enum import Enum, unique
 16from collections import abc
 17from contextlib import ContextDecorator
 18
 19import attrs
 20import numpy as np
 21from PIL import (
 22    Image as PilImage,
 23    ImageOps as PilImageOps,
 24)
 25import cv2 as cv
 26import iolite as io
 27
 28from vkit.utility import PathType
 29from .type import Shapable, ElementSetOperationMode
 30from .opt import generate_shape_and_resized_shape
 31
 32
 33@unique
 34class ImageMode(Enum):
 35    RGB = 'rgb'
 36    RGB_GCN = 'rgb_gcn'
 37    RGBA = 'rgba'
 38    HSV = 'hsv'
 39    HSV_GCN = 'hsv_gcn'
 40    HSL = 'hsl'
 41    HSL_GCN = 'hsl_gcn'
 42    GRAYSCALE = 'grayscale'
 43    GRAYSCALE_GCN = 'grayscale_gcn'
 44    NONE = 'none'
 45
 46    def to_ndim(self):
 47        if self in _IMAGE_MODE_NDIM_3:
 48            return 3
 49        elif self in _IMAGE_MODE_NDIM_2:
 50            return 2
 51        else:
 52            raise NotImplementedError()
 53
 54    def to_dtype(self):
 55        if self in _IMAGE_MODE_DTYPE_UINT8:
 56            return np.uint8
 57        elif self in _IMAGE_MODE_DTYPE_FLOAT32:
 58            return np.float32
 59        else:
 60            raise NotImplementedError()
 61
 62    def to_num_channels(self):
 63        if self in _IMAGE_MODE_NUM_CHANNELS_4:
 64            return 4
 65        elif self in _IMAGE_MODE_NUM_CHANNELS_3:
 66            return 3
 67        elif self in _IMAGE_MODE_NUM_CHANNELS_2:
 68            return None
 69        else:
 70            raise NotImplementedError
 71
 72    def supports_gcn_mode(self):
 73        return self not in _IMAGE_MODE_NON_GCN_TO_GCN
 74
 75    def to_gcn_mode(self):
 76        if not self.supports_gcn_mode():
 77            raise RuntimeError(f'image_mode={self} not supported.')
 78        return _IMAGE_MODE_NON_GCN_TO_GCN[self]
 79
 80    def in_gcn_mode(self):
 81        return self in _IMAGE_MODE_GCN_TO_NON_GCN
 82
 83    def to_non_gcn_mode(self):
 84        if not self.in_gcn_mode():
 85            raise RuntimeError(f'image_mode={self} not in gcn mode.')
 86        return _IMAGE_MODE_GCN_TO_NON_GCN[self]
 87
 88
 89_IMAGE_MODE_NDIM_3 = {
 90    ImageMode.RGB,
 91    ImageMode.RGB_GCN,
 92    ImageMode.RGBA,
 93    ImageMode.HSV,
 94    ImageMode.HSV_GCN,
 95    ImageMode.HSL,
 96    ImageMode.HSL_GCN,
 97}
 98
 99_IMAGE_MODE_NDIM_2 = {
100    ImageMode.GRAYSCALE,
101    ImageMode.GRAYSCALE_GCN,
102}
103
104_IMAGE_MODE_DTYPE_UINT8 = {
105    ImageMode.RGB,
106    ImageMode.RGBA,
107    ImageMode.HSV,
108    ImageMode.HSL,
109    ImageMode.GRAYSCALE,
110}
111
112_IMAGE_MODE_DTYPE_FLOAT32 = {
113    ImageMode.RGB_GCN,
114    ImageMode.HSV_GCN,
115    ImageMode.HSL_GCN,
116    ImageMode.GRAYSCALE_GCN,
117}
118
119_IMAGE_MODE_NUM_CHANNELS_4 = {
120    ImageMode.RGBA,
121}
122
123_IMAGE_MODE_NUM_CHANNELS_3 = {
124    ImageMode.RGB,
125    ImageMode.RGB_GCN,
126    ImageMode.HSV,
127    ImageMode.HSV_GCN,
128    ImageMode.HSL,
129    ImageMode.HSL_GCN,
130}
131
132_IMAGE_MODE_NUM_CHANNELS_2 = {
133    ImageMode.GRAYSCALE,
134    ImageMode.GRAYSCALE_GCN,
135}
136
137_IMAGE_MODE_NON_GCN_TO_GCN = {
138    ImageMode.RGB: ImageMode.RGB_GCN,
139    ImageMode.HSV: ImageMode.HSV_GCN,
140    ImageMode.HSL: ImageMode.HSL_GCN,
141    ImageMode.GRAYSCALE: ImageMode.GRAYSCALE_GCN,
142}
143
144_IMAGE_MODE_GCN_TO_NON_GCN = {val: key for key, val in _IMAGE_MODE_NON_GCN_TO_GCN.items()}
145
146
147@attrs.define
148class ImageSetItemConfig:
149    value: Union[
150        'Image',
151        np.ndarray,
152        Tuple[int, ...],
153        int,
154    ]  # yapf: disable
155    alpha: Union[np.ndarray, float] = 1.0
156
157
158class WritableImageContextDecorator(ContextDecorator):
159
160    def __init__(self, image: 'Image'):
161        super().__init__()
162        self.image = image
163
164    def __enter__(self):
165        if self.image.mat.flags.c_contiguous:
166            assert not self.image.mat.flags.writeable
167
168        try:
169            self.image.mat.flags.writeable = True
170        except ValueError:
171            # Copy on write.
172            object.__setattr__(
173                self.image,
174                'mat',
175                np.array(self.image.mat),
176            )
177            assert self.image.mat.flags.writeable
178
179    def __exit__(self, *exc):  # type: ignore
180        self.image.mat.flags.writeable = False
181
182
183_IMAGE_SRC_MODE_TO_PRE_SLICE: Mapping[ImageMode, Sequence[int]] = {
184    # HSL -> HLS.
185    ImageMode.HSL: [0, 2, 1],
186}
187
188_IMAGE_SRC_MODE_TO_RGB_CV_CODE = {
189    ImageMode.GRAYSCALE: cv.COLOR_GRAY2RGB,
190    ImageMode.RGBA: cv.COLOR_RGBA2RGB,
191    ImageMode.HSV: cv.COLOR_HSV2RGB_FULL,
192    # NOTE: HSL need pre-slicing.
193    ImageMode.HSL: cv.COLOR_HLS2RGB_FULL,
194}
195
196_IMAGE_INV_DST_MODE_TO_RGB_CV_CODE = {
197    ImageMode.GRAYSCALE: cv.COLOR_RGB2GRAY,
198    ImageMode.RGBA: cv.COLOR_RGB2RGBA,
199    ImageMode.HSV: cv.COLOR_RGB2HSV_FULL,
200    # NOTE: HSL need post-slicing.
201    ImageMode.HSL: cv.COLOR_RGB2HLS_FULL,
202}
203
204_IMAGE_DST_MODE_TO_POST_SLICE: Mapping[ImageMode, Sequence[int]] = {
205    # HLS -> HSL.
206    ImageMode.HSL: [0, 2, 1],
207}
208
209_IMAGE_SRC_DST_MODE_TO_CV_CODE: Mapping[Tuple[ImageMode, ImageMode], int] = {
210    (ImageMode.GRAYSCALE, ImageMode.RGBA): cv.COLOR_GRAY2RGBA,
211    (ImageMode.RGBA, ImageMode.GRAYSCALE): cv.COLOR_RGBA2GRAY,
212}
213
214_E = TypeVar('_E', 'Box', 'Polygon', 'Mask', 'ScoreMap')
215
216
217@attrs.define(frozen=True, eq=False)
218class Image(Shapable):
219    mat: np.ndarray
220    mode: ImageMode = ImageMode.NONE
221    box: Optional['Box'] = None
222
223    def __attrs_post_init__(self):
224        if self.mode != ImageMode.NONE:
225            # Validate mat.dtype and mode.
226            assert self.mode.to_dtype() == self.mat.dtype
227            assert self.mode.to_ndim() == self.mat.ndim
228
229        else:
230            # Infer image mode based on mat.
231            if self.mat.dtype == np.float32:
232                raise NotImplementedError('mode is None and mat.dtype == np.float32.')
233
234            elif self.mat.dtype == np.uint8:
235                if self.mat.ndim == 2:
236                    # Defaults to GRAYSCALE.
237                    mode = ImageMode.GRAYSCALE
238                elif self.mat.ndim == 3:
239                    if self.mat.shape[2] == 4:
240                        mode = ImageMode.RGBA
241                    elif self.mat.shape[2] == 3:
242                        # Defaults to RGB.
243                        mode = ImageMode.RGB
244                    else:
245                        raise NotImplementedError(f'Invalid num_channels={self.mat.shape[2]}.')
246                else:
247                    raise NotImplementedError(f'mat.ndim={self.mat.ndim} not supported.')
248
249                object.__setattr__(self, 'mode', mode)
250
251            else:
252                raise NotImplementedError(f'Invalid mat.dtype={self.mat.dtype}.')
253
254        # For the control of write.
255        self.mat.flags.writeable = False
256
257        if self.box and self.shape != self.box.shape:
258            raise RuntimeError('self.shape != box.shape.')
259
260    ###############
261    # Constructor #
262    ###############
263    @classmethod
264    def from_shape(
265        cls,
266        shape: Tuple[int, int],
267        num_channels: int = 3,
268        value: Union[Tuple[int, ...], int] = 255,
269    ):
270        height, width = shape
271
272        if num_channels == 0:
273            mat_shape = (height, width)
274
275        else:
276            assert num_channels > 0
277
278            if isinstance(value, tuple):
279                assert len(value) == num_channels
280
281            mat_shape = (height, width, num_channels)
282
283        mat = np.full(mat_shape, fill_value=value, dtype=np.uint8)
284        return cls(mat=mat)
285
286    @classmethod
287    def from_shapable(
288        cls,
289        shapable: Shapable,
290        num_channels: int = 3,
291        value: Union[Tuple[int, ...], int] = 255,
292    ):
293        return cls.from_shape(
294            shape=shapable.shape,
295            num_channels=num_channels,
296            value=value,
297        )
298
299    ############
300    # Property #
301    ############
302    @property
303    def height(self):
304        return self.mat.shape[0]
305
306    @property
307    def width(self):
308        return self.mat.shape[1]
309
310    @property
311    def num_channels(self):
312        if self.mat.ndim == 2:
313            return 0
314        else:
315            assert self.mat.ndim == 3
316            return self.mat.shape[2]
317
318    @property
319    def writable_context(self):
320        return WritableImageContextDecorator(self)
321
322    ##############
323    # Conversion #
324    ##############
325    @classmethod
326    def from_pil_image(cls, pil_image: PilImage.Image):
327        # NOTE: Make a copy explicitly, otherwise is not writable.
328        mat = np.array(pil_image, dtype=np.uint8)
329        return cls(mat=mat)
330
331    def to_pil_image(self):
332        return PilImage.fromarray(self.mat)
333
334    @classmethod
335    def from_file(cls, path: PathType, disable_exif_orientation: bool = False):
336        # NOTE: PilImage.open cannot handle `~`.
337        path = io.file(path).expanduser()
338
339        pil_image = PilImage.open(str(path))
340        pil_image.load()
341
342        if not disable_exif_orientation:
343            # https://exiftool.org/TagNames/EXIF.html
344            # https://github.com/python-pillow/Pillow/blob/main/src/PIL/ImageOps.py#L571
345            # Avoid unnecessary copy.
346            if pil_image.getexif().get(0x0112):
347                pil_image = PilImageOps.exif_transpose(pil_image)
348
349        return cls.from_pil_image(pil_image)
350
351    def to_file(self, path: PathType, disable_to_rgb_image: bool = False):
352        image = self
353        if not disable_to_rgb_image:
354            image = image.to_rgb_image()
355
356        pil_image = image.to_pil_image()
357
358        path = io.file(path).expanduser()
359        pil_image.save(str(path))
360
361    ############
362    # Operator #
363    ############
364    def copy(self):
365        return attrs.evolve(self, mat=self.mat.copy())
366
367    def assign_mat(self, mat: np.ndarray):
368        with self.writable_context:
369            object.__setattr__(self, 'mat', mat)
370
371    @classmethod
372    def check_values_and_alphas_uniqueness(
373        cls,
374        values: Sequence[Union['Image', np.ndarray, Tuple[int, ...], int, float]],
375        alphas: Sequence[Union['ScoreMap', np.ndarray, float]],
376    ):
377        return check_elements_uniqueness(values) and check_elements_uniqueness(alphas)
378
379    @classmethod
380    def unpack_element_value_tuples(
381        cls,
382        element_value_tuples: Iterable[
383            Union[
384                Tuple[
385                    _E,
386                    Union['Image', np.ndarray, Tuple[int, ...], int],
387                ],
388                Tuple[
389                    _E,
390                    Union['Image', np.ndarray, Tuple[int, ...], int],
391                    Union[float, np.ndarray],
392                ],
393            ]
394        ],
395    ):  # yapf: disable
396        elements: List[_E] = []
397        values: List[Union[Image, np.ndarray, Tuple[int, ...], int]] = []
398        alphas: List[Union[float, np.ndarray]] = []
399
400        for element_value_tuple in element_value_tuples:
401            if len(element_value_tuple) == 2:
402                element, value = element_value_tuple
403                alpha = 1.0
404            else:
405                element, value, alpha = element_value_tuple
406            elements.append(element)
407            values.append(value)
408            alphas.append(alpha)
409
410        return elements, values, alphas
411
412    def fill_by_box_value_tuples(
413        self,
414        box_value_tuples: Iterable[
415            Union[
416                Tuple[
417                    'Box',
418                    Union['Image', np.ndarray, Tuple[int, ...], int],
419                ],
420                Tuple[
421                    'Box',
422                    Union['Image', np.ndarray, Tuple[int, ...], int],
423                    Union[float, np.ndarray],
424                ],
425            ]
426        ],
427        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
428        skip_values_uniqueness_check: bool = False,
429    ):  # yapf: disable
430        boxes, values, alphas = self.unpack_element_value_tuples(box_value_tuples)
431
432        boxes_mask = generate_fill_by_boxes_mask(self.shape, boxes, mode)
433        if boxes_mask is None:
434            for box, value, alpha in zip(boxes, values, alphas):
435                box.fill_image(
436                    image=self,
437                    value=value,
438                    alpha=alpha,
439                )
440
441        else:
442            unique = True
443            if not skip_values_uniqueness_check:
444                unique = self.check_values_and_alphas_uniqueness(values, alphas)
445
446            if unique:
447                boxes_mask.fill_image(
448                    image=self,
449                    value=values[0],
450                    alpha=alphas[0],
451                )
452            else:
453                for box, value, alpha in zip(boxes, values, alphas):
454                    box_mask = box.extract_mask(boxes_mask).to_box_attached(box)
455                    box_mask.fill_image(
456                        image=self,
457                        value=value,
458                        alpha=alpha,
459                    )
460
461    def fill_by_boxes(
462        self,
463        boxes: Iterable['Box'],
464        value: Union['Image', np.ndarray, Tuple[int, ...], int],
465        alpha: Union[np.ndarray, float] = 1.0,
466        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
467    ):
468        self.fill_by_box_value_tuples(
469            box_value_tuples=((box, value, alpha) for box in boxes),
470            mode=mode,
471            skip_values_uniqueness_check=True,
472        )
473
474    def fill_by_polygon_value_tuples(
475        self,
476        polygon_value_tuples: Iterable[
477            Union[
478                Tuple[
479                    'Polygon',
480                    Union['Image', np.ndarray, Tuple[int, ...], int],
481                ],
482                Tuple[
483                    'Polygon',
484                    Union['Image', np.ndarray, Tuple[int, ...], int],
485                    Union[float, np.ndarray],
486                ],
487            ]
488        ],
489        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
490        skip_values_uniqueness_check: bool = False,
491    ):  # yapf: disable
492        polygons, values, alphas = self.unpack_element_value_tuples(polygon_value_tuples)
493
494        polygons_mask = generate_fill_by_polygons_mask(self.shape, polygons, mode)
495        if polygons_mask is None:
496            for polygon, value, alpha in zip(polygons, values, alphas):
497                polygon.fill_image(
498                    image=self,
499                    value=value,
500                    alpha=alpha,
501                )
502
503        else:
504            unique = True
505            if not skip_values_uniqueness_check:
506                unique = self.check_values_and_alphas_uniqueness(values, alphas)
507
508            if unique:
509                polygons_mask.fill_image(
510                    image=self,
511                    value=values[0],
512                    alpha=alphas[0],
513                )
514            else:
515                for polygon, value, alpha in zip(polygons, values, alphas):
516                    bounding_box = polygon.to_bounding_box()
517                    polygon_mask = bounding_box.extract_mask(polygons_mask)
518                    polygon_mask = polygon_mask.to_box_attached(bounding_box)
519                    polygon_mask.fill_image(
520                        image=self,
521                        value=value,
522                        alpha=alpha,
523                    )
524
525    def fill_by_polygons(
526        self,
527        polygons: Iterable['Polygon'],
528        value: Union['Image', np.ndarray, Tuple[int, ...], int],
529        alpha: Union[np.ndarray, float] = 1.0,
530        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
531    ):
532        self.fill_by_polygon_value_tuples(
533            polygon_value_tuples=((polygon, value, alpha) for polygon in polygons),
534            mode=mode,
535            skip_values_uniqueness_check=True,
536        )
537
538    def fill_by_mask_value_tuples(
539        self,
540        mask_value_tuples: Iterable[
541            Union[
542                Tuple[
543                    'Mask',
544                    Union['Image', np.ndarray, Tuple[int, ...], int],
545                ],
546                Tuple[
547                    'Mask',
548                    Union['Image', np.ndarray, Tuple[int, ...], int],
549                    Union[float, np.ndarray],
550                ],
551            ]
552        ],
553        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
554        skip_values_uniqueness_check: bool = False,
555    ):  # yapf: disable
556        masks, values, alphas = self.unpack_element_value_tuples(mask_value_tuples)
557
558        masks_mask = generate_fill_by_masks_mask(self.shape, masks, mode)
559        if masks_mask is None:
560            for mask, value, alpha in zip(masks, values, alphas):
561                mask.fill_image(
562                    image=self,
563                    value=value,
564                    alpha=alpha,
565                )
566
567        else:
568            unique = True
569            if not skip_values_uniqueness_check:
570                unique = self.check_values_and_alphas_uniqueness(values, alphas)
571
572            if unique:
573                masks_mask.fill_image(
574                    image=self,
575                    value=values[0],
576                    alpha=alphas[0],
577                )
578            else:
579                for mask, value, alpha in zip(masks, values, alphas):
580                    if mask.box:
581                        boxed_mask = mask.box.extract_mask(masks_mask)
582                    else:
583                        boxed_mask = masks_mask
584
585                    boxed_mask = boxed_mask.copy()
586                    mask.to_inverted_mask().fill_mask(boxed_mask, value=0)
587                    boxed_mask.fill_image(
588                        image=self,
589                        value=value,
590                        alpha=alpha,
591                    )
592
593    def fill_by_masks(
594        self,
595        masks: Iterable['Mask'],
596        value: Union['Image', np.ndarray, Tuple[int, ...], int],
597        alpha: Union[np.ndarray, float] = 1.0,
598        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
599    ):
600        self.fill_by_mask_value_tuples(
601            mask_value_tuples=((mask, value, alpha) for mask in masks),
602            mode=mode,
603            skip_values_uniqueness_check=True,
604        )
605
606    def fill_by_score_map_value_tuples(
607        self,
608        score_map_value_tuples: Iterable[
609            Tuple[
610                'ScoreMap',
611                Union['Image', np.ndarray, Tuple[int, ...], int],
612            ]
613        ],
614        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
615        skip_values_uniqueness_check: bool = False,
616    ):  # yapf: disable
617        # NOTE: score maps serve as masks & alphas, hence ignoring unpacked alphas.
618        score_maps, values, _ = self.unpack_element_value_tuples(score_map_value_tuples)
619
620        score_maps_mask = generate_fill_by_score_maps_mask(self.shape, score_maps, mode)
621        if score_maps_mask is None:
622            for score_map, value in zip(score_maps, values):
623                score_map.fill_image(
624                    image=self,
625                    value=value,
626                )
627
628        else:
629            unique = True
630            if not skip_values_uniqueness_check:
631                unique = check_elements_uniqueness(values)
632
633            if unique:
634                # This is unlikely to happen.
635                score_maps_mask.fill_image(
636                    image=self,
637                    value=values[0],
638                    alpha=score_maps[0],
639                )
640            else:
641                for score_map, value in zip(score_maps, values):
642                    if score_map.box:
643                        boxed_mask = score_map.box.extract_mask(score_maps_mask)
644                    else:
645                        boxed_mask = score_maps_mask
646
647                    boxed_mask = boxed_mask.copy()
648                    score_map.to_mask().to_inverted_mask().fill_mask(boxed_mask, value=0)
649                    boxed_mask.fill_image(
650                        image=self,
651                        value=value,
652                        alpha=score_map,
653                    )
654
655    def fill_by_score_maps(
656        self,
657        score_maps: Iterable['ScoreMap'],
658        value: Union['Image', np.ndarray, Tuple[int, ...], int],
659        mode: ElementSetOperationMode = ElementSetOperationMode.UNION,
660    ):
661        self.fill_by_score_map_value_tuples(
662            score_map_value_tuples=((score_map, value) for score_map in score_maps),
663            mode=mode,
664            skip_values_uniqueness_check=True,
665        )
666
667    def __setitem__(
668        self,
669        element: Union[
670            'Box',
671            'Polygon',
672            'Mask',
673            'ScoreMap',
674        ],
675        config: Union[
676            'Image',
677            np.ndarray,
678            Tuple[int, ...],
679            int,
680            ImageSetItemConfig,
681        ],
682    ):  # yapf: disable
683        if not isinstance(config, ImageSetItemConfig):
684            value = config
685            alpha = 1.0
686        else:
687            assert isinstance(config, ImageSetItemConfig)
688            value = config.value
689            alpha = config.alpha
690
691        if isinstance(value, tuple):
692            assert value
693            assert isinstance(value[0], int)
694        else:
695            assert not isinstance(value, abc.Iterable)
696
697        # Type inference cannot handle this case.
698        value = cast(
699            Union[
700                'Image',
701                np.ndarray,
702                Tuple[int, ...],
703                int,
704            ],
705            value
706        )  # yapf: disable
707        assert not isinstance(alpha, abc.Iterable)
708
709        if isinstance(element, ScoreMap):
710            element.fill_image(image=self, value=value)
711        else:
712            element.fill_image(image=self, value=value, alpha=alpha)
713
714    def __getitem__(
715        self,
716        element: Union[
717            'Box',
718            'Polygon',
719            'Mask',
720        ],
721    ):  # yapf: disable
722        return element.extract_image(self)
723
724    def to_box_attached(self, box: 'Box'):
725        assert self.height == box.height
726        assert self.width == box.width
727        return attrs.evolve(self, box=box)
728
729    def to_box_detached(self):
730        assert self.box
731        return attrs.evolve(self, box=None)
732
733    def to_gcn_image(
734        self,
735        lamb: float = 0,
736        eps: float = 1E-8,
737        scale: float = 1.0,
738    ):
739        # Global contrast normalization.
740        # https://cedar.buffalo.edu/~srihari/CSE676/12.2%20Computer%20Vision.pdf
741        # (H, W) or (H, W, 3)
742        mode = self.mode.to_gcn_mode()
743
744        mat = self.mat.astype(np.float32)
745
746        # Normalize mean(contrast).
747        mean = np.mean(mat)
748        mat -= mean
749
750        # Std normalized.
751        std = np.sqrt(lamb + np.mean(mat**2))
752        mat /= max(eps, std)
753        if scale != 1.0:
754            mat *= scale
755
756        return Image(mat=mat, mode=mode)
757
758    def to_non_gcn_image(self):
759        mode = self.mode.to_non_gcn_mode()
760
761        assert self.mat.dtype == np.float32
762        val_min = np.min(self.mat)
763        mat = self.mat - val_min
764        gap = np.max(mat)
765        mat = mat / gap * 255.0
766        mat = np.round(mat)
767        mat = np.clip(mat, 0, 255).astype(np.uint8)
768
769        return Image(mat=mat, mode=mode)  # type: ignore
770
771    def to_target_mode_image(self, target_mode: ImageMode):
772        if target_mode == self.mode:
773            # Identity.
774            return self
775
776        skip_copy = False
777        if self.mode.in_gcn_mode():
778            self = self.to_non_gcn_image()
779            skip_copy = True
780
781        if self.mode == target_mode:
782            # GCN to non-GCN conversion.
783            return self if skip_copy else self.copy()
784
785        mat = self.mat
786
787        # Pre-slicing.
788        if self.mode in _IMAGE_SRC_MODE_TO_PRE_SLICE:
789            mat: np.ndarray = mat[:, :, _IMAGE_SRC_MODE_TO_PRE_SLICE[self.mode]]
790
791        if (self.mode, target_mode) in _IMAGE_SRC_DST_MODE_TO_CV_CODE:
792            # Shortcut.
793            cv_code = _IMAGE_SRC_DST_MODE_TO_CV_CODE[(self.mode, target_mode)]
794            dst_mat: np.ndarray = cv.cvtColor(mat, cv_code)
795            return Image(mat=dst_mat, mode=target_mode)
796
797        dst_mat = mat
798        if self.mode != ImageMode.RGB:
799            # Convert to RGB.
800            dst_mat: np.ndarray = cv.cvtColor(mat, _IMAGE_SRC_MODE_TO_RGB_CV_CODE[self.mode])
801
802        if target_mode == ImageMode.RGB:
803            # No need to continue.
804            return Image(mat=dst_mat, mode=ImageMode.RGB)
805
806        # Convert RGB to target mode.
807        assert target_mode in _IMAGE_INV_DST_MODE_TO_RGB_CV_CODE
808        dst_mat: np.ndarray = cv.cvtColor(dst_mat, _IMAGE_INV_DST_MODE_TO_RGB_CV_CODE[target_mode])
809
810        # Post-slicing.
811        if target_mode in _IMAGE_DST_MODE_TO_POST_SLICE:
812            dst_mat: np.ndarray = dst_mat[:, :, _IMAGE_DST_MODE_TO_POST_SLICE[target_mode]]
813
814        return Image(mat=dst_mat, mode=target_mode)
815
816    def to_grayscale_image(self):
817        return self.to_target_mode_image(ImageMode.GRAYSCALE)
818
819    def to_rgb_image(self):
820        return self.to_target_mode_image(ImageMode.RGB)
821
822    def to_rgba_image(self):
823        return self.to_target_mode_image(ImageMode.RGBA)
824
825    def to_hsv_image(self):
826        return self.to_target_mode_image(ImageMode.HSV)
827
828    def to_hsl_image(self):
829        return self.to_target_mode_image(ImageMode.HSL)
830
831    def to_shifted_image(self, offset_y: int = 0, offset_x: int = 0):
832        assert self.box
833        shifted_box = self.box.to_shifted_box(offset_y=offset_y, offset_x=offset_x)
834        return attrs.evolve(self, box=shifted_box)
835
836    def to_resized_image(
837        self,
838        resized_height: Optional[int] = None,
839        resized_width: Optional[int] = None,
840        cv_resize_interpolation: int = cv.INTER_CUBIC,
841    ):
842        _, _, resized_height, resized_width = generate_shape_and_resized_shape(
843            shapable_or_shape=self,
844            resized_height=resized_height,
845            resized_width=resized_width,
846        )
847        mat = cv.resize(
848            self.mat,
849            (resized_width, resized_height),
850            interpolation=cv_resize_interpolation,
851        )
852        return attrs.evolve(self, mat=mat)
853
854    def to_conducted_resized_image(
855        self,
856        shapable_or_shape: Union[Shapable, Tuple[int, int]],
857        resized_height: Optional[int] = None,
858        resized_width: Optional[int] = None,
859        cv_resize_interpolation: int = cv.INTER_CUBIC,
860    ):
861        assert self.box
862        resized_box = self.box.to_conducted_resized_box(
863            shapable_or_shape=shapable_or_shape,
864            resized_height=resized_height,
865            resized_width=resized_width,
866        )
867        resized_image = self.to_box_detached().to_resized_image(
868            resized_height=resized_box.height,
869            resized_width=resized_box.width,
870            cv_resize_interpolation=cv_resize_interpolation,
871        )
872        resized_image = resized_image.to_box_attached(resized_box)
873        return resized_image
874
875    def to_cropped_image(
876        self,
877        up: Optional[int] = None,
878        down: Optional[int] = None,
879        left: Optional[int] = None,
880        right: Optional[int] = None,
881    ):
882        assert not self.box
883
884        up = up or 0
885        down = down or self.height - 1
886        left = left or 0
887        right = right or self.width - 1
888
889        return attrs.evolve(self, mat=self.mat[up:down + 1, left:right + 1])
890
891
892# Cyclic dependency, by design.
893from .uniqueness import check_elements_uniqueness  # noqa: E402
894from .box import Box, generate_fill_by_boxes_mask  # noqa: E402
895from .polygon import Polygon, generate_fill_by_polygons_mask  # noqa: E402
896from .mask import Mask, generate_fill_by_masks_mask  # noqa: E402
897from .score_map import ScoreMap, generate_fill_by_score_maps_mask  # noqa: E402