vedo.core

common

CommonAlgorithms

Common algorithms.

Source code in vedo/core/common.py

class CommonAlgorithms:
    """Common algorithms."""

    def _ensure_cell_locator(self):
        """Build and cache a cell locator for the current dataset if missing."""
        if not self.cell_locator:
            self.cell_locator = vtki.new("CellTreeLocator")
            self.cell_locator.SetDataSet(self.dataset)
            self.cell_locator.BuildLocator()
        return self.cell_locator

    @staticmethod
    def _vtk_idlist_to_numpy(id_list) -> np.ndarray:
        """Convert a vtkIdList to a numpy array of ids."""
        return np.array([id_list.GetId(i) for i in range(id_list.GetNumberOfIds())])

    @staticmethod
    def _parse_vtk_flat_connectivity(arr1d) -> list:
        """Unpack VTK flat connectivity [nids, id0...idn, ...] into a list of lists."""
        i = 0
        conn = []
        n = len(arr1d)
        while i < n:
            nids = arr1d[i]
            conn.append([int(arr1d[i + k]) for k in range(1, nids + 1)])
            i += nids + 1
        return conn

    def _run_gradient_filter(
        self,
        mode: str,
        on: str,
        array_name: str | None,
        fast: bool,
        result_name: str,
    ) -> np.ndarray:
        """Shared implementation for gradient/divergence/vorticity extraction."""
        gf = vtki.new("GradientFilter")
        if on.startswith("p"):
            varr = self.dataset.GetPointData()
            assoc = vtki.vtkDataObject.FIELD_ASSOCIATION_POINTS
            def getter(out):
                return out.GetPointData().GetArray(result_name)
        elif on.startswith("c"):
            varr = self.dataset.GetCellData()
            assoc = vtki.vtkDataObject.FIELD_ASSOCIATION_CELLS
            def getter(out):
                return out.GetCellData().GetArray(result_name)
        else:
            vedo.logger.error(f"in {mode}(): unknown option {on}")
            raise RuntimeError(f"in {mode}(): unknown option '{on}'")

        if array_name is None:
            if mode == "gradient":
                active = varr.GetScalars()
                if not active:
                    vedo.logger.error(f"in gradient: no scalars found for {on}")
                    raise RuntimeError(f"in gradient(): no scalars found for '{on}'")
            else:
                active = varr.GetVectors()
                if not active:
                    vedo.logger.error(f"in {mode}(): no vectors found for {on}")
                    raise RuntimeError(f"in {mode}(): no vectors found for '{on}'")
            array_name = active.GetName()

        gf.SetInputData(self.dataset)
        gf.SetInputScalars(assoc, array_name)
        gf.SetFasterApproximation(fast)

        if mode == "gradient":
            gf.ComputeGradientOn()
        else:
            gf.ComputeGradientOff()
        if mode == "divergence":
            gf.ComputeDivergenceOn()
        else:
            gf.ComputeDivergenceOff()
        if mode == "vorticity":
            gf.ComputeVorticityOn()
        else:
            gf.ComputeVorticityOff()

        if mode == "gradient":
            gf.SetResultArrayName(result_name)
        elif mode == "divergence":
            gf.SetDivergenceArrayName(result_name)
        elif mode == "vorticity":
            gf.SetVorticityArrayName(result_name)

        gf.Update()
        return utils.vtk2numpy(getter(gf.GetOutput()))

    # ====== Data access ======

    @property
    def pointdata(self):
        """
        Return a `DataArrayHelper` to access point (vertex) data arrays.
        A data array can be indexed either as a string or by an integer number.
        E.g.:  `myobj.pointdata["arrayname"]`

        Usage:
            - `myobj.pointdata.keys()` returns the available data array names.
            - `myobj.pointdata.select(name)` makes this array the active one.
            - `myobj.pointdata.remove(name)` removes this array.
        """
        return DataArrayHelper(self, 0)

    @property
    def celldata(self):
        """
        Return a `DataArrayHelper` to access cell (face) data arrays.
        A data array can be indexed either as a string or by an integer number.
        E.g.:  `myobj.celldata["arrayname"]`

        Usage:
            - `myobj.celldata.keys()` returns the available data array names.
            - `myobj.celldata.select(name)` makes this array the active one.
            - `myobj.celldata.remove(name)` removes this array.
        """
        return DataArrayHelper(self, 1)

    @property
    def metadata(self):
        """
        Return a `DataArrayHelper` to access field data arrays (not tied to points or cells).
        A data array can be indexed either as a string or by an integer number.
        E.g.:  `myobj.metadata["arrayname"]`

        Usage:
            - `myobj.metadata.keys()` returns the available data array names.
            - `myobj.metadata.select(name)` makes this array the active one.
            - `myobj.metadata.remove(name)` removes this array.
        """
        return DataArrayHelper(self, 2)

    # ====== Object info ======

    def rename(self, newname: str) -> Self:
        """Rename the object"""
        try:
            self.name = newname
        except AttributeError:
            vedo.logger.error(f"Cannot rename object {self}")
        return self

    def memory_address(self) -> int:
        """
        Return a unique memory address integer which may serve as the ID of the
        object, or passed to c++ code.
        """
        # https://www.linkedin.com/pulse/speedup-your-code-accessing-python-vtk-objects-from-c-pletzer/
        # https://github.com/tfmoraes/polydata_connectivity
        return int(self.dataset.GetAddressAsString("")[5:], 16)

    def memory_size(self) -> int:
        """Return the approximate memory size of the object in kilobytes."""
        return self.dataset.GetActualMemorySize()

    def modified(self) -> Self:
        """Use in conjunction with `tonumpy()` to update any modifications to the image array."""
        self.dataset.GetPointData().Modified()
        scals = self.dataset.GetPointData().GetScalars()
        if scals:
            scals.Modified()
        return self

    def box(self, scale=1, padding=0) -> vedo.Mesh:
        """
        Return the bounding box as a new `Mesh` object.

        Args:
            scale (float):
                box size can be scaled by a factor
            padding (float, list):
                a constant padding can be added (can be a list `[padx,pady,padz]`)
        """
        b = self.bounds()
        if not utils.is_sequence(padding):
            padding = [padding, padding, padding]
        length, width, height = b[1] - b[0], b[3] - b[2], b[5] - b[4]
        tol = (length + width + height) / 30000  # useful for boxing text
        pos = [(b[0] + b[1]) / 2, (b[3] + b[2]) / 2, (b[5] + b[4]) / 2 - tol]
        bx = vedo.shapes.Box(
            pos,
            length * scale + padding[0],
            width * scale + padding[1],
            height * scale + padding[2],
            c="gray",
        )
        try:
            pr = vtki.vtkProperty()
            pr.DeepCopy(self.properties)
            bx.actor.SetProperty(pr)
            bx.properties = pr
        except (AttributeError, TypeError):
            pass
        bx.flat().lighting("off").wireframe(True)
        return bx

    def update_dataset(self, dataset, **kwargs) -> Self:
        """Update the dataset of the object with the provided VTK dataset."""
        self._update(dataset, **kwargs)
        return self

    # ====== Geometry & bounds ======

    def bounds(self) -> np.ndarray:
        """
        Get the object bounds.
        Returns a list in format `[xmin,xmax, ymin,ymax, zmin,zmax]`.
        """
        try:  # this is very slow for large meshes
            pts = self.vertices
            xmin, ymin, zmin = np.nanmin(pts, axis=0)
            xmax, ymax, zmax = np.nanmax(pts, axis=0)
            return np.array([xmin, xmax, ymin, ymax, zmin, zmax])
        except (AttributeError, ValueError):
            return np.array(self.dataset.GetBounds())

    def xbounds(self) -> np.ndarray:
        """Get the bounds `[xmin,xmax]`."""
        b = self.bounds()
        return np.array([b[0], b[1]])

    def ybounds(self) -> np.ndarray:
        """Get the bounds `[ymin,ymax]`."""
        b = self.bounds()
        return np.array([b[2], b[3]])

    def zbounds(self) -> np.ndarray:
        """Get the bounds `[zmin,zmax]`."""
        b = self.bounds()
        return np.array([b[4], b[5]])

    def diagonal_size(self) -> float:
        """Get the length of the diagonal of the bounding box."""
        b = self.bounds()
        return np.sqrt((b[1] - b[0]) ** 2 + (b[3] - b[2]) ** 2 + (b[5] - b[4]) ** 2)

    def average_size(self) -> float:
        """
        Calculate and return the average size of the object.
        This is the mean of the vertex distances from the center of mass.
        """
        coords = self.vertices
        if coords.shape[0] == 0:
            return 0.0
        cm = np.mean(coords, axis=0)
        cc = coords - cm
        return np.mean(np.linalg.norm(cc, axis=1))

    def center_of_mass(self) -> np.ndarray:
        """Get the center of mass of the object."""
        if isinstance(self, (vedo.RectilinearGrid, vedo.Volume)):
            return np.array(self.dataset.GetCenter())
        cmf = vtki.new("CenterOfMass")
        cmf.SetInputData(self.dataset)
        cmf.Update()
        c = cmf.GetCenter()
        return np.array(c)

    def copy_data_from(self, obj: Any) -> Self:
        """Copy all data (point and cell data) from this input object"""
        self.dataset.GetPointData().PassData(obj.dataset.GetPointData())
        self.dataset.GetCellData().PassData(obj.dataset.GetCellData())
        self.pipeline = utils.OperationNode(
            "copy_data_from",
            parents=[self, obj],
            comment=f"{obj.__class__.__name__}",
            shape="note",
            c="#ccc5b9",
        )
        return self

    def inputdata(self):
        """Obsolete, use `.dataset` instead."""
        vedo.logger.warning(
            "'inputdata()' is obsolete, use '.dataset' instead."
        )
        return self.dataset

    @property
    def npoints(self):
        """Retrieve the number of points (or vertices)."""
        return self.dataset.GetNumberOfPoints()

    @property
    def nvertices(self):
        """Retrieve the number of vertices (or points)."""
        return self.dataset.GetNumberOfPoints()

    @property
    def ncells(self):
        """Retrieve the number of cells."""
        return self.dataset.GetNumberOfCells()

    def cell_centers(self, copy_arrays=False) -> vedo.Points:
        """
        Get the coordinates of the cell centers as a `Points` object.

        Examples:
            - [delaunay2d.py](https://github.com/marcomusy/vedo/tree/master/examples/basic/delaunay2d.py)
        """
        vcen = vtki.new("CellCenters")
        vcen.SetCopyArrays(copy_arrays)
        vcen.SetVertexCells(copy_arrays)
        vcen.SetInputData(self.dataset)
        vcen.Update()
        vpts = vedo.Points(vcen.GetOutput())
        if copy_arrays:
            vpts.copy_properties_from(self)
        return vpts

    # ====== Connectivity ======

    @property
    def lines(self):
        """
        Get lines connectivity ids as a python array
        formatted as `[[id0,id1], [id3,id4], ...]`

        See also: `lines_as_flat_array()`.
        """
        try:
            arr1d = _get_data_legacy_format(self.dataset.GetLines())
        except AttributeError:
            return []
        return self._parse_vtk_flat_connectivity(arr1d)

    @property
    def lines_as_flat_array(self):
        """
        Get lines connectivity ids as a 1D numpy array.
        Format is e.g. [2,  10,20,  3, 10,11,12,  2, 70,80, ...]

        See also: `lines()`.
        """
        try:
            return _get_data_legacy_format(self.dataset.GetLines())
        except AttributeError:
            return np.array([], dtype=int)

    # ====== Spatial queries ======

    def mark_boundaries(self) -> Self:
        """
        Mark cells and vertices if they lie on a boundary.
        A new array called `BoundaryCells` is added to the object.
        """
        mb = vtki.new("MarkBoundaryFilter")
        mb.SetInputData(self.dataset)
        mb.Update()
        self.dataset.DeepCopy(mb.GetOutput())
        self.pipeline = utils.OperationNode("mark_boundaries", parents=[self])
        return self

    def find_cells_in_bounds(self, xbounds=(), ybounds=(), zbounds=()) -> np.ndarray:
        """
        Find cells that are within the specified bounds.
        """
        try:
            xbounds = list(xbounds.bounds())
        except AttributeError:
            pass

        if len(xbounds) == 6:
            bnds = xbounds
        else:
            bnds = list(self.bounds())
            if len(xbounds) == 2:
                bnds[0] = xbounds[0]
                bnds[1] = xbounds[1]
            if len(ybounds) == 2:
                bnds[2] = ybounds[0]
                bnds[3] = ybounds[1]
            if len(zbounds) == 2:
                bnds[4] = zbounds[0]
                bnds[5] = zbounds[1]

        cell_ids = vtki.vtkIdList()
        self._ensure_cell_locator().FindCellsWithinBounds(bnds, cell_ids)
        return self._vtk_idlist_to_numpy(cell_ids)

    def find_cells_along_line(self, p0, p1, tol=0.001) -> np.ndarray:
        """
        Find cells that are intersected by a line segment.
        """
        cell_ids = vtki.vtkIdList()
        self._ensure_cell_locator().FindCellsAlongLine(p0, p1, tol, cell_ids)
        return self._vtk_idlist_to_numpy(cell_ids)

    def find_cells_along_plane(self, origin, normal, tol=0.001) -> np.ndarray:
        """
        Find cells that are intersected by a plane.
        """
        cell_ids = vtki.vtkIdList()
        self._ensure_cell_locator().FindCellsAlongPlane(origin, normal, tol, cell_ids)
        return self._vtk_idlist_to_numpy(cell_ids)

    def keep_cell_types(self, types=()) -> Self:
        """
        Extract cells of a specific type.

        Check the VTK cell types here:
        https://vtk.org/doc/nightly/html/vtkCellType_8h.html
        """
        fe = vtki.new("ExtractCellsByType")
        fe.SetInputData(self.dataset)
        for t in types:
            try:
                if utils.is_integer(t):
                    it = t
                else:
                    it = vtki.cell_types[t.upper()]
            except KeyError:
                vedo.logger.error(f"Cell type '{t}' not recognized")
                continue
            fe.AddCellType(it)
        fe.Update()
        self._update(fe.GetOutput())
        return self

    # ====== Data mapping ======

    def map_cells_to_points(self, arrays=(), move=False) -> Self:
        """
        Interpolate cell data (i.e., data specified per cell or face)
        into point data (i.e., data specified at each vertex).
        The method of transformation is based on averaging the data values
        of all cells using a particular point.

        A custom list of arrays to be mapped can be passed in input.

        Set `move=True` to delete the original `celldata` array.
        """
        c2p = vtki.new("CellDataToPointData")
        c2p.SetInputData(self.dataset)
        if not move:
            c2p.PassCellDataOn()
        if arrays:
            c2p.ClearCellDataArrays()
            c2p.ProcessAllArraysOff()
            for arr in arrays:
                c2p.AddCellDataArray(arr)
        else:
            c2p.ProcessAllArraysOn()
        c2p.Update()
        self._update(c2p.GetOutput(), reset_locators=False)
        self.mapper.SetScalarModeToUsePointData()
        self.pipeline = utils.OperationNode("map_cells_to_points", parents=[self])
        return self

    # ====== Vertices & coordinates ======

    @property
    def vertices(self):
        """
        Return the vertices (points) coordinates.
        This is equivalent to `points` and `coordinates`.
        """
        try:
            # for polydata and unstructured grid
            vpts = self.dataset.GetPoints()
            if vpts is None:
                return np.array([], dtype=float)
            varr = vpts.GetData()
        except AttributeError:
            # 'vtkImageData' object has no attribute 'GetPoints'
            v2p = vtki.new("ImageToPoints")
            v2p.SetInputData(self.dataset)
            v2p.Update()
            varr = v2p.GetOutput().GetPoints().GetData()
        except TypeError:
            # for RectilinearGrid, StructuredGrid
            vpts = vtki.vtkPoints()
            self.dataset.GetPoints(vpts)
            varr = vpts.GetData()
        except Exception as e:
            vedo.logger.error(f"Cannot get point coords for {type(self)}: {e}")
            return np.array([], dtype=float)

        return utils.vtk2numpy(varr)

    # setter
    @vertices.setter
    def vertices(self, pts):
        """Set vertex coordinates. Same as `points` and `coordinates`."""
        pts = utils.make3d(pts)
        arr = utils.numpy2vtk(pts, dtype=np.float32)
        try:
            vpts = self.dataset.GetPoints()
            vpts.SetData(arr)
            vpts.Modified()
        except (AttributeError, TypeError):
            vedo.logger.error(f"Cannot set vertices for {type(self)}")
            return
        # reset mesh to identity matrix position/rotation:
        self.point_locator = None
        self.cell_locator = None
        self.line_locator = None
        self.transform = LinearTransform()

    @property
    def points(self):
        """
        Return the points coordinates. Same as `vertices` and `coordinates`.
        """
        return self.vertices

    @points.setter
    def points(self, pts):
        """Set points coordinates. Same as `vertices` and `coordinates`."""
        self.vertices = pts

    @property
    def coordinates(self):
        """Return the points coordinates. Same as `vertices` and `points`."""
        return self.vertices

    @coordinates.setter
    def coordinates(self, pts):
        """Set points coordinates. Same as `vertices` and `points`."""
        self.vertices = pts

    # ====== Cell connectivity ======

    @property
    def cells_as_flat_array(self):
        """
        Get cell connectivity ids as a 1D numpy array.
        Format is e.g. [3,  10,20,30  4, 10,11,12,13  ...]
        """
        try:
            # valid for unstructured grid
            arr1d = _get_data_legacy_format(self.dataset.GetCells())
        except AttributeError:
            try:
                # valid for polydata
                arr1d = _get_data_legacy_format(self.dataset.GetPolys())
            except AttributeError:
                return np.array([], dtype=int)
        return arr1d

    @property
    def cells(self):
        """
        Get the cells connectivity ids as a numpy array.

        The output format is: `[[id0 ... idn], [id0 ... idm],  etc]`.
        """
        try:
            # valid for unstructured grid
            arr1d = _get_data_legacy_format(self.dataset.GetCells())
        except AttributeError:
            try:
                # valid for polydata
                arr1d = _get_data_legacy_format(self.dataset.GetPolys())
            except AttributeError:
                return []
        return self._parse_vtk_flat_connectivity(arr1d)

    def cell_edge_neighbors(self):
        """
        Get the cell neighbor indices of each cell.

        Returns a python list of lists.
        """

        def face_to_edges(face):
            n = len(face)
            return [[face[i], face[(i + 1) % n]] for i in range(n)]

        pd = self.dataset
        pd.BuildLinks()

        neicells = []
        for i, cell in enumerate(self.cells):
            nn = []
            for edge in face_to_edges(cell):
                neighbors = vtki.vtkIdList()
                pd.GetCellEdgeNeighbors(i, edge[0], edge[1], neighbors)
                if neighbors.GetNumberOfIds() > 0:
                    neighbor = neighbors.GetId(0)
                    nn.append(neighbor)
            neicells.append(nn)

        return neicells

    def map_points_to_cells(self, arrays=(), move=False) -> Self:
        """
        Interpolate point data (i.e., data specified per point or vertex)
        into cell data (i.e., data specified per cell).
        The method of transformation is based on averaging the data values
        of all points defining a particular cell.

        A custom list of arrays to be mapped can be passed in input.

        Set `move=True` to delete the original `pointdata` array.

        Examples:
            - [mesh_map2cell.py](https://github.com/marcomusy/vedo/tree/master/examples/basic/mesh_map2cell.py)
        """
        p2c = vtki.new("PointDataToCellData")
        p2c.SetInputData(self.dataset)
        if not move:
            p2c.PassPointDataOn()
        if arrays:
            p2c.ClearPointDataArrays()
            p2c.ProcessAllArraysOff()
            for arr in arrays:
                p2c.AddPointDataArray(arr)
        else:
            p2c.ProcessAllArraysOn()
        p2c.Update()
        self._update(p2c.GetOutput(), reset_locators=False)
        self.mapper.SetScalarModeToUseCellData()
        self.pipeline = utils.OperationNode("map_points_to_cells", parents=[self])
        return self

    def resample_data_from(self, source, tol=None, categorical=False) -> Self:
        """
        Resample point and cell data from another dataset.
        The output has the same structure but its point data have
        the resampled values from target.

        Use `tol` to set the tolerance used to compute whether
        a point in the source is in a cell of the current object.
        Points without resampled values, and their cells, are marked as blank.
        If the data is categorical, then the resulting data will be determined
        by a nearest neighbor interpolation scheme.

        Examples:
        ```python
        from vedo import *
        m1 = Mesh(dataurl+'bunny.obj')#.add_gaussian_noise(0.1)
        pts = m1.coordinates
        ces = m1.cell_centers().coordinates
        m1.pointdata["xvalues"] = np.power(pts[:,0], 3)
        m1.celldata["yvalues"]  = np.power(ces[:,1], 3)
        m2 = Mesh(dataurl+'bunny.obj')
        m2.resample_data_from(m1)
        # print(m2.pointdata["xvalues"])
        show(m1, m2 , N=2, axes=1)
        ```
        """
        rs = vtki.new("ResampleWithDataSet")
        rs.SetInputData(self.dataset)
        rs.SetSourceData(source.dataset)

        rs.SetPassPointArrays(True)
        rs.SetPassCellArrays(True)
        rs.SetPassFieldArrays(True)
        rs.SetCategoricalData(categorical)

        rs.SetComputeTolerance(True)
        if tol is not None:
            rs.SetComputeTolerance(False)
            rs.SetTolerance(tol)
        rs.Update()
        self._update(rs.GetOutput(), reset_locators=False)
        self.pipeline = utils.OperationNode(
            "resample_data_from",
            comment=f"{source.__class__.__name__}",
            parents=[self, source],
        )
        return self

    def interpolate_data_from(
        self,
        source,
        radius=None,
        n=None,
        kernel="shepard",
        exclude=("Normals",),
        on="points",
        null_strategy=1,
        null_value=0,
    ) -> Self:
        """
        Interpolate over source to port its data onto the current object using various kernels.

        If n (number of closest points to use) is set then radius value is ignored.

        Check out also:
            `probe()` which in many cases can be faster.

        Args:
            kernel (str):
                available kernels are [shepard, gaussian, linear]
            null_strategy (int):
                specify a strategy to use when encountering a "null" point
                during the interpolation process. Null points occur when the local neighborhood
                (of nearby points to interpolate from) is empty.

                - Case 0: an output array is created that marks points
                  as being valid (=1) or null (invalid =0), and the null_value is set as well
                - Case 1: the output data value(s) are set to the provided null_value
                - Case 2: simply use the closest point to perform the interpolation.
            null_value (float):
                see above.

        Examples:
            - [interpolate_scalar1.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/interpolate_scalar1.py)
            - [interpolate_scalar3.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/interpolate_scalar3.py)
            - [interpolate_scalar4.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/interpolate_scalar4.py)
            - [image_probe.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/image_probe.py)

                ![](https://vedo.embl.es/images/advanced/interpolateMeshArray.png)
        """
        if radius is None and not n:
            vedo.logger.error(
                "in interpolate_data_from(): please set either radius or n"
            )
            raise RuntimeError("in interpolate_data_from(): please set either radius or n")

        if on == "points":
            points = source.dataset
        elif on == "cells":
            c2p = vtki.new("CellDataToPointData")
            c2p.SetInputData(source.dataset)
            c2p.Update()
            points = c2p.GetOutput()
        else:
            vedo.logger.error(
                "in interpolate_data_from(), on must be on points or cells"
            )
            raise RuntimeError("in interpolate_data_from(): 'on' must be 'points' or 'cells'")

        locator = vtki.new("PointLocator")
        locator.SetDataSet(points)
        locator.BuildLocator()

        if kernel.lower() == "shepard":
            kern = vtki.new("ShepardKernel")
            kern.SetPowerParameter(2)
        elif kernel.lower() == "gaussian":
            kern = vtki.new("GaussianKernel")
            kern.SetSharpness(2)
        elif kernel.lower() == "linear":
            kern = vtki.new("LinearKernel")
        else:
            vedo.logger.error("available kernels are: [shepard, gaussian, linear]")
            raise RuntimeError("in interpolate_data_from(): unknown kernel, use shepard/gaussian/linear")

        if n:
            kern.SetNumberOfPoints(n)
            kern.SetKernelFootprintToNClosest()
        else:
            kern.SetRadius(radius)
            kern.SetKernelFootprintToRadius()

        # remove arrays already present in self so the interpolator doesn't skip them
        clspd = self.dataset.GetPointData()
        clsnames = [clspd.GetArrayName(i) for i in range(clspd.GetNumberOfArrays())]
        srcpd = points.GetPointData()
        pointsnames = [srcpd.GetArrayName(i) for i in range(srcpd.GetNumberOfArrays())]

        for cname in clsnames:
            if cname in set(pointsnames) - set(exclude):
                clspd.RemoveArray(cname)

        interpolator = vtki.new("PointInterpolator")
        interpolator.SetInputData(self.dataset)
        interpolator.SetSourceData(points)
        interpolator.SetKernel(kern)
        interpolator.SetLocator(locator)
        interpolator.PassFieldArraysOn()
        interpolator.SetNullPointsStrategy(null_strategy)
        interpolator.SetNullValue(null_value)
        interpolator.SetValidPointsMaskArrayName("ValidPointMask")
        for ex in exclude:
            interpolator.AddExcludedArray(ex)

        # Keep existing non-overlapping arrays on destination dataset.
        # Overlapping names were already removed above to force interpolation output.

        interpolator.Update()

        if on == "cells":
            p2c = vtki.new("PointDataToCellData")
            p2c.SetInputData(interpolator.GetOutput())
            p2c.Update()
            cpoly = p2c.GetOutput()
        else:
            cpoly = interpolator.GetOutput()

        self._update(cpoly, reset_locators=False)

        self.pipeline = utils.OperationNode(
            "interpolate_data_from", parents=[self, source]
        )
        return self

    def add_ids(self) -> Self:
        """
        Generate point and cell ids arrays.

        Two new arrays are added to the mesh named `PointID` and `CellID`.
        """
        ids = vtki.new_ids_filter()
        if ids is None:
            vedo.logger.error(
                "add_ids(): cannot instantiate vtkIdFilter/vtkGenerateIds"
            )
            raise RuntimeError("add_ids(): missing VTK ids filter")
        ids.SetInputData(self.dataset)
        ids.PointIdsOn()
        ids.CellIdsOn()
        ids.FieldDataOff()
        ids.SetPointIdsArrayName("PointID")
        ids.SetCellIdsArrayName("CellID")
        ids.Update()
        # self._update(ids.GetOutput(), reset_locators=False)  # https://github.com/marcomusy/vedo/issues/1267
        point_arr = ids.GetOutput().GetPointData().GetArray("PointID")
        cell_arr = ids.GetOutput().GetCellData().GetArray("CellID")
        if point_arr:
            self.dataset.GetPointData().AddArray(point_arr)
        if cell_arr:
            self.dataset.GetCellData().AddArray(cell_arr)
        self.pipeline = utils.OperationNode("add_ids", parents=[self])
        return self

    # ====== Field operations ======

    def gradient(self, input_array=None, on="points", fast=False) -> np.ndarray:
        """
        Compute and return the gradient of the active scalar field as a numpy array.

        Args:
            input_array (str):
                array of the scalars to compute the gradient,
                if None the current active array is selected
            on (str):
                compute either on 'points' or 'cells' data
            fast (bool):
                if True, will use a less accurate algorithm
                that performs fewer derivative calculations (and is therefore faster).

        Examples:
            - [isolines.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/isolines.py)

            ![](https://user-images.githubusercontent.com/32848391/72433087-f00a8780-3798-11ea-9778-991f0abeca70.png)
        """
        return self._run_gradient_filter(
            mode="gradient",
            on=on,
            array_name=input_array,
            fast=fast,
            result_name="Gradient",
        )

    def divergence(self, array_name=None, on="points", fast=False) -> np.ndarray:
        """
        Compute and return the divergence of a vector field as a numpy array.

        Args:
            array_name (str):
                name of the array of vectors to compute the divergence,
                if None the current active array is selected
            on (str):
                compute either on 'points' or 'cells' data
            fast (bool):
                if True, will use a less accurate algorithm
                that performs fewer derivative calculations and is therefore faster.
        """
        return self._run_gradient_filter(
            mode="divergence",
            on=on,
            array_name=array_name,
            fast=fast,
            result_name="Divergence",
        )

    def vorticity(self, array_name=None, on="points", fast=False) -> np.ndarray:
        """
        Compute and return the vorticity of a vector field as a numpy array.

        Args:
            array_name (str):
                name of the array to compute the vorticity,
                if None the current active array is selected
            on (str):
                compute either on 'points' or 'cells' data
            fast (bool):
                if True, will use a less accurate algorithm
                that performs fewer derivative calculations (and is therefore faster).
        """
        return self._run_gradient_filter(
            mode="vorticity",
            on=on,
            array_name=array_name,
            fast=fast,
            result_name="Vorticity",
        )

    def probe(
        self,
        source,
        categorical=False,
        snap=False,
        tol=0,
    ) -> Self:
        """
        Takes a data set and probes its scalars at the specified points in space.

        Note that a mask is also output with valid/invalid points which can be accessed
        with `mesh.pointdata['ValidPointMask']`.

        Args:
            source : any dataset
                the data set to probe.
            categorical : bool
                control whether the source pointdata is to be treated as categorical.
            snap : bool
                snap to the cell with the closest point if no cell was found
            tol : float
                the tolerance to use when performing the probe.

        Check out also:
            `interpolate_data_from()` and `tovolume()`

        Examples:
            - [probe_points.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/probe_points.py)

                ![](https://vedo.embl.es/images/volumetric/probePoints.png)
        """
        probe_filter = vtki.new("ProbeFilter")
        probe_filter.SetSourceData(source.dataset)
        probe_filter.SetInputData(self.dataset)
        probe_filter.PassCellArraysOn()
        probe_filter.PassFieldArraysOn()
        probe_filter.PassPointArraysOn()
        probe_filter.SetCategoricalData(categorical)
        probe_filter.ComputeToleranceOff()
        if tol:
            probe_filter.ComputeToleranceOn()
            probe_filter.SetTolerance(tol)
        probe_filter.SetSnapToCellWithClosestPoint(snap)
        probe_filter.Update()
        self._update(probe_filter.GetOutput(), reset_locators=False)
        self.pipeline = utils.OperationNode("probe", parents=[self, source])
        self.pointdata.rename("vtkValidPointMask", "ValidPointMask")
        return self

    def compute_cell_size(self) -> Self:
        """
        Add to this object a cell data array
        containing the area, volume and edge length
        of the cells (when applicable to the object type).

        Array names are: `Area`, `Volume`, `Length`.
        """
        csf = vtki.new("CellSizeFilter")
        csf.SetInputData(self.dataset)
        csf.SetComputeArea(1)
        csf.SetComputeVolume(1)
        csf.SetComputeLength(1)
        csf.SetComputeVertexCount(0)
        csf.SetAreaArrayName("Area")
        csf.SetVolumeArrayName("Volume")
        csf.SetLengthArrayName("Length")
        csf.Update()
        self._update(csf.GetOutput(), reset_locators=False)
        self.pipeline = utils.OperationNode("compute_cell_size", parents=[self])
        return self

    def generate_random_data(self) -> Self:
        """Fill a dataset with random attributes"""
        gen = vtki.new("RandomAttributeGenerator")
        gen.SetInputData(self.dataset)
        gen.GenerateAllDataOn()
        gen.SetDataTypeToFloat()
        gen.GeneratePointNormalsOff()
        gen.GeneratePointTensorsOn()
        gen.GenerateCellScalarsOn()
        gen.Update()
        self._update(gen.GetOutput(), reset_locators=False)
        self.pipeline = utils.OperationNode("generate_random_data", parents=[self])
        return self

    def integrate_data(self) -> dict:
        """
        Integrate point and cell data arrays while computing length,
        area or volume of the domain. It works for 1D, 2D or 3D cells.

        For volumetric datasets, this filter ignores all but 3D cells.
        It will not compute the volume contained in a closed surface.

        Returns a dictionary with keys: `pointdata`, `celldata`, `metadata`,
        which contain the integration result for the corresponding attributes.

        Examples:
            ```python
            from vedo import *
            surf = Sphere(res=100)
            surf.pointdata['scalars'] = np.ones(surf.npoints)
            data = surf.integrate_data()
            print(data['pointdata']['scalars'], "is equal to 4pi", 4*np.pi)
            ```

            ```python
            from vedo import *

            xcoords1 = np.arange(0, 2.2, 0.2)
            xcoords2 = sqrt(np.arange(0, 4.2, 0.2))

            ycoords = np.arange(0, 1.2, 0.2)

            surf1 = Grid(s=(xcoords1, ycoords)).rotate_y(-45).lw(2)
            surf2 = Grid(s=(xcoords2, ycoords)).rotate_y(-45).lw(2)

            surf1.pointdata['scalars'] = surf1.vertices[:,2]
            surf2.pointdata['scalars'] = surf2.vertices[:,2]

            data1 = surf1.integrate_data()
            data2 = surf2.integrate_data()

            print(data1['pointdata']['scalars'],
                "is equal to",
                data2['pointdata']['scalars'],
                "even if the grids are different!",
                "(= the volume under the surface)"
            )
            show(surf1, surf2, N=2, axes=1).close()
            ```
        """
        vinteg = vtki.new("IntegrateAttributes")
        vinteg.SetInputData(self.dataset)
        vinteg.Update()
        ugrid = vedo.UnstructuredGrid(vinteg.GetOutput())
        data = dict(
            pointdata=ugrid.pointdata.todict(),
            celldata=ugrid.celldata.todict(),
            metadata=ugrid.metadata.todict(),
        )
        return data

    # ====== IO & conversion ======

    def write(self, filename, binary=True) -> None:
        """Write object to file."""
        vedo.file_io.write(self, filename, binary)
        self.pipeline = utils.OperationNode(
            "write",
            parents=[self],
            comment=str(filename)[:15],
            shape="folder",
            c="#8a817c",
        )

    def tomesh(self, bounds=(), shrink=0) -> vedo.Mesh:
        """
        Extract boundary geometry from dataset (or convert data to polygonal type).

        Two new arrays are added to the mesh: `OriginalCellIds` and `OriginalPointIds`
        to keep track of the original mesh elements.

        Args:
            bounds (list):
                specify a sub-region to extract
            shrink (float):
                shrink the cells to a fraction of their original size
        """
        geo = vtki.new("GeometryFilter")

        if shrink:
            sf = vtki.new("ShrinkFilter")
            sf.SetInputData(self.dataset)
            sf.SetShrinkFactor(shrink)
            sf.Update()
            geo.SetInputData(sf.GetOutput())
        else:
            geo.SetInputData(self.dataset)

        geo.SetPassThroughCellIds(1)
        geo.SetPassThroughPointIds(1)
        geo.SetOriginalCellIdsName("OriginalCellIds")
        geo.SetOriginalPointIdsName("OriginalPointIds")
        geo.SetNonlinearSubdivisionLevel(1)
        # geo.MergingOff() # crashes on StructuredGrids
        if bounds:
            geo.SetExtent(bounds)
            geo.ExtentClippingOn()
        geo.Update()
        msh = vedo.mesh.Mesh(geo.GetOutput())
        msh.pipeline = utils.OperationNode("tomesh", parents=[self], c="#9e2a2b")
        return msh

    # ====== Distance operations ======

    def signed_distance(
        self, dims=(20, 20, 20), bounds=None, invert=False, max_radius=None
    ) -> vedo.Volume:
        """
        Compute the `Volume` object whose voxels contains the signed distance from
        the object. The calling object must have "Normals" defined.

        Args:
            bounds (list, actor):
                bounding box sizes
            dims (list):
                dimensions (nr. of voxels) of the output volume.
            invert (bool):
                flip the sign
            max_radius (float):
                specify how far out to propagate distance calculation

        Examples:
            - [distance2mesh.py](https://github.com/marcomusy/vedo/blob/master/examples/basic/distance2mesh.py)

                ![](https://vedo.embl.es/images/basic/distance2mesh.png)
        """
        if bounds is None:
            bounds = self.bounds()
        if max_radius is None:
            max_radius = self.diagonal_size() / 2
        dist = vtki.new("SignedDistance")
        dist.SetInputData(self.dataset)
        dist.SetRadius(max_radius)
        dist.SetBounds(bounds)
        dist.SetDimensions(dims)
        dist.Update()
        img = dist.GetOutput()
        if invert:
            mat = vtki.new("ImageMathematics")
            mat.SetInput1Data(img)
            mat.SetOperationToMultiplyByK()
            mat.SetConstantK(-1)
            mat.Update()
            img = mat.GetOutput()

        vol = vedo.Volume(img)
        vol.name = "SignedDistanceVolume"
        vol.pipeline = utils.OperationNode(
            "signed_distance",
            parents=[self],
            comment=f"dims={tuple(vol.dimensions())}",
            c="#e9c46a:#0096c7",
        )
        return vol

    def unsigned_distance(
        self, dims=(25, 25, 25), bounds=(), max_radius=0, cap_value=0
    ) -> vedo.Volume:
        """
        Compute the `Volume` object whose voxels contains the unsigned distance
        from the input object.
        """
        dist = vtki.new("UnsignedDistance")
        dist.SetInputData(self.dataset)
        dist.SetDimensions(dims)

        if len(bounds) == 6:
            dist.SetBounds(bounds)
        else:
            dist.SetBounds(self.bounds())
        if not max_radius:
            max_radius = self.diagonal_size() / 10
        dist.SetRadius(max_radius)

        if self.point_locator:
            dist.SetLocator(self.point_locator)

        if cap_value is not None:
            dist.CappingOn()
            dist.SetCapValue(cap_value)
        dist.SetOutputScalarTypeToFloat()
        dist.Update()
        vol = vedo.Volume(dist.GetOutput())
        vol.name = "UnsignedDistanceVolume"
        vol.pipeline = utils.OperationNode(
            "unsigned_distance", parents=[self], c="#e9c46a:#0096c7"
        )
        return vol

    def smooth_data(
        self,
        niter=10,
        relaxation_factor=0.1,
        strategy=0,
        mask=None,
        mode="distance2",
        exclude=("Normals", "TextureCoordinates"),
    ) -> Self:
        """
        Smooth point attribute data using distance weighted Laplacian kernel.
        The effect is to blur regions of high variation and emphasize low variation regions.

        A central concept of this method is the point smoothing stencil.
        A smoothing stencil for a point p(i) is the list of points p(j) which connect to p(i) via an edge.
        To smooth the attributes of point p(i), p(i)'s attribute data a(i) are iteratively averaged using
        the distance weighted average of the attributes of a(j) (the weights w[j] sum to 1).
        This averaging process is repeated until the maximum number of iterations is reached.

        The relaxation factor (R) is also important as the smoothing process proceeds in an iterative fashion.
        The a(i+1) attributes are determined from the a(i) attributes as follows:
            a(i+1) = (1-R)*a(i) + R*sum(w(j)*a(j))

        Convergence occurs faster for larger relaxation factors.
        Typically a small number of iterations is required for large relaxation factors,
        and in cases where only points adjacent to the boundary are being smoothed, a single iteration with R=1 may be
        adequate (i.e., just a distance weighted average is computed).

        Warning:
            Certain data attributes cannot be correctly interpolated.
            For example, surface normals are expected to be |n|=1;
            after attribute smoothing this constraint is likely to be violated.
            Other vectors and tensors may suffer from similar issues.
            In such a situation, specify `exclude=...` which will not be smoothed
            (and simply passed through to the output).
            Distance weighting function is based on averaging, 1/r, or 1/r**2 weights, where r is the distance
            between the point to be smoothed and an edge connected neighbor (defined by the smoothing stencil).
            The weights are normalized so that sum(w(i))==1. When smoothing based on averaging,
            the weights are simply 1/n, where n is the number of connected points in the stencil.
            The smoothing process reduces high frequency information in the data attributes.
            With excessive smoothing (large numbers of iterations, and/or a large relaxation factor)
            important details may be lost, and the attributes will move towards an "average" value.
            While this filter will process any dataset type, if the input data is a 3D image volume,
            it's likely much faster to use an image-based algorithm to perform data smoothing.
            To determine boundary points in polygonal data, edges used by only one cell are considered boundary
            (and hence the associated points defining the edge).

        Args:
            niter (int):
                number of iterations
            relaxation_factor (float):
                relaxation factor controlling the amount of Laplacian smoothing applied
            strategy (int):
                strategy to use for Laplacian smoothing

                    - 0: use all points, all point data attributes are smoothed
                    - 1: smooth all point attribute data except those on the boundary
                    - 2: only point data connected to a boundary point are smoothed

            mask (str, np.ndarray):
                array to be used as a mask (ignore then the strategy keyword)
            mode (str):
                smoothing mode, either "distance2", "distance" or "average"

                    - distance**2 weighted (i.e., 1/r**2 interpolation weights)
                    - distance weighted (i.e., 1/r) approach;
                    - simple average of all connected points in the stencil

            exclude (list):
                list of arrays to be excluded from smoothing
        """
        saf = vtki.new("AttributeSmoothingFilter")
        saf.SetInputData(self.dataset)
        saf.SetRelaxationFactor(relaxation_factor)
        saf.SetNumberOfIterations(niter)

        for ex in exclude:
            saf.AddExcludedArray(ex)

        if mode == "distance":
            saf.SetWeightsTypeToDistance()
        elif mode == "distance2":
            saf.SetWeightsTypeToDistance2()
        elif mode == "average":
            saf.SetWeightsTypeToAverage()
        else:
            vedo.logger.error(f"smooth_data(): unknown mode '{mode}'")
            raise TypeError(f"smooth_data(): unknown mode '{mode}', use 'distance2', 'distance', or 'average'")

        if mask is not None:
            saf.SetSmoothingStrategyToSmoothingMask()
            if isinstance(mask, str):
                mask_ = self.dataset.GetPointData().GetArray(mask)
                if not mask_:
                    vedo.logger.error(f"smooth_data(): mask array {mask} not found")
                    return self
                mask_array = vtki.vtkUnsignedCharArray()
                mask_array.ShallowCopy(mask_)
                mask_array.SetName(mask_.GetName())
            else:
                mask_array = utils.numpy2vtk(mask, dtype=np.uint8)
            saf.SetSmoothingMask(mask_array)
        else:
            saf.SetSmoothingStrategy(strategy)

        saf.Update()

        self._update(saf.GetOutput())
        self.pipeline = utils.OperationNode(
            "smooth_data", comment=f"strategy {strategy}", parents=[self], c="#9e2a2b"
        )
        return self

    def compute_streamlines(
        self,
        seeds: Any,
        integrator="rk4",
        direction="forward",
        initial_step_size=None,
        max_propagation=None,
        max_steps=10000,
        step_length=0,
        surface_constrained=False,
        compute_vorticity=False,
    ) -> vedo.Lines | None:
        """
        Integrate a vector field to generate streamlines.

        Args:
            seeds (Mesh, Points, list):
                starting points of the streamlines
            integrator (str):
                type of integration method to be used:

                    - rk2: Runge-Kutta 2
                    - rk4: Runge-Kutta 4
                    - rk45: Runge-Kutta 45

            direction (str):
                direction of integration, either "forward", "backward" or "both"
            initial_step_size (float):
                initial step size used for line integration
            max_propagation (float):
                maximum length of a streamline expressed in absolute units
            max_steps (int):
                maximum number of steps for a streamline
            step_length (float):
                maximum length of a step expressed in absolute units
            surface_constrained (bool):
                whether to stop integrating when the streamline leaves the surface
            compute_vorticity (bool):
                whether to compute the vorticity at each streamline point
        """
        b = self.dataset.GetBounds()
        size = (b[5] - b[4] + b[3] - b[2] + b[1] - b[0]) / 3
        if initial_step_size is None:
            initial_step_size = size / 1000.0

        if max_propagation is None:
            max_propagation = size * 2

        if utils.is_sequence(seeds):
            seeds = vedo.Points(seeds)

        sti = vtki.new("StreamTracer")
        sti.SetSourceData(seeds.dataset)
        if isinstance(self, vedo.RectilinearGrid):
            sti.SetInputData(vedo.UnstructuredGrid(self.dataset).dataset)
        else:
            sti.SetInputDataObject(self.dataset)

        sti.SetInitialIntegrationStep(initial_step_size)
        sti.SetComputeVorticity(compute_vorticity)
        sti.SetMaximumNumberOfSteps(max_steps)
        sti.SetMaximumPropagation(max_propagation)
        sti.SetSurfaceStreamlines(surface_constrained)
        if step_length:
            sti.SetMaximumIntegrationStep(step_length)

        if "for" in direction:
            sti.SetIntegrationDirectionToForward()
        elif "back" in direction:
            sti.SetIntegrationDirectionToBackward()
        elif "both" in direction:
            sti.SetIntegrationDirectionToBoth()
        else:
            vedo.logger.error(
                f"in compute_streamlines(), unknown direction {direction}"
            )
            return None

        if integrator == "rk2":
            sti.SetIntegratorTypeToRungeKutta2()
        elif integrator == "rk4":
            sti.SetIntegratorTypeToRungeKutta4()
        elif integrator == "rk45":
            sti.SetIntegratorTypeToRungeKutta45()
        else:
            vedo.logger.error(
                f"in compute_streamlines(), unknown integrator {integrator}"
            )
            return None

        sti.Update()

        stlines = vedo.shapes.Lines(sti.GetOutput(), lw=4)
        stlines.name = "StreamLines"
        self.pipeline = utils.OperationNode(
            "compute_streamlines",
            comment=f"{integrator}",
            parents=[self, seeds],
            c="#9e2a2b",
        )
        return stlines

