yapCAD 0.3.0__py2.py3-none-any.whl → 0.3.1__py2.py3-none-any.whl

yapcad/geometry_utils.py

@@ -0,0 +1,115 @@
+"""Common geometric helpers shared across exporters and validators."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Sequence, Tuple
+
+from yapcad.geom import cross, epsilon, mag
+
+Vec3 = Tuple[float, float, float]
+
+
+@dataclass(frozen=True)
+class Triangle:
+    """Immutable triangle representation in XYZ space."""
+
+    normal: Vec3
+    v0: Vec3
+    v1: Vec3
+    v2: Vec3
+
+
+def to_vec3(point_like: Sequence[float]) -> Vec3:
+    """Return the XYZ components of a yapCAD point/vector as a tuple."""
+
+    if len(point_like) < 3:
+        raise ValueError("value must have at least three components")
+    return float(point_like[0]), float(point_like[1]), float(point_like[2])
+
+
+def to_point(vec: Sequence[float]) -> Tuple[float, float, float, float]:
+    """Lift an XYZ tuple into yapCAD homogeneous point form."""
+
+    if len(vec) < 3:
+        raise ValueError("vector must have three components")
+    return float(vec[0]), float(vec[1]), float(vec[2]), 1.0
+
+
+def to_vector(vec: Sequence[float]) -> Tuple[float, float, float, float]:
+    """Lift an XYZ tuple into yapCAD homogeneous vector form (w=0)."""
+
+    if len(vec) < 3:
+        raise ValueError("vector must have three components")
+    return float(vec[0]), float(vec[1]), float(vec[2]), 0.0
+
+
+def triangle_normal(v0: Vec3, v1: Vec3, v2: Vec3) -> Vec3 | None:
+    """Return the unit normal of a triangle or ``None`` if degenerate."""
+
+    ax, ay, az = v1[0] - v0[0], v1[1] - v0[1], v1[2] - v0[2]
+    bx, by, bz = v2[0] - v0[0], v2[1] - v0[1], v2[2] - v0[2]
+    n = cross([ax, ay, az, 1.0], [bx, by, bz, 1.0])
+    length = mag(n)
+    if length <= epsilon:
+        return None
+    return (n[0] / length, n[1] / length, n[2] / length)
+
+
+def triangle_area(v0: Vec3, v1: Vec3, v2: Vec3) -> float:
+    """Return the area of a triangle."""
+
+    ax, ay, az = v1[0] - v0[0], v1[1] - v0[1], v1[2] - v0[2]
+    bx, by, bz = v2[0] - v0[0], v2[1] - v0[1], v2[2] - v0[2]
+    n = cross([ax, ay, az, 1.0], [bx, by, bz, 1.0])
+    return 0.5 * mag(n)
+
+
+def triangle_is_degenerate(v0: Vec3, v1: Vec3, v2: Vec3, tol: float = epsilon) -> bool:
+    """Return ``True`` if a triangle collapses under the given tolerance."""
+
+    return triangle_area(v0, v1, v2) <= tol
+
+
+def orient_triangle(v0: Vec3, v1: Vec3, v2: Vec3, preferred_normal: Vec3) -> Tuple[Vec3, Vec3, Vec3]:
+    """Ensure triangle winding aligns with ``preferred_normal``."""
+
+    current = triangle_normal(v0, v1, v2)
+    if current is None:
+        return v0, v1, v2
+    dot = current[0] * preferred_normal[0] + current[1] * preferred_normal[1] + current[2] * preferred_normal[2]
+    if dot < 0:
+        return v0, v2, v1
+    return v0, v1, v2
+
+
+def triangle_centroid(v0: Vec3, v1: Vec3, v2: Vec3) -> Vec3:
+    """Return the centroid of a triangle."""
+
+    return (
+        (v0[0] + v1[0] + v2[0]) / 3.0,
+        (v0[1] + v1[1] + v2[1]) / 3.0,
+        (v0[2] + v1[2] + v2[2]) / 3.0,
+    )
+
+
+def triangles_from_mesh(mesh: Iterable[Tuple[Vec3, Vec3, Vec3, Vec3]]) -> Iterable[Triangle]:
+    """Convert ``mesh_view`` output into ``Triangle`` instances."""
+
+    for normal, v0, v1, v2 in mesh:
+        yield Triangle(normal=normal, v0=v0, v1=v1, v2=v2)
+
+
+__all__ = [
+    "Triangle",
+    "Vec3",
+    "to_vec3",
+    "to_point",
+    "to_vector",
+    "triangle_normal",
+    "triangle_area",
+    "triangle_is_degenerate",
+    "orient_triangle",
+    "triangle_centroid",
+    "triangles_from_mesh",
+]

yapcad/io/__init__.py

@@ -0,0 +1,5 @@
+"""I/O utilities for yapCAD."""
+
+from .stl import write_stl
+
+__all__ = ['write_stl']

yapcad/io/stl.py

@@ -0,0 +1,83 @@
+"""STL export utilities for yapCAD surfaces and solids."""
+
+from __future__ import annotations
+
+import io
+import os
+import struct
+from typing import Iterable, Sequence, TextIO
+
+from yapcad.geometry_utils import Triangle, triangles_from_mesh
+from yapcad.mesh import mesh_view
+
+_HEADER_SIZE = 80
+_STRUCT_TRIANGLE = struct.Struct('<12fH')
+
+
+def write_stl(obj: Sequence, path_or_file, *, binary: bool = True, name: str = 'yapCAD') -> None:
+    """Write ``obj`` (surface or solid) to STL.
+
+    ``path_or_file`` can be a filesystem path or an open binary/text stream.
+    """
+
+    triangles = list(triangles_from_mesh(mesh_view(obj)))
+
+    if binary:
+        _write_binary(triangles, path_or_file, name)
+    else:
+        _write_ascii(triangles, path_or_file, name)
+
+
+def _write_binary(triangles: Iterable[Triangle], path_or_file, name: str) -> None:
+    close_when_done = False
+    if hasattr(path_or_file, 'write'):
+        stream = path_or_file
+    else:
+        stream = open(path_or_file, 'wb')
+        close_when_done = True
+
+    try:
+        header = (name[:_HEADER_SIZE]).encode('ascii', errors='replace')
+        header = header.ljust(_HEADER_SIZE, b' ')
+        stream.write(header)
+        stream.write(struct.pack('<I', len(triangles)))
+
+        for tri in triangles:
+            data = _STRUCT_TRIANGLE.pack(
+                *tri.normal,
+                *tri.v0,
+                *tri.v1,
+                *tri.v2,
+                0,
+            )
+            stream.write(data)
+    finally:
+        if close_when_done:
+            stream.close()
+
+
+def _write_ascii(triangles: Iterable[Triangle], path_or_file, name: str) -> None:
+    close_when_done = False
+    if hasattr(path_or_file, 'write'):
+        stream = path_or_file
+    else:
+        stream = open(path_or_file, 'w', encoding='ascii')
+        close_when_done = True
+
+    try:
+        print(f"solid {name}", file=stream)
+        for tri in triangles:
+            print(f"  facet normal {tri.normal[0]:.6e} {tri.normal[1]:.6e} {tri.normal[2]:.6e}", file=stream)
+            print("    outer loop", file=stream)
+            print(f"      vertex {tri.v0[0]:.6e} {tri.v0[1]:.6e} {tri.v0[2]:.6e}", file=stream)
+            print(f"      vertex {tri.v1[0]:.6e} {tri.v1[1]:.6e} {tri.v1[2]:.6e}", file=stream)
+            print(f"      vertex {tri.v2[0]:.6e} {tri.v2[1]:.6e} {tri.v2[2]:.6e}", file=stream)
+            print("    endloop", file=stream)
+            print("  endfacet", file=stream)
+        print(f"endsolid {name}", file=stream)
+    finally:
+        if close_when_done:
+            stream.close()
+
+
+__all__ = ['write_stl']

yapcad/mesh.py

@@ -0,0 +1,46 @@
+"""Utilities for working with triangulated views of yapCAD surfaces."""
+
+from __future__ import annotations
+
+from typing import Iterable, Iterator, Sequence, Tuple
+
+from yapcad.geom3d import issolid, issurface
+from yapcad.geometry_utils import to_vec3, triangle_normal
+
+Vec3 = Tuple[float, float, float]
+TriTuple = Tuple[Vec3, Vec3, Vec3, Vec3]
+
+
+def mesh_view(obj: Sequence) -> Iterator[TriTuple]:
+    """Yield triangles for a surface or solid as ``(normal, v0, v1, v2)``.
+
+    Normals are unit vectors. Vertices are returned as ``(x, y, z)`` tuples.
+    Faces with degenerate geometry (zero area) are skipped silently.
+    """
+
+    surfaces: Iterable[Sequence]
+    if issurface(obj):
+        surfaces = [obj]
+    elif issolid(obj):
+        surfaces = obj[1]
+    else:
+        raise ValueError("mesh_view expects a surface or solid")
+
+    for surf in surfaces:
+        verts = surf[1]
+        faces = surf[3] if len(surf) > 3 else []
+
+        for face in faces:
+            if len(face) != 3:
+                continue
+            idx0, idx1, idx2 = face
+            v0 = to_vec3(verts[idx0])
+            v1 = to_vec3(verts[idx1])
+            v2 = to_vec3(verts[idx2])
+
+            calc_normal = triangle_normal(v0, v1, v2)
+            if calc_normal is None:
+                continue
+
+            yield calc_normal, v0, v1, v2
+

yapcad/metadata.py

@@ -0,0 +1,109 @@
+"""Metadata helpers for yapCAD geometry objects."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Dict, Tuple
+
+from yapcad.geom3d import issolid, issurface
+
+_SURFACE_META_INDEX = 6
+_SOLID_META_INDEX = 4
+
+
+def _ensure_metadata(container: list, index: int, create: bool) -> Dict:
+    if len(container) <= index:
+        if not create:
+            return {}
+        while len(container) <= index:
+            container.append({})
+    meta = container[index]
+    if not isinstance(meta, dict):
+        if not create:
+            return {}
+        meta = {}
+        container[index] = meta
+    return meta
+
+
+def get_surface_metadata(surface: list, create: bool = False) -> Dict:
+    if not issurface(surface):
+        raise ValueError('invalid surface passed to get_surface_metadata')
+    return _ensure_metadata(surface, _SURFACE_META_INDEX, create)
+
+
+def set_surface_metadata(surface: list, metadata: Dict) -> list:
+    if not isinstance(metadata, dict):
+        raise ValueError('surface metadata must be a dictionary')
+    if not issurface(surface):
+        raise ValueError('invalid surface passed to set_surface_metadata')
+    if len(surface) <= _SURFACE_META_INDEX:
+        surface.append(metadata)
+    else:
+        surface[_SURFACE_META_INDEX] = metadata
+    return surface
+
+
+def ensure_surface_id(surface: list) -> str:
+    meta = get_surface_metadata(surface, create=True)
+    if 'id' not in meta:
+        meta['id'] = str(uuid.uuid4())
+    return meta['id']
+
+
+def set_surface_units(surface: list, units: str) -> list:
+    meta = get_surface_metadata(surface, create=True)
+    meta['units'] = units
+    return surface
+
+
+def set_surface_origin(surface: list, origin: str) -> list:
+    meta = get_surface_metadata(surface, create=True)
+    meta['origin'] = origin
+    return surface
+
+
+def get_solid_metadata(sld: list, create: bool = False) -> Dict:
+    if not issolid(sld):
+        raise ValueError('invalid solid passed to get_solid_metadata')
+    return _ensure_metadata(sld, _SOLID_META_INDEX, create)
+
+
+def set_solid_metadata(sld: list, metadata: Dict) -> list:
+    if not isinstance(metadata, dict):
+        raise ValueError('solid metadata must be a dictionary')
+    if not issolid(sld):
+        raise ValueError('invalid solid passed to set_solid_metadata')
+    if len(sld) <= _SOLID_META_INDEX:
+        sld.append(metadata)
+    else:
+        sld[_SOLID_META_INDEX] = metadata
+    return sld
+
+
+def ensure_solid_id(sld: list) -> str:
+    meta = get_solid_metadata(sld, create=True)
+    if 'id' not in meta:
+        meta['id'] = str(uuid.uuid4())
+    return meta['id']
+
+
+def set_solid_context(sld: list, context: Dict) -> list:
+    if not isinstance(context, dict):
+        raise ValueError('context must be a dictionary')
+    meta = get_solid_metadata(sld, create=True)
+    meta['context'] = context
+    return sld
+
+
+__all__ = [
+    'get_surface_metadata',
+    'set_surface_metadata',
+    'ensure_surface_id',
+    'set_surface_units',
+    'set_surface_origin',
+    'get_solid_metadata',
+    'set_solid_metadata',
+    'ensure_solid_id',
+    'set_solid_context',
+]