ScadPy 0.1.0__py3-none-any.whl

scadpy/core/assembly/transformations/resize_vertex_coordinates.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+
+@typechecked
+def resize_vertex_coordinates(
+    vertex_coordinates: NDArray[np.float64],
+    size: Iterable[float | None],
+    n_dims: int,
+    auto: bool = False,
+    pivot: float | Iterable[float] | None = None,
+    vertex_filter: NDArray[np.bool_] | None = None,
+) -> NDArray[np.float64]:
+    """
+    Resize vertex coordinates to fit target dimensions.
+
+    Computes per-axis scale factors from the bounding box of
+    ``vertex_coordinates`` and ``size``, then delegates to
+    :func:`scale_vertex_coordinates`.
+
+    ``None`` entries in ``size`` mark axes to leave unchanged. When
+    ``auto=True``, those axes are scaled proportionally to the average
+    ratio of the defined axes instead.
+
+    Parameters
+    ----------
+    vertex_coordinates : NDArray[np.float64]
+        2D array of shape ``(n_vertices, n_dims)``.
+    size : Iterable[float | None]
+        Target dimensions. ``None`` for an axis means "leave unchanged"
+        (or "scale proportionally" when ``auto=True``). Broadcast rules
+        from :func:`resolve_vector` apply: a shorter iterable is padded
+        with ``None`` (no resize on missing axes).
+    n_dims : int
+        Number of coordinate dimensions. Used to broadcast ``size`` and
+        ``pivot`` to the correct length via :func:`resolve_vector`.
+    auto : bool, default=False
+        If ``True``, axes with ``None`` are scaled proportionally to the
+        average ratio of the defined axes.
+    pivot : float | Iterable[float] | None, default=None
+        The point relative to which scaling is applied. Defaults to the
+        center of the bounding box of ``vertex_coordinates``.
+    vertex_filter : NDArray[np.bool_] | None, default=None
+        Boolean array selecting which vertices are resized. If ``None``,
+        all vertices are resized.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Array of shape ``(n_vertices, n_dims)``, one row per vertex.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scadpy import resize_vertex_coordinates
+
+    Resize a 4×2 rectangle to 6×6:
+
+    >>> coordinates = np.array(
+    ...     [[0., 0.], [4., 0.], [4., 2.], [0., 2.]], dtype=np.float64
+    ... )
+    >>> result = resize_vertex_coordinates(coordinates, size=[6, 6], n_dims=2)
+    >>> (result.max(axis=0) - result.min(axis=0)).tolist()
+    [6.0, 6.0]
+
+    Freeze the Y axis (``None``):
+
+    >>> result = resize_vertex_coordinates(coordinates, size=[6, None], n_dims=2)
+    >>> (result.max(axis=0) - result.min(axis=0)).tolist()
+    [6.0, 2.0]
+
+    Scale the Y axis proportionally with ``auto=True``:
+
+    >>> result = resize_vertex_coordinates(
+    ...     coordinates, size=[6, None], n_dims=2, auto=True
+    ... )
+    >>> (result.max(axis=0) - result.min(axis=0)).tolist()
+    [6.0, 3.0]
+    """
+    from scadpy import resolve_vector, scale_vertex_coordinates
+
+    # Convert None → nan so resolve_vector can broadcast to n_dims.
+    # resolve_vector replaces nan with its default_value; using nan as
+    # default_value preserves the sentinel for frozen axes.
+    size_as_floats = [float("nan") if s is None else float(s) for s in size]
+    size_array = resolve_vector(size_as_floats, float("nan"), n_dims)
+
+    if len(vertex_coordinates) == 0:
+        return vertex_coordinates
+
+    bounds_min = vertex_coordinates.min(axis=0)
+    bounds_max = vertex_coordinates.max(axis=0)
+    current_size = bounds_max - bounds_min
+
+    if pivot is None:
+        effective_pivot = (bounds_min + bounds_max) / 2
+    else:
+        effective_pivot = np.array(resolve_vector(pivot, 0, n_dims))
+
+    defined_scales = [
+        s / c
+        for s, c in zip(size_array, current_size)
+        if not np.isnan(s) and c != 0
+    ]
+    auto_scale = sum(defined_scales) / len(defined_scales) if defined_scales else 1.0
+
+    scale_array = np.ones(n_dims, dtype=np.float64)
+    for i, (s, c) in enumerate(zip(size_array, current_size)):
+        if not np.isnan(s):
+            scale_array[i] = s / c if c != 0 else 1.0
+        elif auto:
+            scale_array[i] = auto_scale
+
+    return scale_vertex_coordinates(
+        vertex_coordinates, scale_array, effective_pivot, vertex_filter
+    )

