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