ScadPy 0.1.0__py3-none-any.whl

scadpy/d2/shape/combinations/subtract_shape_parts.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+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 subtract_shape_parts(
+    to_be_subtracted: Part[Polygon],
+    to_subtract: Part[Polygon],
+    make_assembly_from_parts: Callable[[list[Part[Polygon]]], Shape],
+) -> Shape:
+    """Subtract one shape part from another and return the resulting shape.
+
+    Shortcut for :func:`subtract_parts`.
+    See :func:`subtract_parts` for full documentation.
+
+    Parameters
+    ----------
+    to_be_subtracted : Part[Polygon]
+        The part to subtract from.
+    to_subtract : Part[Polygon]
+        The part to subtract.
+    make_assembly_from_parts : Callable[[list[Part[Polygon]]], Shape]
+        Factory function to build the resulting Shape from a sequence of parts.
+
+    Returns
+    -------
+    Shape
+        A new shape with the geometry of ``to_subtract`` removed from ``to_be_subtracted``.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, subtract_shape_parts, Shape
+
+    >>> subtract_shape_parts(
+    ...     to_be_subtracted=square(4)._parts[0],
+    ...     to_subtract=circle(radius=1)._parts[0],
+    ...     make_assembly_from_parts=Shape.from_parts,
+    ... ) # doctest: +SKIP
+
+    .. render-example::
+        :name: subtract_shape_parts_example
+        :example: subtract_shape_parts(to_be_subtracted=square(4)._parts[0], to_subtract=circle(radius=1)._parts[0], make_assembly_from_parts=Shape.from_parts)
+        :ghost: square(4)
+    """
+    from scadpy import Part, shapely_base_geometry_to_shapely_polygons, 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 p_1, p_2: (
+            shapely_base_geometry_to_shapely_polygons(p_1 - p_2)
+        ),
+        make_part_from_geometry=Part[Polygon].from_geometry,
+        make_assembly_from_parts=make_assembly_from_parts,
+    )

scadpy/d2/shape/combinations/unify_shape.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 Shape
+
+
+@typechecked
+def unify_shape(shapes: Sequence[Shape]) -> Shape:
+    """Unite a sequence of shapes into a single shape using boolean union.
+
+    All overlapping parts across the input shapes are merged geometrically.
+    Use :func:`concat_shape` if you want to combine shapes without merging overlaps.
+
+    Parameters
+    ----------
+    shapes : Sequence[Shape]
+        The shapes to unite.
+
+    Returns
+    -------
+    Shape
+        A new shape containing the geometric union of all input shapes.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, unify_shape
+
+    >>> unify_shape(  # doctest: +SKIP
+    ...     shapes=[square(4), circle(radius=2).translate([2, 0])]
+    ... )
+
+    .. render-example::
+        :name: unify_shape
+        :example: unify_shape(shapes=[square(4), circle(radius=2).translate([2, 0])])
+    """
+    from scadpy import Shape, unify_shape_parts
+    from scadpy.core.assembly import unify_assemblies
+
+    return unify_assemblies(
+        assemblies=shapes,
+        get_assembly_parts=lambda assembly: assembly._parts,
+        unify_parts=lambda parts: unify_shape_parts(
+            parts=parts,
+            make_assembly_from_parts=Shape.from_parts,
+        ),
+    )

