ScadPy 0.1.0__py3-none-any.whl

scadpy/d3/solid/features/is_solid_empty.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Solid
+
+
+@typechecked
+def is_solid_empty(solid: Solid) -> bool:
+    """Return whether the solid has no vertices.
+
+    Parameters
+    ----------
+    solid : Solid
+        The solid to check.
+
+    Returns
+    -------
+    bool
+        True if the solid has no vertices, False otherwise.
+
+    Examples
+    --------
+    >>> from scadpy import Solid, is_solid_empty
+
+    >>> is_solid_empty(Solid.from_parts([]))
+    True
+
+    >>> from scadpy import cuboid
+    >>> is_solid_empty(cuboid(2))
+    False
+    """
+    return len(solid.vertex_coordinates) == 0

scadpy/d3/solid/importers/__init__.py

@@ -0,0 +1,11 @@
+__all__ = [
+    "map_geometries_to_solid",
+    "map_geometry_to_solid",
+    "map_parts_to_solid",
+    "map_stl_to_solid",
+]
+
+from .map_geometries_to_solid import map_geometries_to_solid
+from .map_geometry_to_solid import map_geometry_to_solid
+from .map_parts_to_solid import map_parts_to_solid
+from .map_stl_to_solid import map_stl_to_solid

scadpy/d3/solid/importers/map_geometries_to_solid.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from trimesh import Trimesh
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def map_geometries_to_solid(geometries: Sequence[Trimesh]) -> Solid:
+    """Map a sequence of Trimesh geometries to a solid.
+
+    Parameters
+    ----------
+    geometries : Sequence[Trimesh]
+        The geometries to map.
+
+    Returns
+    -------
+    Solid
+        A new solid containing all input geometries as parts.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, map_geometries_to_solid
+
+    >>> map_geometries_to_solid(  # doctest: +SKIP
+    ...     [cuboid(4)._parts[0].geometry]
+    ... )
+
+    .. render-example::
+        :name: map_geometries_to_solid
+        :example: map_geometries_to_solid([cuboid(4)._parts[0].geometry])
+    """
+    from scadpy.core.part import Part
+    from scadpy.d3.solid import Solid
+
+    return Solid.from_parts([Part[Trimesh].from_geometry(g) for g in geometries])

scadpy/d3/solid/importers/map_geometry_to_solid.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from trimesh import Trimesh
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def map_geometry_to_solid(geometry: Trimesh) -> Solid:
+    """Map a single Trimesh geometry to a solid.
+
+    Shortcut for :func:`map_geometries_to_solid` with a single geometry.
+
+    Parameters
+    ----------
+    geometry : Trimesh
+        The geometry to map.
+
+    Returns
+    -------
+    Solid
+        A new solid containing the single geometry as a part.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, map_geometry_to_solid
+
+    >>> map_geometry_to_solid(  # doctest: +SKIP
+    ...     cuboid(4)._parts[0].geometry
+    ... )
+
+    .. render-example::
+        :name: map_geometry_to_solid
+        :example: map_geometry_to_solid(cuboid(4)._parts[0].geometry)
+    """
+    from scadpy.d3.solid.importers import map_geometries_to_solid
+
+    return map_geometries_to_solid([geometry])

scadpy/d3/solid/importers/map_parts_to_solid.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from trimesh import Trimesh
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Part, Solid
+
+
+@typechecked
+def map_parts_to_solid(
+    parts: Sequence[Part[Trimesh]],
+) -> Solid:
+    """Map a sequence of parts to a solid, repairing geometry where needed.
+
+    For each part, two repairs are applied if needed:
+
+    - **Locally inconsistent winding**: if adjacent faces have inconsistent winding
+      order (e.g. after some boolean operations), :func:`trimesh.Trimesh.fix_normals`
+      is called to make them consistent.
+    - **Globally inverted normals**: if the mesh has negative volume (e.g. after
+      a mirror transform), the face winding order is reversed to restore
+      outward-pointing normals.
+
+    A mesh copy is only made when a repair is actually needed.
+
+    Parameters
+    ----------
+    parts : Sequence[Part[Trimesh]]
+        The parts to map. Each part holds a Trimesh mesh and a color.
+
+    Returns
+    -------
+    Solid
+        A new solid containing all parts with corrected geometry.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, map_parts_to_solid
+
+    >>> map_parts_to_solid(  # doctest: +SKIP
+    ...     cuboid(4)._parts
+    ... )
+
+    .. render-example::
+        :name: map_parts_to_solid
+        :example: map_parts_to_solid(cuboid(4)._parts)
+    """
+    from scadpy.core.part import Part
+    from scadpy.d3.solid.types.solid import Solid
+
+    fixed_parts: list[Part[Trimesh]] = []
+    for part in parts:
+        mesh = part.geometry
+        needs_fix = (not mesh.is_winding_consistent) or (mesh.volume < 0)
+        if needs_fix:
+            mesh = mesh.copy()
+            mesh.fix_normals()
+        fixed_parts.append(Part[Trimesh].from_geometry(mesh, part.color))
+
+    solid = Solid()
+    solid._parts = fixed_parts
+    return solid

