ScadPy 0.1.0__py3-none-any.whl

scadpy/d2/shape/types/utils/__init__.py

@@ -0,0 +1,5 @@
+__all__ = ["shapely_base_geometry_to_shapely_polygons"]
+
+from .shapely_base_geometry_to_shapely_polygons import (
+    shapely_base_geometry_to_shapely_polygons,
+)

scadpy/d2/shape/types/utils/shapely_base_geometry_to_shapely_polygons.py

@@ -0,0 +1,25 @@
+from shapely.geometry import MultiPolygon, Polygon
+from shapely.geometry.base import BaseGeometry
+from shapely.geometry.polygon import orient
+from typeguard import typechecked
+
+
+@typechecked
+def shapely_base_geometry_to_shapely_polygons(
+    base_geometry: BaseGeometry,
+) -> list[Polygon]:
+    if base_geometry.is_empty:
+        return []
+
+    if isinstance(base_geometry, Polygon):
+        # normalize orientation: exterior CCW, interiors CW (shapely convention)
+        return [orient(base_geometry, sign=1.0)]
+
+    if isinstance(base_geometry, MultiPolygon):
+        return [
+            polygon
+            for geom in base_geometry.geoms
+            for polygon in shapely_base_geometry_to_shapely_polygons(geom)
+        ]
+
+    return []

scadpy/d2/shape/utils/__init__.py

@@ -0,0 +1,5 @@
+__all__ = ["shapely_base_geometry_to_shapely_polygons"]
+
+from .shapely_base_geometry_to_shapely_polygons import (
+    shapely_base_geometry_to_shapely_polygons,
+)

scadpy/d2/shape/utils/shapely_base_geometry_to_shapely_polygons.py

@@ -0,0 +1,55 @@
+from shapely.geometry import MultiPolygon, Polygon
+from shapely.geometry.base import BaseGeometry
+from typeguard import typechecked
+
+
+@typechecked
+def shapely_base_geometry_to_shapely_polygons(
+    base_geometry: BaseGeometry,
+) -> list[Polygon]:
+    """Recursively extract all polygons from a Shapely geometry.
+
+    Handles :class:`~shapely.geometry.Polygon` and
+    :class:`~shapely.geometry.MultiPolygon`; returns an empty list for empty
+    or unsupported geometry types.
+
+    Parameters
+    ----------
+    base_geometry : BaseGeometry
+        Any Shapely geometry.
+
+    Returns
+    -------
+    list[Polygon]
+        Flat list of all non-empty polygons found in *base_geometry*.
+
+    Examples
+    --------
+    >>> from shapely.geometry import MultiPolygon, Polygon
+    >>> from scadpy.d2.shape.utils import (
+    ...     shapely_base_geometry_to_shapely_polygons,
+    ... )
+
+    >>> polygons = shapely_base_geometry_to_shapely_polygons(
+    ...     MultiPolygon([
+    ...         Polygon([(0, 0), (1, 0), (1, 1)]),
+    ...         Polygon([(2, 0), (3, 0), (3, 1)]),
+    ...     ])
+    ... )
+    >>> len(polygons)
+    2
+    """
+    if base_geometry.is_empty:
+        return []
+
+    if isinstance(base_geometry, Polygon):
+        return [base_geometry]
+
+    if isinstance(base_geometry, MultiPolygon):
+        return [
+            polygon
+            for geom in base_geometry.geoms
+            for polygon in shapely_base_geometry_to_shapely_polygons(geom)
+        ]
+
+    return []

scadpy/d2/utils/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["resolve_vector_2d"]
+
+from .resolve_vector_2d import resolve_vector_2d

scadpy/d2/utils/resolve_vector_2d.py