celldata property

Return a DataArrayHelper to access cell (face) data arrays. A data array can be indexed either as a string or by an integer number. E.g.: myobj.celldata["arrayname"]

Usage

• myobj.celldata.keys() returns the available data array names.
• myobj.celldata.select(name) makes this array the active one.
• myobj.celldata.remove(name) removes this array.

cells property

Get the cells connectivity ids as a numpy array.

The output format is: [[id0 ... idn], [id0 ... idm], etc].

cells_as_flat_array property

Get cell connectivity ids as a 1D numpy array. Format is e.g. [3, 10,20,30 4, 10,11,12,13 ...]

coordinates property writable

Return the points coordinates. Same as vertices and points.

lines property

Get lines connectivity ids as a python array formatted as [[id0,id1], [id3,id4], ...]

See also: lines_as_flat_array().

lines_as_flat_array property

Get lines connectivity ids as a 1D numpy array. Format is e.g. [2, 10,20, 3, 10,11,12, 2, 70,80, ...]

See also: lines().

metadata property

Return a DataArrayHelper to access field data arrays (not tied to points or cells). A data array can be indexed either as a string or by an integer number. E.g.: myobj.metadata["arrayname"]

Usage

• myobj.metadata.keys() returns the available data array names.
• myobj.metadata.select(name) makes this array the active one.
• myobj.metadata.remove(name) removes this array.

ncells property

Retrieve the number of cells.

npoints property

Retrieve the number of points (or vertices).

nvertices property

Retrieve the number of vertices (or points).

pointdata property

Return a DataArrayHelper to access point (vertex) data arrays. A data array can be indexed either as a string or by an integer number. E.g.: myobj.pointdata["arrayname"]

Usage

• myobj.pointdata.keys() returns the available data array names.
• myobj.pointdata.select(name) makes this array the active one.
• myobj.pointdata.remove(name) removes this array.

points property writable

Return the points coordinates. Same as vertices and coordinates.

vertices property writable

Return the vertices (points) coordinates. This is equivalent to points and coordinates.

add_ids()

Generate point and cell ids arrays.

Two new arrays are added to the mesh named PointID and CellID.

Source code in vedo/core/common.py

def add_ids(self) -> Self:
    """
    Generate point and cell ids arrays.

    Two new arrays are added to the mesh named `PointID` and `CellID`.
    """
    ids = vtki.new_ids_filter()
    if ids is None:
        vedo.logger.error(
            "add_ids(): cannot instantiate vtkIdFilter/vtkGenerateIds"
        )
        raise RuntimeError("add_ids(): missing VTK ids filter")
    ids.SetInputData(self.dataset)
    ids.PointIdsOn()
    ids.CellIdsOn()
    ids.FieldDataOff()
    ids.SetPointIdsArrayName("PointID")
    ids.SetCellIdsArrayName("CellID")
    ids.Update()
    # self._update(ids.GetOutput(), reset_locators=False)  # https://github.com/marcomusy/vedo/issues/1267
    point_arr = ids.GetOutput().GetPointData().GetArray("PointID")
    cell_arr = ids.GetOutput().GetCellData().GetArray("CellID")
    if point_arr:
        self.dataset.GetPointData().AddArray(point_arr)
    if cell_arr:
        self.dataset.GetCellData().AddArray(cell_arr)
    self.pipeline = utils.OperationNode("add_ids", parents=[self])
    return self

average_size()

Calculate and return the average size of the object. This is the mean of the vertex distances from the center of mass.

Source code in vedo/core/common.py

def average_size(self) -> float:
    """
    Calculate and return the average size of the object.
    This is the mean of the vertex distances from the center of mass.
    """
    coords = self.vertices
    if coords.shape[0] == 0:
        return 0.0
    cm = np.mean(coords, axis=0)
    cc = coords - cm
    return np.mean(np.linalg.norm(cc, axis=1))

bounds()

Get the object bounds. Returns a list in format [xmin,xmax, ymin,ymax, zmin,zmax].

Source code in vedo/core/common.py

def bounds(self) -> np.ndarray:
    """
    Get the object bounds.
    Returns a list in format `[xmin,xmax, ymin,ymax, zmin,zmax]`.
    """
    try:  # this is very slow for large meshes
        pts = self.vertices
        xmin, ymin, zmin = np.nanmin(pts, axis=0)
        xmax, ymax, zmax = np.nanmax(pts, axis=0)
        return np.array([xmin, xmax, ymin, ymax, zmin, zmax])
    except (AttributeError, ValueError):
        return np.array(self.dataset.GetBounds())

box(scale=1, padding=0)

Return the bounding box as a new Mesh object.

Parameters:

Name	Type	Description	Default
scale	float	box size can be scaled by a factor	1
padding	(float, list)	a constant padding can be added (can be a list [padx,pady,padz])	0

Source code in vedo/core/common.py

def box(self, scale=1, padding=0) -> vedo.Mesh:
    """
    Return the bounding box as a new `Mesh` object.

    Args:
        scale (float):
            box size can be scaled by a factor
        padding (float, list):
            a constant padding can be added (can be a list `[padx,pady,padz]`)
    """
    b = self.bounds()
    if not utils.is_sequence(padding):
        padding = [padding, padding, padding]
    length, width, height = b[1] - b[0], b[3] - b[2], b[5] - b[4]
    tol = (length + width + height) / 30000  # useful for boxing text
    pos = [(b[0] + b[1]) / 2, (b[3] + b[2]) / 2, (b[5] + b[4]) / 2 - tol]
    bx = vedo.shapes.Box(
        pos,
        length * scale + padding[0],
        width * scale + padding[1],
        height * scale + padding[2],
        c="gray",
    )
    try:
        pr = vtki.vtkProperty()
        pr.DeepCopy(self.properties)
        bx.actor.SetProperty(pr)
        bx.properties = pr
    except (AttributeError, TypeError):
        pass
    bx.flat().lighting("off").wireframe(True)
    return bx

cell_centers(copy_arrays=False)

Get the coordinates of the cell centers as a Points object.

Examples:

• delaunay2d.py

Source code in vedo/core/common.py

def cell_centers(self, copy_arrays=False) -> vedo.Points:
    """
    Get the coordinates of the cell centers as a `Points` object.

    Examples:
        - [delaunay2d.py](https://github.com/marcomusy/vedo/tree/master/examples/basic/delaunay2d.py)
    """
    vcen = vtki.new("CellCenters")
    vcen.SetCopyArrays(copy_arrays)
    vcen.SetVertexCells(copy_arrays)
    vcen.SetInputData(self.dataset)
    vcen.Update()
    vpts = vedo.Points(vcen.GetOutput())
    if copy_arrays:
        vpts.copy_properties_from(self)
    return vpts

cell_edge_neighbors()

Get the cell neighbor indices of each cell.

Returns a python list of lists.

Source code in vedo/core/common.py

def cell_edge_neighbors(self):
    """
    Get the cell neighbor indices of each cell.

    Returns a python list of lists.
    """

    def face_to_edges(face):
        n = len(face)
        return [[face[i], face[(i + 1) % n]] for i in range(n)]

    pd = self.dataset
    pd.BuildLinks()

    neicells = []
    for i, cell in enumerate(self.cells):
        nn = []
        for edge in face_to_edges(cell):
            neighbors = vtki.vtkIdList()
            pd.GetCellEdgeNeighbors(i, edge[0], edge[1], neighbors)
            if neighbors.GetNumberOfIds() > 0:
                neighbor = neighbors.GetId(0)
                nn.append(neighbor)
        neicells.append(nn)

    return neicells

center_of_mass()

Get the center of mass of the object.

Source code in vedo/core/common.py

def center_of_mass(self) -> np.ndarray:
    """Get the center of mass of the object."""
    if isinstance(self, (vedo.RectilinearGrid, vedo.Volume)):
        return np.array(self.dataset.GetCenter())
    cmf = vtki.new("CenterOfMass")
    cmf.SetInputData(self.dataset)
    cmf.Update()
    c = cmf.GetCenter()
    return np.array(c)

compute_cell_size()

Add to this object a cell data array containing the area, volume and edge length of the cells (when applicable to the object type).

Array names are: Area, Volume, Length.

Source code in vedo/core/common.py

def compute_cell_size(self) -> Self:
    """
    Add to this object a cell data array
    containing the area, volume and edge length
    of the cells (when applicable to the object type).

    Array names are: `Area`, `Volume`, `Length`.
    """
    csf = vtki.new("CellSizeFilter")
    csf.SetInputData(self.dataset)
    csf.SetComputeArea(1)
    csf.SetComputeVolume(1)
    csf.SetComputeLength(1)
    csf.SetComputeVertexCount(0)
    csf.SetAreaArrayName("Area")
    csf.SetVolumeArrayName("Volume")
    csf.SetLengthArrayName("Length")
    csf.Update()
    self._update(csf.GetOutput(), reset_locators=False)
    self.pipeline = utils.OperationNode("compute_cell_size", parents=[self])
    return self

compute_streamlines(seeds, integrator='rk4', direction='forward', initial_step_size=None, max_propagation=None, max_steps=10000, step_length=0, surface_constrained=False, compute_vorticity=False)

Integrate a vector field to generate streamlines.

Parameters:

Name	Type	Description	Default
seeds	(Mesh, Points, list)	starting points of the streamlines	required
integrator	str	type of integration method to be used: - rk2: Runge-Kutta 2 - rk4: Runge-Kutta 4 - rk45: Runge-Kutta 45	'rk4'
direction	str	direction of integration, either "forward", "backward" or "both"	'forward'
initial_step_size	float	initial step size used for line integration	None
max_propagation	float	maximum length of a streamline expressed in absolute units	None
max_steps	int	maximum number of steps for a streamline	10000
step_length	float	maximum length of a step expressed in absolute units	0
surface_constrained	bool	whether to stop integrating when the streamline leaves the surface	False
compute_vorticity	bool	whether to compute the vorticity at each streamline point	False

Source code in vedo/core/common.py

def compute_streamlines(
    self,
    seeds: Any,
    integrator="rk4",
    direction="forward",
    initial_step_size=None,
    max_propagation=None,
    max_steps=10000,
    step_length=0,
    surface_constrained=False,
    compute_vorticity=False,
) -> vedo.Lines | None:
    """
    Integrate a vector field to generate streamlines.

    Args:
        seeds (Mesh, Points, list):
            starting points of the streamlines
        integrator (str):
            type of integration method to be used:

                - rk2: Runge-Kutta 2
                - rk4: Runge-Kutta 4
                - rk45: Runge-Kutta 45

        direction (str):
            direction of integration, either "forward", "backward" or "both"
        initial_step_size (float):
            initial step size used for line integration
        max_propagation (float):
            maximum length of a streamline expressed in absolute units
        max_steps (int):
            maximum number of steps for a streamline
        step_length (float):
            maximum length of a step expressed in absolute units
        surface_constrained (bool):
            whether to stop integrating when the streamline leaves the surface
        compute_vorticity (bool):
            whether to compute the vorticity at each streamline point
    """
    b = self.dataset.GetBounds()
    size = (b[5] - b[4] + b[3] - b[2] + b[1] - b[0]) / 3
    if initial_step_size is None:
        initial_step_size = size / 1000.0

    if max_propagation is None:
        max_propagation = size * 2

    if utils.is_sequence(seeds):
        seeds = vedo.Points(seeds)

    sti = vtki.new("StreamTracer")
    sti.SetSourceData(seeds.dataset)
    if isinstance(self, vedo.RectilinearGrid):
        sti.SetInputData(vedo.UnstructuredGrid(self.dataset).dataset)
    else:
        sti.SetInputDataObject(self.dataset)

    sti.SetInitialIntegrationStep(initial_step_size)
    sti.SetComputeVorticity(compute_vorticity)
    sti.SetMaximumNumberOfSteps(max_steps)
    sti.SetMaximumPropagation(max_propagation)
    sti.SetSurfaceStreamlines(surface_constrained)
    if step_length:
        sti.SetMaximumIntegrationStep(step_length)

    if "for" in direction:
        sti.SetIntegrationDirectionToForward()
    elif "back" in direction:
        sti.SetIntegrationDirectionToBackward()
    elif "both" in direction:
        sti.SetIntegrationDirectionToBoth()
    else:
        vedo.logger.error(
            f"in compute_streamlines(), unknown direction {direction}"
        )
        return None

    if integrator == "rk2":
        sti.SetIntegratorTypeToRungeKutta2()
    elif integrator == "rk4":
        sti.SetIntegratorTypeToRungeKutta4()
    elif integrator == "rk45":
        sti.SetIntegratorTypeToRungeKutta45()
    else:
        vedo.logger.error(
            f"in compute_streamlines(), unknown integrator {integrator}"
        )
        return None

    sti.Update()

    stlines = vedo.shapes.Lines(sti.GetOutput(), lw=4)
    stlines.name = "StreamLines"
    self.pipeline = utils.OperationNode(
        "compute_streamlines",
        comment=f"{integrator}",
        parents=[self, seeds],
        c="#9e2a2b",
    )
    return stlines

copy_data_from(obj)

Copy all data (point and cell data) from this input object

Source code in vedo/core/common.py

def copy_data_from(self, obj: Any) -> Self:
    """Copy all data (point and cell data) from this input object"""
    self.dataset.GetPointData().PassData(obj.dataset.GetPointData())
    self.dataset.GetCellData().PassData(obj.dataset.GetCellData())
    self.pipeline = utils.OperationNode(
        "copy_data_from",
        parents=[self, obj],
        comment=f"{obj.__class__.__name__}",
        shape="note",
        c="#ccc5b9",
    )
    return self

diagonal_size()

Get the length of the diagonal of the bounding box.

Source code in vedo/core/common.py

def diagonal_size(self) -> float:
    """Get the length of the diagonal of the bounding box."""
    b = self.bounds()
    return np.sqrt((b[1] - b[0]) ** 2 + (b[3] - b[2]) ** 2 + (b[5] - b[4]) ** 2)

divergence(array_name=None, on='points', fast=False)

Compute and return the divergence of a vector field as a numpy array.

Parameters:

Name	Type	Description	Default
array_name	str	name of the array of vectors to compute the divergence, if None the current active array is selected	None
on	str	compute either on 'points' or 'cells' data	'points'
fast	bool	if True, will use a less accurate algorithm that performs fewer derivative calculations and is therefore faster.	False

Source code in vedo/core/common.py

