ScadPy 0.1.0__py3-none-any.whl

scadpy/d2/shape/topologies/corner/are_shape_corners_convex.py

@@ -0,0 +1,75 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def are_shape_corners_convex(
+    shape: Shape,
+) -> NDArray[np.bool_]:
+    """
+    For each corner in the shape, return whether it is convex.
+
+    A corner is convex if the shape turns left at that vertex on an exterior
+    ring (counter-clockwise winding). Concave corners turn right. Interior
+    rings have their orientation inverted accordingly.
+
+    Use :func:`get_shape_corner_angles` to get the magnitude of the turning
+    angle independently of convexity.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract corner convexity from.
+
+    Returns
+    -------
+    NDArray[np.bool_]
+        1D boolean array of shape (n_corners,). True if convex, False if concave.
+
+    Examples
+    --------
+    >>> from scadpy import are_shape_corners_convex, polygon
+
+    >>> # arrow: 5 convex corners (tip and sides)
+    >>> # + 2 concave corners (the tail notch)
+    >>> arrow = polygon(
+    ...     [(0, 1), (3, 0), (5, 2), (3, 4),
+    ...      (0, 3), (1, 2.5), (1, 1.5)]
+    ... )
+    >>> are_shape_corners_convex(arrow).tolist()
+    [True, True, True, True, True, False, False]
+    """
+    corner_to_vertex = shape.corner_to_vertex
+    coords = shape.vertex_coordinates
+
+    if len(corner_to_vertex) == 0:
+        return np.empty(0, dtype=np.bool_)
+
+    prev_coords = coords[corner_to_vertex[:, 0]]
+    curr_coords = coords[corner_to_vertex[:, 1]]
+    next_coords = coords[corner_to_vertex[:, 2]]
+
+    v_in = curr_coords - prev_coords
+    v_out = next_coords - curr_coords
+
+    # 2D cross product: positive = left turn (convex on CCW ring)
+    cross = v_in[:, 0] * v_out[:, 1] - v_in[:, 1] * v_out[:, 0]
+
+    is_convex = cross > 0
+
+    # interior rings (CW in shapely) have inverted orientation — flip convexity
+    ring_types = shape.ring_types
+    vertex_to_ring = shape.vertex_to_ring
+    corner_ring_indices = vertex_to_ring[corner_to_vertex[:, 1]]
+    is_interior = ring_types[corner_ring_indices] == "interior"
+    is_convex = np.where(is_interior, ~is_convex, is_convex)
+
+    return is_convex

scadpy/d2/shape/topologies/corner/get_shape_corner_angles.py

@@ -0,0 +1,58 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_corner_angles(
+    shape: Shape,
+) -> NDArray[np.float64]:
+    """
+    For each corner in the shape, return its interior angle in degrees.
+
+    The angle is always positive, in the range (0°, 180°). It represents
+    the turning angle at the corner, regardless of whether the corner is
+    convex or concave. Use :func:`are_shape_corners_convex` to distinguish
+    convex corners from concave ones.
+
+    The angle is computed as the absolute value of the signed angle from the
+    incoming edge to the outgoing edge at each corner, using the 2D cross
+    product to determine orientation.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract corner angles from.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        1D array of shape (n_corners,), one angle per corner, in degrees.
+        All values are in the range (0°, 180°).
+
+    Examples
+    --------
+    >>> from scadpy import get_shape_corner_angles, polygon
+
+    >>> # arrow: 5 convex corners + 2 concave corners,
+    >>> # all with different angles
+    >>> arrow = polygon(
+    ...     [(0, 1), (3, 0), (5, 2), (3, 4),
+    ...      (0, 3), (1, 2.5), (1, 1.5)]
+    ... )
+    >>> get_shape_corner_angles(arrow).round(2).tolist()
+    [135.0, 63.43, 90.0, 63.43, 135.0, 63.43, 63.43]
+    """
+    from scadpy.core.assembly import get_assembly_face_corner_angles
+
+    return get_assembly_face_corner_angles(
+        corner_to_vertex=shape.corner_to_vertex,
+        vertex_coordinates=shape.vertex_coordinates,
+    )