@@ -0,0 +1,50 @@
+from collections.abc import Iterable
+
+import numpy as np
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+
+@typechecked
+def resolve_vector_2d(
+    values: float | Iterable[float],
+    default_value: float,
+) -> NDArray[np.float64]:
+    """
+    Resolves input into a 2D vector (NumPy array of length 2).
+
+    Parameters
+    ----------
+    values : float or Iterable[float]
+        The input values to resolve into a 2D vector. It can be:
+        - A single numeric value, repeated to fill the vector.
+        - An iterable of numeric values, extended or truncated to length 2.
+    default_value : float
+        The value used to pad the vector if `values` has fewer than 2 elements.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        A NumPy array of shape (2,) containing the resolved 2D vector.
+
+    Notes
+    -----
+    - If `values` is a single number, the result will be `[values, values]`.
+    - If `values` has one element, the result will be `[values[0], default_value]`.
+    - If `values` has more than 2 elements, only the first two will be kept.
+
+    Examples
+    --------
+    >>> from scadpy import resolve_vector_2d
+    >>> resolve_vector_2d(5, 0)
+    array([5., 5.])
+
+    >>> resolve_vector_2d([1], 0)
+    array([1., 0.])
+
+    >>> resolve_vector_2d([3, 4, 5], 0)
+    array([3., 4.])
+    """
+    from scadpy.utils.resolve_vector import resolve_vector
+
+    return resolve_vector(values, default_value, 2)

scadpy/d3/__init__.py

@@ -0,0 +1,2 @@
+from .solid import *  # noqa: F403
+from .utils import *  # noqa: F403

scadpy/d3/solid/__init__.py

@@ -0,0 +1,8 @@
+from .combinations import *  # noqa: F403
+from .exporters import *  # noqa: F403
+from .features import *  # noqa: F403
+from .topologies import *  # noqa: F403
+from .importers import *  # noqa: F403
+from .primitives import *  # noqa: F403
+from .transformations import *  # noqa: F403
+from .types import *  # noqa: F403

scadpy/d3/solid/combinations/__init__.py

@@ -0,0 +1,21 @@
+__all__ = [
+    "are_solid_parts_intersecting",
+    "concat_solid",
+    "exclude_solid",
+    "intersect_solid",
+    "intersect_solid_parts",
+    "subtract_solid",
+    "subtract_solid_parts",
+    "unify_solid",
+    "unify_solid_parts",
+]
+
+from .are_solid_parts_intersecting import are_solid_parts_intersecting
+from .concat_solid import concat_solid
+from .exclude_solid import exclude_solid
+from .intersect_solid import intersect_solid
+from .intersect_solid_parts import intersect_solid_parts
+from .subtract_solid import subtract_solid
+from .subtract_solid_parts import subtract_solid_parts
+from .unify_solid import unify_solid
+from .unify_solid_parts import unify_solid_parts

scadpy/d3/solid/combinations/are_solid_parts_intersecting.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from trimesh import Trimesh
+from trimesh.boolean import boolean_manifold  # pyright: ignore[reportUnknownVariableType]
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+
+
+@typechecked
+def are_solid_parts_intersecting(part1: Part[Trimesh], part2: Part[Trimesh]) -> bool:
+    """Return whether two solid parts intersect geometrically.
+
+    Parameters
+    ----------
+    part1 : Part[Trimesh]
+        The first solid part.
+    part2 : Part[Trimesh]
+        The second solid part.
+
+    Returns
+    -------
+    bool
+        True if the two parts intersect (shared volume > 0), False otherwise.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, are_solid_parts_intersecting
+
+    >>> are_solid_parts_intersecting(
+    ...     part1=cuboid(2)._parts[0],
+    ...     part2=cuboid(2)._parts[0],
+    ... )
+    True
+    >>> are_solid_parts_intersecting(
+    ...     part1=cuboid(1)._parts[0],
+    ...     part2=cuboid(1).translate(10)._parts[0],
+    ... )
+    False
+    """
+    return bool(
+        boolean_manifold(  # pyright: ignore[reportAny]
+            [part1.geometry, part2.geometry],
+            operation="intersection",
+            check_volume=False,
+        ).volume
+        != 0
+    )