def divergence(self, array_name=None, on="points", fast=False) -> np.ndarray:
    """
    Compute and return the divergence of a vector field as a numpy array.

    Args:
        array_name (str):
            name of the array of vectors to compute the divergence,
            if None the current active array is selected
        on (str):
            compute either on 'points' or 'cells' data
        fast (bool):
            if True, will use a less accurate algorithm
            that performs fewer derivative calculations and is therefore faster.
    """
    return self._run_gradient_filter(
        mode="divergence",
        on=on,
        array_name=array_name,
        fast=fast,
        result_name="Divergence",
    )

find_cells_along_line(p0, p1, tol=0.001)

Find cells that are intersected by a line segment.

Source code in vedo/core/common.py

def find_cells_along_line(self, p0, p1, tol=0.001) -> np.ndarray:
    """
    Find cells that are intersected by a line segment.
    """
    cell_ids = vtki.vtkIdList()
    self._ensure_cell_locator().FindCellsAlongLine(p0, p1, tol, cell_ids)
    return self._vtk_idlist_to_numpy(cell_ids)

find_cells_along_plane(origin, normal, tol=0.001)

Find cells that are intersected by a plane.

Source code in vedo/core/common.py

def find_cells_along_plane(self, origin, normal, tol=0.001) -> np.ndarray:
    """
    Find cells that are intersected by a plane.
    """
    cell_ids = vtki.vtkIdList()
    self._ensure_cell_locator().FindCellsAlongPlane(origin, normal, tol, cell_ids)
    return self._vtk_idlist_to_numpy(cell_ids)

find_cells_in_bounds(xbounds=(), ybounds=(), zbounds=())

Find cells that are within the specified bounds.

Source code in vedo/core/common.py

def find_cells_in_bounds(self, xbounds=(), ybounds=(), zbounds=()) -> np.ndarray:
    """
    Find cells that are within the specified bounds.
    """
    try:
        xbounds = list(xbounds.bounds())
    except AttributeError:
        pass

    if len(xbounds) == 6:
        bnds = xbounds
    else:
        bnds = list(self.bounds())
        if len(xbounds) == 2:
            bnds[0] = xbounds[0]
            bnds[1] = xbounds[1]
        if len(ybounds) == 2:
            bnds[2] = ybounds[0]
            bnds[3] = ybounds[1]
        if len(zbounds) == 2:
            bnds[4] = zbounds[0]
            bnds[5] = zbounds[1]

    cell_ids = vtki.vtkIdList()
    self._ensure_cell_locator().FindCellsWithinBounds(bnds, cell_ids)
    return self._vtk_idlist_to_numpy(cell_ids)

generate_random_data()

Fill a dataset with random attributes

Source code in vedo/core/common.py

def generate_random_data(self) -> Self:
    """Fill a dataset with random attributes"""
    gen = vtki.new("RandomAttributeGenerator")
    gen.SetInputData(self.dataset)
    gen.GenerateAllDataOn()
    gen.SetDataTypeToFloat()
    gen.GeneratePointNormalsOff()
    gen.GeneratePointTensorsOn()
    gen.GenerateCellScalarsOn()
    gen.Update()
    self._update(gen.GetOutput(), reset_locators=False)
    self.pipeline = utils.OperationNode("generate_random_data", parents=[self])
    return self

gradient(input_array=None, on='points', fast=False)

Compute and return the gradient of the active scalar field as a numpy array.

Parameters:

Name	Type	Description	Default
input_array	str	array of the scalars to compute the gradient, if None the current active array is selected	None
on	str	compute either on 'points' or 'cells' data	'points'
fast	bool	if True, will use a less accurate algorithm that performs fewer derivative calculations (and is therefore faster).	False

Examples:

• isolines.py

Source code in vedo/core/common.py

def gradient(self, input_array=None, on="points", fast=False) -> np.ndarray:
    """
    Compute and return the gradient of the active scalar field as a numpy array.

    Args:
        input_array (str):
            array of the scalars to compute the gradient,
            if None the current active array is selected
        on (str):
            compute either on 'points' or 'cells' data
        fast (bool):
            if True, will use a less accurate algorithm
            that performs fewer derivative calculations (and is therefore faster).

    Examples:
        - [isolines.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/isolines.py)

        ![](https://user-images.githubusercontent.com/32848391/72433087-f00a8780-3798-11ea-9778-991f0abeca70.png)
    """
    return self._run_gradient_filter(
        mode="gradient",
        on=on,
        array_name=input_array,
        fast=fast,
        result_name="Gradient",
    )

inputdata()

Obsolete, use .dataset instead.

Source code in vedo/core/common.py

def inputdata(self):
    """Obsolete, use `.dataset` instead."""
    vedo.logger.warning(
        "'inputdata()' is obsolete, use '.dataset' instead."
    )
    return self.dataset

integrate_data()

Integrate point and cell data arrays while computing length, area or volume of the domain. It works for 1D, 2D or 3D cells.

For volumetric datasets, this filter ignores all but 3D cells. It will not compute the volume contained in a closed surface.

Returns a dictionary with keys: pointdata, celldata, metadata, which contain the integration result for the corresponding attributes.

Examples:

from vedo import *
surf = Sphere(res=100)
surf.pointdata['scalars'] = np.ones(surf.npoints)
data = surf.integrate_data()
print(data['pointdata']['scalars'], "is equal to 4pi", 4*np.pi)

from vedo import *

xcoords1 = np.arange(0, 2.2, 0.2)
xcoords2 = sqrt(np.arange(0, 4.2, 0.2))

ycoords = np.arange(0, 1.2, 0.2)

surf1 = Grid(s=(xcoords1, ycoords)).rotate_y(-45).lw(2)
surf2 = Grid(s=(xcoords2, ycoords)).rotate_y(-45).lw(2)

surf1.pointdata['scalars'] = surf1.vertices[:,2]
surf2.pointdata['scalars'] = surf2.vertices[:,2]

data1 = surf1.integrate_data()
data2 = surf2.integrate_data()

print(data1['pointdata']['scalars'],
    "is equal to",
    data2['pointdata']['scalars'],
    "even if the grids are different!",
    "(= the volume under the surface)"
)
show(surf1, surf2, N=2, axes=1).close()

Source code in vedo/core/common.py

def integrate_data(self) -> dict:
    """
    Integrate point and cell data arrays while computing length,
    area or volume of the domain. It works for 1D, 2D or 3D cells.

    For volumetric datasets, this filter ignores all but 3D cells.
    It will not compute the volume contained in a closed surface.

    Returns a dictionary with keys: `pointdata`, `celldata`, `metadata`,
    which contain the integration result for the corresponding attributes.

    Examples:
        ```python
        from vedo import *
        surf = Sphere(res=100)
        surf.pointdata['scalars'] = np.ones(surf.npoints)
        data = surf.integrate_data()
        print(data['pointdata']['scalars'], "is equal to 4pi", 4*np.pi)
        ```

        ```python
        from vedo import *

        xcoords1 = np.arange(0, 2.2, 0.2)
        xcoords2 = sqrt(np.arange(0, 4.2, 0.2))

        ycoords = np.arange(0, 1.2, 0.2)

        surf1 = Grid(s=(xcoords1, ycoords)).rotate_y(-45).lw(2)
        surf2 = Grid(s=(xcoords2, ycoords)).rotate_y(-45).lw(2)

        surf1.pointdata['scalars'] = surf1.vertices[:,2]
        surf2.pointdata['scalars'] = surf2.vertices[:,2]

        data1 = surf1.integrate_data()
        data2 = surf2.integrate_data()

        print(data1['pointdata']['scalars'],
            "is equal to",
            data2['pointdata']['scalars'],
            "even if the grids are different!",
            "(= the volume under the surface)"
        )
        show(surf1, surf2, N=2, axes=1).close()
        ```
    """
    vinteg = vtki.new("IntegrateAttributes")
    vinteg.SetInputData(self.dataset)
    vinteg.Update()
    ugrid = vedo.UnstructuredGrid(vinteg.GetOutput())
    data = dict(
        pointdata=ugrid.pointdata.todict(),
        celldata=ugrid.celldata.todict(),
        metadata=ugrid.metadata.todict(),
    )
    return data

interpolate_data_from(source, radius=None, n=None, kernel='shepard', exclude=('Normals',), on='points', null_strategy=1, null_value=0)

Interpolate over source to port its data onto the current object using various kernels.

If n (number of closest points to use) is set then radius value is ignored.

Check out also

probe() which in many cases can be faster.

Parameters:

Name	Type	Description	Default
kernel	str	available kernels are [shepard, gaussian, linear]	'shepard'
null_strategy	int	specify a strategy to use when encountering a "null" point during the interpolation process. Null points occur when the local neighborhood (of nearby points to interpolate from) is empty. Case 0: an output array is created that marks points as being valid (=1) or null (invalid =0), and the null_value is set as well Case 1: the output data value(s) are set to the provided null_value Case 2: simply use the closest point to perform the interpolation.	1
null_value	float	see above.	0

Examples:

• interpolate_scalar1.py
• interpolate_scalar3.py
• interpolate_scalar4.py

• image_probe.py

  

Source code in vedo/core/common.py

def interpolate_data_from(
    self,
    source,
    radius=None,
    n=None,
    kernel="shepard",
    exclude=("Normals",),
    on="points",
    null_strategy=1,
    null_value=0,
) -> Self:
    """
    Interpolate over source to port its data onto the current object using various kernels.

    If n (number of closest points to use) is set then radius value is ignored.

    Check out also:
        `probe()` which in many cases can be faster.

    Args:
        kernel (str):
            available kernels are [shepard, gaussian, linear]
        null_strategy (int):
            specify a strategy to use when encountering a "null" point
            during the interpolation process. Null points occur when the local neighborhood
            (of nearby points to interpolate from) is empty.

            - Case 0: an output array is created that marks points
              as being valid (=1) or null (invalid =0), and the null_value is set as well
            - Case 1: the output data value(s) are set to the provided null_value
            - Case 2: simply use the closest point to perform the interpolation.
        null_value (float):
            see above.

    Examples:
        - [interpolate_scalar1.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/interpolate_scalar1.py)
        - [interpolate_scalar3.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/interpolate_scalar3.py)
        - [interpolate_scalar4.py](https://github.com/marcomusy/vedo/tree/master/examples/advanced/interpolate_scalar4.py)
        - [image_probe.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/image_probe.py)

            ![](https://vedo.embl.es/images/advanced/interpolateMeshArray.png)
    """
    if radius is None and not n:
        vedo.logger.error(
            "in interpolate_data_from(): please set either radius or n"
        )
        raise RuntimeError("in interpolate_data_from(): please set either radius or n")

    if on == "points":
        points = source.dataset
    elif on == "cells":
        c2p = vtki.new("CellDataToPointData")
        c2p.SetInputData(source.dataset)
        c2p.Update()
        points = c2p.GetOutput()
    else:
        vedo.logger.error(
            "in interpolate_data_from(), on must be on points or cells"
        )
        raise RuntimeError("in interpolate_data_from(): 'on' must be 'points' or 'cells'")

    locator = vtki.new("PointLocator")
    locator.SetDataSet(points)
    locator.BuildLocator()

    if kernel.lower() == "shepard":
        kern = vtki.new("ShepardKernel")
        kern.SetPowerParameter(2)
    elif kernel.lower() == "gaussian":
        kern = vtki.new("GaussianKernel")
        kern.SetSharpness(2)
    elif kernel.lower() == "linear":
        kern = vtki.new("LinearKernel")
    else:
        vedo.logger.error("available kernels are: [shepard, gaussian, linear]")
        raise RuntimeError("in interpolate_data_from(): unknown kernel, use shepard/gaussian/linear")

    if n:
        kern.SetNumberOfPoints(n)
        kern.SetKernelFootprintToNClosest()
    else:
        kern.SetRadius(radius)
        kern.SetKernelFootprintToRadius()

    # remove arrays already present in self so the interpolator doesn't skip them
    clspd = self.dataset.GetPointData()
    clsnames = [clspd.GetArrayName(i) for i in range(clspd.GetNumberOfArrays())]
    srcpd = points.GetPointData()
    pointsnames = [srcpd.GetArrayName(i) for i in range(srcpd.GetNumberOfArrays())]

    for cname in clsnames:
        if cname in set(pointsnames) - set(exclude):
            clspd.RemoveArray(cname)

    interpolator = vtki.new("PointInterpolator")
    interpolator.SetInputData(self.dataset)
    interpolator.SetSourceData(points)
    interpolator.SetKernel(kern)
    interpolator.SetLocator(locator)
    interpolator.PassFieldArraysOn()
    interpolator.SetNullPointsStrategy(null_strategy)
    interpolator.SetNullValue(null_value)
    interpolator.SetValidPointsMaskArrayName("ValidPointMask")
    for ex in exclude:
        interpolator.AddExcludedArray(ex)

    # Keep existing non-overlapping arrays on destination dataset.
    # Overlapping names were already removed above to force interpolation output.

    interpolator.Update()

    if on == "cells":
        p2c = vtki.new("PointDataToCellData")
        p2c.SetInputData(interpolator.GetOutput())
        p2c.Update()
        cpoly = p2c.GetOutput()
    else:
        cpoly = interpolator.GetOutput()

    self._update(cpoly, reset_locators=False)

    self.pipeline = utils.OperationNode(
        "interpolate_data_from", parents=[self, source]
    )
    return self

keep_cell_types(types=())

Extract cells of a specific type.

Check the VTK cell types here: https://vtk.org/doc/nightly/html/vtkCellType_8h.html

Source code in vedo/core/common.py

def keep_cell_types(self, types=()) -> Self:
    """
    Extract cells of a specific type.

    Check the VTK cell types here:
    https://vtk.org/doc/nightly/html/vtkCellType_8h.html
    """
    fe = vtki.new("ExtractCellsByType")
    fe.SetInputData(self.dataset)
    for t in types:
        try:
            if utils.is_integer(t):
                it = t
            else:
                it = vtki.cell_types[t.upper()]
        except KeyError:
            vedo.logger.error(f"Cell type '{t}' not recognized")
            continue
        fe.AddCellType(it)
    fe.Update()
    self._update(fe.GetOutput())
    return self

map_cells_to_points(arrays=(), move=False)

Interpolate cell data (i.e., data specified per cell or face) into point data (i.e., data specified at each vertex). The method of transformation is based on averaging the data values of all cells using a particular point.

A custom list of arrays to be mapped can be passed in input.

Set move=True to delete the original celldata array.

Source code in vedo/core/common.py

def map_cells_to_points(self, arrays=(), move=False) -> Self:
    """
    Interpolate cell data (i.e., data specified per cell or face)
    into point data (i.e., data specified at each vertex).
    The method of transformation is based on averaging the data values
    of all cells using a particular point.

    A custom list of arrays to be mapped can be passed in input.

    Set `move=True` to delete the original `celldata` array.
    """
    c2p = vtki.new("CellDataToPointData")
    c2p.SetInputData(self.dataset)
    if not move:
        c2p.PassCellDataOn()
    if arrays:
        c2p.ClearCellDataArrays()
        c2p.ProcessAllArraysOff()
        for arr in arrays:
            c2p.AddCellDataArray(arr)
    else:
        c2p.ProcessAllArraysOn()
    c2p.Update()
    self._update(c2p.GetOutput(), reset_locators=False)
    self.mapper.SetScalarModeToUsePointData()
    self.pipeline = utils.OperationNode("map_cells_to_points", parents=[self])
    return self

map_points_to_cells(arrays=(), move=False)

Interpolate point data (i.e., data specified per point or vertex) into cell data (i.e., data specified per cell). The method of transformation is based on averaging the data values of all points defining a particular cell.

A custom list of arrays to be mapped can be passed in input.

Set move=True to delete the original pointdata array.

Examples:

• mesh_map2cell.py

Source code in vedo/core/common.py

def map_points_to_cells(self, arrays=(), move=False) -> Self:
    """
    Interpolate point data (i.e., data specified per point or vertex)
    into cell data (i.e., data specified per cell).
    The method of transformation is based on averaging the data values
    of all points defining a particular cell.

    A custom list of arrays to be mapped can be passed in input.

    Set `move=True` to delete the original `pointdata` array.

    Examples:
        - [mesh_map2cell.py](https://github.com/marcomusy/vedo/tree/master/examples/basic/mesh_map2cell.py)
    """
    p2c = vtki.new("PointDataToCellData")
    p2c.SetInputData(self.dataset)
    if not move:
        p2c.PassPointDataOn()
    if arrays:
        p2c.ClearPointDataArrays()
        p2c.ProcessAllArraysOff()
        for arr in arrays:
            p2c.AddPointDataArray(arr)
    else:
        p2c.ProcessAllArraysOn()
    p2c.Update()
    self._update(p2c.GetOutput(), reset_locators=False)
    self.mapper.SetScalarModeToUseCellData()
    self.pipeline = utils.OperationNode("map_points_to_cells", parents=[self])
    return self

mark_boundaries()

Mark cells and vertices if they lie on a boundary. A new array called BoundaryCells is added to the object.

Source code in vedo/core/common.py

def mark_boundaries(self) -> Self:
    """
    Mark cells and vertices if they lie on a boundary.
    A new array called `BoundaryCells` is added to the object.
    """
    mb = vtki.new("MarkBoundaryFilter")
    mb.SetInputData(self.dataset)
    mb.Update()
    self.dataset.DeepCopy(mb.GetOutput())
    self.pipeline = utils.OperationNode("mark_boundaries", parents=[self])
    return self

memory_address()

Return a unique memory address integer which may serve as the ID of the object, or passed to c++ code.

Source code in vedo/core/common.py

def memory_address(self) -> int:
    """
    Return a unique memory address integer which may serve as the ID of the
    object, or passed to c++ code.
    """
    # https://www.linkedin.com/pulse/speedup-your-code-accessing-python-vtk-objects-from-c-pletzer/
    # https://github.com/tfmoraes/polydata_connectivity
    return int(self.dataset.GetAddressAsString("")[5:], 16)

memory_size()

Return the approximate memory size of the object in kilobytes.

Source code in vedo/core/common.py

def memory_size(self) -> int:
    """Return the approximate memory size of the object in kilobytes."""
    return self.dataset.GetActualMemorySize()

modified()

Use in conjunction with tonumpy() to update any modifications to the image array.

Source code in vedo/core/common.py

def modified(self) -> Self:
    """Use in conjunction with `tonumpy()` to update any modifications to the image array."""
    self.dataset.GetPointData().Modified()
    scals = self.dataset.GetPointData().GetScalars()
    if scals:
        scals.Modified()
    return self

probe(source, categorical=False, snap=False, tol=0)

Takes a data set and probes its scalars at the specified points in space.

Note that a mask is also output with valid/invalid points which can be accessed with mesh.pointdata['ValidPointMask'].

Parameters:

Name	Type	Description	Default
source		any dataset the data set to probe.	required
categorical		bool control whether the source pointdata is to be treated as categorical.	required
snap		bool snap to the cell with the closest point if no cell was found	required
tol		float the tolerance to use when performing the probe.	required

Check out also

interpolate_data_from() and tovolume()

Examples:

• probe_points.py

  

Source code in vedo/core/common.py

def probe(
    self,
    source,
    categorical=False,
    snap=False,
    tol=0,
) -> Self:
    """
    Takes a data set and probes its scalars at the specified points in space.

    Note that a mask is also output with valid/invalid points which can be accessed
    with `mesh.pointdata['ValidPointMask']`.

    Args:
        source : any dataset
            the data set to probe.
        categorical : bool
            control whether the source pointdata is to be treated as categorical.
        snap : bool
            snap to the cell with the closest point if no cell was found
        tol : float
            the tolerance to use when performing the probe.

    Check out also:
        `interpolate_data_from()` and `tovolume()`

    Examples:
        - [probe_points.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/probe_points.py)

            ![](https://vedo.embl.es/images/volumetric/probePoints.png)
    """
    probe_filter = vtki.new("ProbeFilter")
    probe_filter.SetSourceData(source.dataset)
    probe_filter.SetInputData(self.dataset)
    probe_filter.PassCellArraysOn()
    probe_filter.PassFieldArraysOn()
    probe_filter.PassPointArraysOn()
    probe_filter.SetCategoricalData(categorical)
    probe_filter.ComputeToleranceOff()
    if tol:
        probe_filter.ComputeToleranceOn()
        probe_filter.SetTolerance(tol)
    probe_filter.SetSnapToCellWithClosestPoint(snap)
    probe_filter.Update()
    self._update(probe_filter.GetOutput(), reset_locators=False)
    self.pipeline = utils.OperationNode("probe", parents=[self, source])
    self.pointdata.rename("vtkValidPointMask", "ValidPointMask")
    return self

rename(newname)

Rename the object

Source code in vedo/core/common.py

def rename(self, newname: str) -> Self:
    """Rename the object"""
    try:
        self.name = newname
    except AttributeError:
        vedo.logger.error(f"Cannot rename object {self}")
    return self

resample_data_from(source, tol=None, categorical=False)

Resample point and cell data from another dataset. The output has the same structure but its point data have the resampled values from target.

Use tol to set the tolerance used to compute whether a point in the source is in a cell of the current object. Points without resampled values, and their cells, are marked as blank. If the data is categorical, then the resulting data will be determined by a nearest neighbor interpolation scheme.

Examples:

from vedo import *
m1 = Mesh(dataurl+'bunny.obj')#.add_gaussian_noise(0.1)
pts = m1.coordinates
ces = m1.cell_centers().coordinates
m1.pointdata["xvalues"] = np.power(pts[:,0], 3)
m1.celldata["yvalues"]  = np.power(ces[:,1], 3)
m2 = Mesh(dataurl+'bunny.obj')
m2.resample_data_from(m1)
# print(m2.pointdata["xvalues"])
show(m1, m2 , N=2, axes=1)

Source code in vedo/core/common.py

def resample_data_from(self, source, tol=None, categorical=False) -> Self:
    """
    Resample point and cell data from another dataset.
    The output has the same structure but its point data have
    the resampled values from target.

    Use `tol` to set the tolerance used to compute whether
    a point in the source is in a cell of the current object.
    Points without resampled values, and their cells, are marked as blank.
    If the data is categorical, then the resulting data will be determined
    by a nearest neighbor interpolation scheme.

    Examples:
    ```python
    from vedo import *
    m1 = Mesh(dataurl+'bunny.obj')#.add_gaussian_noise(0.1)
    pts = m1.coordinates
    ces = m1.cell_centers().coordinates
    m1.pointdata["xvalues"] = np.power(pts[:,0], 3)
    m1.celldata["yvalues"]  = np.power(ces[:,1], 3)
    m2 = Mesh(dataurl+'bunny.obj')
    m2.resample_data_from(m1)
    # print(m2.pointdata["xvalues"])
    show(m1, m2 , N=2, axes=1)
    ```
    """
    rs = vtki.new("ResampleWithDataSet")
    rs.SetInputData(self.dataset)
    rs.SetSourceData(source.dataset)

    rs.SetPassPointArrays(True)
    rs.SetPassCellArrays(True)
    rs.SetPassFieldArrays(True)
    rs.SetCategoricalData(categorical)

    rs.SetComputeTolerance(True)
    if tol is not None:
        rs.SetComputeTolerance(False)
        rs.SetTolerance(tol)
    rs.Update()
    self._update(rs.GetOutput(), reset_locators=False)
    self.pipeline = utils.OperationNode(
        "resample_data_from",
        comment=f"{source.__class__.__name__}",
        parents=[self, source],
    )
    return self

signed_distance(dims=(20, 20, 20), bounds=None, invert=False, max_radius=None)

Compute the Volume object whose voxels contains the signed distance from the object. The calling object must have "Normals" defined.

Parameters:

Name	Type	Description	Default
bounds	(list, actor)	bounding box sizes	None
dims	list	dimensions (nr. of voxels) of the output volume.	(20, 20, 20)
invert	bool	flip the sign	False
max_radius	float	specify how far out to propagate distance calculation	None

Examples:

• distance2mesh.py

  

Source code in vedo/core/common.py

def signed_distance(
    self, dims=(20, 20, 20), bounds=None, invert=False, max_radius=None
) -> vedo.Volume:
    """
    Compute the `Volume` object whose voxels contains the signed distance from
    the object. The calling object must have "Normals" defined.

    Args:
        bounds (list, actor):
            bounding box sizes
        dims (list):
            dimensions (nr. of voxels) of the output volume.
        invert (bool):
            flip the sign
        max_radius (float):
            specify how far out to propagate distance calculation

    Examples:
        - [distance2mesh.py](https://github.com/marcomusy/vedo/blob/master/examples/basic/distance2mesh.py)

            ![](https://vedo.embl.es/images/basic/distance2mesh.png)
    """
    if bounds is None:
        bounds = self.bounds()
    if max_radius is None:
        max_radius = self.diagonal_size() / 2
    dist = vtki.new("SignedDistance")
    dist.SetInputData(self.dataset)
    dist.SetRadius(max_radius)
    dist.SetBounds(bounds)
    dist.SetDimensions(dims)
    dist.Update()
    img = dist.GetOutput()
    if invert:
        mat = vtki.new("ImageMathematics")
        mat.SetInput1Data(img)
        mat.SetOperationToMultiplyByK()
        mat.SetConstantK(-1)
        mat.Update()
        img = mat.GetOutput()

    vol = vedo.Volume(img)
    vol.name = "SignedDistanceVolume"
    vol.pipeline = utils.OperationNode(
        "signed_distance",
        parents=[self],
        comment=f"dims={tuple(vol.dimensions())}",
        c="#e9c46a:#0096c7",
    )
    return vol

smooth_data(niter=10, relaxation_factor=0.1, strategy=0, mask=None, mode='distance2', exclude=('Normals', 'TextureCoordinates'))

Smooth point attribute data using distance weighted Laplacian kernel. The effect is to blur regions of high variation and emphasize low variation regions.

A central concept of this method is the point smoothing stencil. A smoothing stencil for a point p(i) is the list of points p(j) which connect to p(i) via an edge. To smooth the attributes of point p(i), p(i)'s attribute data a(i) are iteratively averaged using the distance weighted average of the attributes of a(j) (the weights w[j] sum to 1). This averaging process is repeated until the maximum number of iterations is reached.

The relaxation factor (R) is also important as the smoothing process proceeds in an iterative fashion. The a(i+1) attributes are determined from the a(i) attributes as follows: a(i+1) = (1-R)a(i) + Rsum(w(j)*a(j))

Convergence occurs faster for larger relaxation factors. Typically a small number of iterations is required for large relaxation factors, and in cases where only points adjacent to the boundary are being smoothed, a single iteration with R=1 may be adequate (i.e., just a distance weighted average is computed).

Warning

Certain data attributes cannot be correctly interpolated. For example, surface normals are expected to be |n|=1; after attribute smoothing this constraint is likely to be violated. Other vectors and tensors may suffer from similar issues. In such a situation, specify exclude=... which will not be smoothed (and simply passed through to the output). Distance weighting function is based on averaging, 1/r, or 1/r**2 weights, where r is the distance between the point to be smoothed and an edge connected neighbor (defined by the smoothing stencil). The weights are normalized so that sum(w(i))==1. When smoothing based on averaging, the weights are simply 1/n, where n is the number of connected points in the stencil. The smoothing process reduces high frequency information in the data attributes. With excessive smoothing (large numbers of iterations, and/or a large relaxation factor) important details may be lost, and the attributes will move towards an "average" value. While this filter will process any dataset type, if the input data is a 3D image volume, it's likely much faster to use an image-based algorithm to perform data smoothing. To determine boundary points in polygonal data, edges used by only one cell are considered boundary (and hence the associated points defining the edge).

Parameters:

Name	Type	Description	Default
niter	int	number of iterations	10
relaxation_factor	float	relaxation factor controlling the amount of Laplacian smoothing applied	0.1
strategy	int	strategy to use for Laplacian smoothing - 0: use all points, all point data attributes are smoothed - 1: smooth all point attribute data except those on the boundary - 2: only point data connected to a boundary point are smoothed	0
mask	(str, ndarray)	array to be used as a mask (ignore then the strategy keyword)	None
mode	str	smoothing mode, either "distance2", "distance" or "average" - distance**2 weighted (i.e., 1/r**2 interpolation weights) - distance weighted (i.e., 1/r) approach; - simple average of all connected points in the stencil	'distance2'
exclude	list	list of arrays to be excluded from smoothing	('Normals', 'TextureCoordinates')

Source code in vedo/core/common.py

