ScadPy 0.1.0__py3-none-any.whl

scadpy/d2/shape/features/is_shape_empty.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Shape
+
+
+@typechecked
+def is_shape_empty(shape: Shape) -> bool:
+    """
+    Return whether the shape has no vertices.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to check.
+
+    Returns
+    -------
+    bool
+        True if the shape has no vertices, False otherwise.
+
+    Examples
+    --------
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import Shape, is_shape_empty
+
+    >>> is_shape_empty(Shape.from_parts([]))
+    True
+
+    >>> polygon = Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])
+    >>> is_shape_empty(Shape.from_geometry(polygon))
+    False
+    """
+    return len(shape.vertex_coordinates) == 0

scadpy/d2/shape/importers/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    "map_dxf_to_shape",
+    "map_geometries_to_shape",
+    "map_geometry_to_shape",
+    "map_parts_to_shape",
+    "map_svg_to_shape",
+]
+
+from .map_dxf_to_shape import map_dxf_to_shape
+from .map_geometries_to_shape import map_geometries_to_shape
+from .map_geometry_to_shape import map_geometry_to_shape
+from .map_parts_to_shape import map_parts_to_shape
+from .map_svg_to_shape import map_svg_to_shape

scadpy/d2/shape/importers/map_dxf_to_shape.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from io import BytesIO
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+from urllib.request import Request, urlopen
+
+from trimesh import load
+from trimesh.path import Path2D
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def map_dxf_to_shape(source: str | Path) -> Shape:
+    """Load a 2D shape from a DXF file or URL.
+
+    Closed paths in the DXF are converted to filled polygons. Open paths
+    (lines, arcs, splines that do not form a closed region) are ignored.
+    ``source`` can be a local file path or an ``http``/``https`` URL.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to a local ``.dxf`` file or an HTTP/HTTPS URL pointing to one.
+
+    Returns
+    -------
+    Shape
+        A new shape whose parts correspond to the closed filled regions
+        found in the DXF.
+
+    Examples
+    --------
+    >>> from scadpy import map_dxf_to_shape
+
+    >>> map_dxf_to_shape("https://raw.githubusercontent.com/mikedh/trimesh/main/models/2D/wrench.dxf")  # doctest: +SKIP
+
+    .. render-example::
+        :name: map_dxf_to_shape
+        :example: map_dxf_to_shape("https://raw.githubusercontent.com/mikedh/trimesh/main/models/2D/wrench.dxf")
+    """
+    from scadpy import map_geometries_to_shape
+
+    if isinstance(source, str) and source.startswith(("http://", "https://")):
+        req = Request(source, headers={"User-Agent": "ScadPy"})
+        with urlopen(req) as response:
+            data = BytesIO(response.read())
+        path = cast(Path2D, load(data, file_type="dxf"))
+    else:
+        path = cast(Path2D, load(source))
+
+    return map_geometries_to_shape(list(path.polygons_full))

scadpy/d2/shape/importers/map_geometries_to_shape.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from shapely.geometry import Polygon
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def map_geometries_to_shape(geometries: Sequence[Polygon]) -> Shape:
+    """Map a sequence of polygons to a shape.
+
+    Each polygon is validated and oriented via :func:`map_parts_to_shape`.
+
+    Parameters
+    ----------
+    geometries : Sequence[Polygon]
+        The polygons to map.
+
+    Returns
+    -------
+    Shape
+        A new shape containing all valid, oriented polygons.
+
+    Examples
+    --------
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import map_geometries_to_shape
+
+    >>> map_geometries_to_shape(  # doctest: +SKIP
+    ...     [Polygon([(0, 0), (4, 0), (4, 4), (0, 4)])]
+    ... )
+
+    .. render-example::
+        :name: map_geometries_to_shape
+        :example: map_geometries_to_shape([Polygon([(0, 0), (4, 0), (4, 4), (0, 4)])])
+    """
+    from scadpy.core.part import Part
+    from scadpy.d2.shape import Shape
+
+    return Shape.from_parts([Part[Polygon].from_geometry(g) for g in geometries])

