docuemnt face selection #15

Author: drayde

cadscript/body.py

@@ -155,19 +155,20 @@ def intersect(self, tool_body: 'Body') -> 'Body':
         self.__wp = wp
         return self
 
-    def add_extrude(self, faceStr: str, sketch: Optional['Sketch'], amount: float) -> 'Body':
+    def add_extrude(self, faceQuery: str, sketch: Optional['Sketch'], amount: float) -> 'Body':
         """
         Adds an extrusion to the specified face of the body using a sketch.
 
         Args:
-            faceStr (str): The face to extrude.
+            faceQuery (str): Query string that selects the face to extrude. Must evaluate to exactly one face.
+                The query syntax is documented at :ref:`query_faces`. 
             sketch (Sketch): The sketch to extrude. If None is given, the face itself is extruded.
             amount (float): The amount of extrusion.
 
         Returns:
             Body: The modified body object.
         """
-        face = self.__wp.faces(faceStr)
+        face = self.__wp.faces(faceQuery)
         plane = face.workplane(origin=(0, 0, 0))
         if sketch:
             plane = plane.placeSketch(sketch.cq())
@@ -176,19 +177,20 @@ def add_extrude(self, faceStr: str, sketch: Optional['Sketch'], amount: float) -
         self.__wp = plane.extrude(amount, "a")
         return self
 
-    def cut_extrude(self, faceStr: str, sketch: Optional['Sketch'], amount: float) -> 'Body':
+    def cut_extrude(self, faceQuery: str, sketch: Optional['Sketch'], amount: float) -> 'Body':
         """
         Adds a cut extrusion to the specified face of the body using a sketch.
 
         Args:
-            faceStr (str): The face to extrude.
+            faceQuery (str): Query string that selects the face to extrude. Must evaluate to exactly one face.
+                The query syntax is documented at :ref:`query_faces`. 
             sketch (Sketch): The sketch to extrude. If None is given, the face itself is extruded.
             amount (float): The amount of extrusion. For cutting you usually want to use a negative value to cut into the body.
 
         Returns:
             Body: The modified body object.
         """
-        face = self.__wp.faces(faceStr)
+        face = self.__wp.faces(faceQuery)
         plane = face.workplane(origin=(0, 0, 0))
         if sketch:
             plane = plane.placeSketch(sketch.cq())
@@ -197,12 +199,13 @@ def cut_extrude(self, faceStr: str, sketch: Optional['Sketch'], amount: float) -
         self.__wp = plane.extrude(amount, "s")
         return self
 
-    def make_extrude(self, faceStr: str, sketch: Optional['Sketch'], amount: DimensionDefinitionType) -> 'Body':
+    def make_extrude(self, faceQuery: str, sketch: Optional['Sketch'], amount: DimensionDefinitionType) -> 'Body':
         """
         Creates a new body by extruding the specified face of the body using a sketch.
 
         Args:
-            faceStr (str): The face to extrude.
+            faceQuery (str): Query string that selects the face to extrude. Must evaluate to exactly one face.
+                The query syntax is documented at :ref:`query_faces`. 
             sketch (Sketch): The sketch to extrude. If None is given, the face itself is extruded.
             amount (float): The amount of extrusion. Can also be a tuple of two floats to extrude between two planes with the given offsets.
 
@@ -215,7 +218,7 @@ def make_extrude(self, faceStr: str, sketch: Optional['Sketch'], amount: Dimensi
         dim = get_dimension(amount, False)
         offset = dim.min if abs(dim.min) > 1e-6 else 0.0
 
-        face = self.__wp.faces(faceStr)
+        face = self.__wp.faces(faceQuery)
         plane = face.workplane(origin=(0, 0, 0))  # offset param does not work for some reason, move result instead
         if sketch:
             plane = plane.placeSketch(sketch.cq())

docs/source/ref_query_string.rst

@@ -66,7 +66,7 @@ Selecting Edges
 ---------------
 
 
-The following methods allow you to select points (aka vertices) in a sketch based on a query string. 
+The following methods allow you to edges of a body based on a query string. 
 
 .. hlist::
 
@@ -91,7 +91,7 @@ The following query bits are supported:
      - Selects all edges
    * - \+
      - \+Z
-     - Edges aligned in the Z direction
+     - Edges aligned in the z direction
    * - \|
      - \|Z
      - Edges parallel to z direction
@@ -130,3 +130,61 @@ The following query bits are supported:
      - not >Y
      - All edges but the farthest in the positive y dir  
 
+
+
+.. _query_faces:
+
+Selecting Faces
+---------------
+
+
+The following methods allow you to select faces of a body based on a query string. 
+
+.. hlist::
+
+    * :py:meth:`Body.make_extrude` 
+    * :py:meth:`Body.add_extrude` 
+    * :py:meth:`Body.cut_extrude` 
+
+The following query bits are supported:
+
+
+
+.. list-table:: 
+   :header-rows: 1
+
+   * - Query
+     - Example
+     - Selects
+   * - \+
+     - \+Z
+     - Faces with normal in positive z direction
+   * - \|
+     - \|Z
+     - Faces with normal in positive or negative z direction
+   * - #
+     - #Z
+     - Faces with normal perpendicular to z direction
+   * - >
+     - >Y
+     - Face farthest in positive y direction
+   * - <
+     - <Y
+     - Face closest in positive y direction
+   * - >>[]
+     - >>Y[1]
+     - The search string ">>Y" sorts all faces in positive Y direction.\ 
+       The "[1]" selects the second face in that list (first in the list has index 0).
+   * - <<[]
+     - <<Y[0]
+     - The search string "<<Y" sorts all faces in negative Y direction.\ 
+       The "[0]" selects the first face in that list.
+   * - or
+     - >Y or <Y
+     - Faces farthest in the positive or negative y dir
+   * - and
+     - >Y and +Y
+     - Faces farthest in the positive y dir and normal in positive y dir
+   * - not
+     - not >Y
+     - All faces but the farthest in the positive y dir