scadpy/core/assembly/transformations/rotate_vertex_coordinates.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+
+@typechecked
+def rotate_vertex_coordinates(
+    vertex_coordinates: NDArray[np.float64],
+    rotation_matrix: NDArray[np.float64],
+    pivot: float | Iterable[float] = 0,
+    vertex_filter: NDArray[np.bool_] | None = None,
+) -> NDArray[np.float64]:
+    """
+    Rotate vertex coordinates using a precomputed rotation matrix and a pivot point.
+
+    Parameters
+    ----------
+    vertex_coordinates : NDArray[np.float64]
+        2D array of shape (n_vertices, dimensions).
+    rotation_matrix : NDArray[np.float64]
+        Square rotation matrix of shape (dimensions, dimensions).
+    pivot : float | Iterable[float], default=0
+        The point around which rotation is applied. If a single float is provided,
+        it will be broadcast to all coordinate dimensions. Defaults to the origin.
+    vertex_filter : NDArray[np.bool_] | None, default=None
+        Boolean array selecting which vertices are rotated. If ``None``, all vertices
+        are rotated.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Array of shape (n_vertices, dimensions), one row per vertex.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import rotate_vertex_coordinates, Shape
+
+    >>> polygon = Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])
+    >>> shape = Shape.from_geometries([polygon])
+    >>> angle = np.deg2rad(90)
+    >>> R = np.array([
+    ...     [np.cos(angle), -np.sin(angle)],
+    ...     [np.sin(angle), np.cos(angle)],
+    ... ])
+    >>> rotate_vertex_coordinates(
+    ...     shape.vertex_coordinates,
+    ...     R,
+    ...     pivot=[1, 1],
+    ... ).round(10) # doctest: +NORMALIZE_WHITESPACE
+    array([[2., 0.],
+           [2., 2.],
+           [0., 2.],
+           [0., 0.]])
+    """
+    from scadpy import resolve_vector
+
+    dimensions: int = vertex_coordinates.shape[1]
+    pivot_array = np.array(resolve_vector(pivot, 0, dimensions))
+
+    if vertex_filter is None:
+        return (vertex_coordinates - pivot_array) @ rotation_matrix.T + pivot_array
+
+    result = np.array(vertex_coordinates)
+    result[vertex_filter] = (
+        (vertex_coordinates[vertex_filter] - pivot_array) @ rotation_matrix.T + pivot_array
+    )
+    return result