def smooth_data(
    self,
    niter=10,
    relaxation_factor=0.1,
    strategy=0,
    mask=None,
    mode="distance2",
    exclude=("Normals", "TextureCoordinates"),
) -> Self:
    """
    Smooth point attribute data using distance weighted Laplacian kernel.
    The effect is to blur regions of high variation and emphasize low variation regions.

    A central concept of this method is the point smoothing stencil.
    A smoothing stencil for a point p(i) is the list of points p(j) which connect to p(i) via an edge.
    To smooth the attributes of point p(i), p(i)'s attribute data a(i) are iteratively averaged using
    the distance weighted average of the attributes of a(j) (the weights w[j] sum to 1).
    This averaging process is repeated until the maximum number of iterations is reached.

    The relaxation factor (R) is also important as the smoothing process proceeds in an iterative fashion.
    The a(i+1) attributes are determined from the a(i) attributes as follows:
        a(i+1) = (1-R)*a(i) + R*sum(w(j)*a(j))

    Convergence occurs faster for larger relaxation factors.
    Typically a small number of iterations is required for large relaxation factors,
    and in cases where only points adjacent to the boundary are being smoothed, a single iteration with R=1 may be
    adequate (i.e., just a distance weighted average is computed).

    Warning:
        Certain data attributes cannot be correctly interpolated.
        For example, surface normals are expected to be |n|=1;
        after attribute smoothing this constraint is likely to be violated.
        Other vectors and tensors may suffer from similar issues.
        In such a situation, specify `exclude=...` which will not be smoothed
        (and simply passed through to the output).
        Distance weighting function is based on averaging, 1/r, or 1/r**2 weights, where r is the distance
        between the point to be smoothed and an edge connected neighbor (defined by the smoothing stencil).
        The weights are normalized so that sum(w(i))==1. When smoothing based on averaging,
        the weights are simply 1/n, where n is the number of connected points in the stencil.
        The smoothing process reduces high frequency information in the data attributes.
        With excessive smoothing (large numbers of iterations, and/or a large relaxation factor)
        important details may be lost, and the attributes will move towards an "average" value.
        While this filter will process any dataset type, if the input data is a 3D image volume,
        it's likely much faster to use an image-based algorithm to perform data smoothing.
        To determine boundary points in polygonal data, edges used by only one cell are considered boundary
        (and hence the associated points defining the edge).

    Args:
        niter (int):
            number of iterations
        relaxation_factor (float):
            relaxation factor controlling the amount of Laplacian smoothing applied
        strategy (int):
            strategy to use for Laplacian smoothing

                - 0: use all points, all point data attributes are smoothed
                - 1: smooth all point attribute data except those on the boundary
                - 2: only point data connected to a boundary point are smoothed

        mask (str, np.ndarray):
            array to be used as a mask (ignore then the strategy keyword)
        mode (str):
            smoothing mode, either "distance2", "distance" or "average"

                - distance**2 weighted (i.e., 1/r**2 interpolation weights)
                - distance weighted (i.e., 1/r) approach;
                - simple average of all connected points in the stencil

        exclude (list):
            list of arrays to be excluded from smoothing
    """
    saf = vtki.new("AttributeSmoothingFilter")
    saf.SetInputData(self.dataset)
    saf.SetRelaxationFactor(relaxation_factor)
    saf.SetNumberOfIterations(niter)

    for ex in exclude:
        saf.AddExcludedArray(ex)

    if mode == "distance":
        saf.SetWeightsTypeToDistance()
    elif mode == "distance2":
        saf.SetWeightsTypeToDistance2()
    elif mode == "average":
        saf.SetWeightsTypeToAverage()
    else:
        vedo.logger.error(f"smooth_data(): unknown mode '{mode}'")
        raise TypeError(f"smooth_data(): unknown mode '{mode}', use 'distance2', 'distance', or 'average'")

    if mask is not None:
        saf.SetSmoothingStrategyToSmoothingMask()
        if isinstance(mask, str):
            mask_ = self.dataset.GetPointData().GetArray(mask)
            if not mask_:
                vedo.logger.error(f"smooth_data(): mask array {mask} not found")
                return self
            mask_array = vtki.vtkUnsignedCharArray()
            mask_array.ShallowCopy(mask_)
            mask_array.SetName(mask_.GetName())
        else:
            mask_array = utils.numpy2vtk(mask, dtype=np.uint8)
        saf.SetSmoothingMask(mask_array)
    else:
        saf.SetSmoothingStrategy(strategy)

    saf.Update()

    self._update(saf.GetOutput())
    self.pipeline = utils.OperationNode(
        "smooth_data", comment=f"strategy {strategy}", parents=[self], c="#9e2a2b"
    )
    return self

tomesh(bounds=(), shrink=0)

Extract boundary geometry from dataset (or convert data to polygonal type).

Two new arrays are added to the mesh: OriginalCellIds and OriginalPointIds to keep track of the original mesh elements.

Parameters:

Name	Type	Description	Default
bounds	list	specify a sub-region to extract	()
shrink	float	shrink the cells to a fraction of their original size	0

Source code in vedo/core/common.py

def tomesh(self, bounds=(), shrink=0) -> vedo.Mesh:
    """
    Extract boundary geometry from dataset (or convert data to polygonal type).

    Two new arrays are added to the mesh: `OriginalCellIds` and `OriginalPointIds`
    to keep track of the original mesh elements.

    Args:
        bounds (list):
            specify a sub-region to extract
        shrink (float):
            shrink the cells to a fraction of their original size
    """
    geo = vtki.new("GeometryFilter")

    if shrink:
        sf = vtki.new("ShrinkFilter")
        sf.SetInputData(self.dataset)
        sf.SetShrinkFactor(shrink)
        sf.Update()
        geo.SetInputData(sf.GetOutput())
    else:
        geo.SetInputData(self.dataset)

    geo.SetPassThroughCellIds(1)
    geo.SetPassThroughPointIds(1)
    geo.SetOriginalCellIdsName("OriginalCellIds")
    geo.SetOriginalPointIdsName("OriginalPointIds")
    geo.SetNonlinearSubdivisionLevel(1)
    # geo.MergingOff() # crashes on StructuredGrids
    if bounds:
        geo.SetExtent(bounds)
        geo.ExtentClippingOn()
    geo.Update()
    msh = vedo.mesh.Mesh(geo.GetOutput())
    msh.pipeline = utils.OperationNode("tomesh", parents=[self], c="#9e2a2b")
    return msh

unsigned_distance(dims=(25, 25, 25), bounds=(), max_radius=0, cap_value=0)

Compute the Volume object whose voxels contains the unsigned distance from the input object.

Source code in vedo/core/common.py

def unsigned_distance(
    self, dims=(25, 25, 25), bounds=(), max_radius=0, cap_value=0
) -> vedo.Volume:
    """
    Compute the `Volume` object whose voxels contains the unsigned distance
    from the input object.
    """
    dist = vtki.new("UnsignedDistance")
    dist.SetInputData(self.dataset)
    dist.SetDimensions(dims)

    if len(bounds) == 6:
        dist.SetBounds(bounds)
    else:
        dist.SetBounds(self.bounds())
    if not max_radius:
        max_radius = self.diagonal_size() / 10
    dist.SetRadius(max_radius)

    if self.point_locator:
        dist.SetLocator(self.point_locator)

    if cap_value is not None:
        dist.CappingOn()
        dist.SetCapValue(cap_value)
    dist.SetOutputScalarTypeToFloat()
    dist.Update()
    vol = vedo.Volume(dist.GetOutput())
    vol.name = "UnsignedDistanceVolume"
    vol.pipeline = utils.OperationNode(
        "unsigned_distance", parents=[self], c="#e9c46a:#0096c7"
    )
    return vol

update_dataset(dataset, **kwargs)

Update the dataset of the object with the provided VTK dataset.

Source code in vedo/core/common.py

def update_dataset(self, dataset, **kwargs) -> Self:
    """Update the dataset of the object with the provided VTK dataset."""
    self._update(dataset, **kwargs)
    return self

vorticity(array_name=None, on='points', fast=False)

Compute and return the vorticity of a vector field as a numpy array.

Parameters:

Name	Type	Description	Default
array_name	str	name of the array to compute the vorticity, if None the current active array is selected	None
on	str	compute either on 'points' or 'cells' data	'points'
fast	bool	if True, will use a less accurate algorithm that performs fewer derivative calculations (and is therefore faster).	False

Source code in vedo/core/common.py

def vorticity(self, array_name=None, on="points", fast=False) -> np.ndarray:
    """
    Compute and return the vorticity of a vector field as a numpy array.

    Args:
        array_name (str):
            name of the array to compute the vorticity,
            if None the current active array is selected
        on (str):
            compute either on 'points' or 'cells' data
        fast (bool):
            if True, will use a less accurate algorithm
            that performs fewer derivative calculations (and is therefore faster).
    """
    return self._run_gradient_filter(
        mode="vorticity",
        on=on,
        array_name=array_name,
        fast=fast,
        result_name="Vorticity",
    )

write(filename, binary=True)

Write object to file.

Source code in vedo/core/common.py

def write(self, filename, binary=True) -> None:
    """Write object to file."""
    vedo.file_io.write(self, filename, binary)
    self.pipeline = utils.OperationNode(
        "write",
        parents=[self],
        comment=str(filename)[:15],
        shape="folder",
        c="#8a817c",
    )

xbounds()

Get the bounds [xmin,xmax].

Source code in vedo/core/common.py

def xbounds(self) -> np.ndarray:
    """Get the bounds `[xmin,xmax]`."""
    b = self.bounds()
    return np.array([b[0], b[1]])

ybounds()

Get the bounds [ymin,ymax].

Source code in vedo/core/common.py

def ybounds(self) -> np.ndarray:
    """Get the bounds `[ymin,ymax]`."""
    b = self.bounds()
    return np.array([b[2], b[3]])

zbounds()

Get the bounds [zmin,zmax].

Source code in vedo/core/common.py

def zbounds(self) -> np.ndarray:
    """Get the bounds `[zmin,zmax]`."""
    b = self.bounds()
    return np.array([b[4], b[5]])

data

DataArrayHelper

Helper class to manage data associated to either points (or vertices) and cells (or faces).

Internal use only.

Source code in vedo/core/data.py

class DataArrayHelper:
    """
    Helper class to manage data associated to either points (or vertices) and cells (or faces).

    Internal use only.
    """

    def __init__(self, obj, association):

        self.obj = obj
        self.association = association

    def __getitem__(self, key):

        if self.association == 0:
            data = self.obj.dataset.GetPointData()

        elif self.association == 1:
            data = self.obj.dataset.GetCellData()

        elif self.association == 2:
            data = self.obj.dataset.GetFieldData()

            varr = data.GetAbstractArray(key)
            if isinstance(varr, vtki.vtkStringArray):
                if isinstance(key, int):
                    key = data.GetArrayName(key)
                n = varr.GetNumberOfValues()
                narr = [varr.GetValue(i) for i in range(n)]
                return narr
                ###########

        else:
            raise RuntimeError()

        if isinstance(key, int):
            key = data.GetArrayName(key)

        arr = data.GetArray(key)
        if not arr:
            return None
        return utils.vtk2numpy(arr)

    def __setitem__(self, key, input_array):

        if self.association == 0:
            data = self.obj.dataset.GetPointData()
            n = self.obj.dataset.GetNumberOfPoints()
            self.obj.mapper.SetScalarModeToUsePointData()

        elif self.association == 1:
            data = self.obj.dataset.GetCellData()
            n = self.obj.dataset.GetNumberOfCells()
            self.obj.mapper.SetScalarModeToUseCellData()

        elif self.association == 2:
            data = self.obj.dataset.GetFieldData()
            if not utils.is_sequence(input_array):
                input_array = [input_array]

            if isinstance(input_array[0], str):
                varr = vtki.vtkStringArray()
                varr.SetName(key)
                varr.SetNumberOfComponents(1)
                varr.SetNumberOfTuples(len(input_array))
                for i, iarr in enumerate(input_array):
                    if isinstance(iarr, np.ndarray):
                        iarr = iarr.tolist()  # better format
                        # Note: a string k can be converted to numpy with
                        # import json; k = np.array(json.loads(k))
                    varr.InsertValue(i, str(iarr))
            else:
                try:
                    varr = utils.numpy2vtk(input_array, name=key)
                except TypeError as e:
                    vedo.logger.error(
                        f"cannot create metadata with input object:\n"
                        f"{input_array}"
                        f"\n\nAllowed content examples are:\n"
                        f"- flat list of strings ['a','b', 1, [1,2,3], ...]"
                        f" (first item must be a string in this case)\n"
                        f"  hint: use k = np.array(json.loads(k)) to convert strings\n"
                        f"- numpy arrays of any shape"
                    )
                    raise e

            data.AddArray(varr)
            return  ############

        else:
            raise RuntimeError()

        if len(input_array) != n:
            vedo.logger.error(
                f"Error in point/cell data: length of input {len(input_array)}"
                f" !=  {n} nr. of elements"
            )
            raise RuntimeError()

        input_array = np.asarray(input_array)
        varr = utils.numpy2vtk(input_array, name=key)
        data.AddArray(varr)

        if len(input_array.shape) == 1:  # scalars
            data.SetActiveScalars(key)
            try:  # could be a volume mapper
                self.obj.mapper.SetScalarRange(data.GetScalars().GetRange())
            except AttributeError:
                pass
        elif len(input_array.shape) == 2 and input_array.shape[1] == 3:  # vectors
            if key.lower() == "normals":
                data.SetActiveNormals(key)
            else:
                data.SetActiveVectors(key)

    def keys(self) -> list[str]:
        """Return the list of available data array names"""
        if self.association == 0:
            data = self.obj.dataset.GetPointData()
        elif self.association == 1:
            data = self.obj.dataset.GetCellData()
        elif self.association == 2:
            data = self.obj.dataset.GetFieldData()
        arrnames = []
        for i in range(data.GetNumberOfArrays()):
            name = ""
            if self.association == 2:
                name = data.GetAbstractArray(i).GetName()
            else:
                iarr = data.GetArray(i)
                if iarr:
                    name = iarr.GetName()
            if name:
                arrnames.append(name)
        return arrnames

    def items(self) -> list:
        """Return the list of available data array `(names, values)`."""
        if self.association == 0:
            data = self.obj.dataset.GetPointData()
        elif self.association == 1:
            data = self.obj.dataset.GetCellData()
        elif self.association == 2:
            data = self.obj.dataset.GetFieldData()
        arrnames = []
        for i in range(data.GetNumberOfArrays()):
            if self.association == 2:
                name = data.GetAbstractArray(i).GetName()
            else:
                name = data.GetArray(i).GetName()
            if name:
                arrnames.append((name, self[name]))
        return arrnames

    def todict(self) -> dict:
        """Return a dictionary of the available data arrays."""
        return dict(self.items())

    def rename(self, oldname: str, newname: str) -> None:
        """Rename an array"""
        if self.association == 0:
            varr = self.obj.dataset.GetPointData().GetArray(oldname)
        elif self.association == 1:
            varr = self.obj.dataset.GetCellData().GetArray(oldname)
        elif self.association == 2:
            varr = self.obj.dataset.GetFieldData().GetAbstractArray(oldname)
        if varr:
            varr.SetName(newname)
        else:
            vedo.logger.warning(
                f"Cannot rename non existing array {oldname} to {newname}"
            )

    def remove(self, key: int | str) -> None:
        """Remove a data array by name or number"""
        if self.association == 0:
            self.obj.dataset.GetPointData().RemoveArray(key)
        elif self.association == 1:
            self.obj.dataset.GetCellData().RemoveArray(key)
        elif self.association == 2:
            self.obj.dataset.GetFieldData().RemoveArray(key)

    def clear(self) -> None:
        """Remove all data associated to this object"""
        if self.association == 0:
            data = self.obj.dataset.GetPointData()
        elif self.association == 1:
            data = self.obj.dataset.GetCellData()
        elif self.association == 2:
            data = self.obj.dataset.GetFieldData()
        names = []
        for i in range(data.GetNumberOfArrays()):
            if self.association == 2:
                arr = data.GetAbstractArray(i)
            else:
                arr = data.GetArray(i)
            if arr:
                names.append(arr.GetName())
        for name in names:
            data.RemoveArray(name)

    def select(self, key: int | str) -> Any:
        """Select one specific array by its name to make it the `active` one."""
        # Default (ColorModeToDefault): unsigned char scalars are treated as colors,
        # and NOT mapped through the lookup table, while everything else is.
        # ColorModeToDirectScalar extends ColorModeToDefault such that all integer
        # types are treated as colors with values in the range 0-255
        # and floating types are treated as colors with values in the range 0.0-1.0.
        # Setting ColorModeToMapScalars means that all scalar data will be mapped
        # through the lookup table.
        # (Note that for multi-component scalars, the particular component
        # to use for mapping can be specified using the SelectColorArray() method.)
        if self.association == 0:
            data = self.obj.dataset.GetPointData()
            self.obj.mapper.SetScalarModeToUsePointData()
        else:
            data = self.obj.dataset.GetCellData()
            self.obj.mapper.SetScalarModeToUseCellData()

        if isinstance(key, int):
            key = data.GetArrayName(key)

        arr = data.GetArray(key)
        if not arr:
            return self.obj

        nc = arr.GetNumberOfComponents()
        # print("GetNumberOfComponents", nc)
        if nc == 1:
            data.SetActiveScalars(key)
        elif nc == 2:
            data.SetTCoords(arr)
        elif nc in (3, 4):
            if "rgb" in key.lower():  # type: ignore
                data.SetActiveScalars(key)
                try:
                    # could be a volume mapper
                    self.obj.mapper.SetColorModeToDirectScalars()
                    data.SetActiveVectors(None)  # need this to fix bug in #1066
                    # print("SetColorModeToDirectScalars for", key)
                except AttributeError:
                    pass
            else:
                data.SetActiveVectors(key)
        elif nc == 9:
            data.SetActiveTensors(key)
        else:
            vedo.logger.error(f"Cannot select array {key} with {nc} components")
            return self.obj

        try:
            # could be a volume mapper
            self.obj.mapper.SetArrayName(key)
            self.obj.mapper.ScalarVisibilityOn()
        except AttributeError:
            pass

        return self.obj

    def select_texture_coords(self, key: int | str) -> Any:
        """Select one specific array to be used as texture coordinates."""
        if self.association == 0:
            data = self.obj.dataset.GetPointData()
            if isinstance(key, int):
                key = data.GetArrayName(key)
            data.SetTCoords(data.GetArray(key))
        else:
            vedo.logger.warning("texture coordinates are only available for point data")
        return self.obj

    def select_normals(self, key: int | str) -> Any:
        """Select one specific normal array by its name to make it the "active" one."""
        if self.association == 0:
            data = self.obj.dataset.GetPointData()
            self.obj.mapper.SetScalarModeToUsePointData()
        else:
            data = self.obj.dataset.GetCellData()
            self.obj.mapper.SetScalarModeToUseCellData()

        if isinstance(key, int):
            key = data.GetArrayName(key)
        data.SetActiveNormals(key)
        return self.obj

    def print(self, **kwargs) -> None:
        """Print the array names available to terminal"""
        colors.printc(self.keys(), **kwargs)

    def __repr__(self) -> str:
        """Representation"""
        out = ""

        def _get_str(pd, header):
            out = f"\x1b[2m\x1b[1m\x1b[7m{header}"
            if pd.GetNumberOfArrays():
                if self.obj.name:
                    out += f" in {self.obj.name}"
                out += f" contains {pd.GetNumberOfArrays()} array(s)\x1b[0m"
                for i in range(pd.GetNumberOfArrays()):
                    varr = pd.GetArray(i)
                    out += f"\n\x1b[1m\x1b[4mArray name    : {varr.GetName()}\x1b[0m"
                    out += "\nindex".ljust(15) + f": {i}"
                    t = varr.GetDataType()
                    if t in vtki.array_types:
                        out += "\ntype".ljust(15)
                        out += f": {vtki.array_types[t]}"
                    shape = (varr.GetNumberOfTuples(), varr.GetNumberOfComponents())
                    out += "\nshape".ljust(15) + f": {shape}"
                    out += "\nrange".ljust(15) + f": {np.array(varr.GetRange())}"
                    out += "\nmax id".ljust(15) + f": {varr.GetMaxId()}"
                    out += (
                        "\nlook up table".ljust(15) + f": {bool(varr.GetLookupTable())}"
                    )
                    out += (
                        "\nin-memory size".ljust(15)
                        + f": {varr.GetActualMemorySize()} KB"
                    )
            else:
                out += " is empty.\x1b[0m"
            return out

        if self.association == 0:
            out = _get_str(self.obj.dataset.GetPointData(), "Point Data")
        elif self.association == 1:
            out = _get_str(self.obj.dataset.GetCellData(), "Cell Data")
        elif self.association == 2:
            pd = self.obj.dataset.GetFieldData()
            if pd.GetNumberOfArrays():
                out = "\x1b[2m\x1b[1m\x1b[7mMeta Data"
                if self.obj.name:
                    out += f" in {self.obj.name}"
                out += f" contains {pd.GetNumberOfArrays()} entries\x1b[0m"
                for i in range(pd.GetNumberOfArrays()):
                    varr = pd.GetAbstractArray(i)
                    out += f"\n\x1b[1m\x1b[4mEntry name    : {varr.GetName()}\x1b[0m"
                    out += "\nindex".ljust(15) + f": {i}"
                    shape = (varr.GetNumberOfTuples(), varr.GetNumberOfComponents())
                    out += "\nshape".ljust(15) + f": {shape}"
            else:
                out = "\x1b[2m\x1b[1m\x1b[7mMeta Data is empty.\x1b[0m"

        return out

clear()

Remove all data associated to this object

Source code in vedo/core/data.py

def clear(self) -> None:
    """Remove all data associated to this object"""
    if self.association == 0:
        data = self.obj.dataset.GetPointData()
    elif self.association == 1:
        data = self.obj.dataset.GetCellData()
    elif self.association == 2:
        data = self.obj.dataset.GetFieldData()
    names = []
    for i in range(data.GetNumberOfArrays()):
        if self.association == 2:
            arr = data.GetAbstractArray(i)
        else:
            arr = data.GetArray(i)
        if arr:
            names.append(arr.GetName())
    for name in names:
        data.RemoveArray(name)

items()

Return the list of available data array (names, values).

Source code in vedo/core/data.py

def items(self) -> list:
    """Return the list of available data array `(names, values)`."""
    if self.association == 0:
        data = self.obj.dataset.GetPointData()
    elif self.association == 1:
        data = self.obj.dataset.GetCellData()
    elif self.association == 2:
        data = self.obj.dataset.GetFieldData()
    arrnames = []
    for i in range(data.GetNumberOfArrays()):
        if self.association == 2:
            name = data.GetAbstractArray(i).GetName()
        else:
            name = data.GetArray(i).GetName()
        if name:
            arrnames.append((name, self[name]))
    return arrnames

keys()

Return the list of available data array names

Source code in vedo/core/data.py

def keys(self) -> list[str]:
    """Return the list of available data array names"""
    if self.association == 0:
        data = self.obj.dataset.GetPointData()
    elif self.association == 1:
        data = self.obj.dataset.GetCellData()
    elif self.association == 2:
        data = self.obj.dataset.GetFieldData()
    arrnames = []
    for i in range(data.GetNumberOfArrays()):
        name = ""
        if self.association == 2:
            name = data.GetAbstractArray(i).GetName()
        else:
            iarr = data.GetArray(i)
            if iarr:
                name = iarr.GetName()
        if name:
            arrnames.append(name)
    return arrnames

print(**kwargs)

Print the array names available to terminal

Source code in vedo/core/data.py

def print(self, **kwargs) -> None:
    """Print the array names available to terminal"""
    colors.printc(self.keys(), **kwargs)

remove(key)

Remove a data array by name or number

Source code in vedo/core/data.py

def remove(self, key: int | str) -> None:
    """Remove a data array by name or number"""
    if self.association == 0:
        self.obj.dataset.GetPointData().RemoveArray(key)
    elif self.association == 1:
        self.obj.dataset.GetCellData().RemoveArray(key)
    elif self.association == 2:
        self.obj.dataset.GetFieldData().RemoveArray(key)

rename(oldname, newname)

Rename an array

Source code in vedo/core/data.py

def rename(self, oldname: str, newname: str) -> None:
    """Rename an array"""
    if self.association == 0:
        varr = self.obj.dataset.GetPointData().GetArray(oldname)
    elif self.association == 1:
        varr = self.obj.dataset.GetCellData().GetArray(oldname)
    elif self.association == 2:
        varr = self.obj.dataset.GetFieldData().GetAbstractArray(oldname)
    if varr:
        varr.SetName(newname)
    else:
        vedo.logger.warning(
            f"Cannot rename non existing array {oldname} to {newname}"
        )

select(key)

Select one specific array by its name to make it the active one.

Source code in vedo/core/data.py

def select(self, key: int | str) -> Any:
    """Select one specific array by its name to make it the `active` one."""
    # Default (ColorModeToDefault): unsigned char scalars are treated as colors,
    # and NOT mapped through the lookup table, while everything else is.
    # ColorModeToDirectScalar extends ColorModeToDefault such that all integer
    # types are treated as colors with values in the range 0-255
    # and floating types are treated as colors with values in the range 0.0-1.0.
    # Setting ColorModeToMapScalars means that all scalar data will be mapped
    # through the lookup table.
    # (Note that for multi-component scalars, the particular component
    # to use for mapping can be specified using the SelectColorArray() method.)
    if self.association == 0:
        data = self.obj.dataset.GetPointData()
        self.obj.mapper.SetScalarModeToUsePointData()
    else:
        data = self.obj.dataset.GetCellData()
        self.obj.mapper.SetScalarModeToUseCellData()

    if isinstance(key, int):
        key = data.GetArrayName(key)

    arr = data.GetArray(key)
    if not arr:
        return self.obj

    nc = arr.GetNumberOfComponents()
    # print("GetNumberOfComponents", nc)
    if nc == 1:
        data.SetActiveScalars(key)
    elif nc == 2:
        data.SetTCoords(arr)
    elif nc in (3, 4):
        if "rgb" in key.lower():  # type: ignore
            data.SetActiveScalars(key)
            try:
                # could be a volume mapper
                self.obj.mapper.SetColorModeToDirectScalars()
                data.SetActiveVectors(None)  # need this to fix bug in #1066
                # print("SetColorModeToDirectScalars for", key)
            except AttributeError:
                pass
        else:
            data.SetActiveVectors(key)
    elif nc == 9:
        data.SetActiveTensors(key)
    else:
        vedo.logger.error(f"Cannot select array {key} with {nc} components")
        return self.obj

    try:
        # could be a volume mapper
        self.obj.mapper.SetArrayName(key)
        self.obj.mapper.ScalarVisibilityOn()
    except AttributeError:
        pass

    return self.obj

select_normals(key)

Select one specific normal array by its name to make it the "active" one.

Source code in vedo/core/data.py

def select_normals(self, key: int | str) -> Any:
    """Select one specific normal array by its name to make it the "active" one."""
    if self.association == 0:
        data = self.obj.dataset.GetPointData()
        self.obj.mapper.SetScalarModeToUsePointData()
    else:
        data = self.obj.dataset.GetCellData()
        self.obj.mapper.SetScalarModeToUseCellData()

    if isinstance(key, int):
        key = data.GetArrayName(key)
    data.SetActiveNormals(key)
    return self.obj

select_texture_coords(key)

Select one specific array to be used as texture coordinates.

Source code in vedo/core/data.py

def select_texture_coords(self, key: int | str) -> Any:
    """Select one specific array to be used as texture coordinates."""
    if self.association == 0:
        data = self.obj.dataset.GetPointData()
        if isinstance(key, int):
            key = data.GetArrayName(key)
        data.SetTCoords(data.GetArray(key))
    else:
        vedo.logger.warning("texture coordinates are only available for point data")
    return self.obj

todict()

Return a dictionary of the available data arrays.

Source code in vedo/core/data.py

def todict(self) -> dict:
    """Return a dictionary of the available data arrays."""
    return dict(self.items())

input

Input normalization helpers shared by mesh-like classes.

as_dataset(obj)

Unwrap vedo-style objects exposing a .dataset attribute.

Source code in vedo/core/input.py

def as_dataset(obj):
    """Unwrap vedo-style objects exposing a `.dataset` attribute."""
    if hasattr(obj, "dataset"):
        return obj.dataset
    return obj

as_path(pathlike)

Convert a path-like object to string (or bytes) path.

Source code in vedo/core/input.py

def as_path(pathlike) -> "str | bytes":
    """Convert a path-like object to string (or bytes) path."""
    return os.fspath(pathlike)

geometry_filter_to_polydata(inputobj)

Convert a generic VTK dataset to vtkPolyData via vtkGeometryFilter.

Source code in vedo/core/input.py

def geometry_filter_to_polydata(inputobj):
    """Convert a generic VTK dataset to vtkPolyData via vtkGeometryFilter."""
    dataset = as_dataset(inputobj)
    if dataset is None or not hasattr(dataset, "GetClassName"):
        raise TypeError(f"expected a VTK dataset, got {type(inputobj)}")
    gf = vtki.new("GeometryFilter")
    gf.SetInputData(dataset)
    gf.Update()
    return gf.GetOutput()

is_path_like(obj)

Return True if obj can be treated as a filesystem path.

Source code in vedo/core/input.py

def is_path_like(obj) -> bool:
    """Return True if obj can be treated as a filesystem path."""
    return isinstance(obj, (str, os.PathLike))

points_polydata_from_dataset(inputobj)

Build a vtkPolyData containing only points and point-data arrays.

Raises:

Type	Description
TypeError	if input does not expose VTK-like point-data APIs.

Source code in vedo/core/input.py

def points_polydata_from_dataset(inputobj):
    """
    Build a vtkPolyData containing only points and point-data arrays.

    Raises:
        TypeError: if input does not expose VTK-like point-data APIs.
    """
    dataset = as_dataset(inputobj)
    if not hasattr(dataset, "GetPoints"):
        raise TypeError("input object does not expose GetPoints()")

    vvpts = dataset.GetPoints()
    if vvpts is None:
        raise TypeError("input dataset has no points")

    poly = vtki.new("PolyData")
    poly.SetPoints(vvpts)

    pd = dataset.GetPointData()
    out_pd = poly.GetPointData()
    for i in range(pd.GetNumberOfArrays()):
        arr = pd.GetArray(i)
        if arr is not None:
            out_pd.AddArray(arr)

    carr = vtki.new("CellArray")
    for i in range(poly.GetNumberOfPoints()):
        carr.InsertNextCell(1)
        carr.InsertCellPoint(i)
    poly.SetVerts(carr)
    return poly

points

PointAlgorithms

Bases: CommonAlgorithms

Methods for point clouds.

Source code in vedo/core/points.py

