ScadPy 0.1.0__py3-none-any.whl

scadpy/core/part/combinations/unify_parts.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    from scadpy.color import Color
+
+
+# @typechecked
+def unify_parts[A, P, G](
+    parts: Sequence[P],
+    get_part_color: Callable[[P], Color],
+    get_part_magnitude: Callable[[P], float],
+    get_part_bounds: Callable[[P], NDArray[np.float64]],
+    are_parts_intersecting: Callable[[P, P], bool],
+    get_part_geometry: Callable[[P], G],
+    unify_geometries: Callable[[list[G]], Iterable[G]],
+    make_part_from_geometry: Callable[[G, Color], P],
+    make_assembly_from_parts: Callable[[Sequence[P]], A],
+) -> A:
+    """
+    Unite (union) groups of intersecting parts, blend their colors (weighted by magnitude), and return a new assembly.
+
+    This function is fully generic and uses dependency injection for all domain-specific
+    operations, making it suitable for a wide range of applications (2D, 3D, CAD, etc.).
+    Colors are blended using a weighted average, where each part's color is weighted by its magnitude.
+
+    Parameters
+    ----------
+    parts : Sequence[Part]
+        Sequence of part objects to process.
+    get_part_color : Callable[[P], Color]
+        Function to extract the color from a part (as a list or tuple of 4 floats: RGBA).
+    get_part_magnitude : Callable[[P], float]
+        Function to extract a magnitude (e.g., area, volume) from a part for color blending.
+    get_part_bounds : Callable[[P], NDArray[np.float64]]
+        Function to extract the bounding box of a part.
+    are_parts_intersecting : Callable[[P, P], bool]
+        Function to determine if two parts intersect.
+    get_part_geometry : Callable[[P], G]
+        Function to extract the geometry from a part.
+    unify_geometries : Callable[[list[G]], Iterable[G]]
+        Function to compute the union of a list of geometries.
+    make_part_from_geometry : Callable[[G, Color], P]
+        Function to create a part from a geometry and a color.
+    make_assembly_from_parts : Callable[[Sequence[P]], A]
+        Function to create an assembly from a sequence of parts.
+
+    Returns
+    -------
+    A
+        The assembly object containing all unified parts with blended colors.
+
+    Examples
+    --------
+    >>> from scadpy import unify_parts
+
+    >>> parts = [
+    ...     {
+    ...         'bounds': [0, 0, 2, 2],
+    ...         'color': [1, 0, 0, 1],
+    ...         'magnitude': 1,
+    ...     },
+    ...     {
+    ...         'bounds': [1, 1, 3, 3],
+    ...         'color': [0, 1, 0, 1],
+    ...         'magnitude': 2,
+    ...     },
+    ...     {
+    ...         'bounds': [5, 5, 6, 6],
+    ...         'color': [0, 0, 1, 1],
+    ...         'magnitude': 1,
+    ...     },
+    ... ]
+    ...
+    >>> def are_intersecting(p1, p2):
+    ...     b1, b2 = p1['bounds'], p2['bounds']
+    ...     return not (b1[2] <= b2[0] or b2[2] <= b1[0] or
+    ...                 b1[3] <= b2[1] or b2[3] <= b1[1])
+    ...
+    >>> def unify_geometries(geometries):
+    ...     minx = min(g[0] for g in geometries)
+    ...     miny = min(g[1] for g in geometries)
+    ...     maxx = max(g[2] for g in geometries)
+    ...     maxy = max(g[3] for g in geometries)
+    ...     return [[minx, miny, maxx, maxy]]
+    ...
+    >>> result = unify_parts(
+    ...     parts,
+    ...     get_part_color=lambda p: p['color'],
+    ...     get_part_magnitude=lambda p: p['magnitude'],
+    ...     get_part_bounds=lambda p: p['bounds'],
+    ...     are_parts_intersecting=are_intersecting,
+    ...     get_part_geometry=lambda p: p['bounds'],
+    ...     unify_geometries=unify_geometries,
+    ...     make_part_from_geometry=lambda geometry, color: {
+    ...         'bounds': geometry,
+    ...         'color': [round(float(v), 2) for v in color]
+    ...     },
+    ...     make_assembly_from_parts=lambda parts: parts
+    ... )
+    ...
+    >>> result == [
+    ...     {'bounds': [0, 0, 3, 3], 'color': [0.33, 0.67, 0.0, 1.0]},
+    ...     {'bounds': [5, 5, 6, 6], 'color': [0.0, 0.0, 1.0, 1.0]}
+    ... ]
+    True
+    """
+
+    from scadpy.core.component.utils import (
+        blend_component_colors,
+        get_intersecting_component_index_groups,
+    )
+
+    intersecting_part_index_groups: list[list[int]] = (
+        get_intersecting_component_index_groups(
+            parts,
+            get_component_bounds=get_part_bounds,
+            are_components_intersecting=are_parts_intersecting,
+        )
+    )
+    intersecting_part_groups: list[list[P]] = [
+        [parts[i] for i in group] for group in intersecting_part_index_groups
+    ]
+
+    unified_parts: list[P] = []
+    for parts in intersecting_part_groups:
+        blended_color = blend_component_colors(
+            components=parts,
+            get_component_color=get_part_color,
+            get_component_magnitude=get_part_magnitude,
+        )
+        geometries = [get_part_geometry(p) for p in parts]
+        unified_geometries = unify_geometries(geometries)
+        unified_parts += [
+            make_part_from_geometry(u, blended_color) for u in unified_geometries
+        ]
+
+    return make_assembly_from_parts(unified_parts)

