vedo.image

   1#!/usr/bin/env python3
   2# -*- coding: utf-8 -*-
   3import numpy as np
   4from weakref import ref as weak_ref_to
   5from typing import Self, Tuple, List, Union, Any
   6
   7import vedo.vtkclasses as vtki
   8
   9import vedo
  10from vedo import colors
  11from vedo import utils
  12
  13__docformat__ = "google"
  14
  15__doc__ = """
  16Submodule to work with common format images.
  17
  18![](https://vedo.embl.es/images/basic/rotateImage.png)
  19"""
  20
  21__all__ = [
  22    "Image",
  23    "Picture",  # Deprecated, use Image instead
  24]
  25
  26
  27#################################################
  28def _get_img(obj: Union[np.ndarray, str], flip=False, translate=()) -> vtki.vtkImageData:
  29    # compute vtkImageData from numpy array or filename
  30
  31    if isinstance(obj, str):
  32        if "https://" in obj:
  33            obj = vedo.file_io.download(obj, verbose=False)
  34
  35        fname = obj.lower()
  36        if fname.endswith(".png"):
  37            picr = vtki.new("PNGReader")
  38        elif fname.endswith(".jpg") or fname.endswith(".jpeg"):
  39            picr = vtki.new("JPEGReader")
  40        elif fname.endswith(".bmp"):
  41            picr = vtki.new("BMPReader")
  42        elif fname.endswith(".tif") or fname.endswith(".tiff"):
  43            picr = vtki.new("TIFFReader")
  44            picr.SetOrientationType(vedo.settings.tiff_orientation_type)
  45        else:
  46            colors.printc("Cannot understand image format", obj, c="r")
  47            return vtki.vtkImageData()
  48        picr.SetFileName(obj)
  49        picr.Update()
  50        img = picr.GetOutput()
  51
  52    else:
  53        obj = np.asarray(obj)
  54
  55        if obj.ndim == 3:  # has shape (nx,ny, ncolor_alpha_chan)
  56            iac = vtki.new("ImageAppendComponents")
  57            nchan = obj.shape[2]  # get number of channels in inputimage (L/LA/RGB/RGBA)
  58            for i in range(nchan):
  59                if flip:
  60                    arr = np.flip(np.flip(obj[:, :, i], 0), 0).ravel()
  61                else:
  62                    arr = np.flip(obj[:, :, i], 0).ravel()
  63                arr = np.clip(arr, 0, 255)
  64                varb = utils.numpy2vtk(arr, dtype=np.uint8, name="RGBA")
  65                imgb = vtki.vtkImageData()
  66                imgb.SetDimensions(obj.shape[1], obj.shape[0], 1)
  67                imgb.GetPointData().AddArray(varb)
  68                imgb.GetPointData().SetActiveScalars("RGBA")
  69                iac.AddInputData(imgb)
  70            iac.Update()
  71            img = iac.GetOutput()
  72
  73        elif obj.ndim == 2:  # black and white
  74            if flip:
  75                arr = np.flip(obj[:, :], 0).ravel()
  76            else:
  77                arr = obj.ravel()
  78            arr = np.clip(arr, 0, 255)
  79            varb = utils.numpy2vtk(arr, dtype=np.uint8, name="RGBA")
  80            img = vtki.vtkImageData()
  81            img.SetDimensions(obj.shape[1], obj.shape[0], 1)
  82
  83            img.GetPointData().AddArray(varb)
  84            img.GetPointData().SetActiveScalars("RGBA")
  85
  86    if len(translate) > 0:
  87        translate_extent = vtki.new("ImageTranslateExtent")
  88        translate_extent.SetTranslation(-translate[0], -translate[1], 0)
  89        translate_extent.SetInputData(img)
  90        translate_extent.Update()
  91        img.DeepCopy(translate_extent.GetOutput())
  92
  93    return img
  94
  95
  96def _set_justification(img, pos):
  97
  98    if not isinstance(pos, str):
  99        return img, pos
 100
 101    sx, sy = img.GetDimensions()[:2]
 102    translate = ()
 103    if "top" in pos:
 104        if "left" in pos:
 105            pos = (0, 1)
 106            translate = (0, sy)
 107        elif "right" in pos:
 108            pos = (1, 1)
 109            translate = (sx, sy)
 110        elif "mid" in pos or "cent" in pos:
 111            pos = (0.5, 1)
 112            translate = (sx / 2, sy)
 113    elif "bottom" in pos:
 114        if "left" in pos:
 115            pos = (0, 0)
 116        elif "right" in pos:
 117            pos = (1, 0)
 118            translate = (sx, 0)
 119        elif "mid" in pos or "cent" in pos:
 120            pos = (0.5, 0)
 121            translate = (sx / 2, 0)
 122    elif "mid" in pos or "cent" in pos:
 123        if "left" in pos:
 124            pos = (0, 0.5)
 125            translate = (0, sy / 2)
 126        elif "right" in pos:
 127            pos = (1, 0.5)
 128            translate = (sx, sy / 2)
 129        else:
 130            pos = (0.5, 0.5)
 131            translate = (sx / 2, sy / 2)
 132
 133    if len(translate) > 0:
 134        translate = np.array(translate).astype(int)
 135        translate_extent = vtki.new("ImageTranslateExtent")
 136        translate_extent.SetTranslation(-translate[0], -translate[1], 0)
 137        translate_extent.SetInputData(img)
 138        translate_extent.Update()
 139        img = translate_extent.GetOutput()
 140
 141    return img, pos
 142
 143
 144class Image(vedo.visual.ImageVisual):
 145    """
 146    Class used to represent 2D images in a 3D world.
 147    """
 148
 149    def __init__(self, obj=None, channels=3):
 150        """
 151        Can be instantiated with a path file name or with a numpy array.
 152        Can also be instantiated with a matplotlib figure.
 153
 154        By default the transparency channel is disabled.
 155        To enable it set `channels=4`.
 156
 157        Use `Image.shape` to get the number of pixels in x and y.
 158
 159        Arguments:
 160            channels :  (int, list)
 161                only select these specific rgba channels (useful to remove alpha)
 162        """
 163        self.name = "Image"
 164        self.filename = ""
 165        self.file_size = 0
 166        self.pipeline = None
 167        self.time = 0
 168        self.rendered_at = set()
 169        self.info = {}
 170
 171        self.actor = vtki.vtkImageActor()
 172        self.actor.retrieve_object = weak_ref_to(self)
 173        self.properties = self.actor.GetProperty()
 174
 175        self.transform = vedo.LinearTransform()
 176
 177        if utils.is_sequence(obj) and len(obj) > 0:  # passing array
 178            img = _get_img(obj, False)
 179
 180        elif isinstance(obj, vtki.vtkImageData):
 181            img = obj
 182
 183        elif isinstance(obj, str):
 184            img = _get_img(obj)
 185            self.filename = obj
 186
 187        elif "matplotlib" in str(obj.__class__):
 188            fig = obj
 189            if hasattr(fig, "gcf"):
 190                fig = fig.gcf()
 191            fig.tight_layout(pad=1)
 192            fig.canvas.draw()
 193
 194            # self.array = np.frombuffer(fig.canvas.tostring_rgb(), dtype=np.uint8)
 195            # self.array = self.array.reshape(fig.canvas.get_width_height()[::-1] + (3,))
 196            width, height = fig.get_size_inches() * fig.get_dpi()
 197            self.array = np.frombuffer(
 198                fig.canvas.buffer_rgba(), dtype=np.uint8
 199            ).reshape((int(height), int(width), 4))
 200            self.array = self.array[:, :, :3]
 201
 202            img = _get_img(self.array)
 203
 204        else:
 205            img = vtki.vtkImageData()
 206
 207        ############# select channels
 208        if isinstance(channels, int):
 209            channels = list(range(channels))
 210
 211        nchans = len(channels)
 212        n = img.GetPointData().GetScalars().GetNumberOfComponents()
 213        if nchans and n > nchans:
 214            pec = vtki.new("ImageExtractComponents")
 215            pec.SetInputData(img)
 216            if nchans == 4:
 217                pec.SetComponents(channels[0], channels[1], channels[2], channels[3])
 218            elif nchans == 3:
 219                pec.SetComponents(channels[0], channels[1], channels[2])
 220            elif nchans == 2:
 221                pec.SetComponents(channels[0], channels[1])
 222            elif nchans == 1:
 223                pec.SetComponents(channels[0])
 224            pec.Update()
 225            img = pec.GetOutput()
 226
 227        self.dataset = img
 228        self.actor.SetInputData(img)
 229        self.mapper = self.actor.GetMapper()
 230
 231        sx, sy, _ = self.dataset.GetDimensions()
 232        shape = np.array([sx, sy])
 233        self.pipeline = utils.OperationNode("Image", comment=f"#shape {shape}", c="#f28482")
 234    
 235    ######################################################################
 236
 237    def __str__(self):
 238        """Print a description of the Image class."""
 239
 240        module = self.__class__.__module__
 241        name = self.__class__.__name__
 242        out = vedo.printc(
 243            f"{module}.{name} at ({hex(id(self))})".ljust(75),
 244            c="y", bold=True, invert=True, return_string=True,
 245        )
 246
 247        # if vedo.colors._terminal_has_colors:
 248        #     thumb = ""
 249        #     try: # to generate a terminal thumbnail
 250        #         w = 75
 251        #         width, height = self.shape
 252        #         h = int(height / width * (w - 1) * 0.5 + 0.5)
 253        #         img_arr = self.clone().resize([w, h]).tonumpy()
 254        #         h, w = img_arr.shape[:2]
 255        #         for x in range(h):
 256        #             for y in range(w):
 257        #                 pix = img_arr[x][y]
 258        #                 r, g, b = pix[:3]
 259        #                 thumb += f"\x1b[48;2;{r};{g};{b}m "
 260        #             thumb += "\x1b[0m\n"
 261        #     except:
 262        #         pass
 263        #     out += thumb
 264        
 265        out += "\x1b[0m\x1b[33;1m"
 266        out += "dimensions".ljust(14) + f": {self.shape}\n"
 267        out += "memory size".ljust(14) + ": "
 268        out += str(int(self.memory_size())) + " kB\n"
 269
 270        bnds = self.bounds()
 271        bx1, bx2 = utils.precision(bnds[0], 3), utils.precision(bnds[1], 3)
 272        by1, by2 = utils.precision(bnds[2], 3), utils.precision(bnds[3], 3)
 273        bz1, bz2 = utils.precision(bnds[4], 3), utils.precision(bnds[5], 3)
 274        out += "position".ljust(14) + f": {self.pos()}\n"
 275        out += "bounds".ljust(14) + ":"
 276        out += " x=(" + bx1 + ", " + bx2 + "),"
 277        out += " y=(" + by1 + ", " + by2 + "),"
 278        out += " z=(" + bz1 + ", " + bz2 + ")\n"
 279        out += "intensty range".ljust(14) + f": {self.scalar_range()}\n"
 280        out += "level/window".ljust(14) + ": "
 281        out += str(self.level()) + " / " + str(self.window()) + "\n"
 282        return out.rstrip() + "\x1b[0m"
 283
 284    def _repr_html_(self):
 285        """
 286        HTML representation of the Image object for Jupyter Notebooks.
 287
 288        Returns:
 289            HTML text with the image and some properties.
 290        """
 291        import io
 292        import base64
 293        from PIL import Image
 294
 295        library_name = "vedo.image.Image"
 296        help_url = "https://vedo.embl.es/docs/vedo/image.html"
 297
 298        arr = self.thumbnail(zoom=1.1)
 299
 300        im = Image.fromarray(arr)
 301        buffered = io.BytesIO()
 302        im.save(buffered, format="PNG", quality=100)
 303        encoded = base64.b64encode(buffered.getvalue()).decode("utf-8")
 304        url = "data:image/png;base64," + encoded
 305        image = f"<img src='{url}'></img>"
 306
 307        help_text = ""
 308        if self.name:
 309            help_text += f"<b> {self.name}: &nbsp&nbsp</b>"
 310        help_text += '<b><a href="' + help_url + '" target="_blank">' + library_name + "</a></b>"
 311        if self.filename:
 312            dots = ""
 313            if len(self.filename) > 30:
 314                dots = "..."
 315            help_text += f"<br/><code><i>({dots}{self.filename[-30:]})</i></code>"
 316
 317        pdata = ""
 318        if self.dataset.GetPointData().GetScalars():
 319            if self.dataset.GetPointData().GetScalars().GetName():
 320                name = self.dataset.GetPointData().GetScalars().GetName()
 321                pdata = "<tr><td><b> point data array </b></td><td>" + name + "</td></tr>"
 322
 323        cdata = ""
 324        if self.dataset.GetCellData().GetScalars():
 325            if self.dataset.GetCellData().GetScalars().GetName():
 326                name = self.dataset.GetCellData().GetScalars().GetName()
 327                cdata = "<tr><td><b> voxel data array </b></td><td>" + name + "</td></tr>"
 328
 329        img = self.dataset
 330
 331        allt = [
 332            "<table>",
 333            "<tr>",
 334            "<td>",
 335            image,
 336            "</td>",
 337            "<td style='text-align: center; vertical-align: center;'><br/>",
 338            help_text,
 339            "<table>",
 340            "<tr><td><b> shape </b></td><td>" + str(img.GetDimensions()[:2]) + "</td></tr>",
 341            "<tr><td><b> in memory size </b></td><td>"
 342            + str(int(img.GetActualMemorySize()))
 343            + " KB</td></tr>",
 344            pdata,
 345            cdata,
 346            "<tr><td><b> intensity range </b></td><td>" + str(img.GetScalarRange()) + "</td></tr>",
 347            "<tr><td><b> level&nbsp/&nbspwindow </b></td><td>"
 348            + str(self.level())
 349            + "&nbsp/&nbsp"
 350            + str(self.window())
 351            + "</td></tr>",
 352            "</table>",
 353            "</table>",
 354        ]
 355        return "\n".join(allt)
 356
 357    ######################################################################
 358    def _update(self, data: vtki.vtkImageData) -> Self:
 359        self.dataset = data
 360        self.mapper.SetInputData(data)
 361        self.mapper.Modified()
 362        return self
 363
 364    def dimensions(self) -> np.ndarray:
 365        """
 366        Return the image dimension as number of pixels in x and y. 
 367        Alias of property `shape`.
 368        """
 369        nx, ny, _ = self.dataset.GetDimensions()
 370        return np.array([nx, ny])
 371
 372    @property
 373    def shape(self) -> np.ndarray:
 374        """Return the image shape as number of pixels in x and y"""
 375        return np.array(self.dimensions())
 376
 377    @property
 378    def channels(self) -> int:
 379        """Return the number of channels in image"""
 380        return self.dataset.GetPointData().GetScalars().GetNumberOfComponents()
 381
 382    @property
 383    def extent(self) -> Tuple[int, int, int, int]:
 384        """Return the physical extent that the image spans."""
 385        return self.dataset.GetExtent()
 386    
 387    @extent.setter
 388    def extent(self, ext: Tuple[int, int, int, int]):
 389        """Set the physical extent that the image spans."""
 390        self.dataset.SetExtent(ext[0], ext[1], ext[2], ext[3], 0, 0)
 391        self.mapper.Modified()
 392
 393    def copy(self) -> "Image":
 394        """Return a copy of the image. Alias of `clone()`."""
 395        return self.clone()
 396
 397    def clone(self) -> "Image":
 398        """Return an exact copy of the input Image.
 399        If transform is True, it is given the same scaling and position."""
 400        img = vtki.vtkImageData()
 401        img.DeepCopy(self.dataset)
 402        pic = Image(img)
 403        pic.name = self.name
 404        pic.filename = self.filename
 405        pic.apply_transform(self.transform)
 406        pic.properties = vtki.vtkImageProperty()
 407        pic.properties.DeepCopy(self.properties)
 408        pic.actor.SetProperty(pic.properties)
 409        pic.pipeline = utils.OperationNode("clone", parents=[self], c="#f7dada", shape="diamond")
 410        return pic
 411    
 412    def clone2d(self, pos=(0, 0), size=1, justify="") -> "vedo.visual.Actor2D":
 413        """
 414        Embed an image as a static 2D image in the canvas.
 415        
 416        Return a 2D (an `Actor2D`) copy of the input Image.
 417        
 418        Arguments:
 419            pos : (list, str)
 420                2D (x,y) position in range [0,1],
 421                [0,0] being the bottom-left corner  
 422            size : (float)
 423                apply a scaling factor to the image
 424            justify : (str)
 425                define the anchor point ("top-left", "top-center", ...)
 426        """
 427        pic = vedo.visual.Actor2D()
 428
 429        pic.name = self.name
 430        pic.filename = self.filename
 431        pic.file_size = self.file_size
 432        
 433        pic.dataset = self.dataset
 434
 435        pic.properties = pic.GetProperty()
 436        pic.properties.SetDisplayLocationToBackground()
 437
 438        if size != 1:
 439            newsize = np.array(self.dataset.GetDimensions()[:2]) * size
 440            newsize = newsize.astype(int)
 441            rsz = vtki.new("ImageResize")
 442            rsz.SetInputData(self.dataset)
 443            rsz.SetResizeMethodToOutputDimensions()
 444            rsz.SetOutputDimensions(newsize[0], newsize[1], 1)
 445            rsz.Update()
 446            pic.dataset = rsz.GetOutput()
 447
 448        if justify:
 449            pic.dataset, pos = _set_justification(pic.dataset, justify)
 450        else:
 451            pic.dataset, pos = _set_justification(pic.dataset, pos)
 452
 453        pic.mapper = vtki.new("ImageMapper")
 454        # pic.SetMapper(pic.mapper)
 455        pic.mapper.SetInputData(pic.dataset)
 456        pic.mapper.SetColorWindow(255)
 457        pic.mapper.SetColorLevel(127.5)
 458
 459        pic.GetPositionCoordinate().SetCoordinateSystem(3)
 460        pic.SetPosition(pos)
 461
 462        pic.pipeline = utils.OperationNode("clone2d", parents=[self], c="#f7dada", shape="diamond")
 463        return pic
 464
 465
 466    def crop(self, top=None, bottom=None, right=None, left=None, pixels=False) -> Self:
 467        """
 468        Crop image.
 469
 470        Arguments:
 471            top : (float)
 472                fraction to crop from the top margin
 473            bottom : (float)
 474                fraction to crop from the bottom margin
 475            left : (float)
 476                fraction to crop from the left margin
 477            right : (float)
 478                fraction to crop from the right margin
 479            pixels : (bool)
 480                units are pixels
 481        """
 482        extractVOI = vtki.new("ExtractVOI")
 483        extractVOI.SetInputData(self.dataset)
 484        extractVOI.IncludeBoundaryOn()
 485
 486        d = self.dataset.GetDimensions()
 487        if pixels:
 488            extractVOI.SetVOI(left, d[0] - right - 1, bottom, d[1] - top - 1, 0, 0)
 489        else:
 490            bx0, bx1, by0, by1 = 0, d[0]-1, 0, d[1]-1
 491            if left is not None:   bx0 = int((d[0]-1)*left)
 492            if right is not None:  bx1 = int((d[0]-1)*(1-right))
 493            if bottom is not None: by0 = int((d[1]-1)*bottom)
 494            if top is not None:    by1 = int((d[1]-1)*(1-top))
 495            extractVOI.SetVOI(bx0, bx1, by0, by1, 0, 0)
 496        extractVOI.Update()
 497
 498        self._update(extractVOI.GetOutput())
 499        self.pipeline = utils.OperationNode(
 500            "crop", comment=f"shape={tuple(self.shape)}", parents=[self], c="#f28482"
 501        )
 502        return self
 503
 504    def pad(self, pixels=10, value=255) -> Self:
 505        """
 506        Add the specified number of pixels at the image borders.
 507        Pixels can be a list formatted as `[left, right, bottom, top]`.
 508
 509        Arguments:
 510            pixels : (int, list)
 511                number of pixels to be added (or a list of length 4)
 512            value : (int)
 513                intensity value (gray-scale color) of the padding
 514        """
 515        x0, x1, y0, y1, _z0, _z1 = self.dataset.GetExtent()
 516        pf = vtki.new("ImageConstantPad")
 517        pf.SetInputData(self.dataset)
 518        pf.SetConstant(value)
 519        if utils.is_sequence(pixels):
 520            pf.SetOutputWholeExtent(
 521                x0 - pixels[0], x1 + pixels[1],
 522                y0 - pixels[2], y1 + pixels[3],
 523                0, 0
 524            )
 525        else:
 526            pf.SetOutputWholeExtent(
 527                x0 - pixels, x1 + pixels,
 528                y0 - pixels, y1 + pixels,
 529                0, 0
 530            )
 531        pf.Update()
 532        self._update(pf.GetOutput())
 533        self.pipeline = utils.OperationNode(
 534            "pad", comment=f"{pixels} pixels", parents=[self], c="#f28482"
 535        )
 536        return self
 537
 538    def tile(self, nx=4, ny=4, shift=(0, 0)) -> "Image":
 539        """
 540        Generate a tiling from the current image by mirroring and repeating it.
 541
 542        Arguments:
 543            nx : (float)
 544                number of repeats along x
 545            ny : (float)
 546                number of repeats along x
 547            shift : (list)
 548                shift in x and y in pixels
 549        """
 550        x0, x1, y0, y1, z0, z1 = self.dataset.GetExtent()
 551        constant_pad = vtki.new("ImageMirrorPad")
 552        constant_pad.SetInputData(self.dataset)
 553        constant_pad.SetOutputWholeExtent(
 554            int(x0 + shift[0] + 0.5),
 555            int(x1 * nx + shift[0] + 0.5),
 556            int(y0 + shift[1] + 0.5),
 557            int(y1 * ny + shift[1] + 0.5),
 558            z0,
 559            z1,
 560        )
 561        constant_pad.Update()
 562        img = Image(constant_pad.GetOutput())
 563
 564        img.pipeline = utils.OperationNode(
 565            "tile", comment=f"by {nx}x{ny}", parents=[self], c="#f28482"
 566        )
 567        return img
 568
 569    def append(self, images: list, axis="z", preserve_extents=False) -> Self:
 570        """
 571        Append the input images to the current one along the specified axis.
 572        Except for the append axis, all inputs must have the same extent.
 573        All inputs must have the same number of scalar components.
 574        The output has the same origin and spacing as the first input.
 575        The origin and spacing of all other inputs are ignored.
 576        All inputs must have the same scalar type.
 577
 578        Arguments:
 579            axis : (int, str)
 580                axis expanded to hold the multiple images
 581            preserve_extents : (bool)
 582                if True, the extent of the inputs is used to place
 583                the image in the output. The whole extent of the output is the union of the input
 584                whole extents. Any portion of the output not covered by the inputs is set to zero.
 585                The origin and spacing is taken from the first input.
 586
 587        Example:
 588            ```python
 589            from vedo import Image, dataurl
 590            pic = Image(dataurl+'dog.jpg').pad()
 591            pic.append([pic, pic], axis='y')
 592            pic.append([pic, pic, pic], axis='x')
 593            pic.show(axes=1).close()
 594            ```
 595            ![](https://vedo.embl.es/images/feats/pict_append.png)
 596        """
 597        ima = vtki.new("ImageAppend")
 598        ima.SetInputData(self.dataset)
 599        for p in images:
 600            if isinstance(p, vtki.vtkImageData):
 601                ima.AddInputData(p)
 602            else:
 603                ima.AddInputData(p.dataset)
 604        ima.SetPreserveExtents(preserve_extents)
 605        if axis == "x":
 606            axis = 0
 607        elif axis == "y":
 608            axis = 1
 609        ima.SetAppendAxis(axis)
 610        ima.Update()
 611        self._update(ima.GetOutput())
 612        self.pipeline = utils.OperationNode(
 613            "append", comment=f"axis={axis}", parents=[self, *images], c="#f28482"
 614        )
 615        return self
 616
 617    def resize(self, newsize: Any) -> Self:
 618        """
 619        Resize the image resolution by specifying the number of pixels in width and height.
 620        If left to zero, it will be automatically calculated to keep the original aspect ratio.
 621
 622        `newsize` is the shape of image as [npx, npy], or it can be also expressed as a fraction.
 623        """
 624        old_dims = np.array(self.dataset.GetDimensions())
 625
 626        if not utils.is_sequence(newsize):
 627            newsize = (old_dims * newsize + 0.5).astype(int)
 628
 629        if not newsize[1]:
 630            ar = old_dims[1] / old_dims[0]
 631            newsize = [newsize[0], int(newsize[0] * ar + 0.5)]
 632        if not newsize[0]:
 633            ar = old_dims[0] / old_dims[1]
 634            newsize = [int(newsize[1] * ar + 0.5), newsize[1]]
 635        newsize = [newsize[0], newsize[1], old_dims[2]]
 636
 637        rsz = vtki.new("ImageResize")
 638        rsz.SetInputData(self.dataset)
 639        rsz.SetResizeMethodToOutputDimensions()
 640        rsz.SetOutputDimensions(newsize)
 641        rsz.Update()
 642        out = rsz.GetOutput()
 643        out.SetSpacing(1, 1, 1)
 644        self._update(out)
 645        self.pipeline = utils.OperationNode(
 646            "resize", comment=f"shape={tuple(self.shape)}", parents=[self], c="#f28482"
 647        )
 648        return self
 649
 650    def mirror(self, axis="x") -> Self:
 651        """Mirror image along x or y axis. Same as `flip()`."""
 652        ff = vtki.new("ImageFlip")
 653        ff.SetInputData(self.dataset)
 654        if axis.lower() == "x":
 655            ff.SetFilteredAxis(0)
 656        elif axis.lower() == "y":
 657            ff.SetFilteredAxis(1)
 658        else:
 659            colors.printc("Error in mirror(): mirror must be set to x or y.", c="r")
 660            raise RuntimeError()
 661        ff.Update()
 662        self._update(ff.GetOutput())
 663        self.pipeline = utils.OperationNode(f"mirror {axis}", parents=[self], c="#f28482")
 664        return self
 665
 666    def flip(self, axis="y") -> Self:
 667        """Mirror image along x or y axis. Same as `mirror()`."""
 668        return self.mirror(axis=axis)
 669
 670    def select(self, component: int) -> "Image":
 671        """Select one single component of the rgb image."""
 672        ec = vtki.new("ImageExtractComponents")
 673        ec.SetInputData(self.dataset)
 674        ec.SetComponents(component)
 675        ec.Update()
 676        pic = Image(ec.GetOutput())
 677        pic.pipeline = utils.OperationNode(
 678            "select", comment=f"component {component}", parents=[self], c="#f28482"
 679        )
 680        return pic
 681
 682    def bw(self) -> Self:
 683        """Make it black and white using luminance calibration."""
 684        n = self.dataset.GetPointData().GetNumberOfComponents()
 685        if n == 4:
 686            ecr = vtki.new("ImageExtractComponents")
 687            ecr.SetInputData(self.dataset)
 688            ecr.SetComponents(0, 1, 2)
 689            ecr.Update()
 690            img = ecr.GetOutput()
 691        else:
 692            img = self.dataset
 693
 694        ecr = vtki.new("ImageLuminance")
 695        ecr.SetInputData(img)
 696        ecr.Update()
 697        self._update(ecr.GetOutput())
 698        self.pipeline = utils.OperationNode("black&white", parents=[self], c="#f28482")
 699        return self
 700
 701    def smooth(self, sigma=3, radius=None) -> Self:
 702        """
 703        Smooth a `Image` with Gaussian kernel.
 704
 705        Arguments:
 706            sigma : (int)
 707                number of sigmas in pixel units
 708            radius : (float)
 709                how far out the gaussian kernel will go before being clamped to zero
 710        """
 711        gsf = vtki.new("ImageGaussianSmooth")
 712        gsf.SetDimensionality(2)
 713        gsf.SetInputData(self.dataset)
 714        if radius is not None:
 715            if utils.is_sequence(radius):
 716                gsf.SetRadiusFactors(radius[0], radius[1])
 717            else:
 718                gsf.SetRadiusFactor(radius)
 719
 720        if utils.is_sequence(sigma):
 721            gsf.SetStandardDeviations(sigma[0], sigma[1])
 722        else:
 723            gsf.SetStandardDeviation(sigma)
 724        gsf.Update()
 725        self._update(gsf.GetOutput())
 726        self.pipeline = utils.OperationNode(
 727            "smooth", comment=f"sigma={sigma}", parents=[self], c="#f28482"
 728        )
 729        return self
 730
 731    def median(self) -> Self:
 732        """
 733        Median filter that preserves thin lines and corners.
 734
 735        It operates on a 5x5 pixel neighborhood. It computes two values initially:
 736        the median of the + neighbors and the median of the x neighbors.
 737        It then computes the median of these two values plus the center pixel.
 738        This result of this second median is the output pixel value.
 739        """
 740        medf = vtki.new("ImageHybridMedian2D")
 741        medf.SetInputData(self.dataset)
 742        medf.Update()
 743        self._update(medf.GetOutput())
 744        self.pipeline = utils.OperationNode("median", parents=[self], c="#f28482")
 745        return self
 746
 747    def enhance(self) -> Self:
 748        """
 749        Enhance a b&w image using the laplacian, enhancing high-freq edges.
 750
 751        Example:
 752            ```python
 753            from vedo import *
 754            pic = Image(dataurl+'images/dog.jpg').bw()
 755            show(pic, pic.clone().enhance(), N=2, mode='image', zoom='tight')
 756            ```
 757            ![](https://vedo.embl.es/images/feats/pict_enhance.png)
 758        """
 759        img = self.dataset
 760        scalarRange = img.GetPointData().GetScalars().GetRange()
 761
 762        cast = vtki.new("ImageCast")
 763        cast.SetInputData(img)
 764        cast.SetOutputScalarTypeToDouble()
 765        cast.Update()
 766
 767        laplacian = vtki.new("ImageLaplacian")
 768        laplacian.SetInputData(cast.GetOutput())
 769        laplacian.SetDimensionality(2)
 770        laplacian.Update()
 771
 772        subtr = vtki.new("ImageMathematics")
 773        subtr.SetInputData(0, cast.GetOutput())
 774        subtr.SetInputData(1, laplacian.GetOutput())
 775        subtr.SetOperationToSubtract()
 776        subtr.Update()
 777
 778        color_window = scalarRange[1] - scalarRange[0]
 779        color_level = color_window / 2
 780        original_color = vtki.new("ImageMapToWindowLevelColors")
 781        original_color.SetWindow(color_window)
 782        original_color.SetLevel(color_level)
 783        original_color.SetInputData(subtr.GetOutput())
 784        original_color.Update()
 785        self._update(original_color.GetOutput())
 786
 787        self.pipeline = utils.OperationNode("enhance", parents=[self], c="#f28482")
 788        return self
 789
 790    def fft(self, mode="magnitude", logscale=12, center=True) -> "Image":
 791        """
 792        Fast Fourier transform of a image.
 793
 794        Arguments:
 795            logscale : (float)
 796                if non-zero, take the logarithm of the intensity and scale it by this factor.
 797            mode : (str)
 798                either [magnitude, real, imaginary, complex], compute the point array data accordingly.
 799            center : (bool)
 800                shift constant zero-frequency to the center of the image for display.
 801                (FFT converts spatial images into frequency space, but puts the zero frequency at the origin)
 802        """
 803        ffti = vtki.new("ImageFFT")
 804        ffti.SetInputData(self.dataset)
 805        ffti.Update()
 806
 807        if "mag" in mode:
 808            mag = vtki.new("ImageMagnitude")
 809            mag.SetInputData(ffti.GetOutput())
 810            mag.Update()
 811            out = mag.GetOutput()
 812        elif "real" in mode:
 813            erf = vtki.new("ImageExtractComponents")
 814            erf.SetInputData(ffti.GetOutput())
 815            erf.SetComponents(0)
 816            erf.Update()
 817            out = erf.GetOutput()
 818        elif "imaginary" in mode:
 819            eimf = vtki.new("ImageExtractComponents")
 820            eimf.SetInputData(ffti.GetOutput())
 821            eimf.SetComponents(1)
 822            eimf.Update()
 823            out = eimf.GetOutput()
 824        elif "complex" in mode:
 825            out = ffti.GetOutput()
 826        else:
 827            colors.printc("Error in fft(): unknown mode", mode)
 828            raise RuntimeError()
 829
 830        if center:
 831            center = vtki.new("ImageFourierCenter")
 832            center.SetInputData(out)
 833            center.Update()
 834            out = center.GetOutput()
 835
 836        if "complex" not in mode:
 837            if logscale:
 838                ils = vtki.new("ImageLogarithmicScale")
 839                ils.SetInputData(out)
 840                ils.SetConstant(logscale)
 841                ils.Update()
 842                out = ils.GetOutput()
 843
 844        pic = Image(out)
 845        pic.pipeline = utils.OperationNode("FFT", parents=[self], c="#f28482")
 846        return pic
 847
 848    def rfft(self, mode="magnitude") -> "Image":
 849        """Reverse Fast Fourier transform of a image."""
 850
 851        ffti = vtki.new("ImageRFFT")
 852        ffti.SetInputData(self.dataset)
 853        ffti.Update()
 854
 855        if "mag" in mode:
 856            mag = vtki.new("ImageMagnitude")
 857            mag.SetInputData(ffti.GetOutput())
 858            mag.Update()
 859            out = mag.GetOutput()
 860        elif "real" in mode:
 861            erf = vtki.new("ImageExtractComponents")
 862            erf.SetInputData(ffti.GetOutput())
 863            erf.SetComponents(0)
 864            erf.Update()
 865            out = erf.GetOutput()
 866        elif "imaginary" in mode:
 867            eimf = vtki.new("ImageExtractComponents")
 868            eimf.SetInputData(ffti.GetOutput())
 869            eimf.SetComponents(1)
 870            eimf.Update()
 871            out = eimf.GetOutput()
 872        elif "complex" in mode:
 873            out = ffti.GetOutput()
 874        else:
 875            colors.printc("Error in rfft(): unknown mode", mode)
 876            raise RuntimeError()
 877
 878        pic = Image(out)
 879        pic.pipeline = utils.OperationNode("rFFT", parents=[self], c="#f28482")
 880        return pic
 881
 882    def filterpass(self, lowcutoff=None, highcutoff=None, order=3) -> Self:
 883        """
 884        Low-pass and high-pass filtering become trivial in the frequency domain.
 885        A portion of the pixels/voxels are simply masked or attenuated.
 886        This function applies a high pass Butterworth filter that attenuates the
 887        frequency domain image with the function
 888
 889        The gradual attenuation of the filter is important.
 890        A simple high-pass filter would simply mask a set of pixels in the frequency domain,
 891        but the abrupt transition would cause a ringing effect in the spatial domain.
 892
 893        Arguments:
 894            lowcutoff : (list)
 895                the cutoff frequencies
 896            highcutoff : (list)
 897                the cutoff frequencies
 898            order : (int)
 899                order determines sharpness of the cutoff curve
 900        """
 901        # https://lorensen.github.io/VTKExamples/site/Cxx/ImageProcessing/IdealHighPass
 902        fft = vtki.new("ImageFFT")
 903        fft.SetInputData(self.dataset)
 904        fft.Update()
 905        out = fft.GetOutput()
 906
 907        if highcutoff:
 908            blp = vtki.new("ImageButterworthLowPass")
 909            blp.SetInputData(out)
 910            blp.SetCutOff(highcutoff)
 911            blp.SetOrder(order)
 912            blp.Update()
 913            out = blp.GetOutput()
 914
 915        if lowcutoff:
 916            bhp = vtki.new("ImageButterworthHighPass")
 917            bhp.SetInputData(out)
 918            bhp.SetCutOff(lowcutoff)
 919            bhp.SetOrder(order)
 920            bhp.Update()
 921            out = bhp.GetOutput()
 922
 923        rfft = vtki.new("ImageRFFT")
 924        rfft.SetInputData(out)
 925        rfft.Update()
 926
 927        ecomp = vtki.new("ImageExtractComponents")
 928        ecomp.SetInputData(rfft.GetOutput())
 929        ecomp.SetComponents(0)
 930        ecomp.Update()
 931
 932        caster = vtki.new("ImageCast")
 933        caster.SetOutputScalarTypeToUnsignedChar()
 934        caster.SetInputData(ecomp.GetOutput())
 935        caster.Update()
 936        self._update(caster.GetOutput())
 937        self.pipeline = utils.OperationNode("filterpass", parents=[self], c="#f28482")
 938        return self
 939
 940    def blend(self, pic, alpha1=0.5, alpha2=0.5) -> Self:
 941        """
 942        Take L, LA, RGB, or RGBA images as input and blends
 943        them according to the alpha values and/or the opacity setting for each input.
 944        """
 945        blf = vtki.new("ImageBlend")
 946        blf.AddInputData(self.dataset)
 947        blf.AddInputData(pic.dataset)
 948        blf.SetOpacity(0, alpha1)
 949        blf.SetOpacity(1, alpha2)
 950        blf.SetBlendModeToNormal()
 951        blf.Update()
 952        self._update(blf.GetOutput())
 953        self.pipeline = utils.OperationNode("blend", parents=[self, pic], c="#f28482")
 954        return self
 955
 956    def warp(
 957        self,
 958        source_pts=(),
 959        target_pts=(),
 960        transform=None,
 961        sigma=1,
 962        mirroring=False,
 963        bc="w",
 964        alpha=1,
 965    ) -> Self:
 966        """
 967        Warp an image using thin-plate splines.
 968
 969        Arguments:
 970            source_pts : (list)
 971                source points
 972            target_pts : (list)
 973                target points
 974            transform : (vtkTransform)
 975                a vtkTransform object can be supplied
 976            sigma : (float), optional
 977                stiffness of the interpolation
 978            mirroring : (bool)
 979                fill the margins with a reflection of the original image
 980            bc : (color)
 981                fill the margins with a solid color
 982            alpha : (float)
 983                opacity of the filled margins
 984        """
 985        if transform is None:
 986            # source and target must be filled
 987            transform = vtki.vtkThinPlateSplineTransform()
 988            transform.SetBasisToR2LogR()
 989
 990            parents = [self]
 991            if isinstance(source_pts, vedo.Points):
 992                parents.append(source_pts)
 993                source_pts = source_pts.vertices
 994            if isinstance(target_pts, vedo.Points):
 995                parents.append(target_pts)
 996                target_pts = target_pts.vertices
 997
 998            ns = len(source_pts)
 999            nt = len(target_pts)