scadpy/d2/shape/topologies/corner/get_shape_corner_normals.py

@@ -0,0 +1,82 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_corner_normals(
+    shape: Shape,
+    epsilon: float = 1e-10,
+) -> NDArray[np.float64]:
+    """
+    For each corner in the shape, return its outward unit normal.
+
+    The normal is the bisector of the outward edge normals at the corner,
+    oriented to point away from the filled material. It points outward for
+    convex corners and inward for concave ones, consistently with
+    :func:`are_shape_corners_convex`.
+
+    Each edge normal is the 90° CW rotation of the edge direction, which
+    points outward for CCW (exterior) rings. The bisector is then the
+    normalized average of the two adjacent edge normals. Its sign is
+    corrected using :func:`are_shape_corners_convex`, which already accounts
+    for ring orientation (interior vs exterior), so no separate handling
+    is needed here.
+
+    For degenerate 180° corners (straight edges) where the bisector
+    vanishes, the normal falls back to the outward edge normal of the
+    incoming edge (90° CW rotation).
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract corner normals from.
+    epsilon : float, optional
+        Threshold below which the bisector norm is considered degenerate
+        (straight 180° corner). Defaults to ``1e-10``.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        2D array of shape (n_corners, 2). Each row is a unit vector ``[nx, ny]``.
+
+    Examples
+    --------
+    >>> from scadpy import (
+    ...     get_shape_corner_normals,
+    ...     are_shape_corners_convex,
+    ...     polygon,
+    ... )
+
+    >>> # arrow: 5 convex corners (normals point outward)
+    >>> # + 2 concave corners (normals point inward,
+    >>> # into the tail notch — x component is positive)
+    >>> arrow = polygon(
+    ...     [(0, 1), (3, 0), (5, 2), (3, 4),
+    ...      (0, 3), (1, 2.5), (1, 1.5)]
+    ... )
+    >>> normals = get_shape_corner_normals(arrow)
+    >>> normals.round(4)  # doctest: +NORMALIZE_WHITESPACE
+    array([[-0.9975, -0.0709],
+           [ 0.2298, -0.9732],
+           [ 1.    ,  0.    ],
+           [ 0.2298,  0.9732],
+           [-0.9975,  0.0709],
+           [ 0.8507,  0.5257],
+           [ 0.8507, -0.5257]])
+    """
+    from scadpy.core.assembly import get_assembly_face_corner_normals
+
+    return get_assembly_face_corner_normals(
+        corner_to_vertex=shape.corner_to_vertex,
+        vertex_coordinates=shape.vertex_coordinates,
+        are_corners_convex=shape.are_corners_convex,
+        epsilon=epsilon,
+    )

scadpy/d2/shape/topologies/corner/get_shape_corner_to_incoming_directed_edge.py

@@ -0,0 +1,39 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_corner_to_incoming_directed_edge(
+    shape: Shape,
+) -> NDArray[np.int64]:
+    """
+    For each corner in the shape, return the index of its incoming directed edge.
+
+    See :func:`get_assembly_face_corner_to_incoming_directed_edge` for full documentation.
+
+    Examples
+    --------
+    >>> from scadpy import (
+    ...     get_shape_corner_to_incoming_directed_edge, polygon
+    ... )
+
+    >>> # triangle: corners (2,0,1), (0,1,2), (1,2,0)
+    >>> # incoming: 2→0, 0→1, 1→2
+    >>> triangle = polygon([(0, 0), (1, 0), (0.5, 1)])
+    >>> get_shape_corner_to_incoming_directed_edge(triangle)
+    array([4, 0, 2])
+    """
+    from scadpy.core.assembly import get_assembly_face_corner_to_incoming_directed_edge
+
+    return get_assembly_face_corner_to_incoming_directed_edge(
+        corner_to_vertex=shape.corner_to_vertex,
+        directed_edge_to_vertex=shape.directed_edge_to_vertex,
+    )

scadpy/d2/shape/topologies/corner/get_shape_corner_to_outgoing_directed_edge.py