scadpy/d2/shape/combinations/unify_shape_parts.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING
+
+from shapely.geometry.polygon import Polygon
+from shapely.ops import unary_union
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+    from scadpy.d2.shape import Shape
+
+
+@typechecked
+def unify_shape_parts(
+    parts: Sequence[Part[Polygon]],
+    make_assembly_from_parts: Callable[[Sequence[Part[Polygon]]], Shape],
+) -> Shape:
+    """Unite a sequence of shape parts and return the resulting shape.
+
+    Shortcut for :func:`unify_parts`.
+    See :func:`unify_parts` for full documentation.
+
+    Parameters
+    ----------
+    parts : Sequence[Part[Polygon]]
+        The shape parts to unite.
+    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 union of the input parts.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, unify_shape_parts, Shape
+
+    >>> unify_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: unify_shape_parts_example
+        :example: unify_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,
+        shapely_base_geometry_to_shapely_polygons,
+        unify_parts,
+    )
+
+    return unify_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,
+        unify_geometries=lambda g: shapely_base_geometry_to_shapely_polygons(
+            unary_union(g)
+        ),
+        make_part_from_geometry=Part[Polygon].from_geometry,
+        make_assembly_from_parts=make_assembly_from_parts,
+    )

scadpy/d2/shape/exporters/__init__.py

@@ -0,0 +1,17 @@
+__all__ = [
+    "map_shape_to_dxf",
+    "map_shape_to_dxf_file",
+    "map_shape_to_html",
+    "map_shape_to_html_file",
+    "map_shape_to_screen",
+    "map_shape_to_svg",
+    "map_shape_to_svg_file",
+]
+
+from .map_shape_to_dxf import map_shape_to_dxf
+from .map_shape_to_dxf_file import map_shape_to_dxf_file
+from .map_shape_to_html import map_shape_to_html
+from .map_shape_to_html_file import map_shape_to_html_file
+from .map_shape_to_screen import map_shape_to_screen
+from .map_shape_to_svg import map_shape_to_svg
+from .map_shape_to_svg_file import map_shape_to_svg_file

scadpy/d2/shape/exporters/map_shape_to_dxf.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import trimesh
+from shapely.geometry import MultiPolygon
+from trimesh.path.exchange.dxf import export_dxf
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Shape
+
+
+@typechecked
+def map_shape_to_dxf(shape: Shape) -> str:
+    """Export a shape to a DXF string.
+
+    Each part of the shape is exported as a closed polyline. Polygon
+    holes are exported as separate polylines.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to export.
+
+    Returns
+    -------
+    str
+        A DXF document as a string.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, map_shape_to_dxf
+
+    >>> dxf = map_shape_to_dxf(square(4) - circle(1))
+    >>> dxf.startswith("999")
+    True
+    """
+    geometries = [part.geometry for part in shape._parts]
+    if not geometries:
+        return ""
+
+    return export_dxf(trimesh.load_path(MultiPolygon(geometries)))

scadpy/d2/shape/exporters/map_shape_to_dxf_file.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Shape
+
+
+@typechecked
+def map_shape_to_dxf_file(shape: Shape, path: str | Path) -> int:
+    """Save a shape as a DXF file.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to export.
+    path : str or Path
+        Destination file path.
+
+    Returns
+    -------
+    int
+        Number of characters written.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, map_shape_to_dxf_file
+
+    >>> map_shape_to_dxf_file(  # doctest: +SKIP
+    ...     shape=square(4) - circle(1), path="output.dxf"
+    ... )
+    """
+    from scadpy import map_shape_to_dxf
+
+    return Path(path).write_text(map_shape_to_dxf(shape), encoding="utf-8")

scadpy/d2/shape/exporters/map_shape_to_html.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from io import StringIO
+from typing import TYPE_CHECKING
+
+import matplotlib.pyplot as plt
+from IPython.core.display import HTML
+from shapely.plotting import plot_polygon
+from typeguard import typechecked
+
+from scadpy.color.constants import BLACK, WHITE
+
+if TYPE_CHECKING:
+    from scadpy import Color, Shape
+
+
+@typechecked
+def map_shape_to_html(
+    shape: Shape,
+    background_color: Color = WHITE,
+    foreground_color: Color = BLACK,
+) -> HTML:
+    """
+    Render a shape assembly as an SVG HTML object using matplotlib and shapely.
+
+    This function extracts all parts from the assembly, converts each to a Shapely
+    polygon, and plots them with their associated colors. The resulting figure is
+    exported as SVG and wrapped in an IPython HTML object for display in notebooks
+    or web interfaces.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to render.
+    background_color : Color, default=WHITE
+        The background color of the rendered output.
+    foreground_color : Color, default=BLACK
+        The foreground color (axes, grid) of the rendered output.
+
+    Returns
+    -------
+    HTML
+        An IPython HTML object containing the SVG rendering of the shape.
+
+    Examples
+    --------
+    >>> from IPython.core.display import HTML
+    >>> from scadpy import square, map_shape_to_html
+
+    >>> html = map_shape_to_html(shape=square(4))
+    >>> isinstance(html, HTML)
+    True
+    """
+    foreground_color_hex = "#{:02X}{:02X}{:02X}".format(
+        *(int(x * 255) for x in foreground_color[:-1])
+    )
+    background_color_hex = "#{:02X}{:02X}{:02X}".format(
+        *(int(x * 255) for x in background_color[:-1])
+    )
+    x_min, y_min, x_max, y_max = shape.bounds
+
+    width = x_max - x_min
+    height = y_max - y_min
+
+    if width > height:
+        difference = width - height
+        y_max = y_max + difference / 2
+        y_min = y_min - difference / 2
+        height = width
+    else:
+        difference = height - width
+        x_max = x_max + difference / 2
+        x_min = x_min - difference / 2
+        width = height
+
+    if width == 0 or height == 0:
+        width = max(width, 1.0)
+        height = max(height, 1.0)
+
+    aspect_ratio = height / width
+    fig_width = 5
+    fig_height = fig_width * aspect_ratio
+    fig, ax = plt.subplots(figsize=(fig_width, fig_height))
+
+    fig.patch.set_facecolor(background_color_hex)
+    ax.set_facecolor(background_color_hex)
+    ax.tick_params(axis="both", colors=foreground_color_hex)
+
+    for spine in ax.spines.values():
+        spine.set_edgecolor(foreground_color_hex)
+
+    for part in shape._parts:
+        color = part.color
+        edge_color = tuple((c + b) / 2 for c, b in zip(color[:3], background_color[:3]))
+        plot_polygon(
+            part.geometry,
+            ax=ax,
+            add_points=False,
+            facecolor=(color[0], color[1], color[2], color[3]),
+            edgecolor=(*edge_color, 1.0),
+            linewidth=2,
+        )
+
+    padding = 0.1 * width
+    ax.set_xlim(x_min - padding, x_max + padding)
+    ax.set_ylim(y_min - padding, y_max + padding)
+
+    ax.set_aspect("equal")
+    ax.grid(True, alpha=0.3, linewidth=0.5)
+    ax.axhline(y=0, color=foreground_color_hex, linewidth=1, alpha=0.3)
+    ax.axvline(x=0, color=foreground_color_hex, linewidth=1, alpha=0.3)
+
+    svg_output = StringIO()
+    plt.savefig(svg_output, format="svg", bbox_inches="tight", pad_inches=0)
+    plt.close()
+
+    return HTML(svg_output.getvalue())

scadpy/d2/shape/exporters/map_shape_to_html_file.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from scadpy.color.constants import BLACK, WHITE
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Color, Shape
+
+
+@typechecked
+def map_shape_to_html_file(
+    shape: Shape,
+    path: str,
+    background_color: Color = WHITE,
+    foreground_color: Color = BLACK,
+) -> int:
+    """Save a shape as an HTML file.
+
+    Shortcut for :func:`map_component_to_html_file`.
+    See :func:`map_component_to_html_file` for full documentation.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to save.
+    path : str
+        The file path where the HTML will be written.
+    background_color : Color, default=WHITE
+        The background color of the rendered output.
+    foreground_color : Color, default=BLACK
+        The foreground color (axes, grid) of the rendered output.
+
+    Returns
+    -------
+    int
+        The number of characters written to the file.
+
+    Examples
+    --------
+    >>> from scadpy import square, map_shape_to_html_file
+
+    >>> map_shape_to_html_file(  # doctest: +SKIP
+    ...     shape=square(4), path="output.html"
+    ... )
+    """
+    from scadpy import map_component_to_html_file, map_shape_to_html
+
+    return map_component_to_html_file(
+        component=shape,
+        path=path,
+        to_html=lambda component: map_shape_to_html(
+            shape=component,
+            background_color=background_color,
+            foreground_color=foreground_color,
+        ),
+    )

scadpy/d2/shape/exporters/map_shape_to_screen.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from scadpy.color.constants import BLACK, WHITE
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Color, Shape
+
+
+@typechecked
+def map_shape_to_screen(
+    shape: Shape,
+    background_color: Color = WHITE,
+    foreground_color: Color = BLACK,
+) -> None:
+    """Display a shape in a Qt-based window.
+
+    Shortcut for :func:`map_component_to_screen`.
+    See :func:`map_component_to_screen` for full documentation.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to display.
+    background_color : Color, default=WHITE
+        The background color of the rendered window.
+    foreground_color : Color, default=BLACK
+        The foreground color (axes, grid) of the rendered window.
+
+    Returns
+    -------
+    None
+
+    Examples
+    --------
+    >>> from scadpy import square, map_shape_to_screen
+
+    >>> map_shape_to_screen(shape=square(4)) # doctest: +SKIP
+    """
+    from scadpy import map_component_to_screen, map_shape_to_html
+
+    map_component_to_screen(
+        component=shape,
+        to_html=lambda component: map_shape_to_html(
+            shape=component,
+            background_color=background_color,
+            foreground_color=foreground_color,
+        ),
+    )

scadpy/d2/shape/exporters/map_shape_to_svg.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import trimesh
+from shapely.geometry import MultiPolygon
+from trimesh.path.exchange.svg_io import export_svg
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Shape
+
+
+@typechecked
+def map_shape_to_svg(shape: Shape) -> str:
+    """Export a shape to an SVG string.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to export.
+
+    Returns
+    -------
+    str
+        A self-contained SVG document as a string.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, map_shape_to_svg
+
+    >>> svg = map_shape_to_svg(square(4) - circle(1))
+    >>> svg.startswith("<svg")
+    True
+    """
+    geometries = [part.geometry for part in shape._parts]
+    if not geometries:
+        return '<svg xmlns="http://www.w3.org/2000/svg"/>'
+
+    return export_svg(trimesh.load_path(MultiPolygon(geometries)))

scadpy/d2/shape/exporters/map_shape_to_svg_file.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy import Shape
+
+
+@typechecked
+def map_shape_to_svg_file(shape: Shape, path: str | Path) -> int:
+    """Save a shape as an SVG file.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to export.
+    path : str or Path
+        Destination file path.
+
+    Returns
+    -------
+    int
+        Number of characters written.
+
+    Examples
+    --------
+    >>> from scadpy import square, circle, map_shape_to_svg_file
+
+    >>> map_shape_to_svg_file(  # doctest: +SKIP
+    ...     shape=square(4) - circle(1), path="output.svg"
+    ... )
+    """
+    from scadpy import map_shape_to_svg
+
+    return Path(path).write_text(map_shape_to_svg(shape), encoding="utf-8")

scadpy/d2/shape/features/__init__.py

@@ -0,0 +1,9 @@
+__all__ = [
+    "get_shape_bounds",
+    "get_shape_part_bounds",
+    "is_shape_empty",
+]
+
+from .get_shape_bounds import get_shape_bounds
+from .get_shape_part_bounds import get_shape_part_bounds
+from .is_shape_empty import is_shape_empty

scadpy/d2/shape/features/get_shape_bounds.py

@@ -0,0 +1,40 @@
+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 Shape
+
+
+@typechecked
+def get_shape_bounds(shape: Shape) -> NDArray[np.float64]:
+    """
+    Return the axis-aligned bounding box of the shape.
+
+    Parameters
+    ----------
+    shape : Shape
+        The shape to compute bounds for.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        1D array ``[min_x, min_y, max_x, max_y]``.
+        Returns zeros if the shape is empty.
+
+    Examples
+    --------
+    >>> from shapely.geometry import Polygon
+    >>> from scadpy import Shape, get_shape_bounds
+
+    >>> polygon = Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])
+    >>> get_shape_bounds(Shape.from_geometry(polygon))
+    array([0., 0., 2., 2.])
+    """
+    from scadpy import get_component_bounds
+
+    return get_component_bounds(shape.vertex_coordinates)

scadpy/d2/shape/features/get_shape_part_bounds.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+from shapely.geometry.polygon import Polygon
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.core.part import Part
+
+
+@typechecked
+def get_shape_part_bounds(part: Part[Polygon]) -> NDArray[np.float64]:
+    """Return the 2D bounding box of a shape part as [minx, miny, maxx, maxy].
+
+    Parameters
+    ----------
+    part : Part[Polygon]
+        The shape part to compute the bounding box of.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Array of shape (4,) containing [minx, miny, maxx, maxy].
+
+    Examples
+    --------
+    >>> from scadpy import square, get_shape_part_bounds
+    >>> bounds = get_shape_part_bounds(part=square(2)._parts[0])
+    >>> bounds.shape
+    (4,)
+    """
+    from scadpy import get_component_bounds, get_shape_part_vertex_coordinates
+
+    return get_component_bounds(get_shape_part_vertex_coordinates(part))