scadpy/d3/solid/importers/map_stl_to_solid.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from trimesh import Trimesh, load
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def map_stl_to_solid(source: str | Path) -> Solid:
+    """Load a solid from an STL file.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the ``.stl`` file.
+
+    Returns
+    -------
+    Solid
+        A new solid loaded from the STL file.
+
+    Examples
+    --------
+    >>> from scadpy import map_stl_to_solid
+
+    >>> map_stl_to_solid("model.stl")  # doctest: +SKIP
+    """
+    from typing import cast
+
+    from scadpy.d3.solid.importers import map_geometry_to_solid
+
+    return map_geometry_to_solid(cast(Trimesh, load(source, force="mesh")))

scadpy/d3/solid/primitives/__init__.py

@@ -0,0 +1,7 @@
+__all__ = ["cone", "cuboid", "cylinder", "polyhedron", "sphere"]
+
+from .cone import cone
+from .cuboid import cuboid
+from .cylinder import cylinder
+from .polyhedron import polyhedron
+from .sphere import sphere

scadpy/d3/solid/primitives/cone.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def cone(radius: float, height: float, section_count: int = 32) -> Solid:
+    """Create a cone centered at the origin, apex pointing along +z.
+
+    Parameters
+    ----------
+    radius : float
+        The radius of the base circle.
+    height : float
+        The total height of the cone.
+    section_count : int, optional
+        The number of sides of the polygonal base approximation. Default is 32.
+
+    Returns
+    -------
+    Solid
+        A :class:`~scadpy.d3.solid.types.solid.Solid` object representing the
+        cone, centered at the origin.
+
+    Examples
+    --------
+    >>> from scadpy import cone
+
+    >>> cone(radius=2, height=4)  # doctest: +SKIP
+
+    .. render-example::
+        :name: cone
+        :example: cone(radius=2, height=4)
+
+    >>> cone(radius=2, height=4, section_count=6)  # doctest: +SKIP
+
+    .. render-example::
+        :name: hexagonal_cone
+        :example: cone(radius=2, height=4, section_count=6)
+    """
+    from scadpy.d3.solid.primitives.polyhedron import polyhedron
+
+    n = section_count
+    angles = np.linspace(0, 2 * np.pi, n, endpoint=False)
+    cos_a = np.cos(angles)
+    sin_a = np.sin(angles)
+
+    # Vertex layout:
+    #   0 .. n-1    base circle at z = -height/2
+    #   n           apex at z = +height/2
+    #   n+1         base center at z = -height/2
+    base = np.column_stack([radius * cos_a, radius * sin_a, np.full(n, -height / 2)])
+    apex = np.array([[0.0, 0.0, height / 2]])
+    base_center = np.array([[0.0, 0.0, -height / 2]])
+    vertices = np.vstack([base, apex, base_center]).astype(np.float64)
+
+    i = np.arange(n, dtype=np.int64)
+    j = (i + 1) % n
+
+    side = np.column_stack([i, j, np.full(n, n, dtype=np.int64)])               # normal outward+up
+    base_cap = np.column_stack([np.full(n, n + 1, dtype=np.int64), j, i])       # normal -z
+
+    faces = np.vstack([side, base_cap]).astype(np.int64)
+    return polyhedron(vertices=vertices, faces=faces)

