primlib 0.3.0__py3-none-any.whl

primlib/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("primlib")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

primlib/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

primlib/line_set.py

@@ -0,0 +1,435 @@
+import copy
+import logging
+from typing import Self, override
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from primlib.triangle_mesh import TriangleMesh
+from primlib.utils import scalar_to_bicolor, scalar_to_color
+from primlib.vertices import Vertices
+
+
+class LineSet(Vertices):
+    __slots__ = ("_line_colors", "_lines")
+
+    def __init__(
+        self,
+        vertices: ArrayLike | None = None,
+        lines: ArrayLike | None = None,
+        vertex_colors: ArrayLike | None = None,
+        line_colors: ArrayLike | None = None,
+    ):
+        """Constructor
+
+        :param vertices: Vertices of the line set, shape (n, 3)
+        :param lines: Lines of the line set as vertex indices,
+            shape (m, 2), integer type
+        :param vertex_colors: RGB colors for each vertex, shape (n, 3),
+            values [0.0..1.0]
+        :param line_colors: RGB colors for each line, shape (m, 3),
+            values [0.0..1.0]
+        """
+        super().__init__(vertices=vertices, colors=vertex_colors)
+        # Define types and initialize
+        self._lines: np.ndarray = np.zeros((0, 2), dtype=int)
+        self._line_colors: np.ndarray = np.zeros((0, 3))
+        # Initialize using parameters and setters
+        self.lines = lines
+        self.line_colors = line_colors
+
+    @property
+    def num_vertices(self) -> int:
+        """Number of vertices of the line set
+        :returns: Number of vertices
+        """
+        return self._vertices.shape[0]
+
+    @property
+    def num_lines(self) -> int:
+        """Number of faces of the line set
+        :returns: Number of lines
+        """
+        return self._lines.shape[0]
+
+    @property
+    def empty(self) -> bool:
+        """Check if line set is empty
+        :returns: True if line set has no vertices and no lines
+        """
+        return self.num_vertices == 0 and self.num_lines == 0
+
+    def __str__(self) -> str:
+        """Get string representation of line set
+        :returns: String representation
+        """
+        if self.empty:
+            return "LineSet(empty)"
+        pmin = self.min()
+        pmax = self.max()
+        result = (
+            f"LineSet({self.num_vertices:_} vertices: "
+            + f"X[{pmin[0]:.3f}..{pmax[0]:.3f}], "
+            + f"Y[{pmin[1]:.3f}..{pmax[1]:.3f}], "
+            + f"Z[{pmin[2]:.3f}..{pmax[2]:.3f}]"
+        )
+        if self.has_colors:
+            result += ", vertex_colors"
+        result += f", {self.num_lines:_} lines"
+        if self.has_line_colors:
+            result += ", line_colors"
+        result += ")"
+        return result
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        """Check two line sets for equality.
+
+        :param other: Other object
+        :returns: True if line sets are equal
+        """
+        if not isinstance(other, LineSet):
+            return NotImplemented
+        return (
+            super().__eq__(other)
+            # Lines
+            and self._lines.shape == other._lines.shape
+            and np.array_equal(self._lines, other._lines)
+            # Line colors
+            and self._line_colors.shape == other._line_colors.shape
+            and np.allclose(
+                self._line_colors,
+                other._line_colors,
+                atol=1.0 / 255.0,
+            )
+        )
+
+    @override
+    def __ne__(self, other: object) -> bool:
+        """Check two line sets for inequality
+
+        :param other: Other object
+        :returns: True, if line sets are not equal
+        """
+        return not self.__eq__(other)
+
+    @override
+    def __iadd__(self, other: Vertices) -> Self:
+        """Concatenate another line set in-place
+
+        :param other: Other line set
+        :returns: This line set (self)
+        """
+        if not isinstance(other, LineSet):
+            raise TypeError("Can only append another LineSet")
+        if self.has_line_colors != other.has_line_colors:
+            raise ValueError("Both line sets must have the same properties")
+        # Append vertices and vertex properties
+        vertex_offset = self.num_vertices
+        super().__iadd__(other)
+        # Append lines, adjusting vertex indices
+        self._lines = np.vstack((self._lines, other._lines + vertex_offset))
+        # Append line colors
+        if self.has_line_colors:
+            self._line_colors = np.vstack((self._line_colors, other._line_colors))
+        return self
+
+    @override
+    def __add__(self, other: Vertices) -> "LineSet":
+        """Concatenate two line sets
+
+        :param other: Other line set
+        :returns: New line set
+        """
+        result = self.copy()
+        result += other
+        return result
+
+    def copy(self) -> Self:
+        """Get copy of line set
+
+        :returns: Copy
+        """
+        return copy.deepcopy(self)
+
+    @property
+    def lines(self) -> np.ndarray:
+        """Get lines
+
+        Lines are 2-tuples of indices of type integer referencing vertices;
+        for example: the line (3, 7) is a line connecting vertices 3 and 7.
+
+        :returns: Lines, shape (n, 2), type int
+        """
+        return self._lines
+
+    @lines.setter
+    def lines(self, value: ArrayLike | None) -> None:
+        """Set lines
+
+        Lines are 2-tuples of indices of type integer referencing vertices;
+        for example: the line (3, 7) is a line connecting vertices 3 and 7.
+
+        If there are line colors defined in the line set,
+        then the number of lines has to match their number.
+
+        :param value: Lines, shape (n, 2), type int
+        """
+        if value is None:
+            value = np.zeros((0, 2), dtype=int)
+        else:
+            value = np.asarray(value, dtype=int)
+        if value.ndim != 2 or value.shape[1] != 2:
+            raise Exception("Provide lines of shape (n, 2)")
+        if self.has_line_colors and value.shape[0] != self._line_colors.shape[0]:
+            raise Exception(
+                "Line set already has line colors, provide proper amount of lines"
+            )
+        unique_indices = np.unique(value)
+        if unique_indices.size > 0 and (
+            unique_indices[0] < 0 or unique_indices[-1] >= self.num_vertices
+        ):
+            logging.warning("Some lines reference invalid vertices.")
+        if unique_indices.size != self.num_vertices:
+            logging.warning("Some vertices are not referenced by lines.")
+        self._lines = value
+
+    @property
+    def line_colors(self) -> np.ndarray:
+        """Get line colors
+
+        RGB values in range [0..1].
+
+        :returns: Line colors, shape (n, 3)
+        """
+        return self._line_colors
+
+    @line_colors.setter
+    def line_colors(self, value: ArrayLike | None) -> None:
+        """Set line colors
+
+        If there are lines defined in the line set, then the number
+        of line colors has to match the number of lines.
+
+        Line colors are RGB values in range [0..1]. If values outside that
+        range are provided, values will be clipped and a warnig is given.
+
+        :param value: Line colors, shape (n, 3)
+        """
+        if value is None:
+            line_colors = np.zeros((0, 3))
+        else:
+            line_colors = np.asarray(value, dtype=float)
+        if line_colors.ndim != 2 or line_colors.shape[1] != 3:
+            raise ValueError("Provide line colors of shape (n, 3)")
+        if line_colors.shape[0] > 0 and line_colors.shape[0] != self.num_lines:
+            raise ValueError("Provide as many line colors as lines")
+        if not np.all(np.logical_and(line_colors >= 0.0, line_colors <= 1.0)):
+            logging.warning("Some colors are out of bounds. Clipping to [0,1] ...")
+            line_colors = np.clip(line_colors, 0.0, 1.0)
+        self._line_colors = line_colors
+
+    @property
+    def has_line_colors(self) -> bool:
+        """Check if line set has line colors
+
+        :returns: True, if line set has line colors
+        """
+        return self._line_colors.shape[0] > 0
+
+    def colorize_lines_by_scalar(
+        self,
+        scalars: ArrayLike,
+        cmap: str = "viridis",
+        min_max: tuple[float, float] | None = None,
+        nan_color: tuple[float, float, float] = (1, 0, 0),
+    ) -> None:
+        """Colorizes line set lines by scalar
+
+        :param scalars: Scalar values, length has to match number of lines
+        :param cmap: Matplotlib color map string
+        :param min_max: Minimum and maximum
+        :param nan_color: Color for NaN values, RGB values [0..1]
+        """
+        scalars = np.asarray(scalars)
+        if scalars.ndim != 1 or scalars.size != self.num_lines:
+            raise Exception("Provide correct number of values to colorize lines")
+        self._line_colors = scalar_to_color(scalars, cmap, min_max, nan_color)
+
+    def colorize_lines_by_scalar_bicolor(
+        self,
+        scalars: ArrayLike,
+        cmaps: tuple[str, str] = ("Blues", "Reds"),
+        vmax: float | None = None,
+        nan_color: tuple[float, float, float] = (0, 1, 0),
+    ) -> None:
+        """Colorizes line set lines by scalar, pos/neg in separate colors
+
+        :param scalars: Scalar values, length has to match number of lines
+        :param cmaps: Matplotlib color map strings for pos/neg
+        :param vmax: Maximum (pos/neg) value
+        :param nan_color: Color for NaN values, RGB values [0..1]
+        """
+        scalars = np.asarray(scalars)
+        if scalars.ndim != 1 or scalars.size != self.num_lines:
+            raise Exception("Provide correct number of values to colorize lines")
+        self._line_colors = scalar_to_bicolor(scalars, cmaps, vmax, nan_color)
+
+    @classmethod
+    def create_from_point_sequence(cls, points: np.ndarray) -> "LineSet":
+        return cls(
+            vertices=points,
+            lines=np.vstack(
+                (
+                    np.arange(0, points.shape[0] - 1),
+                    np.arange(1, points.shape[0]),
+                )
+            ).T,
+        )
+
+    @classmethod
+    def create_from_normals(
+        cls,
+        vertices: Vertices,
+        scale: float = 1.0,
+        keep_ratio: float = 1.0,
+        rng: np.random.Generator | None = None,
+    ) -> "LineSet":
+        """Create line set from the normals of a point cloud or triangle mesh
+
+        :param vertices: Vertices object, i.e. point cloud or triangle mesh
+        :param scale: Length of the normal vectors
+        :param keep_ratio: Ratio of normal vectors to create,
+            0.1 randomly samples 10% in normal vectors in vertices
+        :param rng: NumPy random number generator
+        :returns: Resulting line set
+        """
+        if not vertices.has_normals:
+            raise Exception("No normals to create lineset from")
+        if np.isclose(keep_ratio, 1.0):
+            num_normals = vertices.vertices.shape[0]
+            verts = np.vstack(
+                (
+                    vertices.vertices,
+                    vertices.vertices + scale * vertices.normals,
+                )
+            )
+        else:
+            if rng is None:
+                rng = np.random.default_rng()
+            keep_ratio = np.clip(keep_ratio, 0.0, 1.0)
+            num_normals = np.round(keep_ratio * vertices.vertices.shape[0]).astype(int)
+            normal_indices = rng.choice(
+                vertices.vertices.shape[0], num_normals, replace=False
+            )
+            verts = np.vstack(
+                (
+                    vertices.vertices[normal_indices],
+                    vertices.vertices[normal_indices]
+                    + scale * vertices.normals[normal_indices],
+                )
+            )
+        return cls(
+            vertices=verts,
+            lines=np.vstack(
+                (
+                    np.arange(num_normals),
+                    np.arange(num_normals) + num_normals,
+                )
+            ).T,
+        )
+
+    @classmethod
+    def create_from_mesh(cls, mesh: TriangleMesh) -> "LineSet":
+        """Creates line set from triangle edges of a mesh
+
+        Creates a line set that represents the wire frame of the triangle
+        mesh: we extract each unique edge of the triangle mesh and add
+        that as a line to our line set.
+
+        :param mesh: Triangle mesh
+        :returns: Resulting line set
+        """
+        vertices = mesh.vertices
+        lines = mesh.get_unique_edges()
+        if mesh.has_colors:
+            vertex_colors = mesh.colors
+        else:
+            # Edges separate faces; does not make sense to use
+            # face colors to colorize edges!?
+            vertex_colors = None
+        return cls(
+            vertices=vertices,
+            lines=lines,
+            vertex_colors=vertex_colors,
+        )
+
+    @classmethod
+    def create_box(cls, scale: float | ArrayLike = 1.0) -> "LineSet":
+        """Create a box shaped line set
+
+        Box has 8 vertices and 12 lines.
+        Box starts at (0, 0, 0) and extends to (scale, scale, scale).
+
+        :param scale: Scale of rectangle for X, Y and Z as single float or 3d
+        :returns: Resulting line set
+        """
+        if isinstance(scale, float):
+            scale = np.array((scale, scale, scale))
+        else:
+            scale = np.asarray(scale)
+            if scale.size != 3:
+                raise Exception("Provide proper scale.")
+        vertices = scale * np.array(
+            [
+                [0.0, 0.0, 0.0],  # 0: bottom-back-left
+                [1.0, 0.0, 0.0],  # 1: bottom-back-right
+                [1.0, 1.0, 0.0],  # 2: bottom-front-right
+                [0.0, 1.0, 0.0],  # 3: bottom-front-left
+                [0.0, 0.0, 1.0],  # 4: top-back-left
+                [1.0, 0.0, 1.0],  # 5: top-back-right
+                [1.0, 1.0, 1.0],  # 6: top-front-right
+                [0.0, 1.0, 1.0],  # 7: top-front-left
+            ],
+            dtype=float,
+        )
+        lines = np.array(
+            [
+                # Bottom lines
+                [0, 1],
+                [1, 2],
+                [2, 3],
+                [3, 0],
+                # Top lines
+                [4, 5],
+                [5, 6],
+                [6, 7],
+                [7, 4],
+                # Side lines
+                [0, 4],
+                [1, 5],
+                [2, 6],
+                [3, 7],
+            ]
+        )
+        return cls(vertices=vertices, lines=lines)
+
+    @classmethod
+    def create_bounding_box(cls, bounds: np.ndarray):
+        """Create a line set representing a line set
+
+        Box has 8 vertices and 12 lines.
+        Box starts at bounds[0] and extends to bounds[1].
+
+        Can directly used with Vertices::bounds() to generate a
+        bounding box for e.g. a point cloud or triangle mesh.
+
+        :param bounds: Min and max values for all coordinates, shape (2, 3)
+        :returns: Resulting line set
+        """
+        if bounds.ndim != 2 and bounds.shape != (2, 3):
+            raise Exception(f"Invalid bounds {bounds}, expected shape (2, 3)")
+        bounds = np.array(bounds)
+        box = cls.create_box(scale=bounds[1] - bounds[0])
+        box.vertices += bounds[0]
+        return box