class PointAlgorithms(CommonAlgorithms):
    """Methods for point clouds."""

    def apply_transform(self, LT: Any, deep_copy=True) -> Self:
        """
        Apply a linear or non-linear transformation to the mesh polygonal data.

        Examples:
        ```python
        from vedo import Cube, show, settings
        settings.use_parallel_projection = True
        c1 = Cube().rotate_z(25).pos(2,1).mirror().alpha(0.5)
        T = c1.transform  # rotate by 5 degrees, place at (2,1)
        c2 = Cube().c('red4').wireframe().lw(10).lighting('off')
        c2.apply_transform(T)
        show(c1, c2, "The 2 cubes should overlap!", axes=1).close()
        ```

        ![](https://vedo.embl.es/images/feats/apply_transform.png)
        """
        if self.dataset.GetNumberOfPoints() == 0 or LT is None:
            return self

        if isinstance(LT, LinearTransform):
            LT_is_linear = True
            tr = LT.T
            if LT.is_identity():
                return self

        elif isinstance(
            LT, (vtki.vtkMatrix4x4, vtki.vtkLinearTransform)
        ) or utils.is_sequence(LT):
            LT_is_linear = True
            LT = LinearTransform(LT)
            tr = LT.T
            if LT.is_identity():
                return self

        elif isinstance(LT, NonLinearTransform):
            LT_is_linear = False
            tr = LT.T
            self.transform = LT  # reset

        elif isinstance(LT, vtki.vtkThinPlateSplineTransform):
            LT_is_linear = False
            tr = LT
            self.transform = NonLinearTransform(LT)  # reset

        else:
            vedo.logger.error(f"apply_transform(), unknown input type:\n{LT}")
            return self

        ################
        if LT_is_linear:
            try:
                # self.transform might still not be linear
                self.transform.concatenate(LT)
            except AttributeError:
                # in that case reset it
                self.transform = LT

        ################
        if isinstance(self.dataset, vtki.vtkPolyData):
            tp = vtki.new("TransformPolyDataFilter")
        elif isinstance(
            self.dataset, (vtki.vtkStructuredGrid, vtki.vtkUnstructuredGrid)
        ):
            tp = vtki.new("TransformFilter")
            tp.TransformAllInputVectorsOn()
        else:
            vedo.logger.error(f"apply_transform(), unknown input type: {type(self.dataset)}")
            return self

        tp.SetTransform(tr)
        tp.SetInputData(self.dataset)
        tp.Update()
        out = tp.GetOutput()

        if deep_copy:
            self.dataset.DeepCopy(out)
        else:
            self.dataset.ShallowCopy(out)

        # reset the locators
        self.point_locator = None
        self.cell_locator = None
        self.line_locator = None
        return self

    def apply_transform_from_actor(self) -> LinearTransform:
        """
        Apply the current transformation of the actor to the data.
        Useful when manually moving an actor (eg. when pressing "a").
        Returns the `LinearTransform` object.

        Note that this method is automatically called when the window is closed,
        or the interactor style is changed.
        """
        M = self.actor.GetMatrix()
        self.apply_transform(M)
        LT = LinearTransform(M)
        iden = vtki.vtkMatrix4x4()
        self.actor.PokeMatrix(iden)
        return LT

    def get_transform_from_actor(self) -> LinearTransform:
        """
        Get the current transformation of the actor as a `LinearTransform` object.
        This is useful to retrieve the transformation matrix without applying it to the data.
        """
        M = self.actor.GetMatrix()
        if M is None:
            return LinearTransform()
        return LinearTransform(M)

    def pos(self, x=None, y=None, z=None) -> Self:
        """Set/Get object position."""
        if x is None:  # get functionality
            return self.transform.position

        if z is None and y is None:  # assume x is of the form (x,y,z)
            if len(x) == 3:
                x, y, z = x
            else:
                x, y = x
                z = 0
        elif z is None:  # assume x,y is of the form x, y
            z = 0

        q = self.transform.position
        delta = np.array([x, y, z]) - q
        if delta[0] == delta[1] == delta[2] == 0:
            return self
        LT = LinearTransform().translate(delta)
        return self.apply_transform(LT)

    def shift(self, dx=0, dy=0, dz=0) -> Self:
        """Add a vector to the current object position."""
        if utils.is_sequence(dx):
            dx, dy, dz = utils.make3d(dx)
        if dx == dy == dz == 0:
            return self
        LT = LinearTransform().translate([dx, dy, dz])
        return self.apply_transform(LT)

    def x(self, val=None) -> Self:
        """Set/Get object position along x axis."""
        p = self.transform.position
        if val is None:
            return p[0]
        self.pos(val, p[1], p[2])
        return self

    def y(self, val=None) -> Self:
        """Set/Get object position along y axis."""
        p = self.transform.position
        if val is None:
            return p[1]
        self.pos(p[0], val, p[2])
        return self

    def z(self, val=None) -> Self:
        """Set/Get object position along z axis."""
        p = self.transform.position
        if val is None:
            return p[2]
        self.pos(p[0], p[1], val)
        return self

    def rotate(self, angle: float, axis=(1, 0, 0), point=(0, 0, 0), rad=False) -> Self:
        """
        Rotate around an arbitrary `axis` passing through `point`.

        Examples:
        ```python
        from vedo import *
        c1 = Cube()
        c2 = c1.clone().c('violet').alpha(0.5) # copy of c1
        v = vector(0.2,1,0)
        p = vector(1,0,0)  # axis passes through this point
        c2.rotate(90, axis=v, point=p)
        l = Line(-v+p, v+p).lw(3).c('red')
        show(c1, l, c2, axes=1).close()
        ```

        ![](https://vedo.embl.es/images/feats/rotate_axis.png)
        """
        LT = LinearTransform()
        LT.rotate(angle, axis, point, rad)
        return self.apply_transform(LT)

    def rotate_x(self, angle: float, rad=False, around=None) -> Self:
        """
        Rotate around x-axis. If angle is in radians set `rad=True`.

        Use `around` to define a pivoting point.
        """
        if angle == 0:
            return self
        LT = LinearTransform().rotate_x(angle, rad, around)
        return self.apply_transform(LT)

    def rotate_y(self, angle: float, rad=False, around=None) -> Self:
        """
        Rotate around y-axis. If angle is in radians set `rad=True`.

        Use `around` to define a pivoting point.
        """
        if angle == 0:
            return self
        LT = LinearTransform().rotate_y(angle, rad, around)
        return self.apply_transform(LT)

    def rotate_z(self, angle: float, rad=False, around=None) -> Self:
        """
        Rotate around z-axis. If angle is in radians set `rad=True`.

        Use `around` to define a pivoting point.
        """
        if angle == 0:
            return self
        LT = LinearTransform().rotate_z(angle, rad, around)
        return self.apply_transform(LT)

    def reorient(self, initaxis, newaxis, rotation=0, rad=False, xyplane=False) -> Self:
        """
        Reorient the object to point to a new direction from an initial one.
        If `initaxis` is None, the object will be assumed in its "default" orientation.
        If `xyplane` is True, the object will be rotated to lie on the xy plane.

        Use `rotation` to first rotate the object around its `initaxis`.
        """
        q = self.transform.position
        LT = LinearTransform()
        LT.reorient(initaxis, newaxis, q, rotation, rad, xyplane)
        return self.apply_transform(LT)

    def scale(self, s=None, reset=False, origin=True) -> Self | np.ndarray:
        """
        Set/get object's scaling factor.

        Args:
            s (list, float):
                scaling factor(s).
            reset (bool):
                if True previous scaling factors are ignored.
            origin (bool):
                if True scaling is applied with respect to object's position,
                otherwise is applied respect to (0,0,0).

        Note:
            use `s=(sx,sy,sz)` to scale differently in the three coordinates.
        """
        if s is None:
            return np.array(self.transform.T.GetScale())

        if not utils.is_sequence(s):
            s = [s, s, s]

        LT = LinearTransform()
        if reset:
            old_s = np.array(self.transform.T.GetScale())
            LT.scale(np.array(s) / old_s)
        else:
            if origin is True:
                LT.scale(s, origin=self.transform.position)
            elif origin is False:
                LT.scale(s, origin=False)
            else:
                LT.scale(s, origin=origin)

        return self.apply_transform(LT)

apply_transform(LT, deep_copy=True)

Apply a linear or non-linear transformation to the mesh polygonal data.

Examples:

from vedo import Cube, show, settings
settings.use_parallel_projection = True
c1 = Cube().rotate_z(25).pos(2,1).mirror().alpha(0.5)
T = c1.transform  # rotate by 5 degrees, place at (2,1)
c2 = Cube().c('red4').wireframe().lw(10).lighting('off')
c2.apply_transform(T)
show(c1, c2, "The 2 cubes should overlap!", axes=1).close()

Source code in vedo/core/points.py

def apply_transform(self, LT: Any, deep_copy=True) -> Self:
    """
    Apply a linear or non-linear transformation to the mesh polygonal data.

    Examples:
    ```python
    from vedo import Cube, show, settings
    settings.use_parallel_projection = True
    c1 = Cube().rotate_z(25).pos(2,1).mirror().alpha(0.5)
    T = c1.transform  # rotate by 5 degrees, place at (2,1)
    c2 = Cube().c('red4').wireframe().lw(10).lighting('off')
    c2.apply_transform(T)
    show(c1, c2, "The 2 cubes should overlap!", axes=1).close()
    ```

    ![](https://vedo.embl.es/images/feats/apply_transform.png)
    """
    if self.dataset.GetNumberOfPoints() == 0 or LT is None:
        return self

    if isinstance(LT, LinearTransform):
        LT_is_linear = True
        tr = LT.T
        if LT.is_identity():
            return self

    elif isinstance(
        LT, (vtki.vtkMatrix4x4, vtki.vtkLinearTransform)
    ) or utils.is_sequence(LT):
        LT_is_linear = True
        LT = LinearTransform(LT)
        tr = LT.T
        if LT.is_identity():
            return self

    elif isinstance(LT, NonLinearTransform):
        LT_is_linear = False
        tr = LT.T
        self.transform = LT  # reset

    elif isinstance(LT, vtki.vtkThinPlateSplineTransform):
        LT_is_linear = False
        tr = LT
        self.transform = NonLinearTransform(LT)  # reset

    else:
        vedo.logger.error(f"apply_transform(), unknown input type:\n{LT}")
        return self

    ################
    if LT_is_linear:
        try:
            # self.transform might still not be linear
            self.transform.concatenate(LT)
        except AttributeError:
            # in that case reset it
            self.transform = LT

    ################
    if isinstance(self.dataset, vtki.vtkPolyData):
        tp = vtki.new("TransformPolyDataFilter")
    elif isinstance(
        self.dataset, (vtki.vtkStructuredGrid, vtki.vtkUnstructuredGrid)
    ):
        tp = vtki.new("TransformFilter")
        tp.TransformAllInputVectorsOn()
    else:
        vedo.logger.error(f"apply_transform(), unknown input type: {type(self.dataset)}")
        return self

    tp.SetTransform(tr)
    tp.SetInputData(self.dataset)
    tp.Update()
    out = tp.GetOutput()

    if deep_copy:
        self.dataset.DeepCopy(out)
    else:
        self.dataset.ShallowCopy(out)

    # reset the locators
    self.point_locator = None
    self.cell_locator = None
    self.line_locator = None
    return self

apply_transform_from_actor()

Apply the current transformation of the actor to the data. Useful when manually moving an actor (eg. when pressing "a"). Returns the LinearTransform object.

Note that this method is automatically called when the window is closed, or the interactor style is changed.

Source code in vedo/core/points.py

def apply_transform_from_actor(self) -> LinearTransform:
    """
    Apply the current transformation of the actor to the data.
    Useful when manually moving an actor (eg. when pressing "a").
    Returns the `LinearTransform` object.

    Note that this method is automatically called when the window is closed,
    or the interactor style is changed.
    """
    M = self.actor.GetMatrix()
    self.apply_transform(M)
    LT = LinearTransform(M)
    iden = vtki.vtkMatrix4x4()
    self.actor.PokeMatrix(iden)
    return LT

get_transform_from_actor()

Get the current transformation of the actor as a LinearTransform object. This is useful to retrieve the transformation matrix without applying it to the data.

Source code in vedo/core/points.py

def get_transform_from_actor(self) -> LinearTransform:
    """
    Get the current transformation of the actor as a `LinearTransform` object.
    This is useful to retrieve the transformation matrix without applying it to the data.
    """
    M = self.actor.GetMatrix()
    if M is None:
        return LinearTransform()
    return LinearTransform(M)

pos(x=None, y=None, z=None)

Set/Get object position.

Source code in vedo/core/points.py

def pos(self, x=None, y=None, z=None) -> Self:
    """Set/Get object position."""
    if x is None:  # get functionality
        return self.transform.position

    if z is None and y is None:  # assume x is of the form (x,y,z)
        if len(x) == 3:
            x, y, z = x
        else:
            x, y = x
            z = 0
    elif z is None:  # assume x,y is of the form x, y
        z = 0

    q = self.transform.position
    delta = np.array([x, y, z]) - q
    if delta[0] == delta[1] == delta[2] == 0:
        return self
    LT = LinearTransform().translate(delta)
    return self.apply_transform(LT)

reorient(initaxis, newaxis, rotation=0, rad=False, xyplane=False)

Reorient the object to point to a new direction from an initial one. If initaxis is None, the object will be assumed in its "default" orientation. If xyplane is True, the object will be rotated to lie on the xy plane.

Use rotation to first rotate the object around its initaxis.

Source code in vedo/core/points.py

def reorient(self, initaxis, newaxis, rotation=0, rad=False, xyplane=False) -> Self:
    """
    Reorient the object to point to a new direction from an initial one.
    If `initaxis` is None, the object will be assumed in its "default" orientation.
    If `xyplane` is True, the object will be rotated to lie on the xy plane.

    Use `rotation` to first rotate the object around its `initaxis`.
    """
    q = self.transform.position
    LT = LinearTransform()
    LT.reorient(initaxis, newaxis, q, rotation, rad, xyplane)
    return self.apply_transform(LT)

rotate(angle, axis=(1, 0, 0), point=(0, 0, 0), rad=False)

Rotate around an arbitrary axis passing through point.

Examples:

from vedo import *
c1 = Cube()
c2 = c1.clone().c('violet').alpha(0.5) # copy of c1
v = vector(0.2,1,0)
p = vector(1,0,0)  # axis passes through this point
c2.rotate(90, axis=v, point=p)
l = Line(-v+p, v+p).lw(3).c('red')
show(c1, l, c2, axes=1).close()

Source code in vedo/core/points.py

def rotate(self, angle: float, axis=(1, 0, 0), point=(0, 0, 0), rad=False) -> Self:
    """
    Rotate around an arbitrary `axis` passing through `point`.

    Examples:
    ```python
    from vedo import *
    c1 = Cube()
    c2 = c1.clone().c('violet').alpha(0.5) # copy of c1
    v = vector(0.2,1,0)
    p = vector(1,0,0)  # axis passes through this point
    c2.rotate(90, axis=v, point=p)
    l = Line(-v+p, v+p).lw(3).c('red')
    show(c1, l, c2, axes=1).close()
    ```

    ![](https://vedo.embl.es/images/feats/rotate_axis.png)
    """
    LT = LinearTransform()
    LT.rotate(angle, axis, point, rad)
    return self.apply_transform(LT)

rotate_x(angle, rad=False, around=None)

Rotate around x-axis. If angle is in radians set rad=True.

Use around to define a pivoting point.

Source code in vedo/core/points.py

def rotate_x(self, angle: float, rad=False, around=None) -> Self:
    """
    Rotate around x-axis. If angle is in radians set `rad=True`.

    Use `around` to define a pivoting point.
    """
    if angle == 0:
        return self
    LT = LinearTransform().rotate_x(angle, rad, around)
    return self.apply_transform(LT)

rotate_y(angle, rad=False, around=None)

Rotate around y-axis. If angle is in radians set rad=True.

Use around to define a pivoting point.

Source code in vedo/core/points.py

def rotate_y(self, angle: float, rad=False, around=None) -> Self:
    """
    Rotate around y-axis. If angle is in radians set `rad=True`.

    Use `around` to define a pivoting point.
    """
    if angle == 0:
        return self
    LT = LinearTransform().rotate_y(angle, rad, around)
    return self.apply_transform(LT)

rotate_z(angle, rad=False, around=None)

Rotate around z-axis. If angle is in radians set rad=True.

Use around to define a pivoting point.

Source code in vedo/core/points.py

def rotate_z(self, angle: float, rad=False, around=None) -> Self:
    """
    Rotate around z-axis. If angle is in radians set `rad=True`.

    Use `around` to define a pivoting point.
    """
    if angle == 0:
        return self
    LT = LinearTransform().rotate_z(angle, rad, around)
    return self.apply_transform(LT)

scale(s=None, reset=False, origin=True)

Set/get object's scaling factor.

Parameters:

Name	Type	Description	Default
s	(list, float)	scaling factor(s).	None
reset	bool	if True previous scaling factors are ignored.	False
origin	bool	if True scaling is applied with respect to object's position, otherwise is applied respect to (0,0,0).	True

Note

use s=(sx,sy,sz) to scale differently in the three coordinates.

Source code in vedo/core/points.py

def scale(self, s=None, reset=False, origin=True) -> Self | np.ndarray:
    """
    Set/get object's scaling factor.

    Args:
        s (list, float):
            scaling factor(s).
        reset (bool):
            if True previous scaling factors are ignored.
        origin (bool):
            if True scaling is applied with respect to object's position,
            otherwise is applied respect to (0,0,0).

    Note:
        use `s=(sx,sy,sz)` to scale differently in the three coordinates.
    """
    if s is None:
        return np.array(self.transform.T.GetScale())

    if not utils.is_sequence(s):
        s = [s, s, s]

    LT = LinearTransform()
    if reset:
        old_s = np.array(self.transform.T.GetScale())
        LT.scale(np.array(s) / old_s)
    else:
        if origin is True:
            LT.scale(s, origin=self.transform.position)
        elif origin is False:
            LT.scale(s, origin=False)
        else:
            LT.scale(s, origin=origin)

    return self.apply_transform(LT)

shift(dx=0, dy=0, dz=0)

Add a vector to the current object position.

Source code in vedo/core/points.py

def shift(self, dx=0, dy=0, dz=0) -> Self:
    """Add a vector to the current object position."""
    if utils.is_sequence(dx):
        dx, dy, dz = utils.make3d(dx)
    if dx == dy == dz == 0:
        return self
    LT = LinearTransform().translate([dx, dy, dz])
    return self.apply_transform(LT)

x(val=None)

Set/Get object position along x axis.

Source code in vedo/core/points.py

def x(self, val=None) -> Self:
    """Set/Get object position along x axis."""
    p = self.transform.position
    if val is None:
        return p[0]
    self.pos(val, p[1], p[2])
    return self

y(val=None)

Set/Get object position along y axis.

Source code in vedo/core/points.py

def y(self, val=None) -> Self:
    """Set/Get object position along y axis."""
    p = self.transform.position
    if val is None:
        return p[1]
    self.pos(p[0], val, p[2])
    return self

z(val=None)

Set/Get object position along z axis.

Source code in vedo/core/points.py

def z(self, val=None) -> Self:
    """Set/Get object position along z axis."""
    p = self.transform.position
    if val is None:
        return p[2]
    self.pos(p[0], p[1], val)
    return self

summary

active_array_label(dataset, association, key, base_label)

Return the label for a point/cell array, marking the active role when needed.

Source code in vedo/core/summary.py

def active_array_label(dataset, association: str, key: str, base_label: str) -> str:
    """Return the label for a point/cell array, marking the active role when needed."""
    if association.startswith("p"):
        data = dataset.GetPointData()
    else:
        data = dataset.GetCellData()
    scalars = data.GetScalars()
    vectors = data.GetVectors()
    tensors = data.GetTensors()
    if scalars and scalars.GetName() == key:
        return base_label + " *"
    if vectors and vectors.GetName() == key:
        return base_label + " **"
    if tensors and tensors.GetName() == key:
        return base_label + " ***"
    return base_label

format_bounds(bounds, precision_func, digits=3)

Format a bounds tuple as x/y/z ranges.

Source code in vedo/core/summary.py

def format_bounds(bounds, precision_func, digits: int = 3) -> str:
    """Format a bounds tuple as x/y/z ranges."""
    bx1, bx2 = precision_func(bounds[0], digits), precision_func(bounds[1], digits)
    by1, by2 = precision_func(bounds[2], digits), precision_func(bounds[3], digits)
    bz1, bz2 = precision_func(bounds[4], digits), precision_func(bounds[5], digits)
    return f"x=({bx1}, {bx2}), y=({by1}, {by2}), z=({bz1}, {bz2})"

summarize_array(arr, precision_func, *, include_range=True, dim_label='dim')

Summarize a numpy array for object-printing.

Source code in vedo/core/summary.py

def summarize_array(
    arr, precision_func, *, include_range: bool = True, dim_label: str = "dim"
) -> str:
    """Summarize a numpy array for object-printing."""
    dim = arr.shape[1] if arr.ndim > 1 else 1
    value = f"({arr.dtype}), {dim_label}={dim}"
    if include_range and len(arr) > 0 and dim == 1:
        if "int" in arr.dtype.name:
            rng = f"{arr.min()}, {arr.max()}"
        else:
            rng = precision_func(arr.min(), 3) + ", " + precision_func(arr.max(), 3)
        value += f", range=({rng})"
    elif include_range and len(arr) > 0 and arr.ndim >= 1:
        try:
            arr_min = np.nanmin(arr)
            arr_max = np.nanmax(arr)
            if np.isfinite(arr_min) and np.isfinite(arr_max):
                rng = precision_func(arr_min, 3) + ", " + precision_func(arr_max, 3)
                value += f", range=({rng})"
        except (TypeError, ValueError):
            pass
    return value

summary_panel(obj, rows, color='white', expand=False)

Return a rich panel for the provided summary rows.

Source code in vedo/core/summary.py

def summary_panel(obj, rows, color: str = "white", expand: bool = False):
    """Return a rich panel for the provided summary rows."""
    from rich.panel import Panel
    from rich.table import Table

    table = Table(show_header=False, box=None, pad_edge=False, expand=False)
    table.add_column("Field", style=f"bold {color}", no_wrap=True)
    table.add_column("Value", style=color)
    for field, value in rows:
        table.add_row(str(field), str(value))
    return Panel(
        table,
        title=summary_title(obj),
        title_align="left",
        expand=expand,
        border_style=f"bold {color}",
    )

summary_string(obj, rows, color='white', expand=False)

Use rich formatting in an interactive terminal, else return plain text.

Source code in vedo/core/summary.py

def summary_string(obj, rows, color: str = "white", expand: bool = False) -> str:
    """Use rich formatting in an interactive terminal, else return plain text."""
    fallback = summary_text(obj, rows)
    if (
        sys.stdout is None
        or not hasattr(sys.stdout, "isatty")
        or not sys.stdout.isatty()
    ):
        return fallback
    try:
        from io import StringIO
        from rich.console import Console

        buffer = StringIO()
        Console(file=buffer, force_terminal=True).print(
            summary_panel(obj, rows, color=color, expand=expand)
        )
        return buffer.getvalue().rstrip()
    except Exception:
        return fallback

summary_text(obj, rows)

Return a plain-text summary for the provided rows.

Source code in vedo/core/summary.py

def summary_text(obj, rows) -> str:
    """Return a plain-text summary for the provided rows."""
    rows = [(str(field), str(value)) for field, value in rows]
    width = max((len(field) for field, _ in rows), default=0)
    width = max(width, 14)

    out = [summary_title(obj)]
    for field, value in rows:
        label = field.ljust(width)
        if "\n" in value:
            out.append(f"{label}:")
            indent = " " * (width + 2)
            out.extend(f"{indent}{line}" for line in value.splitlines())
        else:
            out.append(f"{label}: {value}")
    return "\n".join(out)

summary_title(obj)

Build the standard summary title for an object.

Source code in vedo/core/summary.py

def summary_title(obj) -> str:
    """Build the standard summary title for an object."""
    return f"{obj.__class__.__module__}.{obj.__class__.__name__}"

transformations

LinearTransform

Work with linear transformations.

Source code in vedo/core/transformations.py