scadpy/d3/solid/combinations/concat_solid.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Solid
+
+
+@typechecked
+def concat_solid(solids: Sequence[Solid]) -> Solid:
+    """Concatenate a sequence of solids into a single solid without any boolean operation.
+
+    All parts from all input solids are merged into a single solid. Parts that
+    overlap are not merged geometrically — use :func:`unify_solid` for that.
+
+    Parameters
+    ----------
+    solids : Sequence[Solid]
+        The solids to concatenate.
+
+    Returns
+    -------
+    Solid
+        A new solid containing all parts from all input solids.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, sphere, concat_solid
+
+    >>> concat_solid(  # doctest: +SKIP
+    ...     solids=[cuboid(4), sphere(radius=2).translate([3, 2, 0])]
+    ... )
+
+    .. render-example::
+        :name: concat_solid
+        :example: concat_solid(solids=[cuboid(4), sphere(radius=2).translate([3, 2, 0])])
+    """
+    from scadpy import Solid
+    from scadpy.core.assembly import concat_assemblies
+
+    return concat_assemblies(
+        assemblies=solids,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        concat_parts=Solid.from_parts,
+    )

scadpy/d3/solid/combinations/exclude_solid.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Solid
+
+
+@typechecked
+def exclude_solid(solids: Sequence[Solid]) -> Solid:
+    """Compute the symmetric difference (XOR) of a sequence of solids.
+
+    Keeps only the regions that belong to exactly one of the input solids.
+    Regions shared by two or more solids are removed.
+
+    Parameters
+    ----------
+    solids : Sequence[Solid]
+        The solids to compute the symmetric difference of.
+
+    Returns
+    -------
+    Solid
+        A new solid containing only the non-overlapping regions of the input solids.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, exclude_solid, x
+
+    >>> exclude_solid(  # doctest: +SKIP
+    ...     solids=[cuboid(4), cuboid(4).translate(x(2))]
+    ... )
+
+    .. render-example::
+        :name: exclude_solid
+        :example: exclude_solid(solids=[cuboid(4), cuboid(4).translate(x(2))])
+        :ghost: concat_solid(solids=[cuboid(4), cuboid(4).translate(x(2))])
+    """
+    from scadpy import (
+        Solid,
+        are_solid_parts_intersecting,
+        get_solid_part_bounds,
+        intersect_solid_parts,
+        subtract_solid_parts,
+        unify_solid_parts,
+    )
+    from scadpy.core.assembly import exclude_assemblies
+
+    return exclude_assemblies(
+        assemblies=solids,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        get_part_bounds=get_solid_part_bounds,
+        are_parts_intersecting=are_solid_parts_intersecting,
+        subtract_parts=lambda part_base, part_cutter: subtract_solid_parts(
+            to_be_subtracted=part_base,
+            to_subtract=part_cutter,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        intersect_parts=lambda parts: intersect_solid_parts(
+            parts=parts,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        unify_parts=lambda parts: unify_solid_parts(
+            parts=parts,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        concat_parts=Solid.from_parts,
+    )

scadpy/d3/solid/combinations/intersect_solid.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Solid
+
+
+@typechecked
+def intersect_solid(solids: Sequence[Solid]) -> Solid:
+    """Compute the intersection of a sequence of solids.
+
+    Only the regions shared by all input solids are kept.
+
+    Parameters
+    ----------
+    solids : Sequence[Solid]
+        The solids to intersect.
+
+    Returns
+    -------
+    Solid
+        A new solid containing only the regions present in all input solids.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, sphere, intersect_solid
+
+    >>> intersect_solid(  # doctest: +SKIP
+    ...     solids=[cuboid(4), sphere(radius=2).translate(1)]
+    ... )
+
+    .. render-example::
+        :name: intersect_solid
+        :example: intersect_solid(solids=[cuboid(4), sphere(radius=2).translate(1)])
+        :ghost: cuboid(4) + sphere(radius=2).translate(1)
+    """
+    from scadpy import (
+        Solid,
+        are_solid_parts_intersecting,
+        get_solid_part_bounds,
+        intersect_solid_parts,
+        unify_solid_parts,
+    )
+    from scadpy.core.assembly import intersect_assemblies
+
+    return intersect_assemblies(
+        assemblies=solids,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        get_part_bounds=get_solid_part_bounds,
+        are_parts_intersecting=are_solid_parts_intersecting,
+        intersect_parts=lambda parts: intersect_solid_parts(
+            parts=parts,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        unify_parts=lambda parts: unify_solid_parts(
+            parts=parts,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        concat_parts=Solid.from_parts,
+    )

scadpy/d3/solid/combinations/intersect_solid_parts.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING
+
+from trimesh import Trimesh
+from trimesh.boolean import boolean_manifold  # pyright: ignore[reportUnknownVariableType]
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def intersect_solid_parts(
+    parts: Sequence[Part[Trimesh]],
+    make_assembly_from_parts: Callable[[Sequence[Part[Trimesh]]], Solid],
+) -> Solid:
+    """Intersect a sequence of solid parts and return the resulting solid.
+
+    Shortcut for :func:`intersect_parts`.
+    See :func:`intersect_parts` for full documentation.
+
+    Parameters
+    ----------
+    parts : Sequence[Part[Trimesh]]
+        The solid parts to intersect.
+    make_assembly_from_parts : Callable[[Sequence[Part[Trimesh]]], Solid]
+        Factory function to build the resulting Solid from a sequence of parts.
+
+    Returns
+    -------
+    Solid
+        A new solid containing the geometric intersection of the input parts.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, sphere, intersect_solid_parts, Solid
+
+    >>> intersect_solid_parts(  # doctest: +SKIP
+    ...     parts=(
+    ...         list(cuboid(4)._parts)
+    ...         + list(sphere(radius=2).translate([2, 2, 2])._parts)
+    ...     ),
+    ...     make_assembly_from_parts=Solid.from_parts,
+    ... )
+
+    .. render-example::
+        :name: intersect_solid_parts_example
+        :example: intersect_solid_parts(parts=list(cuboid(4)._parts) + list(sphere(radius=2).translate([2, 2, 2])._parts), make_assembly_from_parts=Solid.from_parts)
+        :ghost: concat_solid(solids=[cuboid(4), sphere(radius=2).translate([2, 2, 2])])
+    """
+    from scadpy import (
+        Part,
+        are_solid_parts_intersecting,
+        get_solid_part_bounds,
+    )
+    from scadpy.core.part import intersect_parts
+
+    return intersect_parts(
+        parts=parts,
+        get_part_color=lambda p: p.color,
+        get_part_magnitude=lambda p: p.geometry.volume,  # pyright: ignore[reportAny]
+        get_part_bounds=get_solid_part_bounds,
+        are_parts_intersecting=are_solid_parts_intersecting,
+        get_part_geometry=lambda p: p.geometry,
+        intersect_geometries=lambda g: boolean_manifold(
+            g, operation="intersection", check_volume=False
+        ).split(),  # pyright: ignore[reportUnknownMemberType]
+        make_part_from_geometry=Part[Trimesh].from_geometry,
+        make_assembly_from_parts=make_assembly_from_parts,
+    )

scadpy/d3/solid/combinations/subtract_solid.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Solid
+
+
+@typechecked
+def subtract_solid(to_be_subtracted: Solid, to_subtract: Solid) -> Solid:
+    """Subtract one solid from another using boolean difference.
+
+    The geometry of ``to_subtract`` is removed from ``to_be_subtracted``.
+
+    Parameters
+    ----------
+    to_be_subtracted : Solid
+        The solid to subtract from.
+    to_subtract : Solid
+        The solid to subtract.
+
+    Returns
+    -------
+    Solid
+        A new solid with the geometry of ``to_subtract`` removed from ``to_be_subtracted``.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, sphere, subtract_solid
+
+    >>> subtract_solid(  # doctest: +SKIP
+    ...     to_be_subtracted=cuboid(4), to_subtract=sphere(radius=2)
+    ... )
+
+    .. render-example::
+        :name: subtract_solid
+        :example: subtract_solid(to_be_subtracted=cuboid(4), to_subtract=sphere(radius=2))
+        :ghost: cuboid(4)
+    """
+    from scadpy import (
+        Solid,
+        are_solid_parts_intersecting,
+        get_solid_part_bounds,
+        intersect_solid_parts,
+        subtract_solid_parts,
+        unify_solid_parts,
+    )
+    from scadpy.core.assembly import subtract_assemblies
+
+    return subtract_assemblies(
+        to_be_subtracted=to_be_subtracted,
+        to_subtract=to_subtract,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        get_part_bounds=get_solid_part_bounds,
+        are_parts_intersecting=are_solid_parts_intersecting,
+        subtract_parts=lambda part_base, part_cutter: subtract_solid_parts(
+            to_be_subtracted=part_base,
+            to_subtract=part_cutter,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        intersect_parts=lambda parts: intersect_solid_parts(
+            parts=parts,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        unify_parts=lambda parts: unify_solid_parts(
+            parts=parts,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+        concat_parts=Solid.from_parts,
+    )

scadpy/d3/solid/combinations/subtract_solid_parts.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING
+
+from trimesh import Trimesh
+from trimesh.boolean import boolean_manifold  # pyright: ignore[reportUnknownVariableType]
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+    from scadpy.d3.solid import Solid
+
+
+@typechecked
+def subtract_solid_parts(
+    to_be_subtracted: Part[Trimesh],
+    to_subtract: Part[Trimesh],
+    make_assembly_from_parts: Callable[[Sequence[Part[Trimesh]]], Solid],
+) -> Solid:
+    """Subtract one solid part from another and return the resulting solid.
+
+    Shortcut for :func:`subtract_parts`.
+    See :func:`subtract_parts` for full documentation.
+
+    Parameters
+    ----------
+    to_be_subtracted : Part[Trimesh]
+        The part to subtract from.
+    to_subtract : Part[Trimesh]
+        The part to subtract.
+    make_assembly_from_parts : Callable[[list[Part[Trimesh]]], Solid]
+        Factory function to build the resulting Solid from a sequence of parts.
+
+    Returns
+    -------
+    Solid
+        A new solid with the geometry of ``to_subtract`` removed from ``to_be_subtracted``.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, sphere, subtract_solid_parts, Solid
+
+    >>> subtract_solid_parts(  # doctest: +SKIP
+    ...     to_be_subtracted=cuboid(4)._parts[0],
+    ...     to_subtract=sphere(radius=2)._parts[0],
+    ...     make_assembly_from_parts=Solid.from_parts,
+    ... )
+
+    .. render-example::
+        :name: subtract_solid_parts_example
+        :example: subtract_solid_parts(to_be_subtracted=cuboid(4)._parts[0], to_subtract=sphere(radius=2)._parts[0], make_assembly_from_parts=Solid.from_parts)
+        :ghost: concat_solid(solids=[cuboid(4), sphere(radius=2)])
+    """
+    from scadpy import Part
+    from scadpy.core.part import subtract_parts
+
+    return subtract_parts(
+        to_be_subtracted=to_be_subtracted,
+        to_subtract=to_subtract,
+        get_part_color=lambda p: p.color,
+        get_part_geometry=lambda p: p.geometry,
+        subtract_geometries=lambda g1, g2: boolean_manifold(
+            [g1, g2], operation="difference", check_volume=False
+        ).split(),  # pyright: ignore[reportUnknownMemberType]
+        make_part_from_geometry=Part[Trimesh].from_geometry,
+        make_assembly_from_parts=make_assembly_from_parts,
+    )

scadpy/d3/solid/combinations/unify_solid.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Solid
+
+
+@typechecked
+def unify_solid(solids: Sequence[Solid]) -> Solid:
+    """Unite a sequence of solids into a single solid using boolean union.
+
+    All overlapping parts across the input solids are merged geometrically.
+    Use :func:`concat_solid` if you want to combine solids without merging overlaps.
+
+    Parameters
+    ----------
+    solids : Sequence[Solid]
+        The solids to unite.
+
+    Returns
+    -------
+    Solid
+        A new solid containing the geometric union of all input solids.
+
+    Examples
+    --------
+    >>> from scadpy import cuboid, sphere, unify_solid, x
+
+    >>> unify_solid(  # doctest: +SKIP
+    ...     solids=[cuboid(4), sphere(radius=2).translate(x(2))]
+    ... )
+
+    .. render-example::
+        :name: unify_solid
+        :example: unify_solid(solids=[cuboid(4), sphere(radius=2).translate(x(2))])
+    """
+    from scadpy import Solid, unify_solid_parts
+    from scadpy.core.assembly import unify_assemblies
+
+    return unify_assemblies(
+        assemblies=solids,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        unify_parts=lambda parts: unify_solid_parts(
+            parts=parts,
+            make_assembly_from_parts=Solid.from_parts,
+        ),
+    )