scadpy/core/assembly/transformations/scale_vertex_coordinates.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+
+@typechecked
+def scale_vertex_coordinates(
+    vertex_coordinates: NDArray[np.float64],
+    scale: float | Iterable[float],
+    pivot: float | Iterable[float] = 0,
+    vertex_filter: NDArray[np.bool_] | None = None,
+) -> NDArray[np.float64]:
+    """
+    Scale vertex coordinates by a given factor or vector, relative to a pivot.
+
+    Parameters
+    ----------
+    vertex_coordinates : NDArray[np.float64]
+        2D array of shape (n_vertices, dimensions).
+    scale : float | Iterable[float]
+        The scaling factor(s) to apply. Its length should match the number of coordinate dimensions.
+        If a single float is provided, it will be broadcast to all coordinate dimensions.
+    pivot : float | Iterable[float], default=0
+        The point relative to which scaling is performed. If a single float is provided, it will be broadcast to all coordinate dimensions.
+        Defaults to 0 (the origin).
+    vertex_filter : NDArray[np.bool_] | None, default=None
+        Boolean array selecting which vertices are scaled. If ``None``, all vertices are scaled.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Array of shape (n_vertices, dimensions), one row per vertex.
+
+    Examples
+    --------
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import scale_vertex_coordinates, Shape
+
+    >>> polygon1 = Polygon(
+    ...     shell=[(0, 0), (2, 0), (2, 2), (0, 2)],
+    ...     holes=[[(0.5, 0.5), (1.5, 0.5), (1.5, 1.5), (0.5, 1.5)]]
+    ... )
+    >>> polygon2 = Polygon(
+    ...     shell=[(10, 10), (12, 10), (12, 12), (10, 12)]
+    ... )
+    >>> shape = Shape.from_geometries([polygon1, polygon2])
+    >>> scale_vertex_coordinates(
+    ...     shape.vertex_coordinates,
+    ...     scale=[10, 0.5],
+    ...     pivot=[1, 2]
+    ... ) # doctest: +NORMALIZE_WHITESPACE
+    array([[ -9.  ,   1.  ],
+           [ 11.  ,   1.  ],
+           [ 11.  ,   2.  ],
+           ...
+           [111.  ,   6.  ],
+           [111.  ,   7.  ],
+           [ 91.  ,   7.  ]])
+    """
+    from scadpy import resolve_vector
+
+    dimensions: int = vertex_coordinates.shape[1]
+
+    pivot_array = np.array(resolve_vector(pivot, 0, dimensions))
+    scale_array = np.array(resolve_vector(scale, 1, dimensions))
+
+    if vertex_filter is None:
+        return pivot_array + (vertex_coordinates - pivot_array) * scale_array
+
+    result = np.array(vertex_coordinates)
+    result[vertex_filter] = pivot_array + (vertex_coordinates[vertex_filter] - pivot_array) * scale_array
+    return result

scadpy/core/assembly/transformations/translate_vertex_coordinates.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+
+@typechecked
+def translate_vertex_coordinates(
+    vertex_coordinates: NDArray[np.float64],
+    translation: float | Iterable[float],
+    vertex_filter: NDArray[np.bool_] | None = None,
+) -> NDArray[np.float64]:
+    """
+    Translate vertex coordinates by a given vector.
+
+    Parameters
+    ----------
+    vertex_coordinates : NDArray[np.float64]
+        2D array of shape (n_vertices, dimensions).
+    translation : float | Iterable[float]
+        The translation vector to apply. Its length should match the number of coordinate dimensions.
+        If a single float is provided, it will be broadcast to all coordinate dimensions.
+    vertex_filter : NDArray[np.bool_] | None, default=None
+        Boolean array selecting which vertices are translated. If ``None``, all vertices
+        are translated.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Array of shape (n_vertices, dimensions), one row per vertex.
+
+    Examples
+    --------
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import translate_vertex_coordinates, Shape
+
+    >>> polygon1 = Polygon(
+    ...     shell=[(0, 0), (2, 0), (2, 2), (0, 2)],
+    ...     holes=[[(0.5, 0.5), (1.5, 0.5), (1.5, 1.5), (0.5, 1.5)]]
+    ... )
+    >>> polygon2 = Polygon(
+    ...     shell=[(10, 10), (12, 10), (12, 12), (10, 12)]
+    ... )
+    >>> shape = Shape.from_geometries([polygon1, polygon2])
+    >>> translate_vertex_coordinates(
+    ...     shape.vertex_coordinates,
+    ...     translation=[10, 20]
+    ... ) # doctest: +NORMALIZE_WHITESPACE
+    array([[10. , 20. ],
+           [12. , 20. ],
+           [12. , 22. ],
+           ...
+           [22. , 30. ],
+           [22. , 32. ],
+           [20. , 32. ]])
+    """
+    from scadpy import resolve_vector
+
+    dimensions: int = vertex_coordinates.shape[1]
+    translation_array = np.array(resolve_vector(translation, 0, dimensions))
+
+    if vertex_filter is None:
+        return vertex_coordinates + translation_array
+
+    result = np.array(vertex_coordinates)
+    result[vertex_filter] += translation_array
+    return result

scadpy/core/assembly/types/__init__.py

@@ -0,0 +1,7 @@
+__all__ = [
+    "Assembly",
+    "TopologyFilter",
+]
+
+from .assembly import Assembly
+from .topology_filter import TopologyFilter

scadpy/core/assembly/types/assembly.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from abc import ABC
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+
+
+class Assembly[G](ABC):
+    def __init__(self, *args: Any, **kwargs: Any):  # pyright: ignore[reportExplicitAny, reportAny]
+        super().__init__(*args, **kwargs)
+        self._parts: Sequence[Part[G]] = []