class LinearTransform:
    """Work with linear transformations."""

    def __init__(self, T=None) -> None:
        """
        Define a linear transformation.
        Can be saved to file and reloaded.

        Args:
            T (str, vtkTransform, numpy array):
                input transformation. Defaults to unit.

        Examples:
            ```python
            from vedo import *
            settings.use_parallel_projection = True

            LT = LinearTransform()
            LT.translate([3,0,1]).rotate_z(45)
            LT.comment = "shifting by (3,0,1) and rotating by 45 deg"
            print(LT)

            sph = Sphere(r=0.2)
            sph.apply_transform(LT) # same as: LT.move(s1)
            print(sph.transform)

            show(Point([0,0,0]), sph, str(LT.matrix), axes=1).close()
            ```
        """
        self.name = "LinearTransform"
        self.filename = ""
        self.comment = ""

        if T is None:
            T = vtki.vtkTransform()

        elif isinstance(T, vtki.vtkMatrix4x4):
            S = vtki.vtkTransform()
            S.SetMatrix(T)
            T = S

        elif isinstance(T, vtki.vtkLandmarkTransform):
            S = vtki.vtkTransform()
            S.SetMatrix(T.GetMatrix())
            T = S

        elif _is_sequence(T):
            S = vtki.vtkTransform()
            M = vtki.vtkMatrix4x4()
            arr = np.asarray(T, dtype=float)
            if arr.ndim != 2 or arr.shape[0] != arr.shape[1]:
                raise ValueError(
                    f"LinearTransform: expected a square 2D matrix, got shape {arr.shape}"
                )
            n = arr.shape[0]
            for i in range(n):
                for j in range(n):
                    M.SetElement(i, j, arr[i, j])
            S.SetMatrix(M)
            T = S

        elif isinstance(T, vtki.vtkLinearTransform):
            S = vtki.vtkTransform()
            S.DeepCopy(T)
            T = S

        elif isinstance(T, LinearTransform):
            S = vtki.vtkTransform()
            S.DeepCopy(T.T)
            T = S

        elif isinstance(T, str):
            import json

            self.filename = str(T)
            try:
                with open(self.filename, "r") as read_file:
                    D = json.load(read_file)
                self.name = D.get("name", "LinearTransform")
                self.comment = D.get("comment", "")
                matrix = np.array(D["matrix"])
            except json.decoder.JSONDecodeError:
                ### assuming legacy vedo format E.g.:
                # aligned by manual_align.py
                # 0.8026854838223 -0.0789823873914 -0.508476844097  38.17377632072
                # 0.0679734082661  0.9501827489452 -0.040289803376 -69.53864247951
                # 0.5100652300642 -0.0023313569781  0.805555043665 -81.20317788519
                # 0.0 0.0 0.0 1.0
                with open(self.filename, "r", encoding="UTF-8") as read_file:
                    lines = read_file.readlines()
                    i = 0
                    matrix = np.eye(4)
                    for line in lines:
                        if line.startswith("#"):
                            self.comment = line.replace("#", "").strip()
                            continue
                        vals = line.split()
                        for j in range(len(vals)):
                            v = vals[j].replace("\n", "")
                            if v != "":
                                matrix[i, j] = float(v)
                        i += 1
            T = vtki.vtkTransform()
            m = vtki.vtkMatrix4x4()
            for i in range(4):
                for j in range(4):
                    m.SetElement(i, j, matrix[i][j])
            T.SetMatrix(m)

        self.T = T
        self.T.PostMultiply()
        self.inverse_flag = False

    def _summary_rows(self):
        rows = [("name", self.name)]
        if self.filename:
            rows.append(("filename", self.filename))
        if self.comment:
            rows.append(("comment", self.comment))
        rows.append(("concatenations", str(self.ntransforms)))
        rows.append(("inverse flag", str(bool(self.inverse_flag))))
        rows.append(
            (
                "matrix 4x4",
                np.array2string(
                    self.matrix, separator=", ", precision=6, suppress_small=True
                ),
            )
        )
        return rows

    def __str__(self):
        return summary_string(self, self._summary_rows())

    def __repr__(self):
        return self.__str__()

    def __rich__(self):
        return summary_panel(self, self._summary_rows())

    def print(self) -> LinearTransform:
        """Print transformation."""
        print(self)
        return self

    def __call__(self, obj):
        """
        Apply transformation to object or single point.
        Same as `move()` except that a copy is returned.
        """
        return self.move(obj.copy())

    def transform_point(self, p) -> np.ndarray:
        """
        Apply transformation to a single point.
        """
        if len(p) == 2:
            p = [p[0], p[1], 0]
        return np.array(self.T.TransformFloatPoint(p))

    def move(self, obj):
        """
        Apply transformation to object or single point.

        Note:
            When applying a transformation to a mesh, the mesh is modified in place.
            If you want to keep the original mesh unchanged, use `clone()` method.

        Examples:
            ```python
            from vedo import *
            settings.use_parallel_projection = True

            LT = LinearTransform()
            LT.translate([3,0,1]).rotate_z(45)
            print(LT)

            s = Sphere(r=0.2)
            LT.move(s)
            # same as:
            # s.apply_transform(LT)

            zero = Point([0,0,0])
            show(s, zero, axes=1).close()
            ```
        """
        if _is_sequence(obj):
            n = len(obj)
            if n == 2:
                obj = [obj[0], obj[1], 0]
            return np.array(self.T.TransformFloatPoint(obj))

        obj.apply_transform(self)
        return obj

    def reset(self) -> Self:
        """Reset transformation."""
        self.T.Identity()
        return self

    def compute_main_axes(self) -> np.ndarray:
        """
        Compute main axes of the transformation matrix.
        These are the axes of the ellipsoid that is the
        image of the unit sphere under the transformation.

        Examples:
        ```python
        from vedo import *
        settings.use_parallel_projection = True

        M = np.random.rand(3,3)-0.5
        print(M)
        print(" M@[1,0,0] =", M@[1,1,0])

        ######################
        A = LinearTransform(M)
        print(A)
        pt = Point([1,1,0])
        print(A(pt).coordinates[0], "is the same as", A([1,1,0]))

        maxes = A.compute_main_axes()

        arr1 = Arrow([0,0,0], maxes[0]).c('r')
        arr2 = Arrow([0,0,0], maxes[1]).c('g')
        arr3 = Arrow([0,0,0], maxes[2]).c('b')

        sphere1 = Sphere().wireframe().lighting('off')
        sphere1.cmap('hot', sphere1.coordinates[:,2])

        sphere2 = sphere1.clone().apply_transform(A)

        show([sphere1, [sphere2, arr1, arr2, arr3]], N=2, axes=1, bg='bb')
        ```
        """
        m = self.matrix3x3
        eigval, eigvec = np.linalg.eig(m @ m.T)
        eigval = np.sqrt(eigval)
        return np.array(
            [
                eigvec[:, 0] * eigval[0],
                eigvec[:, 1] * eigval[1],
                eigvec[:, 2] * eigval[2],
            ]
        )

    def pop(self) -> Self:
        """Delete the transformation on the top of the stack
        and sets the top to the next transformation on the stack."""
        self.T.Pop()
        return self

    def is_identity(self) -> bool:
        """Check if the transformation is the identity."""
        m = self.T.GetMatrix()
        M = [[m.GetElement(i, j) for j in range(4)] for i in range(4)]
        return bool(np.allclose(M, np.eye(4)))

    def invert(self) -> Self:
        """Invert the transformation. Acts in-place."""
        self.T.Inverse()
        self.inverse_flag = bool(self.T.GetInverseFlag())
        return self

    def compute_inverse(self) -> LinearTransform:
        """Compute the inverse."""
        t = self.clone()
        t.invert()
        return t

    def transpose(self) -> Self:
        """Transpose the transformation. Acts in-place."""
        M = vtki.vtkMatrix4x4()
        self.T.GetTranspose(M)
        self.T.SetMatrix(M)
        return self

    def copy(self) -> LinearTransform:
        """Return a copy of the transformation. Alias of `clone()`."""
        return self.clone()

    def clone(self) -> LinearTransform:
        """Clone transformation to make an exact copy."""
        return LinearTransform(self.T)

    def concatenate(self, T, pre_multiply=False) -> Self:
        """
        Post-multiply (by default) 2 transfomations.
        T can also be a 4x4 matrix or 3x3 matrix.

        Examples:
            ```python
            from vedo import LinearTransform

            A = LinearTransform()
            A.rotate_x(45)
            A.translate([7,8,9])
            A.translate([10,10,10])
            A.name = "My transformation A"
            print(A)

            B = A.compute_inverse()
            B.shift([1,2,3])
            B.name = "My transformation B (shifted inverse of A)"
            print(B)

            # A is applied first, then B
            # print("A.concatenate(B)", A.concatenate(B))

            # B is applied first, then A
            print(B*A)
            ```
        """
        if _is_sequence(T):
            S = vtki.vtkTransform()
            M = vtki.vtkMatrix4x4()
            n = len(T)
            for i in range(n):
                for j in range(n):
                    M.SetElement(i, j, T[i][j])
            S.SetMatrix(M)
            T = S

        if pre_multiply:
            self.T.PreMultiply()
        transform = T.T if hasattr(T, "T") else T
        self.T.Concatenate(transform)
        self.T.PostMultiply()
        return self

    def __mul__(self, A):
        """Pre-multiply 2 transfomations."""
        return self.concatenate(A, pre_multiply=True)

    def get_concatenated_transform(self, i) -> LinearTransform:
        """Get intermediate matrix by concatenation index."""
        return LinearTransform(self.T.GetConcatenatedTransform(i))

    @property
    def ntransforms(self) -> int:
        """Get the number of concatenated transforms."""
        return self.T.GetNumberOfConcatenatedTransforms()

    def translate(self, p) -> Self:
        """Translate, same as `shift`."""
        if len(p) == 2:
            p = [p[0], p[1], 0]
        self.T.Translate(p)
        return self

    def shift(self, p) -> Self:
        """Shift, same as `translate`."""
        return self.translate(p)

    def scale(self, s, origin=True) -> Self:
        """Scale."""
        if not _is_sequence(s):
            s = [s, s, s]

        if origin is True:
            p = np.array(self.T.GetPosition())
            if np.linalg.norm(p) > 0:
                self.T.Translate(-p)
                self.T.Scale(*s)
                self.T.Translate(p)
            else:
                self.T.Scale(*s)

        elif _is_sequence(origin):
            origin = np.asarray(origin)
            self.T.Translate(-origin)
            self.T.Scale(*s)
            self.T.Translate(origin)

        else:
            self.T.Scale(*s)
        return self

    def rotate(self, angle, axis=(1, 0, 0), point=(0, 0, 0), rad=False) -> Self:
        """
        Rotate around an arbitrary `axis` passing through `point`.

        Examples:
            ```python
            from vedo import *
            c1 = Cube()
            c2 = c1.clone().c('violet').alpha(0.5) # copy of c1
            v = vector(0.2, 1, 0)
            p = vector(1.0, 0, 0)  # axis passes through this point
            c2.rotate(90, axis=v, point=p)
            l = Line(p-v, p+v).c('red5').lw(3)
            show(c1, l, c2, axes=1).close()
            ```
            ![](https://vedo.embl.es/images/feats/rotate_axis.png)
        """
        if not angle:
            return self
        axis = np.asarray(axis, dtype=float)
        axis_norm = np.linalg.norm(axis)
        if axis_norm == 0:
            return self
        if rad:
            anglerad = angle
        else:
            anglerad = np.deg2rad(angle)

        axis = axis / axis_norm
        a = np.cos(anglerad / 2)
        b, c, d = -axis * np.sin(anglerad / 2)
        aa, bb, cc, dd = a * a, b * b, c * c, d * d
        bc, ad, ac, ab, bd, cd = b * c, a * d, a * c, a * b, b * d, c * d
        R = np.array(
            [
                [aa + bb - cc - dd, 2 * (bc + ad), 2 * (bd - ac)],
                [2 * (bc - ad), aa + cc - bb - dd, 2 * (cd + ab)],
                [2 * (bd + ac), 2 * (cd - ab), aa + dd - bb - cc],
            ]
        )
        rv = np.dot(R, self.T.GetPosition() - np.asarray(point)) + point

        if rad:
            angle *= 180.0 / np.pi
        # this vtk method only rotates in the origin of the object:
        self.T.RotateWXYZ(angle, axis[0], axis[1], axis[2])
        self.T.Translate(rv - np.array(self.T.GetPosition()))
        return self

    def _rotatexyz(self, axe, angle, rad, around):
        if not angle:
            return self
        if rad:
            angle *= 180 / np.pi

        rot = dict(x=self.T.RotateX, y=self.T.RotateY, z=self.T.RotateZ)

        if around is None:
            # rotate around its origin
            rot[axe](angle)
        else:
            # displacement needed to bring it back to the origin
            self.T.Translate(-np.asarray(around))
            rot[axe](angle)
            self.T.Translate(around)
        return self

    def rotate_x(self, angle: float, rad=False, around=None) -> Self:
        """
        Rotate around x-axis. If angle is in radians set `rad=True`.

        Use `around` to define a pivoting point.
        """
        return self._rotatexyz("x", angle, rad, around)

    def rotate_y(self, angle: float, rad=False, around=None) -> Self:
        """
        Rotate around y-axis. If angle is in radians set `rad=True`.

        Use `around` to define a pivoting point.
        """
        return self._rotatexyz("y", angle, rad, around)

    def rotate_z(self, angle: float, rad=False, around=None) -> Self:
        """
        Rotate around z-axis. If angle is in radians set `rad=True`.

        Use `around` to define a pivoting point.
        """
        return self._rotatexyz("z", angle, rad, around)

    def set_position(self, p) -> Self:
        """Set position."""
        if len(p) == 2:
            p = np.array([p[0], p[1], 0])
        q = np.array(self.T.GetPosition())
        self.T.Translate(p - q)
        return self

    # def set_scale(self, s):
    #     """Set absolute scale."""
    #     if not _is_sequence(s):
    #         s = [s, s, s]
    #     s0, s1, s2 = 1, 1, 1
    #     b = self.T.GetScale()
    #     print(b)
    #     if b[0]:
    #         s0 = s[0] / b[0]
    #     if b[1]:
    #         s1 = s[1] / b[1]
    #     if b[2]:
    #         s2 = s[2] / b[2]
    #     self.T.Scale(s0, s1, s2)
    #     print()
    #     return self

    def get_scale(self) -> np.ndarray:
        """Get current scale."""
        return np.array(self.T.GetScale())

    @property
    def orientation(self) -> np.ndarray:
        """Compute orientation."""
        return np.array(self.T.GetOrientation())

    @property
    def position(self) -> np.ndarray:
        """Compute position."""
        return np.array(self.T.GetPosition())

    @property
    def matrix(self) -> np.ndarray:
        """Get the 4x4 trasformation matrix."""
        m = self.T.GetMatrix()
        M = [[m.GetElement(i, j) for j in range(4)] for i in range(4)]
        return np.array(M)

    @matrix.setter
    def matrix(self, M) -> None:
        """Set trasformation by assigning a 4x4 or 3x3 numpy matrix."""
        n = len(M)
        m = vtki.vtkMatrix4x4()
        for i in range(n):
            for j in range(n):
                m.SetElement(i, j, M[i][j])
        self.T.SetMatrix(m)

    @property
    def matrix3x3(self) -> np.ndarray:
        """Get the 3x3 trasformation matrix."""
        m = self.T.GetMatrix()
        M = [[m.GetElement(i, j) for j in range(3)] for i in range(3)]
        return np.array(M)

    def write(self, filename="transform.mat") -> Self:
        """Save transformation to ASCII file."""
        import json

        m = self.T.GetMatrix()
        M = [[m.GetElement(i, j) for j in range(4)] for i in range(4)]
        arr = np.array(M)
        dictionary = {
            "name": self.name,
            "comment": self.comment,
            "matrix": arr.astype(float).tolist(),
            "ntransforms": self.ntransforms,
        }
        with open(filename, "w") as outfile:
            json.dump(dictionary, outfile, sort_keys=True, indent=2)
        return self

    def reorient(
        self, initaxis, newaxis, around=(0, 0, 0), rotation=0.0, rad=False, xyplane=True
    ) -> Self:
        """
        Set/Get object orientation.

        Args:
            rotation (float):
                rotate object around newaxis.
            concatenate (bool):
                concatenate the orientation operation with the previous existing transform (if any)
            rad (bool):
                set to True if angle is expressed in radians.
            xyplane (bool):
                make an extra rotation to keep the object aligned to the xy-plane
        """
        newaxis = np.asarray(newaxis) / np.linalg.norm(newaxis)
        initaxis = np.asarray(initaxis) / np.linalg.norm(initaxis)

        if not np.any(initaxis - newaxis):
            return self

        if not np.any(initaxis + newaxis):
            # antiparallel: pick any axis perpendicular to initaxis
            warn("In reorient() initaxis and newaxis are antiparallel", stacklevel=2)
            perp = np.array([1.0, 0.0, 0.0])
            if abs(np.dot(perp, initaxis)) > 0.9:
                perp = np.array([0.0, 1.0, 0.0])
            crossvec = np.cross(initaxis, perp)
            crossvec /= np.linalg.norm(crossvec)
            angleth = np.pi
        else:
            angleth = np.arccos(np.clip(np.dot(initaxis, newaxis), -1.0, 1.0))
            crossvec = np.cross(initaxis, newaxis)

        p = np.asarray(around)
        self.T.Translate(-p)
        if rotation:
            if rad:
                rotation = np.rad2deg(rotation)
            self.T.RotateWXYZ(rotation, initaxis)

        self.T.RotateWXYZ(np.rad2deg(angleth), crossvec)

        if xyplane:
            self.T.RotateWXYZ(-self.orientation[0] * np.sqrt(2), newaxis)

        self.T.Translate(p)
        return self

matrix property writable

Get the 4x4 trasformation matrix.

matrix3x3 property

Get the 3x3 trasformation matrix.

ntransforms property

Get the number of concatenated transforms.

orientation property

Compute orientation.

position property

Compute position.

clone()

Clone transformation to make an exact copy.

Source code in vedo/core/transformations.py

def clone(self) -> LinearTransform:
    """Clone transformation to make an exact copy."""
    return LinearTransform(self.T)

compute_inverse()

Compute the inverse.

Source code in vedo/core/transformations.py

def compute_inverse(self) -> LinearTransform:
    """Compute the inverse."""
    t = self.clone()
    t.invert()
    return t

compute_main_axes()

Compute main axes of the transformation matrix. These are the axes of the ellipsoid that is the image of the unit sphere under the transformation.

Examples:

from vedo import *
settings.use_parallel_projection = True

M = np.random.rand(3,3)-0.5
print(M)
print(" M@[1,0,0] =", M@[1,1,0])

######################
A = LinearTransform(M)
print(A)
pt = Point([1,1,0])
print(A(pt).coordinates[0], "is the same as", A([1,1,0]))

maxes = A.compute_main_axes()

arr1 = Arrow([0,0,0], maxes[0]).c('r')
arr2 = Arrow([0,0,0], maxes[1]).c('g')
arr3 = Arrow([0,0,0], maxes[2]).c('b')

sphere1 = Sphere().wireframe().lighting('off')
sphere1.cmap('hot', sphere1.coordinates[:,2])

sphere2 = sphere1.clone().apply_transform(A)

show([sphere1, [sphere2, arr1, arr2, arr3]], N=2, axes=1, bg='bb')

Source code in vedo/core/transformations.py

def compute_main_axes(self) -> np.ndarray:
    """
    Compute main axes of the transformation matrix.
    These are the axes of the ellipsoid that is the
    image of the unit sphere under the transformation.

    Examples:
    ```python
    from vedo import *
    settings.use_parallel_projection = True

    M = np.random.rand(3,3)-0.5
    print(M)
    print(" M@[1,0,0] =", M@[1,1,0])

    ######################
    A = LinearTransform(M)
    print(A)
    pt = Point([1,1,0])
    print(A(pt).coordinates[0], "is the same as", A([1,1,0]))

    maxes = A.compute_main_axes()

    arr1 = Arrow([0,0,0], maxes[0]).c('r')
    arr2 = Arrow([0,0,0], maxes[1]).c('g')
    arr3 = Arrow([0,0,0], maxes[2]).c('b')

    sphere1 = Sphere().wireframe().lighting('off')
    sphere1.cmap('hot', sphere1.coordinates[:,2])

    sphere2 = sphere1.clone().apply_transform(A)

    show([sphere1, [sphere2, arr1, arr2, arr3]], N=2, axes=1, bg='bb')
    ```
    """
    m = self.matrix3x3
    eigval, eigvec = np.linalg.eig(m @ m.T)
    eigval = np.sqrt(eigval)
    return np.array(
        [
            eigvec[:, 0] * eigval[0],
            eigvec[:, 1] * eigval[1],
            eigvec[:, 2] * eigval[2],
        ]
    )

concatenate(T, pre_multiply=False)

Post-multiply (by default) 2 transfomations. T can also be a 4x4 matrix or 3x3 matrix.

Examples:

from vedo import LinearTransform

A = LinearTransform()
A.rotate_x(45)
A.translate([7,8,9])
A.translate([10,10,10])
A.name = "My transformation A"
print(A)

B = A.compute_inverse()
B.shift([1,2,3])
B.name = "My transformation B (shifted inverse of A)"
print(B)

# A is applied first, then B
# print("A.concatenate(B)", A.concatenate(B))

# B is applied first, then A
print(B*A)

Source code in vedo/core/transformations.py

def concatenate(self, T, pre_multiply=False) -> Self:
    """
    Post-multiply (by default) 2 transfomations.
    T can also be a 4x4 matrix or 3x3 matrix.

    Examples:
        ```python
        from vedo import LinearTransform

        A = LinearTransform()
        A.rotate_x(45)
        A.translate([7,8,9])
        A.translate([10,10,10])
        A.name = "My transformation A"
        print(A)

        B = A.compute_inverse()
        B.shift([1,2,3])
        B.name = "My transformation B (shifted inverse of A)"
        print(B)

        # A is applied first, then B
        # print("A.concatenate(B)", A.concatenate(B))

        # B is applied first, then A
        print(B*A)
        ```
    """
    if _is_sequence(T):
        S = vtki.vtkTransform()
        M = vtki.vtkMatrix4x4()
        n = len(T)
        for i in range(n):
            for j in range(n):
                M.SetElement(i, j, T[i][j])
        S.SetMatrix(M)
        T = S

    if pre_multiply:
        self.T.PreMultiply()
    transform = T.T if hasattr(T, "T") else T
    self.T.Concatenate(transform)
    self.T.PostMultiply()
    return self

copy()

Return a copy of the transformation. Alias of clone().

Source code in vedo/core/transformations.py

def copy(self) -> LinearTransform:
    """Return a copy of the transformation. Alias of `clone()`."""
    return self.clone()

get_concatenated_transform(i)

Get intermediate matrix by concatenation index.

Source code in vedo/core/transformations.py

def get_concatenated_transform(self, i) -> LinearTransform:
    """Get intermediate matrix by concatenation index."""
    return LinearTransform(self.T.GetConcatenatedTransform(i))

get_scale()

Get current scale.

Source code in vedo/core/transformations.py

def get_scale(self) -> np.ndarray:
    """Get current scale."""
    return np.array(self.T.GetScale())

invert()

Invert the transformation. Acts in-place.

Source code in vedo/core/transformations.py

def invert(self) -> Self:
    """Invert the transformation. Acts in-place."""
    self.T.Inverse()
    self.inverse_flag = bool(self.T.GetInverseFlag())
    return self

is_identity()

Check if the transformation is the identity.

Source code in vedo/core/transformations.py

def is_identity(self) -> bool:
    """Check if the transformation is the identity."""
    m = self.T.GetMatrix()
    M = [[m.GetElement(i, j) for j in range(4)] for i in range(4)]
    return bool(np.allclose(M, np.eye(4)))

move(obj)

Apply transformation to object or single point.

Note

When applying a transformation to a mesh, the mesh is modified in place. If you want to keep the original mesh unchanged, use clone() method.

Examples:

from vedo import *
settings.use_parallel_projection = True

LT = LinearTransform()
LT.translate([3,0,1]).rotate_z(45)
print(LT)

s = Sphere(r=0.2)
LT.move(s)
# same as:
# s.apply_transform(LT)

zero = Point([0,0,0])
show(s, zero, axes=1).close()

Source code in vedo/core/transformations.py

def move(self, obj):
    """
    Apply transformation to object or single point.

    Note:
        When applying a transformation to a mesh, the mesh is modified in place.
        If you want to keep the original mesh unchanged, use `clone()` method.

    Examples:
        ```python
        from vedo import *
        settings.use_parallel_projection = True

        LT = LinearTransform()
        LT.translate([3,0,1]).rotate_z(45)
        print(LT)

        s = Sphere(r=0.2)
        LT.move(s)
        # same as:
        # s.apply_transform(LT)

        zero = Point([0,0,0])
        show(s, zero, axes=1).close()
        ```
    """
    if _is_sequence(obj):
        n = len(obj)
        if n == 2:
            obj = [obj[0], obj[1], 0]
        return np.array(self.T.TransformFloatPoint(obj))

    obj.apply_transform(self)
    return obj

pop()

Delete the transformation on the top of the stack and sets the top to the next transformation on the stack.

Source code in vedo/core/transformations.py

def pop(self) -> Self:
    """Delete the transformation on the top of the stack
    and sets the top to the next transformation on the stack."""
    self.T.Pop()
    return self

print()

Print transformation.

Source code in vedo/core/transformations.py

def print(self) -> LinearTransform:
    """Print transformation."""
    print(self)
    return self

reorient(initaxis, newaxis, around=(0, 0, 0), rotation=0.0, rad=False, xyplane=True)

Set/Get object orientation.

Parameters:

Name	Type	Description	Default
rotation	float	rotate object around newaxis.	0.0
concatenate	bool	concatenate the orientation operation with the previous existing transform (if any)	required
rad	bool	set to True if angle is expressed in radians.	False
xyplane	bool	make an extra rotation to keep the object aligned to the xy-plane	True

Source code in vedo/core/transformations.py

def reorient(
    self, initaxis, newaxis, around=(0, 0, 0), rotation=0.0, rad=False, xyplane=True
) -> Self:
    """
    Set/Get object orientation.

    Args:
        rotation (float):
            rotate object around newaxis.
        concatenate (bool):
            concatenate the orientation operation with the previous existing transform (if any)
        rad (bool):
            set to True if angle is expressed in radians.
        xyplane (bool):
            make an extra rotation to keep the object aligned to the xy-plane
    """
    newaxis = np.asarray(newaxis) / np.linalg.norm(newaxis)
    initaxis = np.asarray(initaxis) / np.linalg.norm(initaxis)

    if not np.any(initaxis - newaxis):
        return self

    if not np.any(initaxis + newaxis):
        # antiparallel: pick any axis perpendicular to initaxis
        warn("In reorient() initaxis and newaxis are antiparallel", stacklevel=2)
        perp = np.array([1.0, 0.0, 0.0])
        if abs(np.dot(perp, initaxis)) > 0.9:
            perp = np.array([0.0, 1.0, 0.0])
        crossvec = np.cross(initaxis, perp)
        crossvec /= np.linalg.norm(crossvec)
        angleth = np.pi
    else:
        angleth = np.arccos(np.clip(np.dot(initaxis, newaxis), -1.0, 1.0))
        crossvec = np.cross(initaxis, newaxis)

    p = np.asarray(around)
    self.T.Translate(-p)
    if rotation:
        if rad:
            rotation = np.rad2deg(rotation)
        self.T.RotateWXYZ(rotation, initaxis)

    self.T.RotateWXYZ(np.rad2deg(angleth), crossvec)

    if xyplane:
        self.T.RotateWXYZ(-self.orientation[0] * np.sqrt(2), newaxis)

    self.T.Translate(p)
    return self

reset()

Reset transformation.

Source code in vedo/core/transformations.py

def reset(self) -> Self:
    """Reset transformation."""
    self.T.Identity()
    return self

rotate(angle, axis=(1, 0, 0), point=(0, 0, 0), rad=False)

Rotate around an arbitrary axis passing through point.

Examples:

from vedo import *
c1 = Cube()
c2 = c1.clone().c('violet').alpha(0.5) # copy of c1
v = vector(0.2, 1, 0)
p = vector(1.0, 0, 0)  # axis passes through this point
c2.rotate(90, axis=v, point=p)
l = Line(p-v, p+v).c('red5').lw(3)
show(c1, l, c2, axes=1).close()

Source code in vedo/core/transformations.py

def rotate(self, angle, axis=(1, 0, 0), point=(0, 0, 0), rad=False) -> Self:
    """
    Rotate around an arbitrary `axis` passing through `point`.

    Examples:
        ```python
        from vedo import *
        c1 = Cube()
        c2 = c1.clone().c('violet').alpha(0.5) # copy of c1
        v = vector(0.2, 1, 0)
        p = vector(1.0, 0, 0)  # axis passes through this point
        c2.rotate(90, axis=v, point=p)
        l = Line(p-v, p+v).c('red5').lw(3)
        show(c1, l, c2, axes=1).close()
        ```
        ![](https://vedo.embl.es/images/feats/rotate_axis.png)
    """
    if not angle:
        return self
    axis = np.asarray(axis, dtype=float)
    axis_norm = np.linalg.norm(axis)
    if axis_norm == 0:
        return self
    if rad:
        anglerad = angle
    else:
        anglerad = np.deg2rad(angle)

    axis = axis / axis_norm
    a = np.cos(anglerad / 2)
    b, c, d = -axis * np.sin(anglerad / 2)
    aa, bb, cc, dd = a * a, b * b, c * c, d * d
    bc, ad, ac, ab, bd, cd = b * c, a * d, a * c, a * b, b * d, c * d
    R = np.array(
        [
            [aa + bb - cc - dd, 2 * (bc + ad), 2 * (bd - ac)],
            [2 * (bc - ad), aa + cc - bb - dd, 2 * (cd + ab)],
            [2 * (bd + ac), 2 * (cd - ab), aa + dd - bb - cc],
        ]
    )
    rv = np.dot(R, self.T.GetPosition() - np.asarray(point)) + point

    if rad:
        angle *= 180.0 / np.pi
    # this vtk method only rotates in the origin of the object:
    self.T.RotateWXYZ(angle, axis[0], axis[1], axis[2])
    self.T.Translate(rv - np.array(self.T.GetPosition()))
    return self

rotate_x(angle, rad=False, around=None)

Rotate around x-axis. If angle is in radians set rad=True.

Use around to define a pivoting point.

Source code in vedo/core/transformations.py

def rotate_x(self, angle: float, rad=False, around=None) -> Self:
    """
    Rotate around x-axis. If angle is in radians set `rad=True`.

    Use `around` to define a pivoting point.
    """
    return self._rotatexyz("x", angle, rad, around)

rotate_y(angle, rad=False, around=None)

Rotate around y-axis. If angle is in radians set rad=True.

Use around to define a pivoting point.

Source code in vedo/core/transformations.py

def rotate_y(self, angle: float, rad=False, around=None) -> Self:
    """
    Rotate around y-axis. If angle is in radians set `rad=True`.

    Use `around` to define a pivoting point.
    """
    return self._rotatexyz("y", angle, rad, around)

rotate_z(angle, rad=False, around=None)

Rotate around z-axis. If angle is in radians set rad=True.

Use around to define a pivoting point.

Source code in vedo/core/transformations.py

def rotate_z(self, angle: float, rad=False, around=None) -> Self:
    """
    Rotate around z-axis. If angle is in radians set `rad=True`.

    Use `around` to define a pivoting point.
    """
    return self._rotatexyz("z", angle, rad, around)

scale(s, origin=True)

Scale.

Source code in vedo/core/transformations.py

def scale(self, s, origin=True) -> Self:
    """Scale."""
    if not _is_sequence(s):
        s = [s, s, s]

    if origin is True:
        p = np.array(self.T.GetPosition())
        if np.linalg.norm(p) > 0:
            self.T.Translate(-p)
            self.T.Scale(*s)
            self.T.Translate(p)
        else:
            self.T.Scale(*s)

    elif _is_sequence(origin):
        origin = np.asarray(origin)
        self.T.Translate(-origin)
        self.T.Scale(*s)
        self.T.Translate(origin)

    else:
        self.T.Scale(*s)
    return self

set_position(p)

Set position.

Source code in vedo/core/transformations.py

def set_position(self, p) -> Self:
    """Set position."""
    if len(p) == 2:
        p = np.array([p[0], p[1], 0])
    q = np.array(self.T.GetPosition())
    self.T.Translate(p - q)
    return self

shift(p)

Shift, same as translate.

Source code in vedo/core/transformations.py

def shift(self, p) -> Self:
    """Shift, same as `translate`."""
    return self.translate(p)

transform_point(p)

Apply transformation to a single point.

Source code in vedo/core/transformations.py

def transform_point(self, p) -> np.ndarray:
    """
    Apply transformation to a single point.
    """
    if len(p) == 2:
        p = [p[0], p[1], 0]
    return np.array(self.T.TransformFloatPoint(p))

translate(p)

Translate, same as shift.

Source code in vedo/core/transformations.py

def translate(self, p) -> Self:
    """Translate, same as `shift`."""
    if len(p) == 2:
        p = [p[0], p[1], 0]
    self.T.Translate(p)
    return self

transpose()

Transpose the transformation. Acts in-place.

Source code in vedo/core/transformations.py

def transpose(self) -> Self:
    """Transpose the transformation. Acts in-place."""
    M = vtki.vtkMatrix4x4()
    self.T.GetTranspose(M)
    self.T.SetMatrix(M)
    return self

write(filename='transform.mat')

Save transformation to ASCII file.

Source code in vedo/core/transformations.py

def write(self, filename="transform.mat") -> Self:
    """Save transformation to ASCII file."""
    import json

    m = self.T.GetMatrix()
    M = [[m.GetElement(i, j) for j in range(4)] for i in range(4)]
    arr = np.array(M)
    dictionary = {
        "name": self.name,
        "comment": self.comment,
        "matrix": arr.astype(float).tolist(),
        "ntransforms": self.ntransforms,
    }
    with open(filename, "w") as outfile:
        json.dump(dictionary, outfile, sort_keys=True, indent=2)
    return self

NonLinearTransform

Work with non-linear transformations.

Source code in vedo/core/transformations.py