scadpy/d3/solid/primitives/cuboid.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+import numpy as np
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def cuboid(size: float | Iterable[float]) -> Solid:
+    """Create a box (rectangular cuboid) centered at the origin.
+
+    Parameters
+    ----------
+    size : float | Iterable[float]
+        The dimensions of the cuboid as ``[width, depth, height]``.
+        If a single float is provided, it is broadcast to all three dimensions,
+        producing a cube. Missing values default to 0.
+
+    Returns
+    -------
+    Solid
+        A :class:`~scadpy.d3.solid.types.solid.Solid` object representing the cuboid,
+        centered at the origin.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid
+
+    >>> cuboid(4)  # doctest: +SKIP
+
+    .. render-example::
+        :name: cube
+        :example: cuboid(4)
+
+    >>> cuboid([4, 2, 1])  # doctest: +SKIP
+
+    .. render-example::
+        :name: cuboid
+        :example: cuboid([4, 2, 1])
+    """
+    from scadpy.d3 import resolve_vector_3d
+    from scadpy.d3.solid.primitives.polyhedron import polyhedron
+
+    w, d, h = resolve_vector_3d(size, 0) / 2
+
+    vertices = np.array(
+        [
+            [-w, -d, -h],  # 0
+            [+w, -d, -h],  # 1
+            [+w, +d, -h],  # 2
+            [-w, +d, -h],  # 3
+            [-w, -d, +h],  # 4
+            [+w, -d, +h],  # 5
+            [+w, +d, +h],  # 6
+            [-w, +d, +h],  # 7
+        ],
+        dtype=np.float64,
+    )
+    faces = np.array(
+        [
+            [0, 3, 2], [0, 2, 1],  # bottom  (normal -z)
+            [4, 5, 6], [4, 6, 7],  # top     (normal +z)
+            [0, 1, 5], [0, 5, 4],  # front   (normal -y)
+            [3, 7, 6], [3, 6, 2],  # back    (normal +y)
+            [0, 4, 7], [0, 7, 3],  # left    (normal -x)
+            [1, 2, 6], [1, 6, 5],  # right   (normal +x)
+        ],
+        dtype=np.int64,
+    )
+    return polyhedron(vertices=vertices, faces=faces)

scadpy/d3/solid/primitives/cylinder.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def cylinder(radius: float, height: float, section_count: int = 32) -> Solid:
+    """Create a cylinder centered at the origin, aligned along the z-axis.
+
+    Parameters
+    ----------
+    radius : float
+        The radius of the cylinder.
+    height : float
+        The total height of the cylinder.
+    section_count : int, optional
+        The number of sides of the polygonal approximation. Default is 32.
+
+    Returns
+    -------
+    Solid
+        A :class:`~scadpy.d3.solid.types.solid.Solid` object representing the
+        cylinder, centered at the origin.
+
+    Examples
+    --------
+    >>> from scadpy import cylinder
+
+    >>> cylinder(radius=2, height=4)  # doctest: +SKIP
+
+    .. render-example::
+        :name: cylinder
+        :example: cylinder(radius=2, height=4)
+
+    >>> cylinder(radius=2, height=4, section_count=6)  # doctest: +SKIP
+
+    .. render-example::
+        :name: hexagonal_cylinder
+        :example: cylinder(radius=2, height=4, section_count=6)
+    """
+    from scadpy.d3.solid.primitives.polyhedron import polyhedron
+
+    n = section_count
+    angles = np.linspace(0, 2 * np.pi, n, endpoint=False)
+    cos_a = np.cos(angles)
+    sin_a = np.sin(angles)
+
+    # Vertex layout:
+    #   0 .. n-1        bottom circle
+    #   n .. 2n-1       top circle
+    #   2n              bottom center
+    #   2n+1            top center
+    bottom = np.column_stack([radius * cos_a, radius * sin_a, np.full(n, -height / 2)])
+    top = np.column_stack([radius * cos_a, radius * sin_a, np.full(n, height / 2)])
+    centers = np.array([[0.0, 0.0, -height / 2], [0.0, 0.0, height / 2]])
+    vertices = np.vstack([bottom, top, centers]).astype(np.float64)
+
+    i = np.arange(n, dtype=np.int64)
+    j = (i + 1) % n
+
+    side1 = np.column_stack([i, j, n + j])          # side triangle A
+    side2 = np.column_stack([i, n + j, n + i])      # side triangle B
+    bot_cap = np.column_stack([np.full(n, 2 * n, dtype=np.int64), j, i])   # normal -z
+    top_cap = np.column_stack([np.full(n, 2 * n + 1, dtype=np.int64), n + i, n + j])  # normal +z
+
+    faces = np.vstack([side1, side2, bot_cap, top_cap]).astype(np.int64)
+    return polyhedron(vertices=vertices, faces=faces)

scadpy/d3/solid/primitives/polyhedron.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+from trimesh import Trimesh
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def polyhedron(
+    vertices: NDArray[np.float64],
+    faces: NDArray[np.int64],
+) -> Solid:
+    """Create a solid from raw vertex coordinates and triangular face indices.
+
+    This is the base primitive constructor. All other solid primitives ultimately
+    call this function with numpy-computed geometry.
+
+    Parameters
+    ----------
+    vertices : NDArray[np.float64]
+        Vertex coordinates of shape ``(n, 3)``.
+    faces : NDArray[np.int64]
+        Triangle face indices of shape ``(m, 3)``. Each row contains the indices
+        of three vertices forming a triangle. Winding order follows the
+        right-hand rule: outward-pointing normals require counter-clockwise
+        vertex ordering when viewed from outside.
+
+    Returns
+    -------
+    Solid
+        A new solid built from the given geometry.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scadpy import polyhedron
+
+    >>> polyhedron(  # doctest: +SKIP
+    ...     vertices=np.array([
+    ...         [ 1.0,  1.0,  1.0],
+    ...         [ 1.0, -1.0, -1.0],
+    ...         [-1.0,  1.0, -1.0],
+    ...         [-1.0, -1.0,  1.0],
+    ...     ]),
+    ...     faces=np.array([[0, 1, 2], [0, 2, 3], [0, 3, 1], [1, 3, 2]], dtype=np.int64),
+    ... )
+
+    .. render-example::
+        :name: polyhedron
+        :example: polyhedron(vertices=np.array([[1.0,1.0,1.0],[1.0,-1.0,-1.0],[-1.0,1.0,-1.0],[-1.0,-1.0,1.0]]), faces=np.array([[0,1,2],[0,2,3],[0,3,1],[1,3,2]], dtype=np.int64))
+    """
+    from scadpy.d3.solid import Solid
+
+    return Solid.from_geometry(Trimesh(vertices=vertices, faces=faces))