scadpy/d2/shape/importers/map_geometry_to_shape.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shapely.geometry import Polygon
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def map_geometry_to_shape(geometry: Polygon) -> Shape:
+    """Map a single polygon to a shape.
+
+    Shortcut for :func:`map_geometries_to_shape` with a single polygon.
+
+    Parameters
+    ----------
+    geometry : Polygon
+        The polygon to map.
+
+    Returns
+    -------
+    Shape
+        A new shape containing the single valid, oriented polygon.
+
+    Examples
+    --------
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import map_geometry_to_shape
+
+    >>> map_geometry_to_shape(  # doctest: +SKIP
+    ...     Polygon([(0, 0), (4, 0), (4, 4), (0, 4)])
+    ... )
+
+    .. render-example::
+        :name: map_geometry_to_shape
+        :example: map_geometry_to_shape(Polygon([(0, 0), (4, 0), (4, 4), (0, 4)]))
+    """
+    from scadpy.d2.shape.importers import map_geometries_to_shape
+
+    return map_geometries_to_shape([geometry])

scadpy/d2/shape/importers/map_parts_to_shape.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from shapely.geometry import Polygon
+from shapely.validation import make_valid
+from typeguard import typechecked
+
+from scadpy.d2.shape.types.utils import shapely_base_geometry_to_shapely_polygons
+
+if TYPE_CHECKING:
+    from scadpy import Part, Shape
+
+
+@typechecked
+def map_parts_to_shape(
+    parts: Sequence[Part[Polygon]],
+) -> Shape:
+    """Map a sequence of parts to a shape, repairing and orienting each polygon.
+
+    Each polygon is validated using :func:`shapely.validation.make_valid`. If a
+    polygon is invalid, it is repaired and may be split into multiple valid polygons.
+    All resulting polygons are oriented counter-clockwise (exterior) and clockwise
+    (holes) using :func:`shapely.geometry.polygon.orient`.
+
+    Parameters
+    ----------
+    parts : Sequence[Part[Polygon]]
+        The parts to map. Each part holds a Shapely polygon and a color.
+
+    Returns
+    -------
+    Shape
+        A new shape containing all valid, oriented polygons from the input parts.
+
+    Examples
+    --------
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import map_parts_to_shape
+    >>> from scadpy.core.part import Part
+
+    >>> map_parts_to_shape(  # doctest: +SKIP
+    ...     [Part.from_geometry(Polygon([(0, 0), (4, 0), (4, 4), (0, 4)]))]
+    ... )
+
+    .. render-example::
+        :name: map_parts_to_shape
+        :example: map_parts_to_shape([Part.from_geometry(Polygon([(0, 0), (4, 0), (4, 4), (0, 4)]))])
+    """
+    from scadpy.core.part import Part
+    from scadpy.d2.shape import Shape
+
+    validated: list[Part[Polygon]] = []
+    for part in parts:
+        geom = make_valid(part.geometry) if not part.geometry.is_valid else part.geometry
+        for polygon in shapely_base_geometry_to_shapely_polygons(geom):
+            validated.append(Part.from_geometry(polygon, part.color))
+
+    shape = Shape()
+    shape._parts = validated
+    return shape

scadpy/d2/shape/importers/map_svg_to_shape.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from io import BytesIO
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+from urllib.request import Request, urlopen
+
+from trimesh import load
+from trimesh.path import Path2D
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def map_svg_to_shape(source: str | Path) -> Shape:
+    """Load a 2D shape from an SVG file or URL.
+
+    Closed paths in the SVG are converted to filled polygons. Open paths
+    and decorative elements (text, images, gradients) are ignored.
+    ``source`` can be a local file path or an ``http``/``https`` URL.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to a local ``.svg`` file or an HTTP/HTTPS URL pointing to one.
+
+    Returns
+    -------
+    Shape
+        A new shape whose parts correspond to the closed filled regions
+        found in the SVG.
+
+    Examples
+    --------
+    >>> from scadpy import map_svg_to_shape
+
+    >>> map_svg_to_shape("https://upload.wikimedia.org/wikipedia/commons/0/04/Pentagon.svg")  # doctest: +SKIP
+
+    .. render-example::
+        :name: map_svg_to_shape
+        :example: map_svg_to_shape("https://upload.wikimedia.org/wikipedia/commons/0/04/Pentagon.svg")
+    """
+    from scadpy import map_geometries_to_shape
+
+    if isinstance(source, str) and source.startswith(("http://", "https://")):
+        req = Request(source, headers={"User-Agent": "ScadPy"})
+        with urlopen(req) as response:
+            data = BytesIO(response.read())
+        path = cast(Path2D, load(data, file_type="svg"))
+    else:
+        path = cast(Path2D, load(source))
+
+    return map_geometries_to_shape(list(path.polygons_full))

