trenchfoot 0.1.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

trenchfoot/trench_scene_generator_v3.py

@@ -33,6 +33,9 @@ except Exception:
     plt = None
     Poly3DCollection = None
 
+# Groups kept for internal metrics but excluded from OBJ export and previews
+_INTERNAL_GROUPS = frozenset({"trench_cap_for_volume"})
+
 # ---------------- Geometry helpers ----------------
 
 def _normalize(v: np.ndarray) -> np.ndarray:
@@ -74,6 +77,19 @@ def _sample_polyline_at_s(path: List[Tuple[float,float]], s: float):
         t = seg / L; u = (s_abs - cum[i]) / L; pos = (1-u)*P[i] + u*P[i+1]
     return pos, t
 
+def _is_path_closed(path: List[Tuple[float,float]], threshold: float = 0.01) -> bool:
+    """Detect if a path is explicitly closed (first and last points nearly identical).
+
+    Returns True only if the first and last points are within threshold distance.
+    Use a small threshold (default 0.01) to only catch truly closed paths where
+    the endpoint is repeated.
+    """
+    if len(path) < 3:
+        return False
+    P = np.array(path, float)
+    first_last_dist = np.linalg.norm(P[0] - P[-1])
+    return first_last_dist < threshold
+
 def _offset_polyline(path: List[Tuple[float,float]], offset: float):
     P = np.array(path, float); n = len(P)
     if n < 2: raise ValueError("Polyline needs at least 2 points")
@@ -100,6 +116,43 @@ def _offset_polyline(path: List[Tuple[float,float]], offset: float):
     right_pts.append(P[-1] - offset * normals[-1])
     return left_pts, right_pts
 
+def _offset_closed_polyline(path: List[Tuple[float,float]], offset: float) -> List[np.ndarray]:
+    """Offset a closed polyline, returning a single closed ring.
+
+    Unlike _offset_polyline which returns left/right sides for open paths,
+    this returns a single continuous closed ring for paths where first ≈ last point.
+    """
+    P = np.array(path, float)
+    n = len(P)
+    if n < 3:
+        raise ValueError("Closed polyline needs at least 3 points")
+
+    # Compute tangents treating path as closed loop
+    tangents = []
+    normals = []
+    for i in range(n):
+        t = _normalize(P[(i+1) % n] - P[i])
+        if np.linalg.norm(t) < 1e-12:
+            t = np.array([1.0, 0.0])
+        tangents.append(t)
+        normals.append(_rotate_ccw(t))
+
+    # Compute offset points with proper miter at each vertex
+    offset_pts = []
+    for k in range(n):
+        t_prev, n_prev = tangents[(k-1) % n], normals[(k-1) % n]
+        t_next, n_next = tangents[k], normals[k]
+        L1_p = P[k] + offset * n_prev
+        L1_d = t_prev
+        L2_p = P[k] + offset * n_next
+        L2_d = t_next
+        pt = _line_intersection_2d(L1_p, L1_d, L2_p, L2_d)
+        if pt is None:
+            pt = 0.5 * (L1_p + L2_p)
+        offset_pts.append(pt)
+
+    return offset_pts
+
 def _polygon_area_2d(poly_xy: np.ndarray) -> float:
     x = poly_xy[:,0]; y = poly_xy[:,1]
     return 0.5 * float(np.dot(x, np.roll(y, -1)) - np.dot(y, np.roll(x, -1)))