class NonLinearTransform:
    """Work with non-linear transformations."""

    def __init__(self, T=None, **kwargs) -> None:
        """
        Define a non-linear transformation.
        Can be saved to file and reloaded.

        Args:
            T (vtkThinPlateSplineTransform, str, dict):
                vtk transformation.
                If T is a string, it is assumed to be a filename.
                If T is a dictionary, it is assumed to be a set of keyword arguments.
                Defaults to None.
            **kwargs (dict):
                keyword arguments to define the transformation.
                The following keywords are accepted:
                - name : (str) name of the transformation
                - comment : (str) comment
                - source_points : (list) source points
                - target_points : (list) target points
                - mode : (str) either '2d' or '3d'
                - sigma : (float) sigma parameter

        Examples:
            ```python
            from vedo import *
            settings.use_parallel_projection = True

            NLT = NonLinearTransform()
            NLT.source_points = [[-2,0,0], [1,2,1], [2,-2,2]]
            NLT.target_points = NLT.source_points + np.random.randn(3,3)*0.5
            NLT.mode = '3d'
            print(NLT)

            s1 = Sphere()
            NLT.move(s1)
            # same as:
            # s1.apply_transform(NLT)

            arrs = Arrows(NLT.source_points, NLT.target_points)
            show(s1, arrs, Sphere().alpha(0.1), axes=1).close()
            ```
        """

        self.name = "NonLinearTransform"
        self.filename = ""
        self.comment = ""

        if T is None and len(kwargs) == 0:
            T = vtki.vtkThinPlateSplineTransform()

        elif isinstance(T, vtki.vtkThinPlateSplineTransform):
            S = vtki.vtkThinPlateSplineTransform()
            S.DeepCopy(T)
            T = S

        elif isinstance(T, NonLinearTransform):
            S = vtki.vtkThinPlateSplineTransform()
            S.DeepCopy(T.T)
            T = S

        elif isinstance(T, str):
            import json

            filename = str(T)
            self.filename = filename
            with open(filename, "r") as read_file:
                D = json.load(read_file)
            self.name = D["name"]
            self.comment = D["comment"]
            source = D["source_points"]
            target = D["target_points"]
            mode = D["mode"]
            sigma = D["sigma"]

            T = vtki.vtkThinPlateSplineTransform()
            vptss = vtki.vtkPoints()
            for p in source:
                if len(p) == 2:
                    p = [p[0], p[1], 0.0]
                vptss.InsertNextPoint(p)
            T.SetSourceLandmarks(vptss)
            vptst = vtki.vtkPoints()
            for p in target:
                if len(p) == 2:
                    p = [p[0], p[1], 0.0]
                vptst.InsertNextPoint(p)
            T.SetTargetLandmarks(vptst)
            T.SetSigma(sigma)
            if mode == "2d":
                T.SetBasisToR2LogR()
            elif mode == "3d":
                T.SetBasisToR()
            else:
                warn(f'In {filename} mode can be either "2d" or "3d"', stacklevel=2)

        elif len(kwargs) > 0:
            T = kwargs.copy()
            self.name = T.pop("name", "NonLinearTransform")
            self.comment = T.pop("comment", "")
            source = T.pop("source_points", [])
            target = T.pop("target_points", [])
            mode = T.pop("mode", "3d")
            sigma = T.pop("sigma", 1.0)
            if len(T) > 0:
                warn(
                    f"NonLinearTransform got unexpected keyword arguments: {sorted(T.keys())}",
                    stacklevel=2,
                )

            T = vtki.vtkThinPlateSplineTransform()
            vptss = vtki.vtkPoints()
            for p in source:
                if len(p) == 2:
                    p = [p[0], p[1], 0.0]
                vptss.InsertNextPoint(p)
            T.SetSourceLandmarks(vptss)
            vptst = vtki.vtkPoints()
            for p in target:
                if len(p) == 2:
                    p = [p[0], p[1], 0.0]
                vptst.InsertNextPoint(p)
            T.SetTargetLandmarks(vptst)
            T.SetSigma(sigma)
            if mode == "2d":
                T.SetBasisToR2LogR()
            elif mode == "3d":
                T.SetBasisToR()
            else:
                warn('Mode can be either "2d" or "3d"', stacklevel=2)

        self.T = T
        self.inverse_flag = False

    def _summary_rows(self):
        p = self.source_points
        q = self.target_points
        rows = [("name", self.name)]
        if self.filename:
            rows.append(("filename", self.filename))
        if self.comment:
            rows.append(("comment", self.comment))
        rows.append(("mode", self.mode))
        rows.append(("sigma", str(self.sigma)))
        if len(p):
            rows.append(
                (
                    "sources",
                    f"{len(p)}, bounds {np.min(p, axis=0)}, {np.max(p, axis=0)}",
                )
            )
        else:
            rows.append(("sources", "0"))
        if len(q):
            rows.append(
                (
                    "targets",
                    f"{len(q)}, bounds {np.min(q, axis=0)}, {np.max(q, axis=0)}",
                )
            )
        else:
            rows.append(("targets", "0"))
        return rows

    def __str__(self):
        return summary_string(self, self._summary_rows())

    def __repr__(self):
        return self.__str__()

    def __rich__(self):
        return summary_panel(self, self._summary_rows())

    def print(self) -> Self:
        """Print transformation."""
        print(self)
        return self

    def update(self) -> Self:
        """Update transformation."""
        self.T.Update()
        return self

    @property
    def position(self) -> np.ndarray:
        """
        Trying to get the position of a `NonLinearTransform` always returns [0,0,0].
        """
        return np.array([0.0, 0.0, 0.0], dtype=np.float32)

    # @position.setter
    # def position(self, p):
    #     """
    #     Trying to set position of a `NonLinearTransform`
    #     has no effect and prints a warning.

    #     Use clone() method to create a copy of the object,
    #     or reset it with 'object.transform = vedo.LinearTransform()'
    #     """
    #     print("Warning: NonLinearTransform has no position.")
    #     print("  Use clone() method to create a copy of the object,")
    #     print("  or reset it with 'object.transform = vedo.LinearTransform()'")

    @property
    def source_points(self) -> np.ndarray:
        """Get the source points."""
        pts = self.T.GetSourceLandmarks()
        vpts = []
        if pts:
            for i in range(pts.GetNumberOfPoints()):
                vpts.append(pts.GetPoint(i))
        if not vpts:
            return np.empty((0, 3), dtype=np.float32)
        return np.array(vpts, dtype=np.float32)

    @source_points.setter
    def source_points(self, pts):
        """Set source points."""
        if not _is_sequence(pts):
            pts = pts.coordinates
        vpts = vtki.vtkPoints()
        for p in pts:
            if len(p) == 2:
                p = [p[0], p[1], 0.0]
            vpts.InsertNextPoint(p)
        self.T.SetSourceLandmarks(vpts)

    @property
    def target_points(self) -> np.ndarray:
        """Get the target points."""
        pts = self.T.GetTargetLandmarks()
        vpts = []
        if pts:
            for i in range(pts.GetNumberOfPoints()):
                vpts.append(pts.GetPoint(i))
        if not vpts:
            return np.empty((0, 3), dtype=np.float32)
        return np.array(vpts, dtype=np.float32)

    @target_points.setter
    def target_points(self, pts):
        """Set target points."""
        if not _is_sequence(pts):
            pts = pts.coordinates
        vpts = vtki.vtkPoints()
        for p in pts:
            if len(p) == 2:
                p = [p[0], p[1], 0.0]
            vpts.InsertNextPoint(p)
        self.T.SetTargetLandmarks(vpts)

    @property
    def sigma(self) -> float:
        """Get sigma."""
        return self.T.GetSigma()

    @sigma.setter
    def sigma(self, s):
        """Set sigma."""
        self.T.SetSigma(s)

    @property
    def mode(self) -> str:
        """Get mode."""
        m = self.T.GetBasis()
        # print("T.GetBasis()", m, self.T.GetBasisAsString())
        if m == 2:
            return "2d"
        elif m == 1:
            return "3d"
        else:
            warn("NonLinearTransform has no valid mode.", stacklevel=2)
            return ""

    @mode.setter
    def mode(self, m):
        """Set mode."""
        if m == "3d":
            self.T.SetBasisToR()
        elif m == "2d":
            self.T.SetBasisToR2LogR()
        else:
            warn('In NonLinearTransform mode can be either "2d" or "3d"', stacklevel=2)

    def clone(self) -> NonLinearTransform:
        """Clone transformation to make an exact copy."""
        return NonLinearTransform(self.T)

    def write(self, filename) -> Self:
        """Save transformation to ASCII file."""
        import json

        dictionary = {
            "name": self.name,
            "comment": self.comment,
            "mode": self.mode,
            "sigma": self.sigma,
            "source_points": self.source_points.astype(float).tolist(),
            "target_points": self.target_points.astype(float).tolist(),
        }
        with open(filename, "w") as outfile:
            json.dump(dictionary, outfile, sort_keys=True, indent=2)
        return self

    def invert(self) -> Self:
        """Invert transformation."""
        self.T.Inverse()
        self.inverse_flag = bool(self.T.GetInverseFlag())
        return self

    def compute_inverse(self) -> Self:
        """Compute inverse."""
        t = self.clone()
        t.invert()
        return t

    def __call__(self, obj):
        """
        Apply transformation to object or single point.
        Same as `move()` except that a copy is returned.
        """
        # use copy here not clone in case user passes a numpy array
        return self.move(obj.copy())

    def compute_main_axes(self, pt=(0, 0, 0), ds=1) -> np.ndarray:
        """
        Compute main axes of the transformation.
        These are the axes of the ellipsoid that is the
        image of the unit sphere under the transformation.

        Args:
            pt (list):
                point to compute the axes at.
            ds (float):
                step size to compute the axes.
        """
        if len(pt) == 2:
            pt = [pt[0], pt[1], 0]
        pt = np.asarray(pt)
        p0 = self.transform_point(pt)
        m = np.array(
            [
                self.transform_point(pt + [ds, 0, 0]) - p0,
                self.transform_point(pt + [0, ds, 0]) - p0,
                self.transform_point(pt + [0, 0, ds]) - p0,
            ]
        )
        eigval, eigvec = np.linalg.eig(m @ m.T)
        eigval = np.sqrt(np.abs(eigval))
        return np.array(
            [
                eigvec[:, 0] * eigval[0],
                eigvec[:, 1] * eigval[1],
                eigvec[:, 2] * eigval[2],
            ]
        )

    def transform_point(self, p) -> np.ndarray:
        """
        Apply transformation to a single point.
        """
        if len(p) == 2:
            p = [p[0], p[1], 0]
        return np.array(self.T.TransformFloatPoint(p))

    def move(self, obj):
        """
        Apply transformation to the argument object.

        Note:
            When applying a transformation to a mesh, the mesh is modified in place.
            If you want to keep the original mesh unchanged, use the `clone()` method.

        Examples:
            ```python
            from vedo import *
            np.random.seed(0)
            settings.use_parallel_projection = True

            NLT = NonLinearTransform()
            NLT.source_points = [[-2,0,0], [1,2,1], [2,-2,2]]
            NLT.target_points = NLT.source_points + np.random.randn(3,3)*0.5
            NLT.mode = '3d'
            print(NLT)

            s1 = Sphere()
            NLT.move(s1)
            # same as:
            # s1.apply_transform(NLT)

            arrs = Arrows(NLT.source_points, NLT.target_points)
            show(s1, arrs, Sphere().alpha(0.1), axes=1).close()
            ```
        """
        if _is_sequence(obj):
            return self.transform_point(obj)
        obj.apply_transform(self)
        return obj

mode property writable

Get mode.

position property

Trying to get the position of a NonLinearTransform always returns [0,0,0].

sigma property writable

Get sigma.

source_points property writable

Get the source points.

target_points property writable

Get the target points.

clone()

Clone transformation to make an exact copy.

Source code in vedo/core/transformations.py

def clone(self) -> NonLinearTransform:
    """Clone transformation to make an exact copy."""
    return NonLinearTransform(self.T)

compute_inverse()

Compute inverse.

Source code in vedo/core/transformations.py

def compute_inverse(self) -> Self:
    """Compute inverse."""
    t = self.clone()
    t.invert()
    return t

compute_main_axes(pt=(0, 0, 0), ds=1)

Compute main axes of the transformation. These are the axes of the ellipsoid that is the image of the unit sphere under the transformation.

Parameters:

Name	Type	Description	Default
pt	list	point to compute the axes at.	(0, 0, 0)
ds	float	step size to compute the axes.	1

Source code in vedo/core/transformations.py

def compute_main_axes(self, pt=(0, 0, 0), ds=1) -> np.ndarray:
    """
    Compute main axes of the transformation.
    These are the axes of the ellipsoid that is the
    image of the unit sphere under the transformation.

    Args:
        pt (list):
            point to compute the axes at.
        ds (float):
            step size to compute the axes.
    """
    if len(pt) == 2:
        pt = [pt[0], pt[1], 0]
    pt = np.asarray(pt)
    p0 = self.transform_point(pt)
    m = np.array(
        [
            self.transform_point(pt + [ds, 0, 0]) - p0,
            self.transform_point(pt + [0, ds, 0]) - p0,
            self.transform_point(pt + [0, 0, ds]) - p0,
        ]
    )
    eigval, eigvec = np.linalg.eig(m @ m.T)
    eigval = np.sqrt(np.abs(eigval))
    return np.array(
        [
            eigvec[:, 0] * eigval[0],
            eigvec[:, 1] * eigval[1],
            eigvec[:, 2] * eigval[2],
        ]
    )

invert()

Invert transformation.

Source code in vedo/core/transformations.py

def invert(self) -> Self:
    """Invert transformation."""
    self.T.Inverse()
    self.inverse_flag = bool(self.T.GetInverseFlag())
    return self

move(obj)

Apply transformation to the argument object.

Note

When applying a transformation to a mesh, the mesh is modified in place. If you want to keep the original mesh unchanged, use the clone() method.

Examples:

from vedo import *
np.random.seed(0)
settings.use_parallel_projection = True

NLT = NonLinearTransform()
NLT.source_points = [[-2,0,0], [1,2,1], [2,-2,2]]
NLT.target_points = NLT.source_points + np.random.randn(3,3)*0.5
NLT.mode = '3d'
print(NLT)

s1 = Sphere()
NLT.move(s1)
# same as:
# s1.apply_transform(NLT)

arrs = Arrows(NLT.source_points, NLT.target_points)
show(s1, arrs, Sphere().alpha(0.1), axes=1).close()

Source code in vedo/core/transformations.py

def move(self, obj):
    """
    Apply transformation to the argument object.

    Note:
        When applying a transformation to a mesh, the mesh is modified in place.
        If you want to keep the original mesh unchanged, use the `clone()` method.

    Examples:
        ```python
        from vedo import *
        np.random.seed(0)
        settings.use_parallel_projection = True

        NLT = NonLinearTransform()
        NLT.source_points = [[-2,0,0], [1,2,1], [2,-2,2]]
        NLT.target_points = NLT.source_points + np.random.randn(3,3)*0.5
        NLT.mode = '3d'
        print(NLT)

        s1 = Sphere()
        NLT.move(s1)
        # same as:
        # s1.apply_transform(NLT)

        arrs = Arrows(NLT.source_points, NLT.target_points)
        show(s1, arrs, Sphere().alpha(0.1), axes=1).close()
        ```
    """
    if _is_sequence(obj):
        return self.transform_point(obj)
    obj.apply_transform(self)
    return obj

print()

Print transformation.

Source code in vedo/core/transformations.py

def print(self) -> Self:
    """Print transformation."""
    print(self)
    return self

transform_point(p)

Apply transformation to a single point.

Source code in vedo/core/transformations.py

def transform_point(self, p) -> np.ndarray:
    """
    Apply transformation to a single point.
    """
    if len(p) == 2:
        p = [p[0], p[1], 0]
    return np.array(self.T.TransformFloatPoint(p))

update()

Update transformation.

Source code in vedo/core/transformations.py

def update(self) -> Self:
    """Update transformation."""
    self.T.Update()
    return self

write(filename)

Save transformation to ASCII file.

Source code in vedo/core/transformations.py

def write(self, filename) -> Self:
    """Save transformation to ASCII file."""
    import json

    dictionary = {
        "name": self.name,
        "comment": self.comment,
        "mode": self.mode,
        "sigma": self.sigma,
        "source_points": self.source_points.astype(float).tolist(),
        "target_points": self.target_points.astype(float).tolist(),
    }
    with open(filename, "w") as outfile:
        json.dump(dictionary, outfile, sort_keys=True, indent=2)
    return self

Quaternion

Work with quaternion rotations.

Source code in vedo/core/transformations.py

class Quaternion:
    """Work with quaternion rotations."""

    def __init__(self, q=None, *, axis=None, angle=0.0, rad=False, xyzw=False) -> None:
        """
        Define a quaternion rotation.

        Args:
            q (Quaternion, vtkQuaternion, vtkLinearTransform, vtkMatrix4x4, sequence):
                input quaternion in ``(w, x, y, z)`` order by default, or a 3x3 rotation matrix.
            axis (list):
                optional rotation axis to build the quaternion from axis-angle form.
            angle (float):
                rotation angle associated to ``axis``.
            rad (bool):
                set to ``True`` if ``angle`` is expressed in radians.
            xyzw (bool):
                interpret a 4-sequence input as ``(x, y, z, w)``.
        """
        self.name = "Quaternion"
        self.T = vtki.vtkQuaterniond()
        self.T.ToIdentity()

        if axis is not None:
            if q is not None:
                raise ValueError(
                    "Quaternion() accepts either q=... or axis/angle, not both"
                )
            self.set_axis_angle(angle, axis, rad=rad)
            return

        if q is None:
            return

        if isinstance(q, Quaternion):
            self.T = vtki.vtkQuaterniond(q.T)
            return

        if _is_vtk_quaternion(q):
            self.T = vtki.vtkQuaterniond(q.GetW(), q.GetX(), q.GetY(), q.GetZ())
            return

        if isinstance(q, LinearTransform):
            self.matrix3x3 = q.matrix3x3
            return

        if isinstance(q, vtki.vtkMatrix4x4):
            self.matrix3x3 = np.array(
                [[q.GetElement(i, j) for j in range(3)] for i in range(3)],
                dtype=float,
            )
            return

        if isinstance(q, vtki.vtkLinearTransform):
            self.matrix3x3 = np.array(
                [[q.GetMatrix().GetElement(i, j) for j in range(3)] for i in range(3)],
                dtype=float,
            )
            return

        if _is_sequence(q):
            arr = np.asarray(q, dtype=float)
            if arr.shape == (4,):
                self.set(arr, xyzw=xyzw)
                return
            if arr.shape == (3, 3):
                self.matrix3x3 = arr
                return
            raise ValueError("Quaternion() expects a 4-sequence or a 3x3 matrix")

        raise TypeError(f"Cannot build Quaternion from {type(q).__name__}")

    def _summary_rows(self):
        angle, axis = self.angle_axis()
        return [
            ("q (wxyz)", np.array2string(self.wxyz, precision=6, separator=", ")),
            ("q (xyzw)", np.array2string(self.xyzw, precision=6, separator=", ")),
            ("angle", f"{angle:.6f} deg"),
            ("axis", np.array2string(axis, precision=6, separator=", ")),
        ]

    def __str__(self):
        return summary_string(self, self._summary_rows())

    def __repr__(self):
        return self.__str__()

    def __rich__(self):
        return summary_panel(self, self._summary_rows())

    def print(self) -> Quaternion:
        """Print quaternion details."""
        print(self)
        return self

    def __call__(self, p) -> np.ndarray:
        """Rotate a single 2D or 3D vector."""
        return self.rotate(p)

    @classmethod
    def from_xyzw(cls, q) -> Quaternion:
        """Build a quaternion from ``(x, y, z, w)`` components."""
        return cls(q, xyzw=True)

    @classmethod
    def from_axis_angle(cls, angle, axis=(1, 0, 0), rad=False) -> Quaternion:
        """Build a quaternion from axis-angle form."""
        return cls(axis=axis, angle=angle, rad=rad)

    def copy(self) -> Quaternion:
        """Return a copy of the quaternion. Alias of ``clone()``."""
        return self.clone()

    def clone(self) -> Quaternion:
        """Clone the quaternion to make an exact copy."""
        return Quaternion(self.T)

    def reset(self) -> Self:
        """Reset quaternion to identity."""
        self.T.ToIdentity()
        return self

    def set(self, q, xyzw=False) -> Self:
        """Set quaternion components."""
        arr = np.asarray(q, dtype=float).ravel()
        if arr.shape != (4,):
            raise ValueError("Quaternion.set() expects a 4-sequence")
        if xyzw:
            self.T.Set(arr[3], arr[0], arr[1], arr[2])
        else:
            self.T.Set(arr)
        return self

    def set_axis_angle(self, angle, axis=(1, 0, 0), rad=False) -> Self:
        """Set quaternion from axis-angle form."""
        axis = np.asarray(axis, dtype=float)
        axis_norm = np.linalg.norm(axis)
        if axis_norm == 0:
            raise ValueError("Quaternion axis cannot have zero length")
        axis = axis / axis_norm
        if not rad:
            angle = np.deg2rad(angle)
        self.T.SetRotationAngleAndAxis(angle, axis)
        return self

    def angle_axis(self, rad=False) -> tuple[float, np.ndarray]:
        """Return the quaternion as ``(angle, axis)``."""
        axis = np.zeros(3, dtype=float)
        angle = float(self.T.GetRotationAngleAndAxis(axis))
        if not rad:
            angle = np.rad2deg(angle)
        return angle, axis

    def normalize(self) -> Self:
        """Normalize the quaternion in place."""
        self.T.Normalize()
        return self

    def normalized(self) -> Quaternion:
        """Return a normalized copy of the quaternion."""
        return Quaternion(self.T.Normalized())

    def conjugate(self) -> Self:
        """Conjugate the quaternion in place."""
        self.T.Conjugate()
        return self

    def conjugated(self) -> Quaternion:
        """Return the conjugated quaternion."""
        return Quaternion(self.T.Conjugated())

    def invert(self) -> Self:
        """Invert the quaternion in place."""
        self.T.Invert()
        return self

    def inverse(self) -> Quaternion:
        """Return the inverse quaternion."""
        return Quaternion(self.T.Inverse())

    def slerp(self, t: float, q) -> Quaternion:
        """Spherically interpolate towards quaternion ``q``."""
        q0 = self.normalized().wxyz
        q1 = Quaternion(q).normalized().wxyz
        dot = float(np.clip(np.dot(q0, q1), -1.0, 1.0))

        # Flip the second quaternion so we stay on the shortest arc.
        if dot < 0.0:
            q1 = -q1
            dot = -dot

        if dot > 0.9995:
            out = q0 + t * (q1 - q0)
            out /= np.linalg.norm(out)
            return Quaternion(out)

        theta0 = np.arccos(dot)
        theta = theta0 * t
        sin_theta0 = np.sin(theta0)
        out = np.sin(theta0 - theta) / sin_theta0 * q0 + np.sin(theta) / sin_theta0 * q1
        return Quaternion(out)

    def rotate(self, p) -> np.ndarray:
        """Rotate a single 2D or 3D vector."""
        p = np.asarray(p, dtype=float)
        if p.shape == (2,):
            p = np.array([p[0], p[1], 0.0], dtype=float)
        if p.shape != (3,):
            raise ValueError("Quaternion.rotate() expects a 2D or 3D vector")
        return self.matrix3x3 @ p

    transform_point = rotate

    def to_transform(self) -> LinearTransform:
        """Convert the quaternion to a ``LinearTransform``."""
        return LinearTransform(self.matrix3x3)

    @property
    def w(self) -> float:
        return float(self.T.GetW())

    @w.setter
    def w(self, value) -> None:
        self.T.SetW(float(value))

    @property
    def x(self) -> float:
        return float(self.T.GetX())

    @x.setter
    def x(self, value) -> None:
        self.T.SetX(float(value))

    @property
    def y(self) -> float:
        return float(self.T.GetY())

    @y.setter
    def y(self, value) -> None:
        self.T.SetY(float(value))

    @property
    def z(self) -> float:
        return float(self.T.GetZ())

    @z.setter
    def z(self, value) -> None:
        self.T.SetZ(float(value))

    @property
    def wxyz(self) -> np.ndarray:
        """Get the quaternion as ``(w, x, y, z)``."""
        return np.array([self.w, self.x, self.y, self.z], dtype=float)

    @wxyz.setter
    def wxyz(self, q) -> None:
        self.set(q)

    @property
    def xyzw(self) -> np.ndarray:
        """Get the quaternion as ``(x, y, z, w)``."""
        return np.array([self.x, self.y, self.z, self.w], dtype=float)

    @xyzw.setter
    def xyzw(self, q) -> None:
        self.set(q, xyzw=True)

    @property
    def norm(self) -> float:
        """Get the quaternion norm."""
        return float(self.T.Norm())

    @property
    def squared_norm(self) -> float:
        """Get the squared quaternion norm."""
        return float(self.T.SquaredNorm())

    @property
    def matrix3x3(self) -> np.ndarray:
        """Get the 3x3 rotation matrix."""
        M = np.zeros((3, 3), dtype=float)
        self.T.ToMatrix3x3(M)
        return M

    @matrix3x3.setter
    def matrix3x3(self, M) -> None:
        """Set quaternion from a 3x3 rotation matrix."""
        arr = np.asarray(M, dtype=float)
        if arr.shape != (3, 3):
            raise ValueError("Quaternion.matrix3x3 expects a 3x3 matrix")
        self.T.FromMatrix3x3(arr)

    @property
    def matrix(self) -> np.ndarray:
        """Alias of ``matrix3x3``."""
        return self.matrix3x3

    @matrix.setter
    def matrix(self, M) -> None:
        self.matrix3x3 = M

matrix property writable

Alias of matrix3x3.

matrix3x3 property writable

Get the 3x3 rotation matrix.

norm property

Get the quaternion norm.

squared_norm property

Get the squared quaternion norm.

wxyz property writable

Get the quaternion as (w, x, y, z).

xyzw property writable

Get the quaternion as (x, y, z, w).

angle_axis(rad=False)

Return the quaternion as (angle, axis).

Source code in vedo/core/transformations.py

def angle_axis(self, rad=False) -> tuple[float, np.ndarray]:
    """Return the quaternion as ``(angle, axis)``."""
    axis = np.zeros(3, dtype=float)
    angle = float(self.T.GetRotationAngleAndAxis(axis))
    if not rad:
        angle = np.rad2deg(angle)
    return angle, axis

clone()

Clone the quaternion to make an exact copy.

Source code in vedo/core/transformations.py

def clone(self) -> Quaternion:
    """Clone the quaternion to make an exact copy."""
    return Quaternion(self.T)

conjugate()

Conjugate the quaternion in place.

Source code in vedo/core/transformations.py

def conjugate(self) -> Self:
    """Conjugate the quaternion in place."""
    self.T.Conjugate()
    return self

conjugated()

Return the conjugated quaternion.

Source code in vedo/core/transformations.py

def conjugated(self) -> Quaternion:
    """Return the conjugated quaternion."""
    return Quaternion(self.T.Conjugated())

copy()

Return a copy of the quaternion. Alias of clone().

Source code in vedo/core/transformations.py

def copy(self) -> Quaternion:
    """Return a copy of the quaternion. Alias of ``clone()``."""
    return self.clone()

from_axis_angle(angle, axis=(1, 0, 0), rad=False) classmethod

Build a quaternion from axis-angle form.

Source code in vedo/core/transformations.py

@classmethod
def from_axis_angle(cls, angle, axis=(1, 0, 0), rad=False) -> Quaternion:
    """Build a quaternion from axis-angle form."""
    return cls(axis=axis, angle=angle, rad=rad)

from_xyzw(q) classmethod

Build a quaternion from (x, y, z, w) components.

Source code in vedo/core/transformations.py

@classmethod
def from_xyzw(cls, q) -> Quaternion:
    """Build a quaternion from ``(x, y, z, w)`` components."""
    return cls(q, xyzw=True)

inverse()

Return the inverse quaternion.

Source code in vedo/core/transformations.py

def inverse(self) -> Quaternion:
    """Return the inverse quaternion."""
    return Quaternion(self.T.Inverse())

invert()

Invert the quaternion in place.

Source code in vedo/core/transformations.py

def invert(self) -> Self:
    """Invert the quaternion in place."""
    self.T.Invert()
    return self

normalize()

Normalize the quaternion in place.

Source code in vedo/core/transformations.py

def normalize(self) -> Self:
    """Normalize the quaternion in place."""
    self.T.Normalize()
    return self

normalized()

Return a normalized copy of the quaternion.

Source code in vedo/core/transformations.py

def normalized(self) -> Quaternion:
    """Return a normalized copy of the quaternion."""
    return Quaternion(self.T.Normalized())

print()

Print quaternion details.

Source code in vedo/core/transformations.py

def print(self) -> Quaternion:
    """Print quaternion details."""
    print(self)
    return self

reset()

Reset quaternion to identity.

Source code in vedo/core/transformations.py

def reset(self) -> Self:
    """Reset quaternion to identity."""
    self.T.ToIdentity()
    return self

rotate(p)

Rotate a single 2D or 3D vector.

Source code in vedo/core/transformations.py

def rotate(self, p) -> np.ndarray:
    """Rotate a single 2D or 3D vector."""
    p = np.asarray(p, dtype=float)
    if p.shape == (2,):
        p = np.array([p[0], p[1], 0.0], dtype=float)
    if p.shape != (3,):
        raise ValueError("Quaternion.rotate() expects a 2D or 3D vector")
    return self.matrix3x3 @ p

set(q, xyzw=False)

Set quaternion components.

Source code in vedo/core/transformations.py

def set(self, q, xyzw=False) -> Self:
    """Set quaternion components."""
    arr = np.asarray(q, dtype=float).ravel()
    if arr.shape != (4,):
        raise ValueError("Quaternion.set() expects a 4-sequence")
    if xyzw:
        self.T.Set(arr[3], arr[0], arr[1], arr[2])
    else:
        self.T.Set(arr)
    return self

set_axis_angle(angle, axis=(1, 0, 0), rad=False)

Set quaternion from axis-angle form.

Source code in vedo/core/transformations.py

def set_axis_angle(self, angle, axis=(1, 0, 0), rad=False) -> Self:
    """Set quaternion from axis-angle form."""
    axis = np.asarray(axis, dtype=float)
    axis_norm = np.linalg.norm(axis)
    if axis_norm == 0:
        raise ValueError("Quaternion axis cannot have zero length")
    axis = axis / axis_norm
    if not rad:
        angle = np.deg2rad(angle)
    self.T.SetRotationAngleAndAxis(angle, axis)
    return self

slerp(t, q)

Spherically interpolate towards quaternion q.

Source code in vedo/core/transformations.py

def slerp(self, t: float, q) -> Quaternion:
    """Spherically interpolate towards quaternion ``q``."""
    q0 = self.normalized().wxyz
    q1 = Quaternion(q).normalized().wxyz
    dot = float(np.clip(np.dot(q0, q1), -1.0, 1.0))

    # Flip the second quaternion so we stay on the shortest arc.
    if dot < 0.0:
        q1 = -q1
        dot = -dot

    if dot > 0.9995:
        out = q0 + t * (q1 - q0)
        out /= np.linalg.norm(out)
        return Quaternion(out)

    theta0 = np.arccos(dot)
    theta = theta0 * t
    sin_theta0 = np.sin(theta0)
    out = np.sin(theta0 - theta) / sin_theta0 * q0 + np.sin(theta) / sin_theta0 * q1
    return Quaternion(out)

to_transform()

Convert the quaternion to a LinearTransform.

Source code in vedo/core/transformations.py

def to_transform(self) -> LinearTransform:
    """Convert the quaternion to a ``LinearTransform``."""
    return LinearTransform(self.matrix3x3)

TransformInterpolator

Interpolate between a set of linear transformations.

Position, scale and orientation (i.e., rotations) are interpolated separately, and can be interpolated linearly or with a spline function. Note that orientation is interpolated using quaternions via SLERP (spherical linear interpolation) or the special vtkQuaternionSpline class.

To use this class, add at least two pairs of (t, transformation) with the add() method. Then interpolate the transforms with the TransformInterpolator(t) call method, where "t" must be in the range of (min, max) times specified by the add() method.

Examples:

from vedo import *

T0 = LinearTransform()
T1 = LinearTransform().rotate_x(90).shift([12,0,0])

TRI = TransformInterpolator("linear")
TRI.add(0, T0)
TRI.add(1, T1)

plt = Plotter(axes=1)
for i in range(11):
    t = i/10
    T = TRI(t)
    plt += Cube().color(i).apply_transform(T)
plt.show().close()

Source code in vedo/core/transformations.py