scadpy/core/assembly/types/topology_filter.py

@@ -0,0 +1,6 @@
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import NDArray
+
+type TopologyFilter[A] = NDArray[np.bool_] | Callable[[A], NDArray[np.bool_]]

scadpy/core/assembly/utils/__init__.py

@@ -0,0 +1,9 @@
+__all__ = [
+    "lookup_pairs",
+    "resolve_topology_filter",
+    "transform_filtered_parts",
+]
+
+from .lookup_pairs import lookup_pairs
+from .resolve_topology_filter import resolve_topology_filter
+from .transform_filtered_parts import transform_filtered_parts

scadpy/core/assembly/utils/lookup_pairs.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+
+@typechecked
+def lookup_pairs(
+    queries: NDArray[np.int64],
+    haystack: NDArray[np.int64],
+) -> NDArray[np.int64]:
+    """
+    For each queried pair, return its index in the haystack.
+
+    Each pair ``(a, b)`` is encoded as ``a * n + b`` where ``n`` is
+    ``max(haystack) + 1``, then looked up via binary search. This is
+    fully vectorized with no Python loops.
+
+    Parameters
+    ----------
+    queries : NDArray[np.int64]
+        2D array of shape ``(n_queries, 2)``. Pairs to look up.
+    haystack : NDArray[np.int64]
+        2D array of shape ``(n_items, 2)``. The reference pairs.
+        Each pair must appear exactly once.
+
+    Returns
+    -------
+    NDArray[np.int64]
+        1D array of shape ``(n_queries,)``. Each entry is the index
+        in ``haystack`` of the corresponding query pair.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scadpy import lookup_pairs
+
+    >>> haystack = np.array(
+    ...     [[0, 1], [1, 0], [1, 2], [2, 1], [2, 0], [0, 2]],
+    ...     dtype=np.int64,
+    ... )
+    >>> queries = np.array([[2, 0], [0, 1], [1, 2]], dtype=np.int64)
+    >>> lookup_pairs(queries, haystack)
+    array([4, 0, 2])
+    """
+    if len(queries) == 0:
+        return np.empty(0, dtype=np.int64)
+
+    n = int(haystack.max()) + 1
+    haystack_keys = haystack[:, 0] * n + haystack[:, 1]
+    sort_order = np.argsort(haystack_keys)
+    haystack_keys_sorted = haystack_keys[sort_order]
+
+    query_keys = queries[:, 0] * n + queries[:, 1]
+    return sort_order[np.searchsorted(haystack_keys_sorted, query_keys)]

scadpy/core/assembly/utils/resolve_topology_filter.py

@@ -0,0 +1,84 @@
+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 import TopologyFilter
+
+
+@typechecked
+def resolve_topology_filter[A](
+    assembly: A,
+    count: int,
+    topology_filter: TopologyFilter[A] | None,
+) -> NDArray[np.bool_] | None:
+    """
+    Resolve a topology filter into a boolean mask.
+
+    A topology filter can be either a precomputed boolean mask or a callable
+    that derives one from the assembly. This function normalizes both forms
+    into a concrete mask and validates its length against the expected
+    topology count (vertices, edges, parts, etc.).
+
+    Parameters
+    ----------
+    assembly : A
+        The assembly to pass to the filter if it is a callable.
+    topology_filter : TopologyFilter[A] | None
+        A boolean mask, a callable that produces one from the assembly,
+        or None. If None, the function returns None immediately.
+    count : int
+        The expected length of the resulting mask. Should match the number
+        of topological elements being filtered (e.g. vertex_count, edge_count,
+        part count).
+
+    Returns
+    -------
+    NDArray[np.bool_] | None
+        The resolved boolean mask, or None if topology_filter is None.
+
+    Raises
+    ------
+    ValueError
+        If the resolved mask length does not match the expected count.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scadpy import resolve_topology_filter
+
+    >>> # none passthrough
+    >>> resolve_topology_filter("any", 4, None) is None
+    True
+
+    >>> # direct mask
+    >>> mask = np.array([True, False, True, False])
+    >>> resolve_topology_filter("any", 4, mask)
+    array([ True, False,  True, False])
+
+    >>> # callable filter
+    >>> resolve_topology_filter(
+    ...     "hello", 1, lambda s: np.array([len(s) > 3])
+    ... )
+    array([ True])
+
+    >>> # mismatched count
+    >>> resolve_topology_filter(
+    ...     "any", 5, np.array([True, False])
+    ... )  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+        ...
+    ValueError: Topology filter length (2) does not match...
+    """
+    if topology_filter is None:
+        return None
+    mask = topology_filter(assembly) if callable(topology_filter) else topology_filter
+    if len(mask) != count:
+        raise ValueError(
+            f"Topology filter length ({len(mask)}) does not match expected count ({count})."
+        )
+    return mask