@@ -262,9 +315,14 @@ def _compute_surface_metrics(
     return metrics
 
 
-def _render_surface_previews(groups: Dict[str, Tuple[np.ndarray, np.ndarray]]) -> Dict[str, bytes]:
+def _render_surface_previews(
+    groups: Dict[str, Tuple[np.ndarray, np.ndarray]],
+    exclude_groups: Optional[frozenset] = None,
+) -> Dict[str, bytes]:
     if plt is None or not groups:
         return {}
+    if exclude_groups:
+        groups = {k: v for k, v in groups.items() if k not in exclude_groups}
     all_vertices = [V for (V, F) in groups.values() if V.size > 0]
     if not all_vertices:
         return {}
@@ -380,7 +438,9 @@ class SurfaceMeshResult:
         out_path = Path(out_dir)
         out_path.mkdir(parents=True, exist_ok=True)
         obj_path = out_path / "trench_scene.obj"
-        write_obj_with_groups(obj_path.as_posix(), self.groups)
+        # Exclude internal groups (like trench_cap_for_volume) from OBJ export
+        export_groups = {k: v for k, v in self.groups.items() if k not in _INTERNAL_GROUPS}
+        write_obj_with_groups(obj_path.as_posix(), export_groups)
         metrics_path = out_path / "metrics.json"
         with metrics_path.open("w") as fh:
             json.dump(self.metrics, fh, indent=2)
@@ -491,60 +551,276 @@ def make_trench_from_path_sloped(path_xy: List[Tuple[float,float]], width_top: f
     half_top = width_top/2.0
     shrink = max(0.0, wall_slope * depth)
     half_bot = max(1e-3, half_top - shrink)
-    L_top, R_top = _offset_polyline(path_xy, half_top)
-    L_bot, R_bot = _offset_polyline(path_xy, half_bot)
-    poly_top = _ensure_ccw(_ring_from_LR(L_top, R_top))
-    poly_bot = _ensure_ccw(_ring_from_LR(L_bot, R_bot))
 
-    gfun = _ground_fn(ground)
-    # Top and bottom rings lie on the ground plane and ground-depth respectively
-    z_top = np.array([gfun(x,y) for x,y in poly_top]); z_bot = np.array([gfun(x,y) - depth for x,y in poly_bot])
-    tris_top = _ear_clipping_triangulation(poly_top)
-    tris_bot = _ear_clipping_triangulation(poly_bot)
-    V_cap = np.column_stack([poly_top, z_top])
-    V_bottom = np.column_stack([poly_bot, z_bot])
-    F_cap = tris_top
-    F_bottom = tris_bot[:, ::-1]  # outward
-
-    # Walls: connect corresponding indices
-    N = len(poly_top); assert N == len(poly_bot)
-    walls_V = []; walls_F = []
-    for i in range(N):
-        j=(i+1)%N
-        A_top = np.array([poly_top[i,0], poly_top[i,1], z_top[i]])
-        B_top = np.array([poly_top[j,0], poly_top[j,1], z_top[j]])
-        A_bot = np.array([poly_bot[i,0], poly_bot[i,1], z_bot[i]])
-        B_bot = np.array([poly_bot[j,0], poly_bot[j,1], z_bot[j]])
-        base=len(walls_V)
-        walls_V.extend([A_top, B_top, B_bot, A_bot])
-        walls_F.extend([[base, base+1, base+2], [base, base+2, base+3]])
-    V_walls = np.array(walls_V,float); F_walls = np.array(walls_F,int)
+    is_closed = _is_path_closed(path_xy)
+
+    if is_closed:
+        # For closed paths (like circles), create outer/inner rings
+        # Outer ring: centerline offset outward (positive)
+        # Inner ring: centerline offset inward (negative)
+        outer_top = np.array(_offset_closed_polyline(path_xy, half_top), float)
+        inner_top = np.array(_offset_closed_polyline(path_xy, -half_top), float)
+        outer_bot = np.array(_offset_closed_polyline(path_xy, half_bot), float)
+        inner_bot = np.array(_offset_closed_polyline(path_xy, -half_bot), float)
+
+        # Ensure CCW orientation (outer should be CCW, inner CW for proper normals)
+        outer_top = _ensure_ccw(outer_top)
+        outer_bot = _ensure_ccw(outer_bot)
+        # Inner rings should go opposite direction
+        if _polygon_area_2d(inner_top) > 0:
+            inner_top = inner_top[::-1].copy()
+        if _polygon_area_2d(inner_bot) > 0:
+            inner_bot = inner_bot[::-1].copy()
+
+        gfun = _ground_fn(ground)
+
+        # For closed trenches, we need outer wall, inner wall, and bottom (no cap for annular trench)
+        # Actually, for annular trench, the "bottom" is an annulus and the "cap" is also an annulus
+        z_outer_top = np.array([gfun(x,y) for x,y in outer_top])
+        z_inner_top = np.array([gfun(x,y) for x,y in inner_top])
+        z_outer_bot = np.array([gfun(x,y) - depth for x,y in outer_bot])
+        z_inner_bot = np.array([gfun(x,y) - depth for x,y in inner_bot])
+
+        # Triangulate annular cap and bottom
+        cap_verts, cap_faces = _triangulate_annulus(outer_top, inner_top[::-1])  # reverse inner for CCW
+        V_cap = np.column_stack([cap_verts, np.concatenate([z_outer_top, z_inner_top[::-1]])])
+        F_cap = cap_faces
+
+        bot_verts, bot_faces = _triangulate_annulus(outer_bot, inner_bot[::-1])
+        V_bottom = np.column_stack([bot_verts, np.concatenate([z_outer_bot, z_inner_bot[::-1]])])
+        F_bottom = bot_faces[:, ::-1]  # flip for outward normals
+
+        # Outer wall: connects outer_top to outer_bot (facing outward from trench)
+        n_outer = len(outer_top)
+        walls_V = []
+        walls_F = []
+        for i in range(n_outer):
+            j = (i + 1) % n_outer
+            A_top = np.array([outer_top[i,0], outer_top[i,1], z_outer_top[i]])
+            B_top = np.array([outer_top[j,0], outer_top[j,1], z_outer_top[j]])
+            A_bot = np.array([outer_bot[i,0], outer_bot[i,1], z_outer_bot[i]])
+            B_bot = np.array([outer_bot[j,0], outer_bot[j,1], z_outer_bot[j]])
+            base = len(walls_V)
+            walls_V.extend([A_top, B_top, B_bot, A_bot])
+            # Winding for outward-facing (away from center)
+            walls_F.extend([[base, base+1, base+2], [base, base+2, base+3]])
+
+        # Inner wall: connects inner_top to inner_bot (facing inward toward center)
+        n_inner = len(inner_top)
+        for i in range(n_inner):
+            j = (i + 1) % n_inner
+            A_top = np.array([inner_top[i,0], inner_top[i,1], z_inner_top[i]])
+            B_top = np.array([inner_top[j,0], inner_top[j,1], z_inner_top[j]])
+            A_bot = np.array([inner_bot[i,0], inner_bot[i,1], z_inner_bot[i]])
+            B_bot = np.array([inner_bot[j,0], inner_bot[j,1], z_inner_bot[j]])
+            base = len(walls_V)
+            walls_V.extend([A_top, B_top, B_bot, A_bot])
+            # Winding for inward-facing (toward center) - reverse winding
+            walls_F.extend([[base, base+2, base+1], [base, base+3, base+2]])
+
+        V_walls = np.array(walls_V, float)
+        F_walls = np.array(walls_F, int)
+
+        # For closed path, poly_top is the outer ring (used for ground plane hole)
+        poly_top = outer_top
+        poly_bot = outer_bot
+
+        extra = {
+            "width_top": width_top,
+            "width_bottom": 2.0*half_bot,
+            "area_top": abs(_polygon_area_2d(outer_top)) - abs(_polygon_area_2d(inner_top)),
+            "area_bottom": abs(_polygon_area_2d(outer_bot)) - abs(_polygon_area_2d(inner_bot)),
+            "is_closed_path": True
+        }
+    else:
+        # Original logic for open paths
+        L_top, R_top = _offset_polyline(path_xy, half_top)
+        L_bot, R_bot = _offset_polyline(path_xy, half_bot)
+        poly_top = _ensure_ccw(_ring_from_LR(L_top, R_top))
+        poly_bot = _ensure_ccw(_ring_from_LR(L_bot, R_bot))
+
+        gfun = _ground_fn(ground)
+        # Top and bottom rings lie on the ground plane and ground-depth respectively
+        z_top = np.array([gfun(x,y) for x,y in poly_top])
+        z_bot = np.array([gfun(x,y) - depth for x,y in poly_bot])
+        tris_top = _ear_clipping_triangulation(poly_top)
+        tris_bot = _ear_clipping_triangulation(poly_bot)
+        V_cap = np.column_stack([poly_top, z_top])
+        V_bottom = np.column_stack([poly_bot, z_bot])
+        F_cap = tris_top
+        F_bottom = tris_bot[:, ::-1]  # outward
+
+        # Walls: connect corresponding indices
+        N = len(poly_top)
+        assert N == len(poly_bot)
+        walls_V = []
+        walls_F = []
+        for i in range(N):
+            j = (i+1) % N
+            A_top = np.array([poly_top[i,0], poly_top[i,1], z_top[i]])
+            B_top = np.array([poly_top[j,0], poly_top[j,1], z_top[j]])
+            A_bot = np.array([poly_bot[i,0], poly_bot[i,1], z_bot[i]])
+            B_bot = np.array([poly_bot[j,0], poly_bot[j,1], z_bot[j]])
+            base = len(walls_V)
+            walls_V.extend([A_top, B_top, B_bot, A_bot])
+            walls_F.extend([[base, base+1, base+2], [base, base+2, base+3]])
+        V_walls = np.array(walls_V, float)
+        F_walls = np.array(walls_F, int)
+
+        extra = {
+            "width_top": width_top,
+            "width_bottom": 2.0*half_bot,
+            "area_top": abs(_polygon_area_2d(poly_top)),
+            "area_bottom": abs(_polygon_area_2d(poly_bot)),
+            "is_closed_path": False
+        }
 
     groups = {
         "trench_bottom": (V_bottom, F_bottom),
         "trench_cap_for_volume": (V_cap, F_cap),
         "trench_walls": (V_walls, F_walls)
     }
-    extra = {
-        "width_top": width_top,
-        "width_bottom": 2.0*half_bot,
-        "area_top": abs(_polygon_area_2d(poly_top)),
-        "area_bottom": abs(_polygon_area_2d(poly_bot))
-    }
+
     return groups, poly_top, poly_bot, extra
 
+def _triangulate_annulus(outer: np.ndarray, inner: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    """Triangulate the annular region between outer and inner polygons.
+
+    Creates triangles that fill ONLY the region between the two polygons,
+    leaving the inner polygon area as an open hole.
+
+    Both polygons should be CCW oriented. Returns (vertices, faces) where
+    vertices is the concatenation of outer and inner, and faces index into it.
+    """
+    n_outer = len(outer)
+    n_inner = len(inner)
+
+    # Vertices: outer first, then inner
+    verts = np.vstack([outer, inner])
+
+    # Create triangles by "zipping" around the two polygons
+    # This works well when both polygons have similar vertex counts
+    # For different counts, we need to handle the ratio
+
+    tris = []
+
+    # Use a marching approach: for each outer edge, connect to nearest inner vertices
+    # and vice versa. This creates a proper triangulated annulus.
+
+    # Simple approach: interpolate around both polygons simultaneously
+    # treating them as having a common parameter t in [0, 1]
+
+    i_outer = 0  # current outer vertex index
+    i_inner = 0  # current inner vertex index
+    t_outer = 0.0  # parameter position on outer polygon
+    t_inner = 0.0  # parameter position on inner polygon
+
+    outer_step = 1.0 / n_outer
+    inner_step = 1.0 / n_inner
+
+    # March around creating triangles
+    while i_outer < n_outer or i_inner < n_inner:
+        # Current vertices
+        o_curr = i_outer % n_outer
+        o_next = (i_outer + 1) % n_outer
+        i_curr = i_inner % n_inner
+        i_next = (i_inner + 1) % n_inner
+
+        # Indices in combined vertex array
+        vo_curr = o_curr
+        vo_next = o_next
+        vi_curr = n_outer + i_curr
+        vi_next = n_outer + i_next
+
+        if i_outer >= n_outer:
+            # Finished outer, just advance inner
+            tris.append([vo_curr, vi_next, vi_curr])
+            i_inner += 1
+            t_inner += inner_step
+        elif i_inner >= n_inner:
+            # Finished inner, just advance outer
+            tris.append([vo_curr, vo_next, vi_curr])
+            i_outer += 1
+            t_outer += outer_step
+        elif t_outer + outer_step <= t_inner + inner_step:
+            # Advance outer - create triangle: o_curr, o_next, i_curr
+            tris.append([vo_curr, vo_next, vi_curr])
+            i_outer += 1
+            t_outer += outer_step
+        else:
+            # Advance inner - create triangle: o_curr, i_next, i_curr
+            tris.append([vo_curr, vi_next, vi_curr])
+            i_inner += 1
+            t_inner += inner_step
+
+    return verts, np.array(tris, dtype=int)
+
+
 def make_ground_surface_plane(path_xy: List[Tuple[float,float]], width_top: float, ground) -> Dict[str,Tuple[np.ndarray,np.ndarray]]:
-    # single rectangular plane covering the trench projection + margin
-    half_top = width_top/2.0
-    L, R = _offset_polyline(path_xy, half_top)
-    ring = _ensure_ccw(_ring_from_LR(L, R))
-    minx, miny = ring.min(axis=0); maxx, maxy = ring.max(axis=0)
-    m = float(max(1.0, ground.size_margin))
+    """Create ground surface as an offset polygon around the trench opening.
+
+    The ground surface forms an annulus (ring) around the trench, leaving
+    the trench opening as an open hole. This creates a natural shape that
+    hugs L-shaped, U-shaped, and curved trenches.
+
+    For closed paths (like circles), also creates a center island inside
+    the inner edge of the annular trench.
+    """
+    half_top = width_top / 2.0
+    m = float(max(0.5, ground.size_margin))
     gfun = _ground_fn(ground)
-    corners_xy = np.array([[minx-m,miny-m],[maxx+m,miny-m],[maxx+m,maxy+m],[minx-m,maxy+m]], float)
-    Vg = np.array([[x,y,gfun(x,y)] for (x,y) in corners_xy], float)
-    Fg = np.array([[0,1,2],[0,2,3]], int) if _polygon_area_2d(corners_xy)>0 else np.array([[0,2,1],[0,3,2]], int)
-    return {"ground_surface": (Vg, Fg)}
+    is_closed = _is_path_closed(path_xy)
+
+    if is_closed:
+        # For closed paths, we have:
+        # - Outer ground: annulus from ground_outer to trench_outer
+        # - Center island: filled polygon inside trench_inner
+
+        # Trench boundaries
+        trench_outer = np.array(_offset_closed_polyline(path_xy, half_top), float)
+        trench_inner = np.array(_offset_closed_polyline(path_xy, -half_top), float)
+
+        # Ground outer boundary
+        ground_outer = np.array(_offset_closed_polyline(path_xy, half_top + m), float)
+
+        # Ensure proper orientations
+        trench_outer = _ensure_ccw(trench_outer)
+        trench_inner = _ensure_ccw(trench_inner)
+        ground_outer = _ensure_ccw(ground_outer)
+
+        # Outer ground annulus
+        outer_combined_xy, outer_tris = _triangulate_annulus(ground_outer, trench_outer)
+        outer_Vg = np.array([[x, y, gfun(x, y)] for (x, y) in outer_combined_xy], float)
+
+        # Center island (simple filled polygon)
+        center_tris = _ear_clipping_triangulation(trench_inner)
+        center_Vg = np.array([[x, y, gfun(x, y)] for (x, y) in trench_inner], float)
+
+        # Combine into single ground surface
+        n_outer_verts = len(outer_Vg)
+        center_tris_offset = center_tris + n_outer_verts
+
+        Vg = np.vstack([outer_Vg, center_Vg])
+        tris = np.vstack([outer_tris, center_tris_offset])
+
+        return {"ground_surface": (Vg, tris)}
+    else:
+        # Original logic for open paths
+        # Inner boundary: the trench opening (same as trench top ring)
+        L_inner, R_inner = _offset_polyline(path_xy, half_top)
+        inner_ring = _ensure_ccw(_ring_from_LR(L_inner, R_inner))
+
+        # Outer boundary: offset by additional margin
+        L_outer, R_outer = _offset_polyline(path_xy, half_top + m)
+        outer_ring = _ensure_ccw(_ring_from_LR(L_outer, R_outer))
+
+        # Triangulate the annular region (leaves hole open)
+        combined_xy, tris = _triangulate_annulus(outer_ring, inner_ring)
+
+        # Apply ground elevation to get 3D vertices
+        Vg = np.array([[x, y, gfun(x, y)] for (x, y) in combined_xy], float)
+
+        return {"ground_surface": (Vg, tris)}
 
 def _half_width_at_depth(half_top: float, slope: float, top_z: float, z: float) -> float:
     return max(1e-6, half_top - slope * (top_z - z))
@@ -731,7 +1007,8 @@ def _build_surface_groups(
 def generate_surface_mesh(spec: SceneSpec, *, make_preview: bool = False) -> SurfaceMeshResult:
     groups, object_counts, extra = _build_surface_groups(spec)
     metrics = _compute_surface_metrics(groups, extra, spec)
-    previews = _render_surface_previews(groups) if make_preview else {}
+    # Exclude internal groups (like cap) from previews to show open-topped trenches
+    previews = _render_surface_previews(groups, exclude_groups=_INTERNAL_GROUPS) if make_preview else {}
     return SurfaceMeshResult(
         spec=spec,
         groups=groups,

trenchfoot-0.2.2.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: trenchfoot
+Version: 0.2.2
+Summary: Synthetic trench scenario generator bundle (surfaces + volumetrics).
+Author: Liam Moore
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Provides-Extra: mesher
+Requires-Dist: gmsh>=4.11; extra == 'mesher'
+Provides-Extra: preview
+Requires-Dist: matplotlib>=3.8; extra == 'preview'
+Provides-Extra: viz
+Requires-Dist: plotly>=5.24; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# Trenchfoot
+
+Surface and volumetric trench mesh generator with shipped presets, Plotly previews, and a lightweight Python SDK.
+
+## Install
+
+```bash
+pip install trenchfoot
+```
+
+Want volumetrics or visualisations? Install extras as needed:
+- `pip install "trenchfoot[mesher]"` for gmsh-powered volume meshes.
+- `pip install "trenchfoot[preview]"` for matplotlib snapshot renders.
+- `pip install "trenchfoot[viz]"` for Plotly HTML viewers.
+
+## Scenario Gallery
+
+Color key: trench surfaces use warm soil tones; embedded geometry is colour-coded per group.
+
+| Scenario | Top | Side | Oblique |
+| --- | --- | --- | --- |
+| S01_straight_vwalls | ![S01 top](packages/trenchfoot/scenarios/S01_straight_vwalls/preview_top.png) | ![S01 side](packages/trenchfoot/scenarios/S01_straight_vwalls/preview_side.png) | ![S01 oblique](packages/trenchfoot/scenarios/S01_straight_vwalls/preview_oblique.png) |
+| S02_straight_slope_pipe | ![S02 top](packages/trenchfoot/scenarios/S02_straight_slope_pipe/preview_top.png) | ![S02 side](packages/trenchfoot/scenarios/S02_straight_slope_pipe/preview_side.png) | ![S02 oblique](packages/trenchfoot/scenarios/S02_straight_slope_pipe/preview_oblique.png) |
+| S03_L_slope_two_pipes_box | ![S03 top](packages/trenchfoot/scenarios/S03_L_slope_two_pipes_box/preview_top.png) | ![S03 side](packages/trenchfoot/scenarios/S03_L_slope_two_pipes_box/preview_side.png) | ![S03 oblique](packages/trenchfoot/scenarios/S03_L_slope_two_pipes_box/preview_oblique.png) |
+| S04_U_slope_multi_noise | ![S04 top](packages/trenchfoot/scenarios/S04_U_slope_multi_noise/preview_top.png) | ![S04 side](packages/trenchfoot/scenarios/S04_U_slope_multi_noise/preview_side.png) | ![S04 oblique](packages/trenchfoot/scenarios/S04_U_slope_multi_noise/preview_oblique.png) |
+| S05_wide_slope_pair | ![S05 top](packages/trenchfoot/scenarios/S05_wide_slope_pair/preview_top.png) | ![S05 side](packages/trenchfoot/scenarios/S05_wide_slope_pair/preview_side.png) | ![S05 oblique](packages/trenchfoot/scenarios/S05_wide_slope_pair/preview_oblique.png) |
+| S06_bumpy_wide_loop | ![S06 top](packages/trenchfoot/scenarios/S06_bumpy_wide_loop/preview_top.png) | ![S06 side](packages/trenchfoot/scenarios/S06_bumpy_wide_loop/preview_side.png) | ![S06 oblique](packages/trenchfoot/scenarios/S06_bumpy_wide_loop/preview_oblique.png) |
+| S07_circular_well | ![S07 top](packages/trenchfoot/scenarios/S07_circular_well/preview_top.png) | ![S07 side](packages/trenchfoot/scenarios/S07_circular_well/preview_side.png) | ![S07 oblique](packages/trenchfoot/scenarios/S07_circular_well/preview_oblique.png) |
+
+### S07 circular well preset
+
+A deep cylindrical well with criss-crossing pipes at different elevations:
+
+```json
+{
+  "path_xy": "<<32-vertex circle approximation, radius=1.5>>",
+  "width": 2.0,
+  "depth": 2.5,
+  "wall_slope": 0.05,
+  "ground": {"z0": 0.0, "slope": [0.0, 0.0], "size_margin": 2.0},
+  "pipes": [
+    {"radius": 0.20, "length": 4.0, "angle_deg": 0, "s_center": 0.25, "z": -0.5},
+    {"radius": 0.15, "length": 3.5, "angle_deg": 45, "s_center": 0.5, "z": -1.2},
+    {"radius": 0.10, "length": 3.0, "angle_deg": -60, "s_center": 0.75, "z": -1.8},
+    {"radius": 0.12, "length": 3.2, "angle_deg": 90, "s_center": 0.0, "z": -2.2}
+  ],
+  "spheres": [{"radius": 0.25, "s": 0.4, "z": -1.5}],
+  "noise": {"enable": true, "amplitude": 0.02, "corr_length": 0.4, "octaves": 2, "gain": 0.5}
+}
+```
+
+## CLI quick start
+
+```bash
+trenchfoot-generate --help
+trenchfoot-generate --preview --skip-volumetric --gallery docs/scenario_gallery.md
+trenchfoot-plot packages/trenchfoot/scenarios/S05_wide_slope_pair/trench_scene.obj --open
+```
+
+Set `TRENCHFOOT_SCENARIO_OUT_ROOT=/tmp/trench-previews` (or another writable path) to keep generated assets out of your checkout.
+
+## Python API
+
+```python
+from trenchfoot import scene_spec_from_dict, generate_surface_mesh, generate_trench_volume, gmsh_available
+
+spec_dict = {
+    "path_xy": [[0.0, 0.0], [5.0, 0.0]],
+    "width": 1.0,
+    "depth": 1.2,
+    "pipes": [{"radius": 0.1, "length": 1.8, "angle_deg": 0.0, "s_center": 0.5}],
+    "boxes": [],
+    "spheres": [],
+    "noise": {"enable": False},
+}
+
+scene = scene_spec_from_dict(spec_dict)
+surface = generate_surface_mesh(scene, make_preview=True)
+surface.persist("./surface")
+
+if gmsh_available():
+    volume = generate_trench_volume(spec_dict, lc=0.4, persist_path="./volume/trench_volume.msh")
+```
+
+`SurfaceMeshResult` keeps per-group faces, metrics, and optional preview PNG bytes; call `.persist(...)` when you need files. `VolumeMeshResult` exposes node coordinates, elements, and physical groups while still letting you stay in memory.
+
+## Testing
+
+```bash
+pytest -rs
+```
+
+The suite exercises each preset (surface + volumetric), the gallery helpers, and the SDK smoke paths.