@@ -0,0 +1,39 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_corner_to_outgoing_directed_edge(
+    shape: Shape,
+) -> NDArray[np.int64]:
+    """
+    For each corner in the shape, return the index of its outgoing directed edge.
+
+    See :func:`get_assembly_face_corner_to_outgoing_directed_edge` for full documentation.
+
+    Examples
+    --------
+    >>> from scadpy import (
+    ...     get_shape_corner_to_outgoing_directed_edge, polygon
+    ... )
+
+    >>> # triangle: corners (2,0,1), (0,1,2), (1,2,0)
+    >>> # outgoing: 0→1, 1→2, 2→0
+    >>> triangle = polygon([(0, 0), (1, 0), (0.5, 1)])
+    >>> get_shape_corner_to_outgoing_directed_edge(triangle)
+    array([0, 2, 4])
+    """
+    from scadpy.core.assembly import get_assembly_face_corner_to_outgoing_directed_edge
+
+    return get_assembly_face_corner_to_outgoing_directed_edge(
+        corner_to_vertex=shape.corner_to_vertex,
+        directed_edge_to_vertex=shape.directed_edge_to_vertex,
+    )

scadpy/d2/shape/topologies/corner/get_shape_corner_to_vertex.py

@@ -0,0 +1,65 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_corner_to_vertex(
+    shape: Shape,
+) -> NDArray[np.int64]:
+    """
+    For each corner in the shape, return its three vertex indices (prev, curr, next).
+
+    A corner is defined by three consecutive vertices on a ring. Each ring of ``n``
+    vertices yields ``n`` corners (the ring is treated as cyclic).
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract corner vertex indices from.
+
+    Returns
+    -------
+    NDArray[np.int64]
+        2D array of shape (n_corners, 3). Each row contains the indices
+        ``[prev, curr, next]`` into the shape's global vertex array.
+
+    Examples
+    --------
+    >>> from scadpy import get_shape_corner_to_vertex, polygon
+
+    >>> triangle = polygon([(0, 0), (1, 0), (0.5, 1)])
+    >>> get_shape_corner_to_vertex(  # doctest: +NORMALIZE_WHITESPACE
+    ...     triangle
+    ... )
+    array([[2, 0, 1],
+           [0, 1, 2],
+           [1, 2, 0]])
+    """
+    vertex_to_ring = shape.vertex_to_ring
+
+    if len(vertex_to_ring) == 0:
+        return np.empty((0, 3), dtype=np.int64)
+
+    indices = np.arange(len(vertex_to_ring), dtype=np.int64)
+
+    # for each vertex, prev and next are within the same ring (cyclic)
+    # shift by +1 and -1 within each ring using modular arithmetic per ring
+    ring_starts = np.searchsorted(vertex_to_ring, np.arange(vertex_to_ring[-1] + 1))
+    ring_sizes = np.diff(np.append(ring_starts, len(vertex_to_ring)))
+
+    # offset of each vertex within its ring
+    offsets = indices - ring_starts[vertex_to_ring]
+    ring_size_per_vertex = ring_sizes[vertex_to_ring]
+
+    prev_indices = ring_starts[vertex_to_ring] + (offsets - 1) % ring_size_per_vertex
+    next_indices = ring_starts[vertex_to_ring] + (offsets + 1) % ring_size_per_vertex
+
+    return np.stack([prev_indices, indices, next_indices], axis=1)

scadpy/d2/shape/topologies/directed_edge/__init__.py

@@ -0,0 +1,11 @@
+__all__ = [
+    "get_shape_directed_edge_directions",
+    "get_shape_directed_edge_to_corner",
+    "get_shape_directed_edge_to_edge",
+    "get_shape_directed_edge_to_vertex",
+]
+
+from .get_shape_directed_edge_directions import get_shape_directed_edge_directions
+from .get_shape_directed_edge_to_corner import get_shape_directed_edge_to_corner
+from .get_shape_directed_edge_to_edge import get_shape_directed_edge_to_edge
+from .get_shape_directed_edge_to_vertex import get_shape_directed_edge_to_vertex

scadpy/d2/shape/topologies/directed_edge/get_shape_directed_edge_directions.py