class TransformInterpolator:
    """
    Interpolate between a set of linear transformations.

    Position, scale and orientation (i.e., rotations) are interpolated separately,
    and can be interpolated linearly or with a spline function.
    Note that orientation is interpolated using quaternions via
    SLERP (spherical linear interpolation) or the special `vtkQuaternionSpline` class.

    To use this class, add at least two pairs of (t, transformation) with the add() method.
    Then interpolate the transforms with the `TransformInterpolator(t)` call method,
    where "t" must be in the range of `(min, max)` times specified by the add() method.

    Examples:
        ```python
        from vedo import *

        T0 = LinearTransform()
        T1 = LinearTransform().rotate_x(90).shift([12,0,0])

        TRI = TransformInterpolator("linear")
        TRI.add(0, T0)
        TRI.add(1, T1)

        plt = Plotter(axes=1)
        for i in range(11):
            t = i/10
            T = TRI(t)
            plt += Cube().color(i).apply_transform(T)
        plt.show().close()
        ```
        ![](https://vedo.embl.es/images/extras/transf_interp.png)
    """

    def __init__(self, mode="linear") -> None:
        """
        Interpolate between two or more linear transformations.
        """
        self.vtk_interpolator = vtki.new("TransformInterpolator")
        self.mode(mode)
        self.TS: list[LinearTransform] = []

    def _mode_name(self) -> str:
        mapping = {
            0: "linear",
            1: "spline",
            2: "manual",
        }
        return mapping.get(self.vtk_interpolator.GetInterpolationType(), "unknown")

    def _summary_rows(self):
        rows = [
            ("mode", self._mode_name()),
            ("ntransforms", str(self.ntransforms)),
        ]
        if self.ntransforms:
            tmin, tmax = self.trange()
            rows.append(("trange", f"[{tmin}, {tmax}]"))
        else:
            rows.append(("trange", "[]"))
        return rows

    def __str__(self):
        return summary_string(self, self._summary_rows())

    def __repr__(self):
        return self.__str__()

    def __rich__(self):
        return summary_panel(self, self._summary_rows())

    def print(self) -> TransformInterpolator:
        """Print interpolator details."""
        print(self)
        return self

    def __call__(self, t):
        """
        Get the intermediate transformation at time `t`.
        """
        xform = vtki.vtkTransform()
        self.vtk_interpolator.InterpolateTransform(t, xform)
        return LinearTransform(xform)

    def add(self, t, T) -> TransformInterpolator:
        """Add intermediate transformations."""
        try:
            # in case a vedo object is passed
            T = T.transform
        except AttributeError:
            pass
        if isinstance(T, LinearTransform):
            LT = T
        elif isinstance(T, vtki.vtkLinearTransform):
            LT = LinearTransform(T)
        else:
            raise TypeError(
                "TransformInterpolator.add() expects LinearTransform or vtkLinearTransform"
            )

        self.TS.append(LT)
        self.vtk_interpolator.AddTransform(t, LT.T)
        return self

    # def remove(self, t) -> TransformInterpolator:
    #     """Remove intermediate transformations."""
    #     self.TS.pop(t)
    #     self.vtk_interpolator.RemoveTransform(t)
    #     return self

    def trange(self) -> np.ndarray:
        """Get interpolation range."""
        tmin = self.vtk_interpolator.GetMinimumT()
        tmax = self.vtk_interpolator.GetMaximumT()
        return np.array([tmin, tmax])

    def clear(self) -> TransformInterpolator:
        """Clear all intermediate transformations."""
        self.TS = []
        self.vtk_interpolator.Initialize()
        return self

    def mode(self, m) -> TransformInterpolator:
        """Set interpolation mode ('linear' or 'spline')."""
        if m == "linear":
            self.vtk_interpolator.SetInterpolationTypeToLinear()
        elif m == "spline":
            self.vtk_interpolator.SetInterpolationTypeToSpline()
        else:
            warn(
                'In TransformInterpolator mode can be either "linear" or "spline"',
                stacklevel=2,
            )
        return self

    @property
    def ntransforms(self) -> int:
        """Get number of transformations."""
        return self.vtk_interpolator.GetNumberOfTransforms()

ntransforms property

Get number of transformations.

add(t, T)

Add intermediate transformations.

Source code in vedo/core/transformations.py

def add(self, t, T) -> TransformInterpolator:
    """Add intermediate transformations."""
    try:
        # in case a vedo object is passed
        T = T.transform
    except AttributeError:
        pass
    if isinstance(T, LinearTransform):
        LT = T
    elif isinstance(T, vtki.vtkLinearTransform):
        LT = LinearTransform(T)
    else:
        raise TypeError(
            "TransformInterpolator.add() expects LinearTransform or vtkLinearTransform"
        )

    self.TS.append(LT)
    self.vtk_interpolator.AddTransform(t, LT.T)
    return self

clear()

Clear all intermediate transformations.

Source code in vedo/core/transformations.py

def clear(self) -> TransformInterpolator:
    """Clear all intermediate transformations."""
    self.TS = []
    self.vtk_interpolator.Initialize()
    return self

mode(m)

Set interpolation mode ('linear' or 'spline').

Source code in vedo/core/transformations.py

def mode(self, m) -> TransformInterpolator:
    """Set interpolation mode ('linear' or 'spline')."""
    if m == "linear":
        self.vtk_interpolator.SetInterpolationTypeToLinear()
    elif m == "spline":
        self.vtk_interpolator.SetInterpolationTypeToSpline()
    else:
        warn(
            'In TransformInterpolator mode can be either "linear" or "spline"',
            stacklevel=2,
        )
    return self

print()

Print interpolator details.

Source code in vedo/core/transformations.py

def print(self) -> TransformInterpolator:
    """Print interpolator details."""
    print(self)
    return self

trange()

Get interpolation range.

Source code in vedo/core/transformations.py

def trange(self) -> np.ndarray:
    """Get interpolation range."""
    tmin = self.vtk_interpolator.GetMinimumT()
    tmax = self.vtk_interpolator.GetMaximumT()
    return np.array([tmin, tmax])

cart2cyl(x, y, z)

3D Cartesian to Cylindrical coordinate conversion.

Source code in vedo/core/transformations.py

def cart2cyl(x, y, z) -> np.ndarray:
    """3D Cartesian to Cylindrical coordinate conversion."""
    rho = np.hypot(x, y)
    theta = np.arctan2(y, x)
    return np.array([rho, theta, z])

cart2pol(x, y)

2D Cartesian to Polar coordinates conversion.

Source code in vedo/core/transformations.py

def cart2pol(x, y) -> np.ndarray:
    """2D Cartesian to Polar coordinates conversion."""
    theta = np.arctan2(y, x)
    rho = np.hypot(x, y)
    return np.array([rho, theta])

cart2spher(x, y, z)

3D Cartesian to Spherical coordinate conversion.

Source code in vedo/core/transformations.py

def cart2spher(x, y, z) -> np.ndarray:
    """3D Cartesian to Spherical coordinate conversion."""
    hxy = np.hypot(x, y)
    rho = np.hypot(hxy, z)
    theta = np.arctan2(hxy, z)
    phi = np.arctan2(y, x)
    return np.array([rho, theta, phi])

cyl2cart(rho, theta, z)

3D Cylindrical to Cartesian coordinate conversion.

Source code in vedo/core/transformations.py

def cyl2cart(rho, theta, z) -> np.ndarray:
    """3D Cylindrical to Cartesian coordinate conversion."""
    x = rho * np.cos(theta)
    y = rho * np.sin(theta)
    return np.array([x, y, z])

cyl2spher(rho, theta, z)

3D Cylindrical to Spherical coordinate conversion.

Source code in vedo/core/transformations.py

def cyl2spher(rho, theta, z) -> np.ndarray:
    """3D Cylindrical to Spherical coordinate conversion."""
    rhos = np.sqrt(rho * rho + z * z)
    phi = np.arctan2(rho, z)
    return np.array([rhos, phi, theta])

pol2cart(rho, theta)

2D Polar to Cartesian coordinates conversion.

Source code in vedo/core/transformations.py

def pol2cart(rho, theta) -> np.ndarray:
    """2D Polar to Cartesian coordinates conversion."""
    x = rho * np.cos(theta)
    y = rho * np.sin(theta)
    return np.array([x, y])

spher2cart(rho, theta, phi)

3D Spherical to Cartesian coordinate conversion.

Source code in vedo/core/transformations.py

def spher2cart(rho, theta, phi) -> np.ndarray:
    """3D Spherical to Cartesian coordinate conversion."""
    st = np.sin(theta)
    sp = np.sin(phi)
    ct = np.cos(theta)
    cp = np.cos(phi)
    rst = rho * st
    x = rst * cp
    y = rst * sp
    z = rho * ct
    return np.array([x, y, z])

spher2cyl(rho, theta, phi)

3D Spherical to Cylindrical coordinate conversion.

Source code in vedo/core/transformations.py

def spher2cyl(rho, theta, phi) -> np.ndarray:
    """3D Spherical to Cylindrical coordinate conversion."""
    rhoc = rho * np.sin(theta)
    z = rho * np.cos(theta)
    return np.array([rhoc, phi, z])

volume

VolumeAlgorithms

Bases: CommonAlgorithms

Methods for Volume objects.

Source code in vedo/core/volume.py

class VolumeAlgorithms(CommonAlgorithms):
    """Methods for Volume objects."""

    def bounds(self) -> np.ndarray:
        """
        Get the object bounds.
        Returns a list in format `[xmin,xmax, ymin,ymax, zmin,zmax]`.
        """
        # OVERRIDE CommonAlgorithms.bounds() which is too slow
        return np.array(self.dataset.GetBounds())

    def isosurface(self, value=None, flying_edges=False) -> vedo.mesh.Mesh:
        """
        Return a `Mesh` isosurface extracted from the `Volume` object.

        Set `value` as single float or list of values to draw the isosurface(s).
        Use flying_edges for faster results (but sometimes can interfere with `smooth()`).

        The isosurface values can be accessed with `mesh.metadata["isovalue"]`.

        Examples:
            - [isosurfaces1.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/isosurfaces1.py)

                ![](https://vedo.embl.es/images/volumetric/isosurfaces.png)
        """
        scrange = self.dataset.GetScalarRange()

        if flying_edges:
            cf = vtki.new("FlyingEdges3D")
            cf.InterpolateAttributesOn()
        else:
            cf = vtki.new("ContourFilter")
            cf.UseScalarTreeOn()

        cf.SetInputData(self.dataset)
        cf.ComputeNormalsOn()

        if utils.is_sequence(value):
            cf.SetNumberOfContours(len(value))
            for i, t in enumerate(value):
                cf.SetValue(i, t)
        else:
            if value is None:
                value = (2 * scrange[0] + scrange[1]) / 3.0
                # print("automatic isosurface value =", value)
            cf.SetValue(0, value)

        cf.Update()
        poly = cf.GetOutput()

        out = vedo.mesh.Mesh(poly, c=None).phong()
        out.mapper.SetScalarRange(scrange[0], scrange[1])
        out.metadata["isovalue"] = value

        out.pipeline = utils.OperationNode(
            "isosurface",
            parents=[self],
            comment=f"#pts {out.dataset.GetNumberOfPoints()}",
            c="#4cc9f0:#e9c46a",
        )
        return out

    def isosurface_discrete(
        self,
        values,
        background_label=None,
        internal_boundaries=True,
        use_quads=False,
        nsmooth=0,
    ) -> vedo.mesh.Mesh:
        """
        Create boundary/isocontour surfaces from a label map (e.g., a segmented image) using a threaded,
        3D version of the multiple objects/labels Surface Nets algorithm.
        The input is a 3D image (i.e., volume) where each voxel is labeled
        (integer labels are preferred to real values), and the output data is a polygonal mesh separating
        labeled regions / objects.
        (Note that on output each region [corresponding to a different segmented object] will share
        points/edges on a common boundary, i.e., two neighboring objects will share the boundary that separates them).

        Besides output geometry defining the surface net, the filter outputs a two-component celldata array indicating
        the labels on either side of the polygons composing the output Mesh.
        (This can be used for advanced operations like extracting shared/contacting boundaries between two objects.
        The name of this celldata array is "BoundaryLabels").

        The values can be accessed with `mesh.metadata["isovalue"]`.

        Args:
            values (float, list):
                single value or list of values to draw the isosurface(s).
            background_label (float):
                this value specifies the label value to use when referencing the background
                region outside of any of the specified regions.
            internal_boundaries (bool, list):
                if True, the output will only contain the boundary surface. Internal surfaces will be removed.
                If a list of integers is provided, only the boundaries between the specified labels will be extracted.
            use_quads (bool):
                if True, the output polygons will be quads. If False, the output polygons will be triangles.
            nsmooth (int):
                number of iterations of smoothing (0 means no smoothing).

        Examples:
            - [isosurfaces2.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/isosurfaces2.py)
        """
        logger = vtki.get_class("Logger")
        logger.SetStderrVerbosity(logger.VERBOSITY_ERROR)

        snets = vtki.new("SurfaceNets3D")
        snets.SetInputData(self.dataset)

        if nsmooth:
            snets.SmoothingOn()
            snets.AutomaticSmoothingConstraintsOn()
            snets.GetSmoother().SetNumberOfIterations(nsmooth)
            # snets.GetSmoother().SetRelaxationFactor(relaxation_factor)
            # snets.GetSmoother().SetConstraintDistance(constraint_distance)
        else:
            snets.SmoothingOff()

        if internal_boundaries is False:
            snets.SetOutputStyleToBoundary()
        elif internal_boundaries is True:
            snets.SetOutputStyleToDefault()
        elif utils.is_sequence(internal_boundaries):
            snets.SetOutputStyleToSelected()
            snets.InitializeSelectedLabelsList()
            for val in internal_boundaries:
                snets.AddSelectedLabel(val)
        else:
            vedo.logger.error("isosurface_discrete(): unknown boundaries option")

        n = len(values)
        snets.SetNumberOfContours(n)

        if background_label is not None:
            snets.SetBackgroundLabel(background_label)

        for i, val in enumerate(values):
            snets.SetValue(i, val)

        if use_quads:
            snets.SetOutputMeshTypeToQuads()
        else:
            snets.SetOutputMeshTypeToTriangles()
        snets.Update()

        out = vedo.mesh.Mesh(snets.GetOutput())
        out.metadata["isovalue"] = values
        out.pipeline = utils.OperationNode(
            "isosurface_discrete",
            parents=[self],
            comment=f"#pts {out.dataset.GetNumberOfPoints()}",
            c="#4cc9f0:#e9c46a",
        )

        logger.SetStderrVerbosity(logger.VERBOSITY_INFO)
        return out

    def legosurface(
        self,
        vmin=None,
        vmax=None,
        invert=False,
        boundary=True,
        array_name=None,
    ) -> vedo.mesh.Mesh:
        """
        Represent an object - typically a `Volume` - as lego blocks (voxels).
        By default colors correspond to the volume's scalar.
        Returns an `Mesh` object.

        Args:
            vmin (float):
                the lower threshold, voxels below this value are not shown.
            vmax (float):
                the upper threshold, voxels above this value are not shown.
            boundary (bool):
                controls whether to include cells that are partially inside
            array_name (int, str):
                name or index of the scalar array to be considered

        Examples:
            - [legosurface.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/legosurface.py)

                ![](https://vedo.embl.es/images/volumetric/56820682-da40e500-684c-11e9-8ea3-91cbcba24b3a.png)
        """
        if array_name is None:
            pt_scalars = self.dataset.GetPointData().GetScalars()
            array_name = pt_scalars.GetName() if pt_scalars is not None else "input_scalars"

        imp_dataset = vtki.new("ImplicitDataSet")
        imp_dataset.SetDataSet(self.dataset)
        window = vtki.new("ImplicitWindowFunction")
        window.SetImplicitFunction(imp_dataset)

        srng = list(self.dataset.GetScalarRange())
        if vmin is not None:
            srng[0] = vmin
        if vmax is not None:
            srng[1] = vmax
        if not boundary:
            tol = 0.00001 * (srng[1] - srng[0])
            srng[0] -= tol
            srng[1] += tol
        window.SetWindowRange(srng)
        # print("legosurface window range:", srng)

        extract = vtki.new("ExtractGeometry")
        extract.SetInputData(self.dataset)
        extract.SetImplicitFunction(window)
        extract.SetExtractInside(invert)
        extract.SetExtractBoundaryCells(boundary)
        extract.Update()

        gf = vtki.new("GeometryFilter")
        gf.SetInputData(extract.GetOutput())
        gf.Update()

        m = vedo.mesh.Mesh(gf.GetOutput()).lw(0.1).flat()
        m.map_points_to_cells()
        m.celldata.select(array_name)

        m.pipeline = utils.OperationNode(
            "legosurface",
            parents=[self],
            comment=f"array: {array_name}",
            c="#4cc9f0:#e9c46a",
        )
        return m

    def tomesh(self, fill=True, shrink=1.0) -> vedo.mesh.Mesh:
        """
        Build a polygonal Mesh from the current object.

        If `fill=True`, the interior faces of all the cells are created.
        (setting a `shrink` value slightly smaller than the default 1.0
        can avoid flickering due to internal adjacent faces).

        If `fill=False`, only the boundary faces will be generated.
        """
        gf = vtki.new("GeometryFilter")
        if fill:
            sf = vtki.new("ShrinkFilter")
            sf.SetInputData(self.dataset)
            sf.SetShrinkFactor(shrink)
            sf.Update()
            gf.SetInputData(sf.GetOutput())
            gf.Update()
            poly = gf.GetOutput()
            if shrink == 1.0:
                clean_poly = vtki.new("CleanPolyData")
                clean_poly.PointMergingOn()
                clean_poly.ConvertLinesToPointsOn()
                clean_poly.ConvertPolysToLinesOn()
                clean_poly.ConvertStripsToPolysOn()
                clean_poly.SetInputData(poly)
                clean_poly.Update()
                poly = clean_poly.GetOutput()
        else:
            gf.SetInputData(self.dataset)
            gf.Update()
            poly = gf.GetOutput()

        msh = vedo.mesh.Mesh(poly).flat()
        msh.scalarbar = self.scalarbar
        lut = utils.ctf2lut(self)
        if lut:
            msh.mapper.SetLookupTable(lut)

        msh.pipeline = utils.OperationNode(
            "tomesh", parents=[self], comment=f"fill={fill}", c="#9e2a2b:#e9c46a"
        )
        return msh

bounds()

Get the object bounds. Returns a list in format [xmin,xmax, ymin,ymax, zmin,zmax].

Source code in vedo/core/volume.py

def bounds(self) -> np.ndarray:
    """
    Get the object bounds.
    Returns a list in format `[xmin,xmax, ymin,ymax, zmin,zmax]`.
    """
    # OVERRIDE CommonAlgorithms.bounds() which is too slow
    return np.array(self.dataset.GetBounds())

isosurface(value=None, flying_edges=False)

Return a Mesh isosurface extracted from the Volume object.

Set value as single float or list of values to draw the isosurface(s). Use flying_edges for faster results (but sometimes can interfere with smooth()).

The isosurface values can be accessed with mesh.metadata["isovalue"].

Examples:

• isosurfaces1.py

  

Source code in vedo/core/volume.py

def isosurface(self, value=None, flying_edges=False) -> vedo.mesh.Mesh:
    """
    Return a `Mesh` isosurface extracted from the `Volume` object.

    Set `value` as single float or list of values to draw the isosurface(s).
    Use flying_edges for faster results (but sometimes can interfere with `smooth()`).

    The isosurface values can be accessed with `mesh.metadata["isovalue"]`.

    Examples:
        - [isosurfaces1.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/isosurfaces1.py)

            ![](https://vedo.embl.es/images/volumetric/isosurfaces.png)
    """
    scrange = self.dataset.GetScalarRange()

    if flying_edges:
        cf = vtki.new("FlyingEdges3D")
        cf.InterpolateAttributesOn()
    else:
        cf = vtki.new("ContourFilter")
        cf.UseScalarTreeOn()

    cf.SetInputData(self.dataset)
    cf.ComputeNormalsOn()

    if utils.is_sequence(value):
        cf.SetNumberOfContours(len(value))
        for i, t in enumerate(value):
            cf.SetValue(i, t)
    else:
        if value is None:
            value = (2 * scrange[0] + scrange[1]) / 3.0
            # print("automatic isosurface value =", value)
        cf.SetValue(0, value)

    cf.Update()
    poly = cf.GetOutput()

    out = vedo.mesh.Mesh(poly, c=None).phong()
    out.mapper.SetScalarRange(scrange[0], scrange[1])
    out.metadata["isovalue"] = value

    out.pipeline = utils.OperationNode(
        "isosurface",
        parents=[self],
        comment=f"#pts {out.dataset.GetNumberOfPoints()}",
        c="#4cc9f0:#e9c46a",
    )
    return out

isosurface_discrete(values, background_label=None, internal_boundaries=True, use_quads=False, nsmooth=0)

Create boundary/isocontour surfaces from a label map (e.g., a segmented image) using a threaded, 3D version of the multiple objects/labels Surface Nets algorithm. The input is a 3D image (i.e., volume) where each voxel is labeled (integer labels are preferred to real values), and the output data is a polygonal mesh separating labeled regions / objects. (Note that on output each region [corresponding to a different segmented object] will share points/edges on a common boundary, i.e., two neighboring objects will share the boundary that separates them).

Besides output geometry defining the surface net, the filter outputs a two-component celldata array indicating the labels on either side of the polygons composing the output Mesh. (This can be used for advanced operations like extracting shared/contacting boundaries between two objects. The name of this celldata array is "BoundaryLabels").

The values can be accessed with mesh.metadata["isovalue"].

Parameters:

Name	Type	Description	Default
values	(float, list)	single value or list of values to draw the isosurface(s).	required
background_label	float	this value specifies the label value to use when referencing the background region outside of any of the specified regions.	None
internal_boundaries	(bool, list)	if True, the output will only contain the boundary surface. Internal surfaces will be removed. If a list of integers is provided, only the boundaries between the specified labels will be extracted.	True
use_quads	bool	if True, the output polygons will be quads. If False, the output polygons will be triangles.	False
nsmooth	int	number of iterations of smoothing (0 means no smoothing).	0

Examples:

• isosurfaces2.py

Source code in vedo/core/volume.py

def isosurface_discrete(
    self,
    values,
    background_label=None,
    internal_boundaries=True,
    use_quads=False,
    nsmooth=0,
) -> vedo.mesh.Mesh:
    """
    Create boundary/isocontour surfaces from a label map (e.g., a segmented image) using a threaded,
    3D version of the multiple objects/labels Surface Nets algorithm.
    The input is a 3D image (i.e., volume) where each voxel is labeled
    (integer labels are preferred to real values), and the output data is a polygonal mesh separating
    labeled regions / objects.
    (Note that on output each region [corresponding to a different segmented object] will share
    points/edges on a common boundary, i.e., two neighboring objects will share the boundary that separates them).

    Besides output geometry defining the surface net, the filter outputs a two-component celldata array indicating
    the labels on either side of the polygons composing the output Mesh.
    (This can be used for advanced operations like extracting shared/contacting boundaries between two objects.
    The name of this celldata array is "BoundaryLabels").

    The values can be accessed with `mesh.metadata["isovalue"]`.

    Args:
        values (float, list):
            single value or list of values to draw the isosurface(s).
        background_label (float):
            this value specifies the label value to use when referencing the background
            region outside of any of the specified regions.
        internal_boundaries (bool, list):
            if True, the output will only contain the boundary surface. Internal surfaces will be removed.
            If a list of integers is provided, only the boundaries between the specified labels will be extracted.
        use_quads (bool):
            if True, the output polygons will be quads. If False, the output polygons will be triangles.
        nsmooth (int):
            number of iterations of smoothing (0 means no smoothing).

    Examples:
        - [isosurfaces2.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/isosurfaces2.py)
    """
    logger = vtki.get_class("Logger")
    logger.SetStderrVerbosity(logger.VERBOSITY_ERROR)

    snets = vtki.new("SurfaceNets3D")
    snets.SetInputData(self.dataset)

    if nsmooth:
        snets.SmoothingOn()
        snets.AutomaticSmoothingConstraintsOn()
        snets.GetSmoother().SetNumberOfIterations(nsmooth)
        # snets.GetSmoother().SetRelaxationFactor(relaxation_factor)
        # snets.GetSmoother().SetConstraintDistance(constraint_distance)
    else:
        snets.SmoothingOff()

    if internal_boundaries is False:
        snets.SetOutputStyleToBoundary()
    elif internal_boundaries is True:
        snets.SetOutputStyleToDefault()
    elif utils.is_sequence(internal_boundaries):
        snets.SetOutputStyleToSelected()
        snets.InitializeSelectedLabelsList()
        for val in internal_boundaries:
            snets.AddSelectedLabel(val)
    else:
        vedo.logger.error("isosurface_discrete(): unknown boundaries option")

    n = len(values)
    snets.SetNumberOfContours(n)

    if background_label is not None:
        snets.SetBackgroundLabel(background_label)

    for i, val in enumerate(values):
        snets.SetValue(i, val)

    if use_quads:
        snets.SetOutputMeshTypeToQuads()
    else:
        snets.SetOutputMeshTypeToTriangles()
    snets.Update()

    out = vedo.mesh.Mesh(snets.GetOutput())
    out.metadata["isovalue"] = values
    out.pipeline = utils.OperationNode(
        "isosurface_discrete",
        parents=[self],
        comment=f"#pts {out.dataset.GetNumberOfPoints()}",
        c="#4cc9f0:#e9c46a",
    )

    logger.SetStderrVerbosity(logger.VERBOSITY_INFO)
    return out

legosurface(vmin=None, vmax=None, invert=False, boundary=True, array_name=None)

Represent an object - typically a Volume - as lego blocks (voxels). By default colors correspond to the volume's scalar. Returns an Mesh object.

Parameters:

Name	Type	Description	Default
vmin	float	the lower threshold, voxels below this value are not shown.	None
vmax	float	the upper threshold, voxels above this value are not shown.	None
boundary	bool	controls whether to include cells that are partially inside	True
array_name	(int, str)	name or index of the scalar array to be considered	None

Examples:

• legosurface.py

  

Source code in vedo/core/volume.py

def legosurface(
    self,
    vmin=None,
    vmax=None,
    invert=False,
    boundary=True,
    array_name=None,
) -> vedo.mesh.Mesh:
    """
    Represent an object - typically a `Volume` - as lego blocks (voxels).
    By default colors correspond to the volume's scalar.
    Returns an `Mesh` object.

    Args:
        vmin (float):
            the lower threshold, voxels below this value are not shown.
        vmax (float):
            the upper threshold, voxels above this value are not shown.
        boundary (bool):
            controls whether to include cells that are partially inside
        array_name (int, str):
            name or index of the scalar array to be considered

    Examples:
        - [legosurface.py](https://github.com/marcomusy/vedo/tree/master/examples/volumetric/legosurface.py)

            ![](https://vedo.embl.es/images/volumetric/56820682-da40e500-684c-11e9-8ea3-91cbcba24b3a.png)
    """
    if array_name is None:
        pt_scalars = self.dataset.GetPointData().GetScalars()
        array_name = pt_scalars.GetName() if pt_scalars is not None else "input_scalars"

    imp_dataset = vtki.new("ImplicitDataSet")
    imp_dataset.SetDataSet(self.dataset)
    window = vtki.new("ImplicitWindowFunction")
    window.SetImplicitFunction(imp_dataset)

    srng = list(self.dataset.GetScalarRange())
    if vmin is not None:
        srng[0] = vmin
    if vmax is not None:
        srng[1] = vmax
    if not boundary:
        tol = 0.00001 * (srng[1] - srng[0])
        srng[0] -= tol
        srng[1] += tol
    window.SetWindowRange(srng)
    # print("legosurface window range:", srng)

    extract = vtki.new("ExtractGeometry")
    extract.SetInputData(self.dataset)
    extract.SetImplicitFunction(window)
    extract.SetExtractInside(invert)
    extract.SetExtractBoundaryCells(boundary)
    extract.Update()

    gf = vtki.new("GeometryFilter")
    gf.SetInputData(extract.GetOutput())
    gf.Update()

    m = vedo.mesh.Mesh(gf.GetOutput()).lw(0.1).flat()
    m.map_points_to_cells()
    m.celldata.select(array_name)

    m.pipeline = utils.OperationNode(
        "legosurface",
        parents=[self],
        comment=f"array: {array_name}",
        c="#4cc9f0:#e9c46a",
    )
    return m

tomesh(fill=True, shrink=1.0)

Build a polygonal Mesh from the current object.

If fill=True, the interior faces of all the cells are created. (setting a shrink value slightly smaller than the default 1.0 can avoid flickering due to internal adjacent faces).

If fill=False, only the boundary faces will be generated.

Source code in vedo/core/volume.py

def tomesh(self, fill=True, shrink=1.0) -> vedo.mesh.Mesh:
    """
    Build a polygonal Mesh from the current object.

    If `fill=True`, the interior faces of all the cells are created.
    (setting a `shrink` value slightly smaller than the default 1.0
    can avoid flickering due to internal adjacent faces).

    If `fill=False`, only the boundary faces will be generated.
    """
    gf = vtki.new("GeometryFilter")
    if fill:
        sf = vtki.new("ShrinkFilter")
        sf.SetInputData(self.dataset)
        sf.SetShrinkFactor(shrink)
        sf.Update()
        gf.SetInputData(sf.GetOutput())
        gf.Update()
        poly = gf.GetOutput()
        if shrink == 1.0:
            clean_poly = vtki.new("CleanPolyData")
            clean_poly.PointMergingOn()
            clean_poly.ConvertLinesToPointsOn()
            clean_poly.ConvertPolysToLinesOn()
            clean_poly.ConvertStripsToPolysOn()
            clean_poly.SetInputData(poly)
            clean_poly.Update()
            poly = clean_poly.GetOutput()
    else:
        gf.SetInputData(self.dataset)
        gf.Update()
        poly = gf.GetOutput()

    msh = vedo.mesh.Mesh(poly).flat()
    msh.scalarbar = self.scalarbar
    lut = utils.ctf2lut(self)
    if lut:
        msh.mapper.SetLookupTable(lut)

    msh.pipeline = utils.OperationNode(
        "tomesh", parents=[self], comment=f"fill={fill}", c="#9e2a2b:#e9c46a"
    )
    return msh