first commit

2026-07-22 13:48:46 +08:00
commit c87751c3dc
2820 changed files with 726976 additions and 0 deletions
@@ -0,0 +1,119 @@
+# SimpleCAD API Index
+
+This index includes API docs generated from `operations.py`, `evolve.py`, `constraints.py`, and `ql.py`.
+
+## Basic Creation
+
+- [make_angle_arc_redge](make_angle_arc_redge.md) *(from operations.py)*
+- [make_angle_arc_rwire](make_angle_arc_rwire.md) *(from operations.py)*
+- [make_box_rscalarfield](make_box_rscalarfield.md) *(from field.py)*
+- [make_box_rsolid](make_box_rsolid.md) *(from operations.py)*
+- [make_capsule_rscalarfield](make_capsule_rscalarfield.md) *(from field.py)*
+- [make_circle_redge](make_circle_redge.md) *(from operations.py)*
+- [make_circle_rface](make_circle_rface.md) *(from operations.py)*
+- [make_circle_rwire](make_circle_rwire.md) *(from operations.py)*
+- [make_cone_rsolid](make_cone_rsolid.md) *(from operations.py)*
+- [make_cylinder_rsolid](make_cylinder_rsolid.md) *(from operations.py)*
+- [make_ellipsoid_rscalarfield](make_ellipsoid_rscalarfield.md) *(from field.py)*
+- [make_face_from_wire_rface](make_face_from_wire_rface.md) *(from operations.py)*
+- [make_field_surface_rsolid](make_field_surface_rsolid.md) *(from operations.py)*
+- [make_helix_redge](make_helix_redge.md) *(from operations.py)*
+- [make_helix_rwire](make_helix_rwire.md) *(from operations.py)*
+- [make_line_redge](make_line_redge.md) *(from operations.py)*
+- [make_point_rvertex](make_point_rvertex.md) *(from operations.py)*
+- [make_polyline_rwire](make_polyline_rwire.md) *(from operations.py)*
+- [make_rectangle_rface](make_rectangle_rface.md) *(from operations.py)*
+- [make_rectangle_rwire](make_rectangle_rwire.md) *(from operations.py)*
+- [make_segment_redge](make_segment_redge.md) *(from operations.py)*
+- [make_segment_rwire](make_segment_rwire.md) *(from operations.py)*
+- [make_sphere_rscalarfield](make_sphere_rscalarfield.md) *(from field.py)*
+- [make_sphere_rsolid](make_sphere_rsolid.md) *(from operations.py)*
+- [make_spline_redge](make_spline_redge.md) *(from operations.py)*
+- [make_spline_rwire](make_spline_rwire.md) *(from operations.py)*
+- [make_three_point_arc_redge](make_three_point_arc_redge.md) *(from operations.py)*
+- [make_three_point_arc_rwire](make_three_point_arc_rwire.md) *(from operations.py)*
+- [make_wire_from_edges_rwire](make_wire_from_edges_rwire.md) *(from operations.py)*
+
+## Transforms
+
+- [mirror_shape](mirror_shape.md) *(from operations.py)*
+- [rotate_rscalarfield](rotate_rscalarfield.md) *(from field.py)*
+- [rotate_shape](rotate_shape.md) *(from operations.py)*
+- [translate_rscalarfield](translate_rscalarfield.md) *(from field.py)*
+- [translate_shape](translate_shape.md) *(from operations.py)*
+
+## 3D Operations
+
+- [extrude_rsolid](extrude_rsolid.md) *(from operations.py)*
+- [loft_rsolid](loft_rsolid.md) *(from operations.py)*
+- [revolve_rsolid](revolve_rsolid.md) *(from operations.py)*
+- [sweep_rsolid](sweep_rsolid.md) *(from operations.py)*
+
+## Tagging and Selection
+
+- [select_edges_by_tag](select_edges_by_tag.md) *(from operations.py)*
+- [select_faces_by_tag](select_faces_by_tag.md) *(from operations.py)*
+- [set_tag](set_tag.md) *(from operations.py)*
+
+## Boolean Operations
+
+- [cut_rsolidlist](cut_rsolidlist.md) *(from operations.py)*
+- [intersect_rscalarfield](intersect_rscalarfield.md) *(from field.py)*
+- [intersect_rsolidlist](intersect_rsolidlist.md) *(from operations.py)*
+- [union_rscalarfield](union_rscalarfield.md) *(from field.py)*
+- [union_rsolidlist](union_rsolidlist.md) *(from operations.py)*
+
+## Export
+
+- [export_step](export_step.md) *(from operations.py)*
+- [export_stl](export_stl.md) *(from operations.py)*
+
+## Advanced Features
+
+- [chamfer_rsolid](chamfer_rsolid.md) *(from operations.py)*
+- [fillet_rsolid](fillet_rsolid.md) *(from operations.py)*
+- [helical_sweep_rsolid](helical_sweep_rsolid.md) *(from operations.py)*
+- [shell_rsolid](shell_rsolid.md) *(from operations.py)*
+
+## Evolve
+
+- [make_n_hole_flange_rsolid](make_n_hole_flange_rsolid.md) *(from evolve.py)*
+- [make_naca_propeller_blade_rsolid](make_naca_propeller_blade_rsolid.md) *(from evolve.py)*
+- [make_threaded_rod_rsolid](make_threaded_rod_rsolid.md) *(from evolve.py)*
+
+## Assembly Constraints
+
+- [add_part_rassembly](add_part_rassembly.md) *(from constraints.py)*
+- [clear_constraints_rassembly](clear_constraints_rassembly.md) *(from constraints.py)*
+- [clone_assembly_rassembly](clone_assembly_rassembly.md) *(from constraints.py)*
+- [constrain_coincident_rassembly](constrain_coincident_rassembly.md) *(from constraints.py)*
+- [constrain_concentric_rassembly](constrain_concentric_rassembly.md) *(from constraints.py)*
+- [constrain_distance_rassembly](constrain_distance_rassembly.md) *(from constraints.py)*
+- [constrain_offset_rassembly](constrain_offset_rassembly.md) *(from constraints.py)*
+- [make_assembly_rassembly](make_assembly_rassembly.md) *(from constraints.py)*
+- [rotate_part_rassembly](rotate_part_rassembly.md) *(from constraints.py)*
+- [solve_assembly_rresult](solve_assembly_rresult.md) *(from constraints.py)*
+- [stack](stack.md) *(from constraints.py)*
+- [stack_rassembly](stack_rassembly.md) *(from constraints.py)*
+- [translate_part_rassembly](translate_part_rassembly.md) *(from constraints.py)*
+
+## Other
+
+- [and_](and_.md) *(from ql.py)*
+- [bounds_rbbox](bounds_rbbox.md) *(from field.py)*
+- [eval_rarray](eval_rarray.md) *(from field.py)*
+- [eval_rscalar](eval_rscalar.md) *(from field.py)*
+- [geo](geo.md) *(from ql.py)*
+- [linear_pattern_rsolidlist](linear_pattern_rsolidlist.md) *(from operations.py)*
+- [meta](meta.md) *(from ql.py)*
+- [not_](not_.md) *(from ql.py)*
+- [or_](or_.md) *(from ql.py)*
+- [radial_pattern_rsolidlist](radial_pattern_rsolidlist.md) *(from operations.py)*
+- [render_screenshot_rpath](render_screenshot_rpath.md) *(from operations.py)*
+- [scale_rscalarfield](scale_rscalarfield.md) *(from field.py)*
+- [select](select.md) *(from ql.py)*
+- [smooth_subtract_rscalarfield](smooth_subtract_rscalarfield.md) *(from field.py)*
+- [smooth_union_rscalarfield](smooth_union_rscalarfield.md) *(from field.py)*
+- [subtract_rscalarfield](subtract_rscalarfield.md) *(from field.py)*
+- [tag](tag.md) *(from ql.py)*
+- [value](value.md) *(from ql.py)*
@@ -0,0 +1,13 @@
+# add_part_rassembly
+
+## API Definition
+
+```python
+def add_part_rassembly(assembly: Assembly, name: str, solid: Solid, parent: Optional[Union[str, PartHandle]] = None, local_transform: Optional[Union[np.ndarray, Sequence[Sequence[float]]]] = None) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: add a part in assembly space and return a new assembly.
@@ -0,0 +1,25 @@
+# and_
+
+## API Definition
+
+```python
+def and_(*predicates: Predicate) -> Predicate
+```
+
+*Source: ql.py*
+
+## Description
+
+Build an AND-composed predicate.
+
+Q.and_(Q.tag("face.top"), Q.tag("role.mounting_surface"))
+
+## Parameters
+
+### *predicates
+
+- **Description**: Any number of predicates.
+
+## Returns
+
+Callable[[Any], bool]: Combined predicate.
@@ -0,0 +1,23 @@
+# bounds_rbbox
+
+## API Definition
+
+```python
+def bounds_rbbox(field: ScalarField) -> Tuple[Tuple[float, float, float], Tuple[float, float, float]]
+```
+
+*Source: field.py*
+
+## Description
+
+Compute the axis-aligned bounding box of a scalar field.
+
+## Parameters
+
+### field
+
+- **Description**: Scalar field.
+
+## Returns
+
+Tuple[min_xyz, max_xyz]: Bounding box.
@@ -0,0 +1,13 @@
+# chamfer_rsolid
+
+## API Definition
+
+```python
+def chamfer_rsolid(solid: Solid, edges: List[Edge], distance: float) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Apply chamfers to selected solid edges.
@@ -0,0 +1,13 @@
+# clear_constraints_rassembly
+
+## API Definition
+
+```python
+def clear_constraints_rassembly(assembly: Assembly) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: clear constraints and return a new assembly.
@@ -0,0 +1,13 @@
+# clone_assembly_rassembly
+
+## API Definition
+
+```python
+def clone_assembly_rassembly(assembly: Assembly) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: clone one assembly object into another.
@@ -0,0 +1,13 @@
+# constrain_coincident_rassembly
+
+## API Definition
+
+```python
+def constrain_coincident_rassembly(assembly: Assembly, reference: PointAnchor, moving: PointAnchor) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: add a coincident constraint and return a new assembly.
@@ -0,0 +1,13 @@
+# constrain_concentric_rassembly
+
+## API Definition
+
+```python
+def constrain_concentric_rassembly(assembly: Assembly, reference: AxisAnchor, moving: AxisAnchor, same_direction: bool = False) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: add a concentric constraint and return a new assembly.
@@ -0,0 +1,13 @@
+# constrain_distance_rassembly
+
+## API Definition
+
+```python
+def constrain_distance_rassembly(assembly: Assembly, reference: PointAnchor, moving: PointAnchor, distance: float, fallback_axis: AxisLike = 'x') -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: add a point-distance constraint and return a new assembly.
@@ -0,0 +1,13 @@
+# constrain_offset_rassembly
+
+## API Definition
+
+```python
+def constrain_offset_rassembly(assembly: Assembly, reference: PointAnchor, moving: PointAnchor, distance: float, axis: AxisLike = 'z') -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: add an axial offset constraint and return a new assembly.
@@ -0,0 +1,65 @@
+# cut_rsolidlist
+
+## API Definition
+
+```python
+def cut_rsolidlist(*solids: Union[Solid, Sequence[Solid]]) -> List[Solid]
+```
+
+*Source: operations.py*
+
+## Description
+
+Compute the boolean difference of solids.
+
+All boolean operations (union/cut/intersect) accept a mix of Solid and
+sequences; results are always returned as a list of Solid.
+`cut_rsolidlist(base, [tool_a, tool_b])` is valid input.
+If an earlier union returned multiple solids, keep that list and process each
+solid intentionally instead of collapsing it to `result[0]` without proof.
+If a later step truly requires one solid, first verify `len(results) == 1`.
+When a preceding union produced multiple tangent-only solids, adjust the part
+placement so the intended bodies overlap slightly, re-run the union, and only
+then unwrap the single result.
+
+## Parameters
+
+### solids
+
+- **Description**: One or more Solid objects or sequences of Solid. Nested sequences are flattened before processing; the first solid is the base, the rest are subtracted in order.
+
+## Returns
+
+List[Solid]: A list containing the cut result solid, or an empty list when
+there is no valid input. The result is returned as a list for consistency
+with other boolean operations.
+
+## Examples
+
+### Example 1
+```python
+body = make_box_rsolid(12, 4, 4, bottom_face_center=(0, 0, 0))
+slot = make_box_rsolid(2, 2, 6, bottom_face_center=(2, 1, -1))
+relief = make_cylinder_rsolid(radius=0.8, height=6, center=(8, 2, 2))
+```
+
+### Example 2
+```python
+results = cut_rsolidlist(body, [slot, relief])
+print(f"Cut result count: {len(results)}")
+```
+
+### Example 3
+```python
+# If a previous union returned multiple solids, keep the list and cut each part.
+tangent_parts = union_rsolidlist(
+    body,
+    [
+        make_sphere_rsolid(2.0, center=(-2.0, 2.0, 2.0)),
+        make_sphere_rsolid(2.0, center=(14.0, 2.0, 2.0)),
+    ],
+)
+trimmed_parts = []
+for part in tangent_parts:
+    trimmed_parts.extend(cut_rsolidlist(part, [slot, relief]))
+```
@@ -0,0 +1,35 @@
+# eval_rarray
+
+## API Definition
+
+```python
+def eval_rarray(field: ScalarField, xs: np.ndarray, ys: np.ndarray, zs: np.ndarray) -> np.ndarray
+```
+
+*Source: field.py*
+
+## Description
+
+Evaluate a scalar field on arrays of points.
+
+## Parameters
+
+### field
+
+- **Description**: Scalar field.
+
+### xs
+
+- **Description**: Array of X coordinates.
+
+### ys
+
+- **Description**: Array of Y coordinates.
+
+### zs
+
+- **Description**: Array of Z coordinates.
+
+## Returns
+
+np.ndarray: Array of field values.
@@ -0,0 +1,35 @@
+# eval_rscalar
+
+## API Definition
+
+```python
+def eval_rscalar(field: ScalarField, x: float, y: float, z: float) -> float
+```
+
+*Source: field.py*
+
+## Description
+
+Evaluate a scalar field at a single point.
+
+## Parameters
+
+### field
+
+- **Description**: Scalar field.
+
+### x
+
+- **Description**: X coordinate.
+
+### y
+
+- **Description**: Y coordinate.
+
+### z
+
+- **Description**: Z coordinate.
+
+## Returns
+
+float: Field value.
@@ -0,0 +1,47 @@
+# export_step
+
+## API Definition
+
+```python
+def export_step(shapes: Union[AnyShape, Sequence[AnyShape]], filename: str) -> None
+```
+
+*Source: operations.py*
+
+## Description
+
+Export shapes to STEP.
+
+Use this function when you want to export one shape or many shapes into the
+same STEP file. Passing `List[Solid]` is valid and often preferred when a
+previous boolean operation returned multiple solids.
+
+## Parameters
+
+### shapes
+
+- **Description**: A single exportable shape or any nested sequence of exportable shapes. Lists of Solid are supported directly, including list results returned by boolean operations.
+
+### filename
+
+- **Description**: Output STEP file path.
+
+## Returns
+
+None: Writes the provided shapes into one STEP file.
+
+## Examples
+
+### Example 1
+```python
+main_body = make_box_rsolid(10, 4, 4, bottom_face_center=(0, 0, 0))
+left_cap = make_sphere_rsolid(2.0, center=(-2.0, 2.0, 2.0))
+right_cap = make_sphere_rsolid(2.0, center=(12.0, 2.0, 2.0))
+body_parts = union_rsolidlist(main_body, [left_cap, right_cap])
+```
+
+### Example 2
+```python
+# Export the full list directly; no need to collapse to body_parts[0].
+export_step(body_parts, "rounded_bar.step")
+```
@@ -0,0 +1,47 @@
+# export_stl
+
+## API Definition
+
+```python
+def export_stl(shapes: Union[AnyShape, Sequence[AnyShape]], filename: str) -> None
+```
+
+*Source: operations.py*
+
+## Description
+
+Export shapes to STL.
+
+Use this function when you want to export one solid or many solids/faces into
+the same STL file. Passing `List[Solid]` is valid and often preferred when a
+previous boolean operation returned multiple solids.
+
+## Parameters
+
+### shapes
+
+- **Description**: A single Solid or Face, or any nested sequence of Solid/Face. Lists of Solid are supported directly, including list results returned by boolean operations.
+
+### filename
+
+- **Description**: Output STL file path.
+
+## Returns
+
+None: Writes the provided shapes into one STL file.
+
+## Examples
+
+### Example 1
+```python
+main_body = make_box_rsolid(10, 4, 4, bottom_face_center=(0, 0, 0))
+left_cap = make_sphere_rsolid(2.0, center=(-2.0, 2.0, 2.0))
+right_cap = make_sphere_rsolid(2.0, center=(12.0, 2.0, 2.0))
+body_parts = union_rsolidlist(main_body, [left_cap, right_cap])
+```
+
+### Example 2
+```python
+# Export the list result directly.
+export_stl(body_parts, "rounded_bar.stl")
+```
@@ -0,0 +1,13 @@
+# extrude_rsolid
+
+## API Definition
+
+```python
+def extrude_rsolid(profile: Union[Wire, Face], direction: Tuple[float, float, float], distance: float) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a solid by extruding a profile.
@@ -0,0 +1,13 @@
+# fillet_rsolid
+
+## API Definition
+
+```python
+def fillet_rsolid(solid: Solid, edges: List[Edge], radius: float) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Apply fillets to selected solid edges.
@@ -0,0 +1,29 @@
+# geo
+
+## API Definition
+
+```python
+def geo(field: str, default: Any = None) -> KeyFn
+```
+
+*Source: ql.py*
+
+## Description
+
+Convenience builder for a `geo` metadata getter.
+
+Q.select(items).order_by(Q.geo("height"))
+
+## Parameters
+
+### field
+
+- **Description**: `geo` field name, such as `type` or `height`.
+
+### default
+
+- **Description**: Default value when lookup fails.
+
+## Returns
+
+Callable[[Any], Any]: Getter function.
@@ -0,0 +1,13 @@
+# helical_sweep_rsolid
+
+## API Definition
+
+```python
+def helical_sweep_rsolid(profile: Wire, pitch: float, height: float, radius: float, center: Tuple[float, float, float] = (0, 0, 0), dir: Tuple[float, float, float] = (0, 0, 1)) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a solid by sweeping a profile along a helical path.
@@ -0,0 +1,23 @@
+# intersect_rscalarfield
+
+## API Definition
+
+```python
+def intersect_rscalarfield(*fields: ScalarField) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create an intersection scalar field.
+
+## Parameters
+
+### *fields
+
+- **Description**: Input scalar fields.
+
+## Returns
+
+ScalarField: Intersection scalar field.
@@ -0,0 +1,65 @@
+# intersect_rsolidlist
+
+## API Definition
+
+```python
+def intersect_rsolidlist(*solids: Union[Solid, Sequence[Solid]]) -> List[Solid]
+```
+
+*Source: operations.py*
+
+## Description
+
+Compute the boolean intersection of solids.
+
+All boolean operations (union/cut/intersect) accept a mix of Solid and
+sequences; results are always returned as a list of Solid.
+`intersect_rsolidlist(body, [clip_a, clip_b])` is valid input.
+If an earlier union returned multiple solids, keep that list and intersect
+each solid intentionally instead of collapsing it to `result[0]`.
+If a later step truly requires one solid, first verify `len(results) == 1`.
+When a preceding union produced multiple tangent-only solids, adjust the part
+placement so the intended bodies overlap slightly, re-run the union, and only
+then unwrap the single result.
+
+## Parameters
+
+### solids
+
+- **Description**: One or more Solid objects or sequences of Solid. Nested sequences are flattened before processing.
+
+## Returns
+
+List[Solid]: A list containing the intersection result, or an empty list if
+the solids do not overlap. The result is returned as a list for
+consistency with other boolean operations.
+
+## Examples
+
+### Example 1
+```python
+body = make_box_rsolid(12, 4, 4, bottom_face_center=(0, 0, 0))
+clip_a = make_box_rsolid(8, 4, 4, bottom_face_center=(2, 0, 0))
+clip_b = make_box_rsolid(6, 6, 6, bottom_face_center=(3, -1, -1))
+```
+
+### Example 2
+```python
+results = intersect_rsolidlist(body, [clip_a, clip_b])
+print(f"Intersect result count: {len(results)}")
+```
+
+### Example 3
+```python
+# A previous union may return multiple solids; keep the list and intersect each part.
+tangent_parts = union_rsolidlist(
+    body,
+    [
+        make_sphere_rsolid(2.0, center=(-2.0, 2.0, 2.0)),
+        make_sphere_rsolid(2.0, center=(14.0, 2.0, 2.0)),
+    ],
+)
+clipped_parts = []
+for part in tangent_parts:
+    clipped_parts.extend(intersect_rsolidlist(part, clip_a))
+```
@@ -0,0 +1,13 @@
+# linear_pattern_rsolidlist
+
+## API Definition
+
+```python
+def linear_pattern_rsolidlist(shape: AnyShape, direction: Tuple[float, float, float], count: int, spacing: float) -> List[Solid]
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a linear pattern of solids.
@@ -0,0 +1,13 @@
+# loft_rsolid
+
+## API Definition
+
+```python
+def loft_rsolid(profiles: List[Wire], ruled: bool = False) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a solid by lofting multiple profiles.
@@ -0,0 +1,13 @@
+# make_angle_arc_redge
+
+## API Definition
+
+```python
+def make_angle_arc_redge(center: Tuple[float, float, float], radius: float, start_angle: float, end_angle: float, normal: Tuple[float, float, float] = (0, 0, 1)) -> Edge
+```
+
+*Source: operations.py*
+
+## Description
+
+Create an arc edge from a center, radius, and angle range.
@@ -0,0 +1,13 @@
+# make_angle_arc_rwire
+
+## API Definition
+
+```python
+def make_angle_arc_rwire(center: Tuple[float, float, float], radius: float, start_angle: float, end_angle: float, normal: Tuple[float, float, float] = (0, 0, 1)) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a wire containing an arc defined by a center, radius, and angle range.
@@ -0,0 +1,13 @@
+# make_assembly_rassembly
+
+## API Definition
+
+```python
+def make_assembly_rassembly(parts: Sequence[Tuple[str, Solid]], name: str = 'assembly', parents: Optional[Dict[str, str]] = None, local_transforms: Optional[Dict[str, Union[np.ndarray, Sequence[Sequence[float]]]]] = None) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-1 mapping: lift a parameter description into an assembly object.
@@ -0,0 +1,27 @@
+# make_box_rscalarfield
+
+## API Definition
+
+```python
+def make_box_rscalarfield(center: Tuple[float, float, float], size: Tuple[float, float, float]) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create an axis-aligned box scalar field.
+
+## Parameters
+
+### center
+
+- **Description**: Box center coordinates `(x, y, z)`.
+
+### size
+
+- **Description**: Box size `(sx, sy, sz)`.
+
+## Returns
+
+ScalarField: Box scalar field.
@@ -0,0 +1,13 @@
+# make_box_rsolid
+
+## API Definition
+
+```python
+def make_box_rsolid(width: float, height: float, depth: float, bottom_face_center: Tuple[float, float, float] = (0, 0, 0)) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a box solid.
@@ -0,0 +1,31 @@
+# make_capsule_rscalarfield
+
+## API Definition
+
+```python
+def make_capsule_rscalarfield(p0: Tuple[float, float, float], p1: Tuple[float, float, float], radius: float) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create a capsule scalar field.
+
+## Parameters
+
+### p0
+
+- **Description**: First endpoint coordinates.
+
+### p1
+
+- **Description**: Second endpoint coordinates.
+
+### radius
+
+- **Description**: Capsule radius.
+
+## Returns
+
+ScalarField: Capsule scalar field.
@@ -0,0 +1,13 @@
+# make_circle_redge
+
+## API Definition
+
+```python
+def make_circle_redge(center: Tuple[float, float, float], radius: float, normal: Tuple[float, float, float] = (0, 0, 1)) -> Edge
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a circular edge.
@@ -0,0 +1,13 @@
+# make_circle_rface
+
+## API Definition
+
+```python
+def make_circle_rface(center: Tuple[float, float, float], radius: float, normal: Tuple[float, float, float] = (0, 0, 1)) -> Face
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a circular face.
@@ -0,0 +1,13 @@
+# make_circle_rwire
+
+## API Definition
+
+```python
+def make_circle_rwire(center: Tuple[float, float, float], radius: float, normal: Tuple[float, float, float] = (0, 0, 1)) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a circular wire.
@@ -0,0 +1,13 @@
+# make_cone_rsolid
+
+## API Definition
+
+```python
+def make_cone_rsolid(bottom_radius: float, height: float, top_radius: float = 0.0, bottom_face_center: Tuple[float, float, float] = (0, 0, 0), axis: Tuple[float, float, float] = (0, 0, 1)) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a cone or truncated cone solid.
@@ -0,0 +1,13 @@
+# make_cylinder_rsolid
+
+## API Definition
+
+```python
+def make_cylinder_rsolid(radius: float, height: float, bottom_face_center: Tuple[float, float, float] = (0, 0, 0), axis: Tuple[float, float, float] = (0, 0, 1)) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a cylinder solid.
@@ -0,0 +1,27 @@
+# make_ellipsoid_rscalarfield
+
+## API Definition
+
+```python
+def make_ellipsoid_rscalarfield(center: Tuple[float, float, float], radii: Tuple[float, float, float]) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create an ellipsoid scalar field.
+
+## Parameters
+
+### center
+
+- **Description**: Ellipsoid center coordinates `(x, y, z)`.
+
+### radii
+
+- **Description**: Radii `(rx, ry, rz)`.
+
+## Returns
+
+ScalarField: Ellipsoid scalar field.
@@ -0,0 +1,13 @@
+# make_face_from_wire_rface
+
+## API Definition
+
+```python
+def make_face_from_wire_rface(wire: Wire, normal: Tuple[float, float, float] = (0, 0, 1)) -> Face
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a face from a closed wire.
@@ -0,0 +1,13 @@
+# make_field_surface_rsolid
+
+## API Definition
+
+```python
+def make_field_surface_rsolid(field, bounds: Optional[Tuple[Tuple[float, float, float], Tuple[float, float, float]]] = None, resolution: Tuple[int, int, int] = (24, 24, 24), iso: float = 0.0, cap_bounds: bool = True) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Build a closed solid from a scalar field isosurface.
@@ -0,0 +1,13 @@
+# make_helix_redge
+
+## API Definition
+
+```python
+def make_helix_redge(pitch: float, height: float, radius: float, center: Tuple[float, float, float] = (0, 0, 0), dir: Tuple[float, float, float] = (0, 0, 1)) -> Edge
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a helix edge.
@@ -0,0 +1,13 @@
+# make_helix_rwire
+
+## API Definition
+
+```python
+def make_helix_rwire(pitch: float, height: float, radius: float, center: Tuple[float, float, float] = (0, 0, 0), dir: Tuple[float, float, float] = (0, 0, 1)) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a helix wire.
@@ -0,0 +1,13 @@
+# make_line_redge
+
+## API Definition
+
+```python
+def make_line_redge(start: Tuple[float, float, float], end: Tuple[float, float, float]) -> Edge
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a straight edge between two points.
@@ -0,0 +1,13 @@
+# make_n_hole_flange_rsolid
+
+## API Definition
+
+```python
+def make_n_hole_flange_rsolid(flange_outer_diameter = 120.0, flange_inner_diameter = 60.0, flange_thickness = 15.0, boss_outer_diameter = 80.0, boss_height = 5.0, hole_diameter = 8.0, hole_circle_diameter = 100.0, hole_count = 8, chamfer_size = 1.0) -> Solid
+```
+
+*Source: evolve.py*
+
+## Description
+
+Create an n-hole flange with a raised boss ring and optional chamfers. The center of the bottom face is placed at the origin.
@@ -0,0 +1,13 @@
+# make_naca_propeller_blade_rsolid
+
+## API Definition
+
+```python
+def make_naca_propeller_blade_rsolid(blade_length = 5.0, root_chord = 1.5, tip_chord = 0.3, total_twist_angle = 45.0, num_sections = 7, t_c = 0.16) -> Solid
+```
+
+*Source: evolve.py*
+
+## Description
+
+Create a single propeller blade solid from a twisted NACA 0016 profile. The blade root starts at the origin and extends along +Z.
@@ -0,0 +1,13 @@
+# make_point_rvertex
+
+## API Definition
+
+```python
+def make_point_rvertex(x: float, y: float, z: float) -> Vertex
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a point in 3D space and return it as a vertex.
@@ -0,0 +1,13 @@
+# make_polyline_rwire
+
+## API Definition
+
+```python
+def make_polyline_rwire(points: List[Tuple[float, float, float]], closed: bool = False) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a polyline wire from a point list.
@@ -0,0 +1,13 @@
+# make_rectangle_rface
+
+## API Definition
+
+```python
+def make_rectangle_rface(width: float, height: float, center: Tuple[float, float, float] = (0, 0, 0), normal: Tuple[float, float, float] = (0, 0, 1)) -> Face
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a rectangular face.
@@ -0,0 +1,13 @@
+# make_rectangle_rwire
+
+## API Definition
+
+```python
+def make_rectangle_rwire(width: float, height: float, center: Tuple[float, float, float] = (0, 0, 0), normal: Tuple[float, float, float] = (0, 0, 1)) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a rectangular wire.
@@ -0,0 +1,13 @@
+# make_segment_redge
+
+## API Definition
+
+```python
+def make_segment_redge(start: Tuple[float, float, float], end: Tuple[float, float, float]) -> Edge
+```
+
+*Source: operations.py*
+
+## Description
+
+Alias of `make_line_redge` that returns a straight edge.
@@ -0,0 +1,13 @@
+# make_segment_rwire
+
+## API Definition
+
+```python
+def make_segment_rwire(start: Tuple[float, float, float], end: Tuple[float, float, float]) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a wire containing a single straight segment.
@@ -0,0 +1,27 @@
+# make_sphere_rscalarfield
+
+## API Definition
+
+```python
+def make_sphere_rscalarfield(center: Tuple[float, float, float], radius: float) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create a spherical scalar field.
+
+## Parameters
+
+### center
+
+- **Description**: Sphere center coordinates `(x, y, z)`.
+
+### radius
+
+- **Description**: Sphere radius.
+
+## Returns
+
+ScalarField: Sphere scalar field.
@@ -0,0 +1,13 @@
+# make_sphere_rsolid
+
+## API Definition
+
+```python
+def make_sphere_rsolid(radius: float, center: Tuple[float, float, float] = (0, 0, 0)) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a sphere solid.
@@ -0,0 +1,13 @@
+# make_spline_redge
+
+## API Definition
+
+```python
+def make_spline_redge(points: List[Tuple[float, float, float]], tangents: Optional[List[Tuple[float, float, float]]] = None) -> Edge
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a spline edge through control points.
@@ -0,0 +1,13 @@
+# make_spline_rwire
+
+## API Definition
+
+```python
+def make_spline_rwire(points: List[Tuple[float, float, float]], tangents: Optional[List[Tuple[float, float, float]]] = None, closed: bool = False) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a spline wire through control points.
@@ -0,0 +1,13 @@
+# make_threaded_rod_rsolid
+
+## API Definition
+
+```python
+def make_threaded_rod_rsolid(thread_diameter = 8.0, thread_length = 20.0, total_length = 30.0, thread_pitch = 1.25, thread_start_position = 0.0, chamfer_size = 0.5) -> Solid
+```
+
+*Source: evolve.py*
+
+## Description
+
+Create a threaded rod with configurable rod length, thread span, and pitch. The top center is placed at the origin and the rod extends in -Z.
@@ -0,0 +1,13 @@
+# make_three_point_arc_redge
+
+## API Definition
+
+```python
+def make_three_point_arc_redge(start: Tuple[float, float, float], middle: Tuple[float, float, float], end: Tuple[float, float, float]) -> Edge
+```
+
+*Source: operations.py*
+
+## Description
+
+Create an arc edge from three points.
@@ -0,0 +1,13 @@
+# make_three_point_arc_rwire
+
+## API Definition
+
+```python
+def make_three_point_arc_rwire(start: Tuple[float, float, float], middle: Tuple[float, float, float], end: Tuple[float, float, float]) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a wire containing an arc defined by three points.
@@ -0,0 +1,13 @@
+# make_wire_from_edges_rwire
+
+## API Definition
+
+```python
+def make_wire_from_edges_rwire(edges: List[Edge]) -> Wire
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a wire from a list of connected edges.
@@ -0,0 +1,45 @@
+# meta
+
+## API Definition
+
+```python
+def meta(path: str, op: str, value: Any) -> Predicate
+```
+
+*Source: ql.py*
+
+## Description
+
+Build a metadata-based predicate.
+
+Q.meta("geo.type", "==", "box")
+
+## Parameters
+
+### path
+
+- **Description**: Metadata path, for example `geo.type`.
+
+### op
+
+- **Description**: Comparison operator. Supports `==`, `!=`, `>`, `>=`, `<`, and `<=`.
+
+### value
+
+- **Description**: Comparison target value.
+
+## Returns
+
+Callable[[Any], bool]: Predicate function.
+
+## Raises
+
+- **TypeError**: If op is not a string.
+- **ValueError**: If the operator is unsupported.
+
+## Examples
+
+```python
+pred = Q.meta("geo.size.x", ">", 1.0)
+matched = pred(obj)
+```
@@ -0,0 +1,13 @@
+# mirror_shape
+
+## API Definition
+
+```python
+def mirror_shape(shape: AnyShape, plane_origin: Tuple[float, float, float], plane_normal: Tuple[float, float, float]) -> AnyShape
+```
+
+*Source: operations.py*
+
+## Description
+
+Mirror a shape across a plane.
@@ -0,0 +1,25 @@
+# not_
+
+## API Definition
+
+```python
+def not_(predicate: Predicate) -> Predicate
+```
+
+*Source: ql.py*
+
+## Description
+
+Build a NOT predicate.
+
+Q.not_(Q.tag("state.*"))
+
+## Parameters
+
+### predicate
+
+- **Description**: A single predicate.
+
+## Returns
+
+Callable[[Any], bool]: Negated predicate.
@@ -0,0 +1,25 @@
+# or_
+
+## API Definition
+
+```python
+def or_(*predicates: Predicate) -> Predicate
+```
+
+*Source: ql.py*
+
+## Description
+
+Build an OR-composed predicate.
+
+Q.or_(Q.tag("face.top"), Q.tag("face.bottom"))
+
+## Parameters
+
+### *predicates
+
+- **Description**: Any number of predicates.
+
+## Returns
+
+Callable[[Any], bool]: Combined predicate.
@@ -0,0 +1,13 @@
+# radial_pattern_rsolidlist
+
+## API Definition
+
+```python
+def radial_pattern_rsolidlist(shape: AnyShape, center: Tuple[float, float, float], axis: Tuple[float, float, float], count: int, total_rotation_angle: float) -> List[Solid]
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a radial pattern of solids.
@@ -0,0 +1,13 @@
+# render_screenshot_rpath
+
+## API Definition
+
+```python
+def render_screenshot_rpath(shapes: Union[Solid, Sequence[Solid]], output_path: str, highlight_tags: Optional[Sequence[str]] = None, tag_labels: Optional[Dict[str, str]] = None, image_size: Tuple[int, int] = (1400, 900), view: Union[Tuple[float, float], str] = 'auto', show_axes: bool = True, show_legend: bool = True, zoom: float = 4.0) -> str
+```
+
+*Source: operations.py*
+
+## Description
+
+Render a screenshot of shapes and save it to a file.
@@ -0,0 +1,13 @@
+# revolve_rsolid
+
+## API Definition
+
+```python
+def revolve_rsolid(profile: Union[Wire, Face], axis: Tuple[float, float, float] = (0, 0, 1), angle: float = 360, origin: Tuple[float, float, float] = (0, 0, 0)) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a solid by revolving a profile around an axis.
@@ -0,0 +1,13 @@
+# rotate_part_rassembly
+
+## API Definition
+
+```python
+def rotate_part_rassembly(assembly: Assembly, part: Union[str, PartHandle], angle_deg: float, axis: AxisLike = 'z', origin: Vec3Like = (0.0, 0.0, 0.0), frame: Literal['world', 'local'] = 'world') -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: rotate a part and return a new assembly.
@@ -0,0 +1,31 @@
+# rotate_rscalarfield
+
+## API Definition
+
+```python
+def rotate_rscalarfield(field: ScalarField, axis: Tuple[float, float, float], angle_degrees: float) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Rotate a scalar field around the origin.
+
+## Parameters
+
+### field
+
+- **Description**: Input scalar field.
+
+### axis
+
+- **Description**: Rotation axis vector `(x, y, z)`.
+
+### angle_degrees
+
+- **Description**: Rotation angle in degrees.
+
+## Returns
+
+ScalarField: Rotated scalar field.
@@ -0,0 +1,13 @@
+# rotate_shape
+
+## API Definition
+
+```python
+def rotate_shape(shape: AnyShape, angle: float, axis: Tuple[float, float, float] = (0, 0, 1), origin: Tuple[float, float, float] = (0, 0, 0)) -> AnyShape
+```
+
+*Source: operations.py*
+
+## Description
+
+Rotate a shape around an axis.
@@ -0,0 +1,27 @@
+# scale_rscalarfield
+
+## API Definition
+
+```python
+def scale_rscalarfield(field: ScalarField, factors: Tuple[float, float, float]) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Scale a scalar field around the origin.
+
+## Parameters
+
+### field
+
+- **Description**: Input scalar field.
+
+### factors
+
+- **Description**: Scale factors `(sx, sy, sz)`.
+
+## Returns
+
+ScalarField: Scaled scalar field.
@@ -0,0 +1,25 @@
+# select
+
+## API Definition
+
+```python
+def select(items: Iterable[Any]) -> Query
+```
+
+*Source: ql.py*
+
+## Description
+
+Create a query object.
+
+Q.select(items).where(Q.tag("face.top")).first()
+
+## Parameters
+
+### items
+
+- **Description**: Any iterable.
+
+## Returns
+
+Query: Query object.
@@ -0,0 +1,13 @@
+# select_edges_by_tag
+
+## API Definition
+
+```python
+def select_edges_by_tag(shape: Union[Face, Solid], tag: str) -> List[Edge]
+```
+
+*Source: operations.py*
+
+## Description
+
+Select edges by tag.
@@ -0,0 +1,13 @@
+# select_faces_by_tag
+
+## API Definition
+
+```python
+def select_faces_by_tag(solid: Solid, tag: str) -> List[Face]
+```
+
+*Source: operations.py*
+
+## Description
+
+Select faces by tag.
@@ -0,0 +1,13 @@
+# set_tag
+
+## API Definition
+
+```python
+def set_tag(shape: AnyShape, tag: str) -> AnyShape
+```
+
+*Source: operations.py*
+
+## Description
+
+Attach a tag to a shape.
@@ -0,0 +1,13 @@
+# shell_rsolid
+
+## API Definition
+
+```python
+def shell_rsolid(solid: Solid, faces_to_remove: List[Face], thickness: float) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Shell a solid to create a hollow part.
@@ -0,0 +1,31 @@
+# smooth_subtract_rscalarfield
+
+## API Definition
+
+```python
+def smooth_subtract_rscalarfield(a: ScalarField, b: ScalarField, k: float) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create a smooth subtraction scalar field.
+
+## Parameters
+
+### a
+
+- **Description**: Minuend scalar field.
+
+### b
+
+- **Description**: Subtrahend scalar field.
+
+### k
+
+- **Description**: Smoothing factor, which must be positive.
+
+## Returns
+
+ScalarField: Smooth subtraction scalar field.
@@ -0,0 +1,31 @@
+# smooth_union_rscalarfield
+
+## API Definition
+
+```python
+def smooth_union_rscalarfield(a: ScalarField, b: ScalarField, k: float) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create a smooth union scalar field.
+
+## Parameters
+
+### a
+
+- **Description**: Scalar field A.
+
+### b
+
+- **Description**: Scalar field B.
+
+### k
+
+- **Description**: Smoothing factor, which must be positive.
+
+## Returns
+
+ScalarField: Smooth union scalar field.
@@ -0,0 +1,13 @@
+# solve_assembly_rresult
+
+## API Definition
+
+```python
+def solve_assembly_rresult(assembly: Assembly, max_iterations: int = 30, tolerance: float = 1e-06) -> AssemblyResult
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: map an assembly to a solve result without mutating it.
@@ -0,0 +1,29 @@
+# stack
+
+## API Definition
+
+```python
+def stack(assembly: Assembly, parts: Sequence[Union[str, PartHandle]], axis: str = 'z', gap: float = 0.0, align: Literal['center', 'start', 'end'] = 'center', justify: Literal['start', 'center', 'end', 'space-between'] = 'start', bounds: Optional[Tuple[PointAnchor, PointAnchor]] = None) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Declaratively stack multiple parts along the specified axis.
+
+Semantics:
+- sequential stacking: part i is placed after part i-1 with the given gap
+- cross-axis alignment: the other two axes are aligned according to `align`
+- main-axis distribution: `justify` controls how the whole stack is placed
+within the bounds
+
+BBox-first note:
+- This function uses axis-aligned bounding-box (AABB) anchors such as
+`bbox.top` and `bbox.bottom` to approximate Flexbox-like box semantics.
+- For parts with large rotations, the AABB changes with pose, so the layout
+result changes as well. This is expected in the current MVP stage.
+
+Note:
+- This is container-level sugar that compiles into a set of `offset(...)`
+constraints internally.
@@ -0,0 +1,13 @@
+# stack_rassembly
+
+## API Definition
+
+```python
+def stack_rassembly(assembly: Assembly, parts: Sequence[Union[str, PartHandle]], axis: str = 'z', gap: float = 0.0, align: Literal['center', 'start', 'end'] = 'center', justify: Literal['start', 'center', 'end', 'space-between'] = 'start', bounds: Optional[Tuple[PointAnchor, PointAnchor]] = None) -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: apply a stack layout and return a new assembly.
@@ -0,0 +1,27 @@
+# subtract_rscalarfield
+
+## API Definition
+
+```python
+def subtract_rscalarfield(a: ScalarField, b: ScalarField) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create a subtraction scalar field.
+
+## Parameters
+
+### a
+
+- **Description**: Minuend scalar field.
+
+### b
+
+- **Description**: Subtrahend scalar field.
+
+## Returns
+
+ScalarField: Subtraction scalar field.
@@ -0,0 +1,13 @@
+# sweep_rsolid
+
+## API Definition
+
+```python
+def sweep_rsolid(profile: Face, path: Wire, is_frenet: bool = False) -> Solid
+```
+
+*Source: operations.py*
+
+## Description
+
+Create a solid by sweeping a profile along a path.
@@ -0,0 +1,37 @@
+# tag
+
+## API Definition
+
+```python
+def tag(pattern: str) -> Predicate
+```
+
+*Source: ql.py*
+
+## Description
+
+Build a tag-based predicate.
+
+`Q.tag("face.top")` or `Q.tag("role.*")`.
+
+## Parameters
+
+### pattern
+
+- **Description**: Tag matching pattern. Supports a trailing `*` wildcard.
+
+## Returns
+
+Callable[[Any], bool]: Predicate function.
+
+## Raises
+
+- **TypeError**: If pattern is not a string.
+- **ValueError**: If the wildcard position is invalid.
+
+## Examples
+
+```python
+pred = Q.tag("role.*")
+matched = pred(obj)
+```
@@ -0,0 +1,13 @@
+# translate_part_rassembly
+
+## API Definition
+
+```python
+def translate_part_rassembly(assembly: Assembly, part: Union[str, PartHandle], vector: Vec3Like, frame: Literal['world', 'local'] = 'world') -> Assembly
+```
+
+*Source: constraints.py*
+
+## Description
+
+Type-2 mapping: translate a part and return a new assembly.
@@ -0,0 +1,27 @@
+# translate_rscalarfield
+
+## API Definition
+
+```python
+def translate_rscalarfield(field: ScalarField, offset: Tuple[float, float, float]) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Translate a scalar field.
+
+## Parameters
+
+### field
+
+- **Description**: Input scalar field.
+
+### offset
+
+- **Description**: Translation vector `(dx, dy, dz)`.
+
+## Returns
+
+ScalarField: Translated scalar field.
@@ -0,0 +1,13 @@
+# translate_shape
+
+## API Definition
+
+```python
+def translate_shape(shape: AnyShape, vector: Tuple[float, float, float]) -> AnyShape
+```
+
+*Source: operations.py*
+
+## Description
+
+Translate a shape by an offset vector.
@@ -0,0 +1,23 @@
+# union_rscalarfield
+
+## API Definition
+
+```python
+def union_rscalarfield(*fields: ScalarField) -> ScalarField
+```
+
+*Source: field.py*
+
+## Description
+
+Create a union scalar field.
+
+## Parameters
+
+### *fields
+
+- **Description**: Input scalar fields.
+
+## Returns
+
+ScalarField: Union scalar field.
@@ -0,0 +1,99 @@
+# union_rsolidlist
+
+## API Definition
+
+```python
+def union_rsolidlist(
+    *solids: Union[Solid, Sequence[Solid]],
+    clean: bool = True,
+    glue: bool = True,
+    tol: Optional[float] = None,
+) -> List[Solid]
+```
+
+*Source: operations.py*
+
+## Description
+
+Compute the boolean union of one or more solids.
+
+All boolean operations (union/cut/intersect) accept a mix of Solid and
+sequences; results are always returned as a list of Solid.
+Keep the list result unless you have explicitly verified `len(result) == 1`.
+SimpleCAD enables glue mode by default and applies a conservative internal fuzzy
+tolerance, so normal modeling code does not need to tune boolean parameters.
+By default this follows CadQuery's union flow: perform one OCC fuse across the
+input solids, then call `clean()` to unify same-domain faces when possible.
+Touching-but-not-intersecting inputs can legitimately return multiple solids.
+If that happens, keep using the list: pass it directly into later union calls,
+or iterate over the solids for later cut/intersect steps.
+When the returned solids are still separated by more than the active tolerance,
+SimpleCAD prints a stdout warning explaining that the objects do not touch and
+that their gap exceeds `tol`.
+If you truly need exactly one merged solid, you must check the list length
+before using `result[0]`.
+
+## Parameters
+
+### solids
+
+- **Description**: One or more Solid objects or sequences of Solid. Nested sequences are flattened before processing.
+
+### clean
+
+- **Description**: Call CadQuery's `clean()` after the union to remove splitter edges and unify same-domain faces when possible.
+
+### glue
+
+- **Description**: Enable OCC glue mode for touching or partially overlapping inputs. Defaults to `True` for SimpleCAD's standard union behavior.
+
+### tol
+
+- **Description**: Optional fuzzy-boolean tolerance passed to the OCC union kernel. When omitted, SimpleCAD derives a conservative scale-aware value automatically.
+
+## Returns
+
+List[Solid]: Resulting solids after union attempts. Solids that can be fused
+are merged; disjoint or tangent-only contacts remain separate, so the
+list may contain multiple solids.
+
+## Examples
+
+### Example 1
+```python
+# Rounded-bar style input: end caps only touch the center body.
+main_body = make_box_rsolid(10, 4, 4, bottom_face_center=(0, 0, 0))
+left_cap = make_sphere_rsolid(2.0, center=(-2.0, 2.0, 2.0))
+right_cap = make_sphere_rsolid(2.0, center=(12.0, 2.0, 2.0))
+```
+
+### Example 2
+```python
+body_parts = union_rsolidlist(main_body, [left_cap, right_cap])
+print(f"Union result count: {len(body_parts)}")
+# This is acceptable: tangent-only contact can stay as multiple solids.
+for solid in body_parts:
+    print(f"- volume: {solid.get_volume():.6f}")
+```
+
+### Example 3
+```python
+# Keep using the returned list in later boolean steps.
+rib = make_box_rsolid(2, 4, 4, bottom_face_center=(4, 0, 0))
+combined_parts = union_rsolidlist(body_parts, rib)
+print(f"Combined result count: {len(combined_parts)}")
+```
+
+### Example 4
+```python
+# Only unwrap to one solid after an explicit length check.
+left_cap_embedded = make_sphere_rsolid(2.0, center=(-1.8, 2.0, 2.0))
+right_cap_embedded = make_sphere_rsolid(2.0, center=(11.8, 2.0, 2.0))
+merged = union_rsolidlist(main_body, [left_cap_embedded, right_cap_embedded])
+if len(merged) != 1:
+    raise ValueError(
+        "Adjust part placement so each cap overlaps the body slightly before "
+        "using merged[0]."
+    )
+final_body = merged[0]
+```
@@ -0,0 +1,36 @@
+# value
+
+## API Definition
+
+```python
+def value(path: str, default: Any = None) -> KeyFn
+```
+
+*Source: ql.py*
+
+## Description
+
+Build a value getter for sorting or projection.
+
+Q.select(items).order_by(Q.value("geo.height"))
+
+## Parameters
+
+### path
+
+- **Description**: Metadata path, for example `geo.height`.
+
+### default
+
+- **Description**: Default value when lookup fails.
+
+## Returns
+
+Callable[[Any], Any]: Getter function.
+
+## Examples
+
+```python
+key = Q.value("geo.height", 0.0)
+height = key(obj)
+```