@@ -0,0 +1,44 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_directed_edge_directions(
+    shape: Shape,
+) -> NDArray[np.float64]:
+    """
+    For each directed edge in the shape, return its unit direction vector.
+
+    See :func:`get_assembly_directed_edge_directions` for full documentation.
+
+    Examples
+    --------
+    >>> from scadpy import get_shape_directed_edge_directions, square
+
+    >>> # unit square: 4 edges → 8 directed edges,
+    >>> # forward then backward interleaved
+    >>> square_shape = square(1)
+    >>> get_shape_directed_edge_directions(square_shape).round(4)
+    array([[ 1.,  0.],
+           [-1.,  0.],
+           [ 0.,  1.],
+           [ 0., -1.],
+           [-1.,  0.],
+           [ 1.,  0.],
+           [ 0., -1.],
+           [ 0.,  1.]])
+    """
+    from scadpy.core.assembly import get_assembly_directed_edge_directions
+
+    return get_assembly_directed_edge_directions(
+        directed_edge_to_vertex=shape.directed_edge_to_vertex,
+        vertex_coordinates=shape.vertex_coordinates,
+    )

scadpy/d2/shape/topologies/directed_edge/get_shape_directed_edge_to_corner.py

@@ -0,0 +1,41 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_directed_edge_to_corner(
+    shape: Shape,
+) -> NDArray[np.int64]:
+    """
+    For each directed edge in the shape, return its source and target corner indices.
+
+    See :func:`get_assembly_face_directed_edge_to_corner` for full documentation.
+
+    Examples
+    --------
+    >>> from scadpy import get_shape_directed_edge_to_corner, polygon
+
+    >>> # triangle: corners (2,0,1)=0, (0,1,2)=1, (1,2,0)=2
+    >>> triangle = polygon([(0, 0), (1, 0), (0.5, 1)])
+    >>> get_shape_directed_edge_to_corner(triangle)
+    array([[0, 1],
+           [1, 0],
+           [1, 2],
+           [2, 1],
+           [2, 0],
+           [0, 2]])
+    """
+    from scadpy.core.assembly import get_assembly_face_directed_edge_to_corner
+
+    return get_assembly_face_directed_edge_to_corner(
+        corner_to_outgoing_directed_edge=shape.corner_to_outgoing_directed_edge,
+        corner_to_incoming_directed_edge=shape.corner_to_incoming_directed_edge,
+    )

scadpy/d2/shape/topologies/directed_edge/get_shape_directed_edge_to_edge.py

@@ -0,0 +1,51 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_directed_edge_to_edge(
+    shape: Shape,
+) -> NDArray[np.int64]:
+    """
+    For each directed edge in the shape, return the index of its parent undirected edge.
+
+    Since directed edges are interleaved (``directed_edge 2i`` and
+    ``directed_edge 2i+1`` both belong to ``edge i``), the mapping is:
+    ``edge index = directed_edge index // 2``.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract directed edge-to-edge indices from.
+
+    Returns
+    -------
+    NDArray[np.int64]
+        1D array of shape ``(2 * n_edges,)``. Each entry is the index of
+        the parent undirected edge.
+
+    Examples
+    --------
+    >>> from scadpy import get_shape_directed_edge_to_edge, polygon, square
+
+    >>> # triangle: 3 edges → 6 directed edges
+    >>> triangle = polygon([(0, 0), (1, 0), (0.5, 1)])
+    >>> get_shape_directed_edge_to_edge(triangle)
+    array([0, 0, 1, 1, 2, 2])
+
+    >>> # square: 4 edges → 8 directed edges
+    >>> square_shape = square(1)
+    >>> get_shape_directed_edge_to_edge(square_shape)
+    array([0, 0, 1, 1, 2, 2, 3, 3])
+    """
+    from scadpy.core.assembly import get_assembly_directed_edge_to_edge
+
+    return get_assembly_directed_edge_to_edge(n_edges=len(shape.edge_to_vertex))

scadpy/d2/shape/topologies/directed_edge/get_shape_directed_edge_to_vertex.py

