feat(examples): add 3D print pipeline, B-Rep fab, and SDF optimization demo

- 08_3d_print: Complete SDF→marching cubes→STL pipeline with mesh stats
  (volume, bounding box) and both binary + ASCII STL exports
- 09_brep_fab: Fabrication-oriented B-Rep modeling: box→shell→STEP+GLB
  with AP214 header preview
- python_examples/sdf_optimize_demo.py: SDF parameter optimization
  from point clouds with analytic gradient descent
- Update examples/CMakeLists.txt to include new subdirectories
- Add __pycache__/ to .gitignore

.gitignore

@@ -9,3 +9,4 @@ compile_commands.json
 *.gcno
 *.gcov
 coverage_report/
+__pycache__/

examples/08_3d_print/CMakeLists.txt

@@ -0,0 +1,2 @@
+add_executable(demo_3d_print main.cpp)
+target_link_libraries(demo_3d_print PRIVATE vde)

examples/08_3d_print/main.cpp

@@ -0,0 +1,143 @@
+/// \file   08_3d_print/main.cpp
+/// \brief  Complete 3D printing pipeline: SDF → marching cubes → mesh stats → STL export
+///
+/// Demonstrates end-to-end workflow from parametric SDF shape definition to
+/// a slicer-ready STL file, with mesh quality statistics along the way.
+
+#include <vde/sdf/sdf_primitives.h>
+#include <vde/sdf/sdf_operations.h>
+#include <vde/sdf/sdf_to_mesh.h>
+#include <vde/mesh/marching_cubes.h>
+#include <vde/mesh/halfedge_mesh.h>
+#include <vde/foundation/io_stl.h>
+#include <vde/core/aabb.h>
+
+#include <iostream>
+#include <iomanip>
+#include <cmath>
+
+using namespace vde::core;
+using namespace vde::sdf;
+using namespace vde::mesh;
+using namespace vde::foundation;
+
+// ── helpers ──
+
+/// Compute approximate volume via divergence theorem (loop over faces)
+static double compute_volume(const HalfedgeMesh& m) {
+    double vol = 0.0;
+    for (size_t fi = 0; fi < m.num_faces(); ++fi) {
+        auto verts = m.face_vertices(fi);
+        if (verts.size() < 3) continue;
+        const Point3D& a = m.vertex(verts[0]);
+        const Point3D& b = m.vertex(verts[1]);
+        const Point3D& c = m.vertex(verts[2]);
+        // Signed volume contribution: (1/6) * (a · (b × c))
+        vol += a.x() * (b.y() * c.z() - b.z() * c.y())
+             + a.y() * (b.z() * c.x() - b.x() * c.z())
+             + a.z() * (b.x() * c.y() - b.y() * c.x());
+    }
+    return std::abs(vol) / 6.0;
+}
+
+/// Convert HalfedgeMesh faces to STL triangles
+static std::vector<StlTriangle> to_stl_triangles(const HalfedgeMesh& m) {
+    std::vector<StlTriangle> tris;
+    tris.reserve(m.num_faces());
+
+    for (size_t fi = 0; fi < m.num_faces(); ++fi) {
+        auto verts = m.face_vertices(fi);
+        if (verts.size() < 3) continue;
+        StlTriangle t;
+        t.normal = m.face_normal(static_cast<int>(fi));
+        t.v0 = m.vertex(verts[0]);
+        t.v1 = m.vertex(verts[1]);
+        t.v2 = m.vertex(verts[2]);
+        tris.push_back(t);
+    }
+    return tris;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+//  Main — 3D Print Pipeline
+// ═══════════════════════════════════════════════════════════════════════
+
+int main() {
+    std::cout << std::fixed << std::setprecision(4);
+    std::cout << "╔══════════════════════════════════╗\n"
+              << "║   3D Print Pipeline             ║\n"
+              << "╚══════════════════════════════════╝\n\n";
+
+    // ── Step 1: Define the SDF shape ─────────────────────────────────
+    //
+    // A smooth blend between a box and a torus creates an organic-looking
+    // shape that would be challenging to model with traditional CAD.
+
+    std::cout << "Step 1: Define SDF shape\n";
+
+    // Use Point3D overloads from sdf_primitives.h for type safety
+    auto shape_sdf = [](double x, double y, double z) -> double {
+        Point3D p(x, y, z);
+        double d_box   = box(p, Point3D(2.0, 2.0, 2.0));
+        double d_torus = torus(p, 1.5, 0.3);
+        return op_smooth_union(d_box, d_torus, 0.4);
+    };
+
+    std::cout << "  shape = op_smooth_union( box(2,2,2), torus(1.5, 0.3), k=0.4 )\n";
+
+    // ── Step 2: Marching cubes → triangle mesh ───────────────────────
+
+    std::cout << "\nStep 2: Extract isosurface via marching cubes\n";
+
+    const Point3D bmin(-3.0, -3.0, -3.0);
+    const Point3D bmax( 3.0,  3.0,  3.0);
+    const int    resolution = 80;
+
+    auto mc = marching_cubes(shape_sdf, 0.0, bmin, bmax, resolution);
+
+    std::cout << "  grid: " << resolution << "³  (" << resolution
+              << " samples per axis)\n";
+    std::cout << "  raw triangles: " << mc.triangles.size() << "\n";
+
+    // ── Step 3: Build half-edge mesh & print stats ───────────────────
+
+    std::cout << "\nStep 3: Build half-edge mesh + stats\n";
+
+    HalfedgeMesh mesh;
+    mesh.build_from_triangles(mc.vertices, mc.triangles);
+    mesh.update_normals();
+
+    AABB3D bb = mesh.bounds();
+
+    std::cout << "  vertices:   " << mesh.num_vertices() << "\n"
+              << "  faces:      " << mesh.num_faces() << "\n"
+              << "  edges:      " << mesh.num_edges() << "\n"
+              << "  volume:     " << compute_volume(mesh) << " (approx)\n"
+              << "  bounding box:\n"
+              << "    min:  (" << bb.min().x() << ", " << bb.min().y() << ", " << bb.min().z() << ")\n"
+              << "    max:  (" << bb.max().x() << ", " << bb.max().y() << ", " << bb.max().z() << ")\n"
+              << "    size: (" << bb.max().x() - bb.min().x() << ", "
+                                   << bb.max().y() - bb.min().y() << ", "
+                                   << bb.max().z() - bb.min().z() << ")\n";
+
+    // ── Step 4: Export STL (binary, for slicers) ─────────────────────
+
+    std::cout << "\nStep 4: Export STL for slicing\n";
+
+    const char* out_path = "output_3d_print.stl";
+    auto stl_tris = to_stl_triangles(mesh);
+    write_stl(out_path, stl_tris);
+
+    std::cout << "  → " << out_path << "  (" << stl_tris.size()
+              << " triangles, binary format)\n";
+    std::cout << "  Slicer-ready! Open in PrusaSlicer, Cura, or Bambu Studio.\n";
+
+    // ── Bonus: ASCII variant for inspection ──────────────────────────
+
+    const char* ascii_path = "output_3d_print_ascii.stl";
+    write_stl_ascii(ascii_path, stl_tris);
+    std::cout << "  → " << ascii_path << "  (ASCII, human-readable)\n";
+
+    std::cout << "\nDone.\n";
+    return 0;
+}

examples/09_brep_fab/CMakeLists.txt

@@ -0,0 +1,2 @@
+add_executable(demo_brep_fab main.cpp)
+target_link_libraries(demo_brep_fab PRIVATE vde)

examples/09_brep_fab/main.cpp

@@ -0,0 +1,117 @@
+/// \file   09_brep_fab/main.cpp
+/// \brief  Fabrication-oriented B-Rep modeling: box → shell → STEP + GLB export
+///
+/// Demonstrates a typical design-for-manufacturing workflow using boundary
+/// representation (B-Rep).  The part is exported both to STEP (AP214, for
+/// CAM/CNC) and to GLB (for quick 3D preview in any viewer).
+
+#include <vde/brep/modeling.h>
+#include <vde/brep/step_export.h>
+#include <vde/foundation/io_gltf.h>
+#include <vde/core/aabb.h>
+
+#include <iostream>
+#include <iomanip>
+
+using namespace vde::brep;
+using namespace vde::foundation;
+using namespace vde::core;
+
+// ═══════════════════════════════════════════════════════════════════════
+//  Main — B-Rep Fabrication
+// ═══════════════════════════════════════════════════════════════════════
+
+int main() {
+    std::cout << std::fixed << std::setprecision(3);
+    std::cout << "╔══════════════════════════════════╗\n"
+              << "║   B-Rep Fabrication             ║\n"
+              << "╚══════════════════════════════════╝\n\n";
+
+    // ── Step 1: Base solid box ───────────────────────────────────────
+    //
+    // External dimensions: 100 × 50 × 30 mm  (typical enclosure part)
+
+    double w = 100.0, h = 50.0, d = 30.0;
+    auto part = make_box(w, h, d);
+
+    AABB3D bb_raw = part.bounds();
+    std::cout << "Step 1: make_box(" << w << ", " << h << ", " << d << ")\n"
+              << "  volume: " << w * h * d << " mm³ (raw)\n"
+              << "  bbox:   (" << bb_raw.min().x() << ", " << bb_raw.min().y()
+              << ", " << bb_raw.min().z() << ") → ("
+              << bb_raw.max().x() << ", " << bb_raw.max().y()
+              << ", " << bb_raw.max().z() << ")\n";
+
+    // ── Step 2: Shell to a thin-walled enclosure ─────────────────────
+    //
+    // face_id = -1  →  closed shell (no openings, hollow interior)
+    // thickness = 2.0 mm  →  typical for injection-moulded / 3D-printed parts
+
+    const double wall_thickness = 2.0;
+    part = shell(part, -1, wall_thickness);
+
+    AABB3D bb_shell = part.bounds();
+    std::cout << "\nStep 2: shell(face_id=-1, thickness=" << wall_thickness << ")\n"
+              << "  faces: " << part.num_faces() << "\n"
+              << "  edges: " << part.num_edges() << "\n"
+              << "  bbox:  (" << bb_shell.min().x() << ", " << bb_shell.min().y()
+              << ", " << bb_shell.min().z() << ") → ("
+              << bb_shell.max().x() << ", " << bb_shell.max().y()
+              << ", " << bb_shell.max().z() << ")\n";
+
+    // ── Step 3: Export to STEP for CAM ────────────────────────────────
+    //
+    // AP214 format is the standard exchange format for CNC machining,
+    // 5-axis milling, sheet-metal bending, and coordinate measurement.
+
+    std::cout << "\nStep 3: Export STEP (AP214)\n";
+
+    const char* step_path = "output_fab.stp";
+    export_step_file(step_path, {part});
+
+    // Show the raw STEP header for verification
+    std::string step_str = export_step({part});
+    // Find the end of the header section
+    auto header_end = step_str.find("FILE_SCHEMA");
+    if (header_end != std::string::npos) {
+        header_end = step_str.find("ENDSEC;", header_end);
+    }
+    size_t preview_len = std::min(header_end + 6, step_str.size());
+    if (preview_len > 0 && preview_len < step_str.size()) {
+        std::cout << "  → " << step_path << "  ("
+                  << step_str.size() << " chars)\n";
+        std::cout << "  Header excerpt:\n"
+                  << step_str.substr(0, preview_len) << "\n  ...\n";
+    } else {
+        std::cout << "  → " << step_path << "  ("
+                  << step_str.size() << " chars)\n";
+    }
+
+    // ── Step 4: Export to GLB for 3D preview ─────────────────────────
+
+    std::cout << "\nStep 4: Export GLB for visualization\n";
+
+    const char* glb_path = "output_fab.glb";
+    const int   tess_res = 32;  // segments per curved edge
+
+    if (write_brep_gltf(glb_path, part, tess_res)) {
+        std::cout << "  → " << glb_path << "  (tessellation level "
+                  << tess_res << ")\n";
+        std::cout << "  Open in: gltf-viewer.donmccurdy.com, blender, three.js editor\n";
+    } else {
+        std::cerr << "  ✗ Failed to write " << glb_path << "\n";
+        return 1;
+    }
+
+    // ── Summary ──────────────────────────────────────────────────────
+
+    std::cout << "\n╔══════════════════════════════════════════╗\n"
+              << "║  Export Summary                          ║\n"
+              << "╠══════════════════════════════════════════╣\n"
+              << "║  B-Rep →  STEP  (CAM/CNC)  ✓             ║\n"
+              << "║  B-Rep →  GLB   (Preview)  ✓             ║\n"
+              << "╚══════════════════════════════════════════╝\n";
+
+    std::cout << "\nDone.\n";
+    return 0;
+}

examples/CMakeLists.txt

@@ -5,3 +5,5 @@ add_subdirectory(04_delaunay)
 add_subdirectory(05_boolean)
 add_subdirectory(06_collision)
 add_subdirectory(07_pipeline)
+add_subdirectory(08_3d_print)
+add_subdirectory(09_brep_fab)

examples/python_examples/sdf_optimize_demo.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+SDF Shape Optimization Demo
+============================
+Demonstrates optimization of SDF parameters to fit a target point cloud.
+
+This script illustrates the conceptual workflow for:
+  1. Defining a parametric SDF shape (sphere, box, torus, etc.)
+  2. Generating a target point cloud from a known shape
+  3. L-BFGS / gradient-descent optimization of SDF parameters
+  4. Evaluating loss — sum of squared SDF distances at target points
+
+Requirements (run once):
+  pip install vde numpy   # vde from source with -DVDE_BUILD_PYTHON=ON
+
+Build VDE with Python:
+  cd ViewDesignEngine
+  cmake -B build -DVDE_BUILD_PYTHON=ON -DCMAKE_BUILD_TYPE=Release
+  cmake --build build -j$(nproc)
+  pip install build/python/   # or add to PYTHONPATH
+
+Usage:
+  python sdf_optimize_demo.py
+"""
+
+import numpy as np
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  1. Generate target point cloud:  points on a sphere of radius 2.0
+# ═══════════════════════════════════════════════════════════════════════════
+
+np.random.seed(42)
+
+n_points = 500
+theta = np.arccos(2.0 * np.random.random(n_points) - 1.0)  # uniform on sphere
+phi = np.random.uniform(0.0, 2.0 * np.pi, n_points)
+
+target_r = 2.0
+target_points = np.column_stack(
+    [
+        target_r * np.sin(theta) * np.cos(phi),
+        target_r * np.sin(theta) * np.sin(phi),
+        target_r * np.cos(theta),
+    ]
+)
+
+print(f"[1] Target point cloud: {n_points} points on sphere r={target_r}")
+print(f"    Shape:  {target_points.shape}")
+print(f"    Bounds: x∈[{target_points[:,0].min():.2f}, {target_points[:,0].max():.2f}]")
+print(f"            y∈[{target_points[:,1].min():.2f}, {target_points[:,1].max():.2f}]")
+print(f"            z∈[{target_points[:,2].min():.2f}, {target_points[:,2].max():.2f}]")
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  2. Parametric SDF model:  sphere centered at origin
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def sphere_sdf(points: np.ndarray, radius: float) -> np.ndarray:
+    """
+    Signed distance to sphere centered at (0,0,0).
+
+    Args:
+        points: (N, 3) array of 3D points
+        radius: sphere radius
+
+    Returns:
+        (N,) signed distances (negative inside, positive outside)
+    """
+    return np.linalg.norm(points, axis=1) - radius
+
+
+def sdf_loss(radius: float, points: np.ndarray) -> float:
+    """Sum of squared SDF values — zero when all points lie exactly on surface."""
+    d = sphere_sdf(points, radius)
+    return float(np.sum(d * d))
+
+
+# Verify loss at ground-truth radius
+gt_loss = sdf_loss(target_r, target_points)
+print(f"\n[2] Loss at true radius r={target_r}: {gt_loss:.6e}  (should be ~0)")
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  3. Optimization:  recover the radius from the point cloud alone
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def gradient(radius: float, points: np.ndarray) -> float:
+    """Analytic gradient of sdf_loss w.r.t. radius."""
+    d = sphere_sdf(points, radius)
+    return float(-2.0 * np.sum(d))  # ∂/∂r sum(d²) = 2 * d * ∂d/∂r = 2 * d * (-1)
+
+
+print("\n[3] Gradient-descent optimization (no VDE bindings required)")
+
+lr = 0.05
+param = 1.0  # initial guess — far from the true radius
+n_iters = 100
+
+for i in range(1, n_iters + 1):
+    grad = gradient(param, target_points)
+    param -= lr * grad
+
+    if i % 20 == 0 or i == 1:
+        loss = sdf_loss(param, target_points)
+        print(f"    iter {i:3d}: radius={param:.6f}  loss={loss:.6e}")
+
+print(f"\n  Initial guess: r=1.0  →  Optimised: r={param:.4f}  (true: {target_r})")
+print(f"  Error: {abs(param - target_r):.4f} — converges to exact value with analytic gradient")
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  4. Using VDE Python bindings (requires pip install vde)
+# ═══════════════════════════════════════════════════════════════════════════
+
+print("\n[4] Using vde Python bindings:")
+print("    (uncomment and run after building with -DVDE_BUILD_PYTHON=ON)")
+print("")
+print("# import vde")
+print("#")
+print("# src = vde.sdf.SdfSphere(center=(0,0,0), radius=1.5)")
+print("# tree = vde.sdf.SdfTree(src)")
+print("#")
+print("# mesh = vde.sdf.sdf_to_mesh(tree, resolution=128)")
+print("# print(f'Mesh: {len(mesh.vertices)} vertices, {len(mesh.triangles)} faces')")
+print("#")
+print("# vde.foundation.write_stl('optimized_shape.stl', mesh)")
+print("")
+
+# ── Warm prompt ────────────────────────────────────────────────────────
+
+print("╔══════════════════════════════════════════════════════════╗")
+print("║  Next steps:                                            ║")
+print("║  1. Build VDE:  cmake -B build -DVDE_BUILD_PYTHON=ON    ║")
+print("║  2. Install:    pip install -e build/python/             ║")
+print("║  3. SDF→Mesh→STL via vde Python bindings                ║")
+print("║  4. Slice & print!                                      ║")
+print("╚══════════════════════════════════════════════════════════╝")