scadpy/core/part/types/__init__.py

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

scadpy/core/part/types/part.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Self
+
+from scadpy.color import DEFAULT_COLOR
+
+if TYPE_CHECKING:
+    from scadpy.color import Color
+
+
+@dataclass(frozen=True)
+class Part[G]:
+    _geometry: G
+    _color: Color
+
+    @property
+    def color(self) -> Color:
+        return self._color
+
+    @classmethod
+    def from_geometry_ref(
+        cls: type[Self], geometry: G, color: Color = DEFAULT_COLOR
+    ) -> Self:
+        return cls(_geometry=geometry, _color=color)
+
+    @classmethod
+    def from_geometry(cls: type[Self], geometry: G, color: Color = DEFAULT_COLOR) -> Self:
+        return cls(_geometry=deepcopy(geometry), _color=color)
+
+    @property
+    def geometry(self) -> G:
+        return self._geometry

scadpy/core/part/utils/__init__.py

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

scadpy/core/part/utils/blend_part_colors.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from scadpy import Color, Part
+
+
+# @typechecked
+def blend_part_colors[G](
+    parts: Sequence[Part[G]],
+    get_part_magnitude: Callable[[Part[G]], float],
+) -> Color:
+    from scadpy.color import DEFAULT_COLOR
+
+    total_magnitude = 0.0
+    weighted_color = np.zeros(4, dtype=np.float64)
+
+    for part in parts:
+        color = np.array(part.color)
+        magnitude = get_part_magnitude(part)
+        weighted_color += color * magnitude
+        total_magnitude += magnitude
+
+    if total_magnitude == 0:
+        return DEFAULT_COLOR
+
+    blended = weighted_color / total_magnitude
+    return [float(x) for x in blended]  # pyright: ignore[reportAny]

scadpy/d2/__init__.py

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

scadpy/d2/shape/__init__.py

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

scadpy/d2/shape/combinations/__init__.py

@@ -0,0 +1,21 @@
+__all__ = [
+    "are_shape_parts_intersecting",
+    "concat_shape",
+    "exclude_shape",
+    "intersect_shape",
+    "intersect_shape_parts",
+    "subtract_shape",
+    "subtract_shape_parts",
+    "unify_shape",
+    "unify_shape_parts",
+]
+
+from .are_shape_parts_intersecting import are_shape_parts_intersecting
+from .concat_shape import concat_shape
+from .exclude_shape import exclude_shape
+from .intersect_shape import intersect_shape
+from .intersect_shape_parts import intersect_shape_parts
+from .subtract_shape import subtract_shape
+from .subtract_shape_parts import subtract_shape_parts
+from .unify_shape import unify_shape
+from .unify_shape_parts import unify_shape_parts

scadpy/d2/shape/combinations/are_shape_parts_intersecting.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shapely.geometry.polygon import Polygon
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+
+
+@typechecked
+def are_shape_parts_intersecting(
+    part1: Part[Polygon],
+    part2: Part[Polygon],
+) -> bool:
+    """Return whether two shape parts intersect geometrically.
+
+    Parameters
+    ----------
+    part1 : Part[Polygon]
+        The first shape part.
+    part2 : Part[Polygon]
+        The second shape part.
+
+    Returns
+    -------
+    bool
+        True if the two parts intersect, False otherwise.
+
+    Examples
+    --------
+    >>> from scadpy import (
+    ...     square, circle, are_shape_parts_intersecting
+    ... )
+    >>> are_shape_parts_intersecting(
+    ...     part1=square(2)._parts[0],
+    ...     part2=square(2)._parts[0],
+    ... )
+    True
+    >>> are_shape_parts_intersecting(
+    ...     part1=square(1)._parts[0],
+    ...     part2=square(1).rotate(
+    ...         angle=0
+    ...     ).grow(distance=5)._parts[0],
+    ... )
+    True
+    """
+    return part1.geometry.intersects(part2.geometry)