scadpy/d2/shape/primitives/__init__.py

@@ -0,0 +1,6 @@
+__all__ = ["circle", "polygon", "rectangle", "square"]
+
+from .circle import circle
+from .polygon import polygon
+from .rectangle import rectangle
+from .square import square

scadpy/d2/shape/primitives/circle.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def circle(radius: float, segment_count: int = 64) -> Shape:
+    """
+    Create a circle approximated by a polygon.
+
+    Parameters
+    ----------
+    radius : float
+        The radius of the circle. Must be strictly positive.
+    segment_count : int, optional
+        The number of segments used to approximate the circle.
+        Higher values produce a smoother shape. Default is 64.
+
+    Returns
+    -------
+    Shape
+        A :class:`~scadpy.d2.shape.types.Shape` object representing the approximated circle.
+
+    Notes
+    -----
+    - The circle is centered at the origin (0, 0).
+    - The more segments, the smoother the approximation.
+
+    Examples
+    --------
+    >>> from scadpy import circle
+
+    >>> # circle of radius 5 with default resolution (64 vertices)
+    >>> x = circle(5)
+    >>> len(x.vertex_coordinates)
+    64
+
+    >>> # circle of radius 3 with low resolution
+    >>> x = circle(3, segment_count=8)
+    >>> coords = x.vertex_coordinates[:4]
+    >>> coords.round(2)  # doctest: +NORMALIZE_WHITESPACE
+    array([[ 3.  ,  0.  ],
+           [ 2.12,  2.12],
+           [ 0.  ,  3.  ],
+           [-2.12,  2.12]])
+
+    >>> # invalid circle (radius <= 0)
+    >>> circle(0)
+    Traceback (most recent call last):
+        ...
+    ValueError: Circle radius must be strictly positive.
+    """
+    from scadpy.d2.shape import polygon
+
+    if radius <= 0:
+        raise ValueError("Circle radius must be strictly positive.")
+    if segment_count < 3:
+        raise ValueError("Circle vertex segment_count must be at least 3.")
+
+    angles = np.linspace(0, 2 * np.pi, segment_count, endpoint=False)
+    points = np.column_stack((radius * np.cos(angles), radius * np.sin(angles)))
+    return polygon(points=points)

