ScadPy 0.2.10__tar.gz → 0.2.12__tar.gz

{scadpy-0.2.10 → scadpy-0.2.12}/.gitignore

@@ -16,6 +16,7 @@ dist/
 
 # --- Documentation build ---
 docs/build/
+docs/_build/
 
 # --- Logs and temporary files ---
 *.log

{scadpy-0.2.10 → scadpy-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ScadPy
-Version: 0.2.10
+Version: 0.2.12
 Summary: Simplified 2D/3D modeling for Python with fluent API and boolean operations
 Author: m-fabregue
 License: # MIT License
@@ -96,14 +96,15 @@ Requirements: Python ≥ 3.12.
 
 ```python
 # 2D — chamfered mounting plate
-from scadpy import *
+from scadpy import rectangle, circle, text
 import numpy as np
 
-PLATE_WIDTH  = 80
-PLATE_HEIGHT = 50
-HOLE_RADIUS  = 4
-HOLE_MARGIN  = 10
-CHAMFER_SIZE = 8
+PLATE_WIDTH   = 80
+PLATE_HEIGHT  = 50
+PLATE_THICKNESS = 10
+HOLE_RADIUS   = 4
+HOLE_MARGIN   = 10
+CHAMFER_SIZE  = 8
 
 base  = rectangle([PLATE_WIDTH, PLATE_HEIGHT])
 plate = base.chamfer(CHAMFER_SIZE)
@@ -111,7 +112,7 @@ plate = base.chamfer(CHAMFER_SIZE)
 for position, normal in zip(base.vertex_coordinates, base.vertex_normals):
     hole_center = position - HOLE_MARGIN * np.sqrt(2) * normal
     plate -= circle(HOLE_RADIUS).translate(hole_center)
-    
+
 plate.to_screen()
 ```
 
@@ -120,10 +121,25 @@ plate.to_screen()
   <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/plate_light.png" alt="chamfered mounting plate" width="400">
 </picture>
 
+```python
+# 3D — extruded mounting plate with label (continues from above)
+TEXT_THICKNESS = 2
+
+extruded_plate = plate.linear_extrude(PLATE_THICKNESS)
+label = text("ScadPy", size=15).linear_extrude(TEXT_THICKNESS)
+extruded_plate |= label.translate(z(PLATE_THICKNESS))
+extruded_plate.to_screen()
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/extruded_plate_dark.png">
+  <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/extruded_plate_light.png" alt="chamfered mounting plate" width="400">
+</picture>
+
 ```python
 # 3D — parametric ball bearing
+from scadpy import circle, rectangle, sphere, x, y, GRAY, ORANGE
 import numpy as np
-from scadpy import *
 
 BALL_RADIUS    = 3
 RACE_RADIUS    = 15
@@ -134,10 +150,11 @@ RACE_THICKNESS = 10
 
 groove  = circle(BALL_RADIUS + CLEARANCE) | rectangle([BALL_RADIUS, RING_HEIGHT])
 race    = rectangle([RACE_THICKNESS, RING_HEIGHT]) - groove
-bearing = race.radial_extrude(axis=y(), pivot=x(RACE_RADIUS))
+bearing = race.radial_extrude(axis=y(), pivot=x(RACE_RADIUS)).color(GRAY)
 
+ball = sphere(BALL_RADIUS).color(ORANGE)
 for angle in np.linspace(0, 360, NB_BALLS, endpoint=False):
-    bearing += sphere(BALL_RADIUS).rotate(angle, axis=y(), pivot=x(RACE_RADIUS))
+    bearing += ball.rotate(angle, axis=y(), pivot=x(RACE_RADIUS))
 
 bearing.to_screen()
 ```
@@ -147,6 +164,69 @@ bearing.to_screen()
   <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/bearing_light.png" alt="parametric ball bearing" width="400">
 </picture>
 
+```python
+# 3D — dice
+from scadpy import cuboid, sphere, x, y, z
+
+SIZE = 20
+dice = cuboid(SIZE)
+pip  = sphere(SIZE / 12).translate(z(SIZE / 2))
+
+one   = pip
+two   = pip.translate([SIZE / 4, SIZE / 4, 0]) + pip.translate([-SIZE / 4, -SIZE / 4, 0])
+three = one + two
+four  = two + two.rotate(90, z())
+five  = one + four
+six   = four + pip.translate(x(SIZE / 4)) + pip.translate(x(-SIZE / 4))
+
+dice -= (
+    one
+    + two.rotate(90, x())
+    + three.rotate(90, y())
+    + four.rotate(-90, y())
+    + five.rotate(-90, x())
+    + six.rotate(-180, x())
+)
+
+dice.to_screen()
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/dice_dark.png">
+  <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/dice_light.png" alt="chamfered mounting plate" width="400">
+</picture>
+
+```python
+# 3D — storage box
+from scadpy import square, x, z
+
+SIZE_OUTER      = 20
+SIZE_INNER      = 18
+FILLET          = 1
+BASE_HEIGHT     = 10
+CUT_HEIGHT      = 8
+CAP_HEIGHT_OUTER = 1.5
+CAP_HEIGHT_INNER = 3
+CAP_OFFSET_X    = 25
+CUT_OFFSET_Z    = 2
+
+outer_base = square(SIZE_OUTER).fillet(FILLET).linear_extrude(BASE_HEIGHT)
+inner_cut  = square(SIZE_INNER).linear_extrude(CUT_HEIGHT).translate(z(CUT_OFFSET_Z))
+base       = outer_base - inner_cut
+
+cap_outer = square(SIZE_OUTER).fillet(FILLET).linear_extrude(CAP_HEIGHT_OUTER)
+cap_inner = square(SIZE_INNER).linear_extrude(CAP_HEIGHT_INNER)
+cap       = (cap_outer | cap_inner).translate(x(CAP_OFFSET_X))
+
+storage_box = base + cap
+storage_box.to_screen()
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/storage_box_dark.png">
+  <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/storage_box_light.png" alt="chamfered mounting plate" width="400">
+</picture>
+
 ## Cheat sheet
 
 *Parameters shown in `# comments` are optional, with their default values.*

{scadpy-0.2.10 → scadpy-0.2.12}/README.md

@@ -24,14 +24,15 @@ Requirements: Python ≥ 3.12.
 
 ```python
 # 2D — chamfered mounting plate
-from scadpy import *
+from scadpy import rectangle, circle, text
 import numpy as np
 
-PLATE_WIDTH  = 80
-PLATE_HEIGHT = 50
-HOLE_RADIUS  = 4
-HOLE_MARGIN  = 10
-CHAMFER_SIZE = 8
+PLATE_WIDTH   = 80
+PLATE_HEIGHT  = 50
+PLATE_THICKNESS = 10
+HOLE_RADIUS   = 4
+HOLE_MARGIN   = 10
+CHAMFER_SIZE  = 8
 
 base  = rectangle([PLATE_WIDTH, PLATE_HEIGHT])
 plate = base.chamfer(CHAMFER_SIZE)
@@ -39,7 +40,7 @@ plate = base.chamfer(CHAMFER_SIZE)
 for position, normal in zip(base.vertex_coordinates, base.vertex_normals):
     hole_center = position - HOLE_MARGIN * np.sqrt(2) * normal
     plate -= circle(HOLE_RADIUS).translate(hole_center)
-    
+
 plate.to_screen()
 ```
 
@@ -48,10 +49,25 @@ plate.to_screen()
   <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/plate_light.png" alt="chamfered mounting plate" width="400">
 </picture>
 
+```python
+# 3D — extruded mounting plate with label (continues from above)
+TEXT_THICKNESS = 2
+
+extruded_plate = plate.linear_extrude(PLATE_THICKNESS)
+label = text("ScadPy", size=15).linear_extrude(TEXT_THICKNESS)
+extruded_plate |= label.translate(z(PLATE_THICKNESS))
+extruded_plate.to_screen()
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/extruded_plate_dark.png">
+  <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/extruded_plate_light.png" alt="chamfered mounting plate" width="400">
+</picture>
+
 ```python
 # 3D — parametric ball bearing
+from scadpy import circle, rectangle, sphere, x, y, GRAY, ORANGE
 import numpy as np
-from scadpy import *
 
 BALL_RADIUS    = 3
 RACE_RADIUS    = 15
@@ -62,10 +78,11 @@ RACE_THICKNESS = 10
 
 groove  = circle(BALL_RADIUS + CLEARANCE) | rectangle([BALL_RADIUS, RING_HEIGHT])
 race    = rectangle([RACE_THICKNESS, RING_HEIGHT]) - groove
-bearing = race.radial_extrude(axis=y(), pivot=x(RACE_RADIUS))
+bearing = race.radial_extrude(axis=y(), pivot=x(RACE_RADIUS)).color(GRAY)
 
+ball = sphere(BALL_RADIUS).color(ORANGE)
 for angle in np.linspace(0, 360, NB_BALLS, endpoint=False):
-    bearing += sphere(BALL_RADIUS).rotate(angle, axis=y(), pivot=x(RACE_RADIUS))
+    bearing += ball.rotate(angle, axis=y(), pivot=x(RACE_RADIUS))
 
 bearing.to_screen()
 ```
@@ -75,6 +92,69 @@ bearing.to_screen()
   <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/bearing_light.png" alt="parametric ball bearing" width="400">
 </picture>
 
+```python
+# 3D — dice
+from scadpy import cuboid, sphere, x, y, z
+
+SIZE = 20
+dice = cuboid(SIZE)
+pip  = sphere(SIZE / 12).translate(z(SIZE / 2))
+
+one   = pip
+two   = pip.translate([SIZE / 4, SIZE / 4, 0]) + pip.translate([-SIZE / 4, -SIZE / 4, 0])
+three = one + two
+four  = two + two.rotate(90, z())
+five  = one + four
+six   = four + pip.translate(x(SIZE / 4)) + pip.translate(x(-SIZE / 4))
+
+dice -= (
+    one
+    + two.rotate(90, x())
+    + three.rotate(90, y())
+    + four.rotate(-90, y())
+    + five.rotate(-90, x())
+    + six.rotate(-180, x())
+)
+
+dice.to_screen()
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/dice_dark.png">
+  <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/dice_light.png" alt="chamfered mounting plate" width="400">
+</picture>
+
+```python
+# 3D — storage box
+from scadpy import square, x, z
+
+SIZE_OUTER      = 20
+SIZE_INNER      = 18
+FILLET          = 1
+BASE_HEIGHT     = 10
+CUT_HEIGHT      = 8
+CAP_HEIGHT_OUTER = 1.5
+CAP_HEIGHT_INNER = 3
+CAP_OFFSET_X    = 25
+CUT_OFFSET_Z    = 2
+
+outer_base = square(SIZE_OUTER).fillet(FILLET).linear_extrude(BASE_HEIGHT)
+inner_cut  = square(SIZE_INNER).linear_extrude(CUT_HEIGHT).translate(z(CUT_OFFSET_Z))
+base       = outer_base - inner_cut
+
+cap_outer = square(SIZE_OUTER).fillet(FILLET).linear_extrude(CAP_HEIGHT_OUTER)
+cap_inner = square(SIZE_INNER).linear_extrude(CAP_HEIGHT_INNER)
+cap       = (cap_outer | cap_inner).translate(x(CAP_OFFSET_X))
+
+storage_box = base + cap
+storage_box.to_screen()
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/storage_box_dark.png">
+  <img src="https://raw.githubusercontent.com/m-fabregue/scadpy/main/docs/_static/examples/storage_box_light.png" alt="chamfered mounting plate" width="400">
+</picture>
+
 ## Cheat sheet
 
 *Parameters shown in `# comments` are optional, with their default values.*

{scadpy-0.2.10 → scadpy-0.2.12}/docs/Makefile

@@ -9,6 +9,9 @@ SPHINXAUTOGEN ?= sphinx-autogen
 SOURCEDIR = .
 BUILDDIR = build
 
+skills:
+	@python scripts/build_skills.py
+
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 

{scadpy-0.2.10 → scadpy-0.2.12}/docs/_static/badges/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 93.55%"><title>coverage: 93.55%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">93.55%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">93.55%</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 92.90%"><title>coverage: 92.90%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">92.90%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">92.90%</text></g></svg>

{scadpy-0.2.10 → scadpy-0.2.12}/docs/_static/badges/interrogate.svg

@@ -1,5 +1,5 @@
 <svg width="140" height="20" viewBox="0 0 140 20" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
-    <title>interrogate: 91.5%</title>
+    <title>interrogate: 91.6%</title>
     <g transform="matrix(1,0,0,1,22,0)">
         <g id="backgrounds" transform="matrix(1.32789,0,0,1,-22.3892,0)">
             <rect x="0" y="0" width="71" height="20" style="fill:rgb(85,85,85);"/>
@@ -12,8 +12,8 @@
     <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110">
         <text x="590" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="610">interrogate</text>
         <text x="590" y="140" transform="scale(.1)" textLength="610">interrogate</text>
-        <text x="1160" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370" data-interrogate="result">91.5%</text>
-        <text x="1160" y="140" transform="scale(.1)" textLength="370" data-interrogate="result">91.5%</text>
+        <text x="1160" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370" data-interrogate="result">91.6%</text>
+        <text x="1160" y="140" transform="scale(.1)" textLength="370" data-interrogate="result">91.6%</text>
     </g>
     <g id="logo-shadow" serif:id="logo shadow" transform="matrix(0.854876,0,0,0.854876,-6.73514,1.732)">
         <g transform="matrix(0.299012,0,0,0.299012,9.70229,-6.68582)">

{scadpy-0.2.10 → scadpy-0.2.12}/docs/conf.py

@@ -192,3 +192,8 @@ FOREGROUND_DARK = [0.972, 0.972, 0.949, DEFAULT_OPACITY]
 GHOST_DARK = [1.0, 0.64, 0.2, 0.0]
 GHOST_LIGHT = [0.85, 0.468, 0.0, 0.0]
 """
+
+# Github light background: [1.0, 1.0, 1.0, DEFAULT_OPACITY]
+# Github dark background: [0.051, 0.067, 0.090, DEFAULT_OPACITY]
+# Furo light background: [0.949, 0.949, 0.949, DEFAULT_OPACITY]
+# Furo dark background: [0.168, 0.168, 0.168, DEFAULT_OPACITY]

{scadpy-0.2.10 → scadpy-0.2.12}/docs/index.rst

@@ -41,12 +41,13 @@ Quick examples
 .. doctest::
 
    >>> # 2D — chamfered mounting plate
-   >>> from scadpy import circle, cuboid, rectangle, sphere, square, x, y, z, GRAY, ORANGE
+   >>> from scadpy import circle, cuboid, rectangle, sphere, square, text
+   >>> from scadpy import x, y, z, GRAY, ORANGE
    >>> import numpy as np
 
    >>> PLATE_WIDTH  = 80
    >>> PLATE_HEIGHT = 50
-   >>> PLATE_THICKESS = 10
+   >>> PLATE_THICKNESS = 10
    >>> HOLE_RADIUS  = 4
    >>> HOLE_MARGIN  = 10
    >>> CHAMFER_SIZE = 8
@@ -66,8 +67,12 @@ Quick examples
 
 .. doctest::
 
-   >>> # 3D — extrude mounting plate
-   >>> extruded_plate = plate.linear_extrude(PLATE_THICKESS)
+   >>> # 3D — extrude mounting plate with label
+   >>> TEXT_THICKNESS = 2
+
+   >>> extruded_plate = plate.linear_extrude(PLATE_THICKNESS)
+   >>> label = text("ScadPy", size=15).linear_extrude(TEXT_THICKNESS)
+   >>> extruded_plate |= label.translate(z(PLATE_THICKNESS))
    >>> extruded_plate.to_screen() # doctest: +SKIP
 
 .. render-example::

scadpy-0.2.12/docs/snapshots/d2__index_extruded_plate__dark.md5

@@ -0,0 +1 @@
+a7c7139280ac83767d105106bc33a3f4

scadpy-0.2.12/docs/snapshots/d2__index_extruded_plate__light.md5

@@ -0,0 +1 @@
+71a376f56370c01f428947df022da681

scadpy-0.2.12/docs/snapshots/d2__text_example__dark.md5

@@ -0,0 +1 @@
+2345ae8d8a5eac8056f54f0699e5af42

scadpy-0.2.12/docs/snapshots/d2__text_example__light.md5

@@ -0,0 +1 @@
+f52da4681c411220cff4b4d248801dd9

{scadpy-0.2.10 → scadpy-0.2.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ScadPy"
-version = "0.2.10"
+version = "0.2.12"
 description = "Simplified 2D/3D modeling for Python with fluent API and boolean operations"
 requires-python = ">= 3.12"
 authors = [{ name = "m-fabregue" }]

{scadpy-0.2.10 → scadpy-0.2.12}/scadpy/d2/shape/primitives/__init__.py

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

scadpy-0.2.12/scadpy/d2/shape/primitives/text.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from matplotlib import font_manager as fm
+from matplotlib.path import Path
+from matplotlib.textpath import TextPath
+from numpy.typing import NDArray
+from typeguard import typechecked
+
+if TYPE_CHECKING:
+    from scadpy.d2.shape import Shape
+
+
+def _quadratic_bezier(
+    p0: NDArray[np.float64],
+    p1: NDArray[np.float64],
+    p2: NDArray[np.float64],
+    n: int,
+) -> NDArray[np.float64]:
+    """Sample a quadratic Bézier curve at n equally-spaced parameter values.
+
+    The start point p0 is not included in the output (it is assumed to already
+    be in the caller's point list).
+
+    Parameters
+    ----------
+    p0 : NDArray[np.float64]
+        Start point (shape (2,)).
+    p1 : NDArray[np.float64]
+        Control point (shape (2,)).
+    p2 : NDArray[np.float64]
+        End point (shape (2,)).
+    n : int
+        Number of output samples (not counting p0).
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Sampled points of shape (n, 2).
+    """
+    t = np.linspace(0, 1, n + 1)[1:]
+    return np.outer((1 - t) ** 2, p0) + np.outer(2 * (1 - t) * t, p1) + np.outer(t**2, p2)
+
+
+def _cubic_bezier(
+    p0: NDArray[np.float64],
+    p1: NDArray[np.float64],
+    p2: NDArray[np.float64],
+    p3: NDArray[np.float64],
+    n: int,
+) -> NDArray[np.float64]:
+    """Sample a cubic Bézier curve at n equally-spaced parameter values.
+
+    The start point p0 is not included in the output.
+
+    Parameters
+    ----------
+    p0 : NDArray[np.float64]
+        Start point (shape (2,)).
+    p1 : NDArray[np.float64]
+        First control point (shape (2,)).
+    p2 : NDArray[np.float64]
+        Second control point (shape (2,)).
+    p3 : NDArray[np.float64]
+        End point (shape (2,)).
+    n : int
+        Number of output samples (not counting p0).
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Sampled points of shape (n, 2).
+    """
+    t = np.linspace(0, 1, n + 1)[1:]
+    return (
+        np.outer((1 - t) ** 3, p0)
+        + np.outer(3 * (1 - t) ** 2 * t, p1)
+        + np.outer(3 * (1 - t) * t**2, p2)
+        + np.outer(t**3, p3)
+    )
+
+
+def _path_to_contours(
+    path: Path,
+    curve_segments: int,
+) -> list[NDArray[np.float64]]:
+    """Convert a matplotlib Path into a list of closed 2D contours.
+
+    Each MOVETO/CLOSEPOLY pair produces one contour. Bézier segments
+    (CURVE3, CURVE4) are approximated by straight-line sequences.
+
+    Parameters
+    ----------
+    path : Path
+        Matplotlib path, typically from TextPath.
+    curve_segments : int
+        Number of line segments used to approximate each Bézier curve.
+
+    Returns
+    -------
+    list[NDArray[np.float64]]
+        List of contours, each of shape (n_points, 2).
+    """
+    contours: list[NDArray[np.float64]] = []
+    current: list[NDArray[np.float64]] = []
+
+    for verts, code in path.iter_segments(simplify=False):
+        if code == Path.MOVETO:
+            if len(current) >= 3:
+                contours.append(np.array(current))
+            current = [verts]
+        elif code == Path.LINETO:
+            current.append(verts)
+        elif code == Path.CURVE3:
+            p0 = np.array(current[-1])
+            pts = _quadratic_bezier(p0, verts[:2], verts[2:], curve_segments)
+            current.extend(pts)
+        elif code == Path.CURVE4:
+            p0 = np.array(current[-1])
+            pts = _cubic_bezier(p0, verts[:2], verts[2:4], verts[4:], curve_segments)
+            current.extend(pts)
+        elif code == Path.CLOSEPOLY:
+            if len(current) >= 3:
+                contours.append(np.array(current))
+            current = []
+
+    if len(current) >= 3:
+        contours.append(np.array(current))
+
+    return contours
+
+
+@typechecked
+def text(
+    content: str,
+    font: str | None = None,
+    size: float = 10,
+    curve_segments: int = 12,
+) -> Shape:
+    """Create a 2D shape from a text string.
+
+    Each glyph is traced from the font outlines and converted to a polygon.
+    Holes (e.g. inside ``o``, ``e``, ``a``) are handled via symmetric
+    difference (XOR) across all contours.
+
+    Parameters
+    ----------
+    content : str
+        The text to render.
+    font : str or None
+        Font family name (e.g. ``"DejaVu Serif"``). Use :func:`available_fonts`
+        to list fonts available on the current system. If ``None``, matplotlib's
+        default font (DejaVu Sans, bundled with matplotlib) is used — this is
+        guaranteed to work cross-platform.
+    size : float
+        Font size in units. Default is 10.
+    curve_segments : int
+        Number of line segments used to approximate each Bézier curve in the
+        font outlines. Higher values produce smoother curves. Default is 12.
+
+    Returns
+    -------
+    Shape
+        A :class:`~scadpy.d2.shape.types.Shape` representing the text outlines.
+
+    Examples
+    --------
+    >>> from scadpy import text
+
+    >>> text("ScadPy", font="DejaVu Sans", size=20) # doctest: +SKIP
+
+    .. render-example::
+        :name: text_example
+        :example: text("ScadPy", font="DejaVu Sans", size=20)
+    """
+    from functools import reduce
+
+    from scadpy.d2.shape.primitives import polygon
+
+    props = fm.FontProperties()
+    if font is not None:
+        props.set_family(font)
+    path = TextPath((0, 0), content, size=size, prop=props)
+    contours = _path_to_contours(path, curve_segments)
+    polygons = [polygon(c) for c in contours]
+    result = reduce(lambda a, b: a ^ b, polygons)
+    bounds = result.bounds
+    cx = (bounds[0] + bounds[2]) / 2
+    cy = (bounds[1] + bounds[3]) / 2
+    return result.translate([-cx, -cy])

scadpy-0.2.12/scadpy/utils/__init__.py

@@ -0,0 +1,7 @@
+__all__ = ["available_fonts", "resolve_vector", "x", "y", "z"]
+
+from .available_fonts import available_fonts
+from .resolve_vector import resolve_vector
+from .x import x
+from .y import y
+from .z import z