1000            if ns != nt:
1001                colors.printc("Error in image.warp(): #source != #target points", ns, nt, c="r")
1002                raise RuntimeError()
1003
1004            ptsou = vtki.vtkPoints()
1005            ptsou.SetNumberOfPoints(ns)
1006
1007            pttar = vtki.vtkPoints()
1008            pttar.SetNumberOfPoints(nt)
1009
1010            for i in range(ns):
1011                p = source_pts[i]
1012                ptsou.SetPoint(i, [p[0], p[1], 0])
1013                p = target_pts[i]
1014                pttar.SetPoint(i, [p[0], p[1], 0])
1015
1016            transform.SetSigma(sigma)
1017            transform.SetSourceLandmarks(pttar)
1018            transform.SetTargetLandmarks(ptsou)
1019        else:
1020            # ignore source and target
1021            pass
1022
1023        reslice = vtki.new("ImageReslice")
1024        reslice.SetInputData(self.dataset)
1025        reslice.SetOutputDimensionality(2)
1026        reslice.SetResliceTransform(transform)
1027        reslice.SetInterpolationModeToCubic()
1028        reslice.SetMirror(mirroring)
1029        c = np.array(colors.get_color(bc)) * 255
1030        reslice.SetBackgroundColor([c[0], c[1], c[2], alpha * 255])
1031        reslice.Update()
1032        self._update(reslice.GetOutput())
1033        self.pipeline = utils.OperationNode("warp", parents=parents, c="#f28482")
1034        return self
1035
1036    def invert(self) -> Self:
1037        """
1038        Return an inverted image (inverted in each color channel).
1039        """
1040        rgb = self.tonumpy()
1041        data = 255 - np.array(rgb)
1042        self._update(_get_img(data))
1043        self.pipeline = utils.OperationNode("invert", parents=[self], c="#f28482")
1044        return self
1045
1046    def binarize(self, threshold=None, invert=False) -> Self:
1047        """
1048        Return a new Image where pixel above threshold are set to 255
1049        and pixels below are set to 0.
1050
1051        Arguments:
1052            threshold : (float)
1053                input threshold value
1054            invert : (bool)
1055                invert threshold direction
1056
1057        Example:
1058        ```python
1059        from vedo import Image, show
1060        pic1 = Image("https://aws.glamour.es/prod/designs/v1/assets/620x459/547577.jpg")
1061        pic2 = pic1.clone().invert()
1062        pic3 = pic1.clone().binarize()
1063        show(pic1, pic2, pic3, N=3, bg="blue9").close()
1064        ```
1065        ![](https://vedo.embl.es/images/feats/pict_binarize.png)
1066        """
1067        rgb = self.tonumpy()
1068        if rgb.ndim == 3:
1069            intensity = np.sum(rgb, axis=2) / 3
1070        else:
1071            intensity = rgb
1072
1073        if threshold is None:
1074            vmin, vmax = np.min(intensity), np.max(intensity)
1075            threshold = (vmax + vmin) / 2
1076
1077        data = np.zeros_like(intensity).astype(np.uint8)
1078        mask = np.where(intensity > threshold)
1079        if invert:
1080            data += 255
1081            data[mask] = 0
1082        else:
1083            data[mask] = 255
1084
1085        self._update(_get_img(data, flip=True))
1086
1087        self.pipeline = utils.OperationNode(
1088            "binarize", comment=f"threshold={threshold}", parents=[self], c="#f28482"
1089        )
1090        return self
1091
1092    def threshold(self, value=None, flip=False) -> "vedo.Mesh":
1093        """
1094        Create a polygonal Mesh from a Image by filling regions with pixels
1095        luminosity above a specified value.
1096
1097        Arguments:
1098            value : (float)
1099                The default is None, e.i. 1/3 of the scalar range.
1100            flip: (bool)
1101                Flip polygon orientations
1102
1103        Returns:
1104            A polygonal mesh.
1105        """
1106        mgf = vtki.new("ImageMagnitude")
1107        mgf.SetInputData(self.dataset)
1108        mgf.Update()
1109        msq = vtki.new("MarchingSquares")
1110        msq.SetInputData(mgf.GetOutput())
1111        if value is None:
1112            r0, r1 = self.dataset.GetScalarRange()
1113            value = r0 + (r1 - r0) / 3
1114        msq.SetValue(0, value)
1115        msq.Update()
1116        if flip:
1117            rs = vtki.new("ReverseSense")
1118            rs.SetInputData(msq.GetOutput())
1119            rs.ReverseCellsOn()
1120            rs.ReverseNormalsOff()
1121            rs.Update()
1122            output = rs.GetOutput()
1123        else:
1124            output = msq.GetOutput()
1125        ctr = vtki.new("ContourTriangulator")
1126        ctr.SetInputData(output)
1127        ctr.Update()
1128        out = vedo.Mesh(ctr.GetOutput(), c="k").bc("t").lighting("off")
1129
1130        out.pipeline = utils.OperationNode(
1131            "threshold", comment=f"{value: .2f}", parents=[self], c="#f28482:#e9c46a"
1132        )
1133        return out
1134
1135    def cmap(self, name: str, vmin=None, vmax=None) -> Self:
1136        """Colorize a image with a colormap representing pixel intensity"""
1137        n = self.dataset.GetPointData().GetNumberOfComponents()
1138        if n > 1:
1139            ecr = vtki.new("ImageExtractComponents")
1140            ecr.SetInputData(self.dataset)
1141            ecr.SetComponents(0, 1, 2)
1142            ecr.Update()
1143            ilum = vtki.new("ImageMagnitude")
1144            ilum.SetInputData(self.dataset)
1145            ilum.Update()
1146            img = ilum.GetOutput()
1147        else:
1148            img = self.dataset
1149
1150        lut = vtki.vtkLookupTable()
1151        _vmin, _vmax = img.GetScalarRange()
1152        if vmin is not None:
1153            _vmin = vmin
1154        if vmax is not None:
1155            _vmax = vmax
1156        lut.SetRange(_vmin, _vmax)
1157
1158        ncols = 256
1159        lut.SetNumberOfTableValues(ncols)
1160        cols = colors.color_map(range(ncols), name, 0, ncols)
1161        for i, c in enumerate(cols):
1162            lut.SetTableValue(i, *c)
1163        lut.Build()
1164
1165        imap = vtki.new("ImageMapToColors")
1166        imap.SetLookupTable(lut)
1167        imap.SetInputData(img)
1168        imap.Update()
1169        self._update(imap.GetOutput())
1170        self.pipeline = utils.OperationNode(
1171            "cmap", comment=f'"{name}"', parents=[self], c="#f28482"
1172        )
1173        return self
1174
1175    def rotate(self, angle: float, center=(), scale=1.0, mirroring=False, bc="w", alpha=1.0) -> Self:
1176        """
1177        Rotate by the specified angle (anticlockwise).
1178
1179        Arguments:
1180            angle : (float)
1181                rotation angle in degrees
1182            center : (list)
1183                center of rotation (x,y) in pixels
1184        """
1185        bounds = self.bounds()
1186        pc = [0, 0, 0]
1187        if center:
1188            pc[0] = center[0]
1189            pc[1] = center[1]
1190        else:
1191            pc[0] = (bounds[1] + bounds[0]) / 2.0
1192            pc[1] = (bounds[3] + bounds[2]) / 2.0
1193        pc[2] = (bounds[5] + bounds[4]) / 2.0
1194
1195        transform = vtki.vtkTransform()
1196        transform.Translate(pc)
1197        transform.RotateWXYZ(-angle, 0, 0, 1)
1198        transform.Scale(1 / scale, 1 / scale, 1)
1199        transform.Translate(-pc[0], -pc[1], -pc[2])
1200
1201        reslice = vtki.new("ImageReslice")
1202        reslice.SetMirror(mirroring)
1203        c = np.array(colors.get_color(bc)) * 255
1204        reslice.SetBackgroundColor([c[0], c[1], c[2], alpha * 255])
1205        reslice.SetInputData(self.dataset)
1206        reslice.SetResliceTransform(transform)
1207        reslice.SetOutputDimensionality(2)
1208        reslice.SetInterpolationModeToCubic()
1209        reslice.AutoCropOutputOn()
1210        reslice.Update()
1211        self._update(reslice.GetOutput())
1212
1213        self.pipeline = utils.OperationNode(
1214            "rotate", comment=f"angle={angle}", parents=[self], c="#f28482"
1215        )
1216        return self
1217
1218    def tomesh(self) -> "vedo.shapes.Grid":
1219        """
1220        Convert an image to polygonal data (quads),
1221        with each polygon vertex assigned a RGBA value.
1222        """
1223        dims = self.dataset.GetDimensions()
1224        gr = vedo.shapes.Grid(s=dims[:2], res=(dims[0] - 1, dims[1] - 1))
1225        gr.pos(int(dims[0] / 2), int(dims[1] / 2)).pickable(True).wireframe(False).lw(0)
1226        self.dataset.GetPointData().GetScalars().SetName("RGBA")
1227        gr.dataset.GetPointData().AddArray(self.dataset.GetPointData().GetScalars())
1228        gr.dataset.GetPointData().SetActiveScalars("RGBA")
1229        gr.mapper.SetArrayName("RGBA")
1230        gr.mapper.SetScalarModeToUsePointData()
1231        gr.mapper.ScalarVisibilityOn()
1232        gr.name = self.name
1233        gr.filename = self.filename
1234        gr.pipeline = utils.OperationNode("tomesh", parents=[self], c="#f28482:#e9c46a")
1235        return gr
1236
1237    def tonumpy(self) -> np.ndarray:
1238        """
1239        Get read-write access to pixels of a Image object as a numpy array.
1240        Note that the shape is (nrofchannels, nx, ny).
1241
1242        When you set values in the output image, you don't want numpy to reallocate the array
1243        but instead set values in the existing array, so use the [:] operator.
1244        Example: arr[:] = arr - 15
1245
1246        If the array is modified call:
1247        `image.modified()`
1248        when all your modifications are completed.
1249        """
1250        nx, ny, _ = self.dataset.GetDimensions()
1251        nchan = self.dataset.GetPointData().GetScalars().GetNumberOfComponents()
1252        narray = utils.vtk2numpy(self.dataset.GetPointData().GetScalars()).reshape(ny, nx, nchan)
1253        narray = np.flip(narray, axis=0).astype(np.uint8)
1254        return narray.squeeze()
1255
1256    def add_rectangle(self, xspan: List[float], yspan: List[float], c="green5", alpha=1.0) -> Self:
1257        """Draw a rectangle box on top of current image. Units are pixels.
1258
1259        Example:
1260            ```python
1261            import vedo
1262            pic = vedo.Image(vedo.dataurl+"images/dog.jpg")
1263            pic.add_rectangle([100,300], [100,200], c='green4', alpha=0.7)
1264            pic.add_line([100,100],[400,500], lw=2, alpha=1)
1265            pic.add_triangle([250,300], [100,300], [200,400], c='blue5')
1266            vedo.show(pic, axes=1).close()
1267            ```
1268            ![](https://vedo.embl.es/images/feats/pict_drawon.png)
1269        """
1270        x1, x2 = xspan
1271        y1, y2 = yspan
1272
1273        r, g, b = vedo.colors.get_color(c)
1274        c = np.array([r, g, b]) * 255
1275        c = c.astype(np.uint8)
1276
1277        alpha = min(alpha, 1)
1278        if alpha <= 0:
1279            return self
1280        alpha2 = alpha
1281        alpha1 = 1 - alpha
1282
1283        nx, ny = self.dimensions()
1284        if x2 > nx:
1285            x2 = nx - 1
1286        if y2 > ny:
1287            y2 = ny - 1
1288
1289        nchan = self.channels
1290        narrayA = self.tonumpy()
1291
1292        canvas_source = vtki.new("ImageCanvasSource2D")
1293        canvas_source.SetExtent(0, nx - 1, 0, ny - 1, 0, 0)
1294        canvas_source.SetScalarTypeToUnsignedChar()
1295        canvas_source.SetNumberOfScalarComponents(nchan)
1296        canvas_source.SetDrawColor(255, 255, 255)
1297        canvas_source.FillBox(x1, x2, y1, y2)
1298        canvas_source.Update()
1299        imagedataset = canvas_source.GetOutput()
1300
1301        vscals = imagedataset.GetPointData().GetScalars()
1302        narrayB = vedo.utils.vtk2numpy(vscals).reshape(ny, nx, nchan)
1303        narrayB = np.flip(narrayB, axis=0)
1304        narrayC = np.where(narrayB < 255, narrayA, alpha1 * narrayA + alpha2 * c)
1305        self._update(_get_img(narrayC))
1306        self.pipeline = utils.OperationNode("rectangle", parents=[self], c="#f28482")
1307        return self
1308
1309    def add_line(self, p1: List[float], p2: List[float], lw=2, c="k2", alpha=1.0) -> Self:
1310        """Draw a line on top of current image. Units are pixels."""
1311        x1, x2 = p1
1312        y1, y2 = p2
1313
1314        r, g, b = vedo.colors.get_color(c)
1315        c = np.array([r, g, b]) * 255
1316        c = c.astype(np.uint8)
1317
1318        alpha = min(alpha, 1)
1319        if alpha <= 0:
1320            return self
1321        alpha2 = alpha
1322        alpha1 = 1 - alpha
1323
1324        nx, ny = self.dimensions()
1325        if x2 > nx:
1326            x2 = nx - 1
1327        if y2 > ny:
1328            y2 = ny - 1
1329
1330        nchan = self.channels
1331        narrayA = self.tonumpy()
1332
1333        canvas_source = vtki.new("ImageCanvasSource2D")
1334        canvas_source.SetExtent(0, nx - 1, 0, ny - 1, 0, 0)
1335        canvas_source.SetScalarTypeToUnsignedChar()
1336        canvas_source.SetNumberOfScalarComponents(nchan)
1337        canvas_source.SetDrawColor(255, 255, 255)
1338        canvas_source.FillTube(x1, x2, y1, y2, lw)
1339        canvas_source.Update()
1340        imagedataset = canvas_source.GetOutput()
1341
1342        vscals = imagedataset.GetPointData().GetScalars()
1343        narrayB = vedo.utils.vtk2numpy(vscals).reshape(ny, nx, nchan)
1344        narrayB = np.flip(narrayB, axis=0)
1345        narrayC = np.where(narrayB < 255, narrayA, alpha1 * narrayA + alpha2 * c)
1346        self._update(_get_img(narrayC))
1347        self.pipeline = utils.OperationNode("line", parents=[self], c="#f28482")
1348        return self
1349
1350    def add_triangle(self, p1: List[float], p2: List[float], p3: List[float], c="red3", alpha=1.0) -> Self:
1351        """Draw a triangle on top of current image. Units are pixels."""
1352        x1, y1 = p1
1353        x2, y2 = p2
1354        x3, y3 = p3
1355
1356        r, g, b = vedo.colors.get_color(c)
1357        c = np.array([r, g, b]) * 255
1358        c = c.astype(np.uint8)
1359
1360        alpha = min(alpha, 1)
1361        if alpha <= 0:
1362            return self
1363        alpha2 = alpha
1364        alpha1 = 1 - alpha
1365
1366        nx, ny = self.dimensions()
1367        x1 = min(x1, nx)
1368        x2 = min(x2, nx)
1369        x3 = min(x3, nx)
1370
1371        y1 = min(y1, ny)
1372        y2 = min(y2, ny)
1373        y3 = min(y3, ny)
1374
1375        nchan = self.channels
1376        narrayA = self.tonumpy()
1377
1378        canvas_source = vtki.new("ImageCanvasSource2D")
1379        canvas_source.SetExtent(0, nx - 1, 0, ny - 1, 0, 0)
1380        canvas_source.SetScalarTypeToUnsignedChar()
1381        canvas_source.SetNumberOfScalarComponents(nchan)
1382        canvas_source.SetDrawColor(255, 255, 255)
1383        canvas_source.FillTriangle(x1, y1, x2, y2, x3, y3)
1384        canvas_source.Update()
1385        imagedataset = canvas_source.GetOutput()
1386
1387        vscals = imagedataset.GetPointData().GetScalars()
1388        narrayB = vedo.utils.vtk2numpy(vscals).reshape(ny, nx, nchan)
1389        narrayB = np.flip(narrayB, axis=0)
1390        narrayC = np.where(narrayB < 255, narrayA, alpha1 * narrayA + alpha2 * c)
1391        self._update(_get_img(narrayC))
1392        self.pipeline = utils.OperationNode("triangle", parents=[self], c="#f28482")
1393        return self
1394
1395    def add_text(
1396        self,
1397        txt: str,
1398        width=400,
1399        height=200,
1400        alpha=1,
1401        c="black",
1402        bg=None,
1403        alpha_bg=1,
1404        font="Theemim",
1405        dpi=200,
1406        justify="bottom-left",
1407    ) -> Self:
1408        """Add text to an image."""
1409
1410        tp = vtki.vtkTextProperty()
1411        tp.BoldOff()
1412        tp.FrameOff()
1413        tp.SetColor(colors.get_color(c))
1414        tp.SetJustificationToLeft()
1415        if "top" in justify:
1416            tp.SetVerticalJustificationToTop()
1417        if "bottom" in justify:
1418            tp.SetVerticalJustificationToBottom()
1419        if "cent" in justify:
1420            tp.SetVerticalJustificationToCentered()
1421            tp.SetJustificationToCentered()
1422        if "left" in justify:
1423            tp.SetJustificationToLeft()
1424        if "right" in justify:
1425            tp.SetJustificationToRight()
1426
1427        if   font.lower() == "courier": tp.SetFontFamilyToCourier()
1428        elif font.lower() == "times": tp.SetFontFamilyToTimes()
1429        elif font.lower() == "arial": tp.SetFontFamilyToArial()
1430        else:
1431            tp.SetFontFamily(vtki.VTK_FONT_FILE)
1432            tp.SetFontFile(utils.get_font_path(font))
1433
1434        if bg:
1435            bgcol = colors.get_color(bg)
1436            tp.SetBackgroundColor(bgcol)
1437            tp.SetBackgroundOpacity(alpha_bg)
1438            tp.SetFrameColor(bgcol)
1439            tp.FrameOn()
1440
1441        tr = vtki.new("TextRenderer")
1442        # GetConstrainedFontSize (const vtkUnicodeString &str,
1443        # vtkTextProperty(*tprop, int targetWidth, int targetHeight, int dpi)
1444        fs = tr.GetConstrainedFontSize(txt, tp, width, height, dpi)
1445        tp.SetFontSize(fs)
1446
1447        img = vtki.vtkImageData()
1448        # img.SetOrigin(*pos,1)
1449        tr.RenderString(tp, txt, img, [width, height], dpi)
1450        # RenderString (vtkTextProperty *tprop, const vtkStdString &str,
1451        #   vtkImageData *data, int textDims[2], int dpi, int backend=Default)
1452
1453        blf = vtki.new("ImageBlend")
1454        blf.AddInputData(self.dataset)
1455        blf.AddInputData(img)
1456        blf.SetOpacity(0, 1)
1457        blf.SetOpacity(1, alpha)
1458        blf.SetBlendModeToNormal()
1459        blf.Update()
1460
1461        self._update(blf.GetOutput())
1462        self.pipeline = utils.OperationNode(
1463            "add_text", comment=f"{txt}", parents=[self], c="#f28482"
1464        )
1465        return self
1466
1467    def modified(self) -> Self:
1468        """Use this method in conjunction with `tonumpy()`
1469        to update any modifications to the image array."""
1470        self.dataset.GetPointData().GetScalars().Modified()
1471        return self
1472
1473    def write(self, filename: str) -> Self:
1474        """Write image to file as png or jpg."""
1475        vedo.file_io.write(self, filename)
1476        self.pipeline = utils.OperationNode(
1477            "write",
1478            comment=filename[:15],
1479            parents=[self],
1480            c="#8a817c",
1481            shape="cylinder",
1482        )
1483        return self
1484
1485#################################################
1486class Picture(Image):
1487    def __init__(self, obj=None, channels=3):
1488        """Deprecated. Use `Image` instead."""
1489        vedo.logger.warning("Picture() is deprecated, use Image() instead.")
1490        super().__init__(obj=obj, channels=channels)