scadpy/d2/shape/primitives/polygon.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from shapely.geometry import Polygon
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def polygon(points: Iterable[Iterable[float]]) -> Shape:
+    """
+    Create a 2D polygon shape from a sequence of points.
+
+    This function constructs a :class:`~scadpy.d2.shape.types.Shape` from the given 2D points.
+    The polygon is automatically closed by connecting the last point to the first.
+    If the polygon is self-intersecting, it may be split into multiple parts.
+
+    Parameters
+    ----------
+    points : Iterable[Iterable[float]]
+        A sequence of coordinate pairs ``[x, y]`` defining the vertices
+        of the polygon. At least three points are required.
+
+    Returns
+    -------
+    Shape
+        A :class:`~scadpy.d2.shape.types.Shape` object representing the polygon.
+
+    Notes
+    -----
+    - The polygon is automatically closed by connecting the last point to the first.
+    - The input points are converted into 2D coordinates; extra dimensions are ignored.
+    - If the polygon is self-intersecting, it may be split into multiple parts.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scadpy import polygon
+
+    >>> # simple triangle
+    >>> p = polygon([[0, 0], [1, 0], [0, 1]])
+    >>> p.vertex_coordinates # doctest: +NORMALIZE_WHITESPACE
+    array([[0., 0.],
+           [1., 0.],
+           [0., 1.]])
+
+    >>> # square defined manually
+    >>> # equivalent to square(2)
+    >>> p = polygon([[-1, -1], [1, -1], [1, 1], [-1, 1]])
+    >>> p.vertex_coordinates # doctest: +NORMALIZE_WHITESPACE
+    array([[-1., -1.],
+           [ 1., -1.],
+           [ 1.,  1.],
+           [-1.,  1.]])
+
+    >>> # self-intersecting polygon generate multiple parts
+    >>> p = polygon([[0, 0], [2, 2], [0, 2], [2, 0]])
+    >>> vtop = p.vertex_to_part[:, np.newaxis]
+    >>> stacked = np.hstack([vtop, p.vertex_coordinates])
+    >>> stacked  # doctest: +NORMALIZE_WHITESPACE
+    array([[0., 2., 0.],
+           [0., 1., 1.],
+           [0., 0., 0.],
+           [1., 2., 2.],
+           [1., 0., 2.],
+           [1., 1., 1.]])
+
+    >>> # invalid polygon (less than 3 points)
+    >>> polygon([[0, 0], [1, 1]])
+    Traceback (most recent call last):
+        ...
+    ValueError: A polygon must have at least 3 points
+    """
+    from scadpy.d2 import resolve_vector_2d
+    from scadpy.d2.shape import Shape
+
+    coords = [tuple(resolve_vector_2d(p, 0)) for p in points]
+    if len(coords) < 3:
+        raise ValueError("A polygon must have at least 3 points")
+
+    polygon = Polygon(coords)
+    return Shape.from_geometry(polygon)

scadpy/d2/shape/primitives/rectangle.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def rectangle(size: Iterable[float]) -> Shape:
+    """
+    Create a rectangle centered at the origin.
+
+    Parameters
+    ----------
+    size : Iterable[float]
+        The dimensions of the rectangle as ``[width, height]``.
+        Both values must be strictly positive numbers.
+
+    Returns
+    -------
+    Shape
+        A :class:`~scadpy.d2.shape.types.Shape` object representing the rectangle.
+
+    Notes
+    -----
+    - The rectangle is always centered at the origin (0, 0).
+    - The edges of the rectangle are aligned with the X and Y axes.
+
+    Examples
+    --------
+    >>> from scadpy import rectangle
+
+    >>> # rectangle 4 units wide and 2 units tall
+    >>> x = rectangle([4, 2])
+    >>> x.vertex_coordinates # doctest: +NORMALIZE_WHITESPACE
+    array([[-2., -1.],
+           [ 2., -1.],
+           [ 2.,  1.],
+           [-2.,  1.]])
+
+    >>> # equivalent to square(10)
+    >>> x = rectangle([10, 10])
+    >>> x.vertex_coordinates # doctest: +NORMALIZE_WHITESPACE
+    array([[-5., -5.],
+           [ 5., -5.],
+           [ 5.,  5.],
+           [-5.,  5.]])
+
+    >>> # if one or no dimension is provided,
+    >>> # the missing value defaults to 1.0
+    >>> x = rectangle([5])
+    >>> x.vertex_coordinates # doctest: +NORMALIZE_WHITESPACE
+    array([[-2.5, -0.5],
+           [ 2.5, -0.5],
+           [ 2.5,  0.5],
+           [-2.5,  0.5]])
+
+    >>> # invalid rectangle
+    >>> rectangle([0, 5])
+    Traceback (most recent call last):
+        ...
+    ValueError: Rectangle dimensions must be strictly positive.
+    """
+
+    from scadpy.d2 import resolve_vector_2d
+    from scadpy.d2.shape import polygon
+
+    width, height = resolve_vector_2d(size, 1.0)  # pyright: ignore[reportAny]
+
+    if width <= 0 or height <= 0:
+        raise ValueError("Rectangle dimensions must be strictly positive.")
+
+    half_width, half_height = width / 2.0, height / 2.0  # pyright: ignore[reportAny]
+
+    points = [
+        (-half_width, -half_height),
+        (half_width, -half_height),
+        (half_width, half_height),
+        (-half_width, half_height),
+    ]
+    return polygon(points=points)