scadpy/core/assembly/utils/transform_filtered_parts.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING
+
+import numpy as np
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Part, TopologyFilter
+
+
+@typechecked
+def transform_filtered_parts[A, G](
+    assembly: A,
+    parts: Sequence[Part[G]],
+    part_filter: TopologyFilter[A] | None,
+    transform: Callable[[Sequence[Part[G]]], Sequence[Part[G]]],
+    concat_parts: Callable[[Sequence[Part[G]]], A],
+) -> A:
+    """Apply a transformation to a filtered subset of parts, keeping the rest unchanged.
+
+    Parameters
+    ----------
+    assembly : A
+        The assembly used to evaluate *part_filter*.
+    parts : Sequence[Part[G]]
+        All parts of the assembly.
+    part_filter : TopologyFilter[A] | None
+        Optional filter selecting which parts to transform. If ``None``, all
+        parts are transformed.
+    transform : Callable[[Sequence[Part[G]]], Sequence[Part[G]]]
+        Function applied to the selected parts.
+    concat_parts : Callable[[Sequence[Part[G]]], A]
+        Function that assembles transformed and untouched parts into a new
+        assembly of type *A*.
+
+    Returns
+    -------
+    A
+        New assembly with the filtered parts transformed and the rest unchanged.
+    """
+    from scadpy import resolve_topology_filter
+
+    mask = resolve_topology_filter(
+        assembly=assembly, count=len(parts), topology_filter=part_filter
+    )
+    if mask is None:
+        mask = np.ones(len(parts), dtype=bool)
+
+    selected = [p for p, m in zip(parts, mask) if m]
+    unselected = [p for p, m in zip(parts, mask) if not m]
+
+    transformed = transform(selected)
+    return concat_parts([*transformed, *unselected])

scadpy/core/component/__init__.py

@@ -0,0 +1,3 @@
+from .exporters import *  # noqa: F403
+from .features import *  # noqa: F403
+from .utils import *  # noqa: F403

scadpy/core/component/exporters/__init__.py

@@ -0,0 +1,7 @@
+__all__ = [
+    "map_component_to_html_file",
+    "map_component_to_screen",
+]
+
+from .map_component_to_html_file import map_component_to_html_file
+from .map_component_to_screen import map_component_to_screen

scadpy/core/component/exporters/map_component_to_html_file.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import cast
+
+from IPython.core.display import HTML
+from typeguard import typechecked
+
+
+@typechecked
+def map_component_to_html_file[Component](
+    component: Component, path: str, to_html: Callable[[Component], HTML]
+) -> int:
+    """
+    Export a component to an HTML file.
+
+    This function uses dependency injection for the HTML conversion, making it
+    suitable for any component type that can be represented as HTML. The HTML
+    is written to the specified file path.
+
+    Parameters
+    ----------
+    component : Component
+        The component to export.
+    path : str
+        The file path where the HTML will be written.
+    to_html : Callable[[Component], HTML]
+        Function that converts the component to an IPython HTML object.
+
+    Returns
+    -------
+    int
+        The number of characters written to the file.
+
+    Examples
+    --------
+    >>> from IPython.core.display import HTML
+    >>> from scadpy import map_component_to_html_file
+    ...
+    >>> map_component_to_html_file(
+    ...     "Hello, World!",
+    ...     "test.html",
+    ...     to_html=lambda c: HTML(f"<h1>{c}</h1>")
+    ... ) > 0 # doctest: +SKIP
+    True
+    """
+    return open(path, "w", encoding="utf-8").write(cast(str, to_html(component).data))