@@ -0,0 +1,63 @@
+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.d2.shape import Shape
+
+
+
+@typechecked
+def get_shape_directed_edge_to_vertex(
+    shape: Shape,
+) -> NDArray[np.int64]:
+    """
+    For each directed edge in the shape, return the indices of its start and end vertices.
+
+    Each undirected edge ``i`` gives rise to two directed edges, interleaved:
+
+    - ``directed_edge 2i``   : forward  → ``[start, end]`` (ring winding order)
+    - ``directed_edge 2i+1`` : backward → ``[end, start]``
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract directed edge-to-vertex indices from.
+
+    Returns
+    -------
+    NDArray[np.int64]
+        2D array of shape ``(2 * n_edges, 2)``. Each row is
+        ``[start_vertex, end_vertex]`` for the directed edge.
+
+    Examples
+    --------
+    >>> from scadpy import (
+    ...     get_shape_directed_edge_to_vertex, polygon, square
+    ... )
+
+    >>> # triangle: 3 edges → 6 directed edges
+    >>> # (forward/backward interleaved)
+    >>> triangle = polygon([(0, 0), (1, 0), (0.5, 1)])
+    >>> get_shape_directed_edge_to_vertex(triangle)
+    array([[0, 1],
+           [1, 0],
+           [1, 2],
+           [2, 1],
+           [2, 0],
+           [0, 2]])
+
+    >>> # square: 4 edges → 8 directed edges
+    >>> square_shape = square(1)
+    >>> get_shape_directed_edge_to_vertex(square_shape).shape
+    (8, 2)
+    """
+    from scadpy.core.assembly import get_assembly_directed_edge_to_vertex
+
+    return get_assembly_directed_edge_to_vertex(
+        edge_to_vertex=shape.edge_to_vertex,
+    )

scadpy/d2/shape/topologies/edge/__init__.py

@@ -0,0 +1,11 @@
+__all__ = [
+    "get_shape_edge_lengths",
+    "get_shape_edge_midpoints",
+    "get_shape_edge_normals",
+    "get_shape_edge_to_vertex",
+]
+
+from .get_shape_edge_lengths import get_shape_edge_lengths
+from .get_shape_edge_midpoints import get_shape_edge_midpoints
+from .get_shape_edge_normals import get_shape_edge_normals
+from .get_shape_edge_to_vertex import get_shape_edge_to_vertex

scadpy/d2/shape/topologies/edge/get_shape_edge_lengths.py

@@ -0,0 +1,43 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_edge_lengths(
+    shape: Shape,
+) -> NDArray[np.float64]:
+    """
+    For each edge in the shape, return its length.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract edge lengths from.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        1D array of shape ``(n_edges,)``, one length per edge.
+
+    Examples
+    --------
+    >>> from scadpy import get_shape_edge_lengths, square
+
+    >>> square_shape = square(2)
+    >>> get_shape_edge_lengths(square_shape)
+    array([2., 2., 2., 2.])
+    """
+    from scadpy.core.assembly import get_assembly_edge_lengths
+
+    return get_assembly_edge_lengths(
+        edge_to_vertex=shape.edge_to_vertex,
+        vertex_coordinates=shape.vertex_coordinates,
+    )

scadpy/d2/shape/topologies/edge/get_shape_edge_midpoints.py

@@ -0,0 +1,46 @@
+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.d2.shape import Shape
+
+
+@typechecked
+def get_shape_edge_midpoints(
+    shape: Shape,
+) -> NDArray[np.float64]:
+    """
+    For each edge in the shape, return the midpoint between its two vertices.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to extract edge midpoints from.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        2D array of shape ``(n_edges, 2)``, one midpoint per edge.
+
+    Examples
+    --------
+    >>> from scadpy import get_shape_edge_midpoints, square
+
+    >>> square_shape = square(2)
+    >>> get_shape_edge_midpoints(square_shape)
+    array([[ 0., -1.],
+           [ 1.,  0.],
+           [ 0.,  1.],
+           [-1.,  0.]])
+    """
+    from scadpy.core.assembly import get_assembly_edge_midpoints
+
+    return get_assembly_edge_midpoints(
+        edge_to_vertex=shape.edge_to_vertex,
+        vertex_coordinates=shape.vertex_coordinates,
+    )