scadpy/d2/shape/primitives/square.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def square(size: float) -> Shape:
+    """
+    Creates a square centered at the origin.
+
+    This function is a convenience wrapper around
+    :func:`~scadpy.d2.shape.primitives.rectangle`, with equal width and height.
+
+    Parameters
+    ----------
+    size : float
+        The length of each side of the square.
+
+    Returns
+    -------
+    Shape
+        A :class:`~scadpy.d2.shape.types.Shape` object representing the square.
+
+    Notes
+    -----
+    - The square is centered at the origin `(0, 0)`.
+    - The square is equivalent to calling ``rectangle([size, size])``.
+
+    Examples
+    --------
+    >>> from scadpy import square
+
+    >>> # square of size 1x1
+    >>> x = square(1)
+    >>> x.vertex_coordinates # doctest: +NORMALIZE_WHITESPACE
+    array([[-0.5, -0.5],
+           [ 0.5, -0.5],
+           [ 0.5,  0.5],
+           [-0.5,  0.5]])
+
+    >>> # square of size 5x5
+    >>> x = square(5)
+    >>> x.vertex_coordinates # doctest: +NORMALIZE_WHITESPACE
+    array([[-2.5, -2.5],
+           [ 2.5, -2.5],
+           [ 2.5,  2.5],
+           [-2.5,  2.5]])
+    """
+
+    from scadpy.d2.shape import rectangle
+
+    return rectangle(size=[size, size])

scadpy/d2/shape/topologies/__init__.py

@@ -0,0 +1,53 @@
+__all__ = [
+    "are_shape_corners_convex",
+    "get_shape_corner_angles",
+    "get_shape_corner_normals",
+    "get_shape_corner_to_incoming_directed_edge",
+    "get_shape_corner_to_outgoing_directed_edge",
+    "get_shape_corner_to_vertex",
+    "get_shape_directed_edge_directions",
+    "get_shape_directed_edge_to_corner",
+    "get_shape_directed_edge_to_edge",
+    "get_shape_directed_edge_to_vertex",
+    "get_shape_edge_lengths",
+    "get_shape_edge_midpoints",
+    "get_shape_edge_normals",
+    "get_shape_edge_to_vertex",
+    "get_shape_part_vertex_coordinates",
+    "get_shape_ring_to_part",
+    "get_shape_ring_types",
+    "get_shape_vertex_coordinates",
+    "get_shape_vertex_to_part",
+    "get_shape_vertex_to_ring",
+]
+
+from .corner import (
+    are_shape_corners_convex,
+    get_shape_corner_angles,
+    get_shape_corner_normals,
+    get_shape_corner_to_incoming_directed_edge,
+    get_shape_corner_to_outgoing_directed_edge,
+    get_shape_corner_to_vertex,
+)
+from .directed_edge import (
+    get_shape_directed_edge_directions,
+    get_shape_directed_edge_to_corner,
+    get_shape_directed_edge_to_edge,
+    get_shape_directed_edge_to_vertex,
+)
+from .edge import (
+    get_shape_edge_lengths,
+    get_shape_edge_midpoints,
+    get_shape_edge_normals,
+    get_shape_edge_to_vertex,
+)
+from .ring import (
+    get_shape_ring_to_part,
+    get_shape_ring_types,
+)
+from .vertex import (
+    get_shape_part_vertex_coordinates,
+    get_shape_vertex_coordinates,
+    get_shape_vertex_to_part,
+    get_shape_vertex_to_ring,
+)

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

@@ -0,0 +1,15 @@
+__all__ = [
+    "are_shape_corners_convex",
+    "get_shape_corner_angles",
+    "get_shape_corner_normals",
+    "get_shape_corner_to_incoming_directed_edge",
+    "get_shape_corner_to_outgoing_directed_edge",
+    "get_shape_corner_to_vertex",
+]
+
+from .are_shape_corners_convex import are_shape_corners_convex
+from .get_shape_corner_angles import get_shape_corner_angles
+from .get_shape_corner_normals import get_shape_corner_normals
+from .get_shape_corner_to_incoming_directed_edge import get_shape_corner_to_incoming_directed_edge
+from .get_shape_corner_to_outgoing_directed_edge import get_shape_corner_to_outgoing_directed_edge
+from .get_shape_corner_to_vertex import get_shape_corner_to_vertex