scadpy/d2/shape/combinations/concat_shape.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 Shape
+
+
+@typechecked
+def concat_shape(shapes: Sequence[Shape]) -> Shape:
+    """Concatenate a sequence of shapes into a single shape without any boolean operation.
+
+    All parts from all input shapes are merged into a single shape. Parts that
+    overlap are not merged geometrically — use :func:`unify_shape` for that.
+
+    Parameters
+    ----------
+    shapes : Sequence[Shape]
+        The shapes to concatenate.
+
+    Returns
+    -------
+    Shape
+        A new shape containing all parts from all input shapes.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, concat_shape
+
+    >>> concat_shape(  # doctest: +SKIP
+    ...     shapes=[square(4), circle(radius=2).translate([3, 2])]
+    ... )
+
+    .. render-example::
+        :name: concat_shape
+        :example: concat_shape(shapes=[square(4), circle(radius=2).translate([3, 2])])
+    """
+    from scadpy import Shape
+    from scadpy.core.assembly import concat_assemblies
+
+    return concat_assemblies(
+        assemblies=shapes,
+        get_assembly_parts=lambda a: a._parts,
+        concat_parts=Shape.from_parts,
+    )

scadpy/d2/shape/combinations/exclude_shape.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 Shape
+
+
+@typechecked
+def exclude_shape(shapes: Sequence[Shape]) -> Shape:
+    """Compute the symmetric difference (XOR) of a sequence of shapes.
+
+    Keeps only the regions that belong to exactly one of the input shapes.
+    Regions shared by two or more shapes are removed.
+
+    Parameters
+    ----------
+    shapes : Sequence[Shape]
+        The shapes to compute the symmetric difference of.
+
+    Returns
+    -------
+    Shape
+        A new shape containing only the non-overlapping regions of the input shapes.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, exclude_shape
+
+    >>> exclude_shape(  # doctest: +SKIP
+    ...     shapes=[square(4), circle(radius=2).translate([1, 1])]
+    ... )
+
+    .. render-example::
+        :name: exclude_shape
+        :example: exclude_shape(shapes=[square(4), circle(radius=2).translate([1, 1])])
+        :ghost: square(4)
+    """
+    from scadpy import (
+        Shape,
+        are_shape_parts_intersecting,
+        get_shape_part_bounds,
+        intersect_shape_parts,
+        subtract_shape_parts,
+        unify_shape_parts,
+    )
+    from scadpy.core.assembly import exclude_assemblies
+
+    return exclude_assemblies(
+        assemblies=shapes,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        get_part_bounds=get_shape_part_bounds,
+        are_parts_intersecting=are_shape_parts_intersecting,
+        subtract_parts=lambda part_base, part_cutter: subtract_shape_parts(
+            to_be_subtracted=part_base,
+            to_subtract=part_cutter,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        intersect_parts=lambda parts: intersect_shape_parts(
+            parts=parts,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        unify_parts=lambda parts: unify_shape_parts(
+            parts=parts,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        concat_parts=Shape.from_parts,
+    )

scadpy/d2/shape/combinations/intersect_shape.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 Shape
+
+
+@typechecked
+def intersect_shape(shapes: Sequence[Shape]) -> Shape:
+    """Compute the intersection of a sequence of shapes.
+
+    Only the regions shared by all input shapes are kept.
+
+    Parameters
+    ----------
+    shapes : Sequence[Shape]
+        The shapes to intersect.
+
+    Returns
+    -------
+    Shape
+        A new shape containing only the regions present in all input shapes.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, intersect_shape
+
+    >>> intersect_shape(  # doctest: +SKIP
+    ...     shapes=[square(4), circle(radius=2).translate([1, 1])]
+    ... )
+
+    .. render-example::
+        :name: intersect_shape
+        :example: intersect_shape(shapes=[square(4), circle(radius=2).translate([1, 1])])
+        :ghost: square(4)
+    """
+    from scadpy import (
+        Shape,
+        are_shape_parts_intersecting,
+        get_shape_part_bounds,
+        intersect_shape_parts,
+        unify_shape_parts,
+    )
+    from scadpy.core.assembly import intersect_assemblies
+
+    return intersect_assemblies(
+        assemblies=shapes,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        get_part_bounds=get_shape_part_bounds,
+        are_parts_intersecting=are_shape_parts_intersecting,
+        intersect_parts=lambda parts: intersect_shape_parts(
+            parts=parts,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        unify_parts=lambda parts: unify_shape_parts(
+            parts=parts,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        concat_parts=Shape.from_parts,
+    )

scadpy/d2/shape/combinations/intersect_shape_parts.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING
+
+from shapely import intersection_all  # pyright: ignore[reportUnknownVariableType]
+from shapely.geometry.polygon import Polygon
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def intersect_shape_parts(
+    parts: Sequence[Part[Polygon]],
+    make_assembly_from_parts: Callable[[Sequence[Part[Polygon]]], Shape],
+) -> Shape:
+    """Intersect a sequence of shape parts and return the resulting shape.
+
+    Shortcut for :func:`intersect_parts`.
+    See :func:`intersect_parts` for full documentation.
+
+    Parameters
+    ----------
+    parts : Sequence[Part[Polygon]]
+        The shape parts to intersect.
+    make_assembly_from_parts : Callable[[Sequence[Part[Polygon]]], Shape]
+        Factory function to build the resulting Shape from a sequence of parts.
+
+    Returns
+    -------
+    Shape
+        A new shape containing the geometric intersection of the input parts.
+
+    Examples
+    --------
+    >>> from scadpy import (
+    ...     square, circle, intersect_shape_parts, Shape
+    ... )
+
+    >>> intersect_shape_parts(  # doctest: +SKIP
+    ...     parts=(
+    ...         list(square(3)._parts)
+    ...         + list(circle(radius=1.5).translate([2, 2])._parts)
+    ...     ),
+    ...     make_assembly_from_parts=Shape.from_parts,
+    ... )
+
+    .. render-example::
+        :name: intersect_shape_parts_example
+        :example: intersect_shape_parts(parts=list(square(3)._parts) + list(circle(radius=1.5).translate([2, 2])._parts), make_assembly_from_parts=Shape.from_parts)
+        :ghost: concat_shape(shapes=[square(3), circle(radius=1.5).translate([2, 2])])
+    """
+    from scadpy import Part, are_shape_parts_intersecting, get_shape_part_bounds
+    from scadpy import intersect_parts, shapely_base_geometry_to_shapely_polygons
+
+    return intersect_parts(
+        parts=parts,
+        get_part_color=lambda p: p.color,
+        get_part_magnitude=lambda p: p.geometry.area,
+        get_part_bounds=get_shape_part_bounds,
+        are_parts_intersecting=are_shape_parts_intersecting,
+        get_part_geometry=lambda p: p.geometry,
+        intersect_geometries=lambda g: shapely_base_geometry_to_shapely_polygons(
+            intersection_all(g)
+        ),
+        make_part_from_geometry=Part[Polygon].from_geometry,
+        make_assembly_from_parts=make_assembly_from_parts,
+    )

scadpy/d2/shape/combinations/subtract_shape.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Shape
+
+
+@typechecked
+def subtract_shape(to_be_subtracted: Shape, to_subtract: Shape) -> Shape:
+    """Subtract one shape from another using boolean difference.
+
+    The geometry of ``to_subtract`` is removed from ``to_be_subtracted``.
+
+    Parameters
+    ----------
+    to_be_subtracted : Shape
+        The shape to subtract from.
+    to_subtract : Shape
+        The shape to subtract.
+
+    Returns
+    -------
+    Shape
+        A new shape with the geometry of ``to_subtract`` removed from ``to_be_subtracted``.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, subtract_shape
+
+    >>> subtract_shape(  # doctest: +SKIP
+    ...     to_be_subtracted=square(4), to_subtract=circle(radius=1)
+    ... )
+
+    .. render-example::
+        :name: subtract_shape
+        :example: subtract_shape(to_be_subtracted=square(4), to_subtract=circle(radius=1))
+        :ghost: square(4)
+    """
+    from scadpy import (
+        Shape,
+        are_shape_parts_intersecting,
+        get_shape_part_bounds,
+        intersect_shape_parts,
+        subtract_shape_parts,
+        unify_shape_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_shape_part_bounds,
+        are_parts_intersecting=are_shape_parts_intersecting,
+        subtract_parts=lambda part_base, part_cutter: subtract_shape_parts(
+            to_be_subtracted=part_base,
+            to_subtract=part_cutter,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        intersect_parts=lambda parts: intersect_shape_parts(
+            parts=parts,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        unify_parts=lambda parts: unify_shape_parts(
+            parts=parts,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+        concat_parts=Shape.from_parts,
+    )