scadpy/d3/solid/primitives/sphere.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from trimesh.creation import icosphere
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def sphere(radius: float, subdivision_count: int = 4) -> Solid:
+    """Create a sphere approximated by an icosphere mesh.
+
+    Parameters
+    ----------
+    radius : float
+        The radius of the sphere. Must be strictly positive.
+    subdivision_count : int, optional
+        The number of subdivision iterations applied to the base icosahedron.
+        Higher values produce a smoother approximation. Default is 4.
+
+    Returns
+    -------
+    Solid
+        A :class:`~scadpy.d3.solid.types.solid.Solid` object representing the
+        approximated sphere, centered at the origin.
+
+    Notes
+    -----
+    - The sphere is always centered at the origin.
+    - Subdivision count of 4 produces 2562 vertices.
+
+    Examples
+    --------
+    >>> from scadpy import sphere
+
+    >>> sphere(radius=2)  # doctest: +SKIP
+
+    .. render-example::
+        :name: sphere
+        :example: sphere(radius=2)
+
+    >>> sphere(radius=2, subdivision_count=1)  # doctest: +SKIP
+
+    .. render-example::
+        :name: low_resolution_sphere
+        :example: sphere(radius=2, subdivision_count=1)
+    """
+    from scadpy.d3.solid.primitives.polyhedron import polyhedron
+
+    mesh = icosphere(radius=radius, subdivisions=subdivision_count)
+    return polyhedron(
+        vertices=mesh.vertices.astype(np.float64),
+        faces=mesh.faces.astype(np.int64),
+    )

scadpy/d3/solid/topologies/__init__.py

@@ -0,0 +1,8 @@
+__all__ = [
+    "get_solid_triangle_to_vertex",
+    "get_solid_vertex_coordinates",
+    "get_solid_vertex_to_part",
+]
+
+from .triangle import get_solid_triangle_to_vertex
+from .vertex import get_solid_vertex_coordinates, get_solid_vertex_to_part

scadpy/d3/solid/topologies/triangle/__init__.py

@@ -0,0 +1,5 @@
+__all__ = [
+    "get_solid_triangle_to_vertex",
+]
+
+from .get_solid_triangle_to_vertex import get_solid_triangle_to_vertex

scadpy/d3/solid/topologies/triangle/get_solid_triangle_to_vertex.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def get_solid_triangle_to_vertex(
+    solid: Solid,
+) -> NDArray[np.int64]:
+    """For each triangle in the solid, return the indices of its three vertices.
+
+    Parameters
+    ----------
+    solid : Solid
+        The solid to extract triangle-to-vertex mapping from.
+
+    Returns
+    -------
+    NDArray[np.int64]
+        2D array of shape (n_triangles, 3), one row per triangle containing
+        the global vertex indices of its three corners.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, get_solid_triangle_to_vertex
+
+    >>> triangle_to_vertex = get_solid_triangle_to_vertex(cuboid(2))
+    >>> triangle_to_vertex.shape[1]
+    3
+    """
+    if not solid._parts:
+        return np.empty((0, 3), dtype=np.int64)
+
+    part_vertex_counts = [len(part.geometry.vertices) for part in solid._parts]
+    offsets = np.concatenate([[0], np.cumsum(part_vertex_counts[:-1])])
+
+    return np.concatenate(
+        [
+            (part.geometry.faces + offset).astype(np.int64)
+            for part, offset in zip(solid._parts, offsets)
+        ]
+    )

scadpy/d3/solid/topologies/vertex/__init__.py

@@ -0,0 +1,7 @@
+__all__ = [
+    "get_solid_vertex_coordinates",
+    "get_solid_vertex_to_part",
+]
+
+from .get_solid_vertex_coordinates import get_solid_vertex_coordinates
+from .get_solid_vertex_to_part import get_solid_vertex_to_part