Add experimental faceOf() stdlib function

docs/kcl-std/functions/std-sketch-faceOf.md

@@ -0,0 +1,68 @@
+---
+title: "faceOf"
+subtitle: "Function in std::sketch"
+excerpt: "Get the face of a solid."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+Get the face of a solid.
+
+```kcl
+faceOf(
+  @solid: Solid,
+  face: TaggedFace,
+): Face
+```
+
+
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `solid` | [`Solid`](/docs/kcl-std/types/std-types-Solid) | The solid that has the face. | Yes |
+| `face` | [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) | Which face of the solid. | Yes |
+
+### Returns
+
+[`Face`](/docs/kcl-std/types/std-types-Face) - A face of a solid.
+
+
+### Examples
+
+```kcl
+@settings(experimentalFeatures = allow)
+
+triangle = startSketchOn(XY)
+  |> startProfile(at = [0, 0])
+  |> line(end = [2, 0])
+  |> line(end = [0, 2], tag = $side)
+  |> line(end = [-2, -2])
+  |> close()
+  |> extrude(length = 2)
+
+// Get the face of the triangle's side face.
+sideFace = faceOf(triangle, face = side)
+
+// Create a new sketch, on the triangle's side face.
+// sketch(on = sideFace) {}
+
+```
+
+
+<model-viewer
+  class="kcl-example"
+  alt="Example showing a rendered KCL program that uses the faceOf function"
+  src="/kcl-test-outputs/models/serial_test_example_fn_std-sketch-faceOf0_output.gltf"
+  ar
+  environment-image="/moon_1k.hdr"
+  poster="/kcl-test-outputs/serial_test_example_fn_std-sketch-faceOf0.png"
+  shadow-intensity="1"
+  camera-controls
+  touch-action="pan-y"
+>
+</model-viewer>
+
+

docs/kcl-std/index.md

@@ -74,6 +74,7 @@ layout: manual
   * [`elliptic`](/docs/kcl-std/functions/std-sketch-elliptic)
   * [`ellipticPoint`](/docs/kcl-std/functions/std-sketch-ellipticPoint)
   * [`extrude`](/docs/kcl-std/functions/std-sketch-extrude)
+  * [`faceOf`](/docs/kcl-std/functions/std-sketch-faceOf)
   * [`getCommonEdge`](/docs/kcl-std/functions/std-sketch-getCommonEdge)
   * [`getNextAdjacentEdge`](/docs/kcl-std/functions/std-sketch-getNextAdjacentEdge)
   * [`getOppositeEdge`](/docs/kcl-std/functions/std-sketch-getOppositeEdge)

docs/kcl-std/modules/std-sketch.md

@@ -24,6 +24,7 @@ This module contains functions for creating and manipulating sketches, and makin
 * [`elliptic`](/docs/kcl-std/functions/std-sketch-elliptic)
 * [`ellipticPoint`](/docs/kcl-std/functions/std-sketch-ellipticPoint)
 * [`extrude`](/docs/kcl-std/functions/std-sketch-extrude)
+* [`faceOf`](/docs/kcl-std/functions/std-sketch-faceOf)
 * [`getCommonEdge`](/docs/kcl-std/functions/std-sketch-getCommonEdge)
 * [`getNextAdjacentEdge`](/docs/kcl-std/functions/std-sketch-getNextAdjacentEdge)
 * [`getOppositeEdge`](/docs/kcl-std/functions/std-sketch-getOppositeEdge)

rust/kcl-derive-docs/src/example_tests.rs

@@ -105,6 +105,7 @@ pub const TEST_NAMES: &[&str] = &[
     "std-offsetPlane-3",
     "std-offsetPlane-4",
     "std-sketch-planeOf-0",
+    "std-sketch-faceOf-0",
     "std-sketch-circle-0",
     "std-sketch-circle-1",
     "std-sketch-rectangle-0",

rust/kcl-lib/src/std/faces.rs

@@ -0,0 +1,39 @@
+//! Standard library face helpers.
+
+use super::sketch::FaceTag;
+use crate::{
+    errors::KclError,
+    execution::{ExecState, Face, KclValue, Solid, types::RuntimeType},
+    std::Args,
+};
+
+/// Face of a given solid.
+pub async fn face_of(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
+    let solid = args.get_unlabeled_kw_arg("solid", &RuntimeType::solid(), exec_state)?;
+    let face = args.get_kw_arg("face", &RuntimeType::tagged_face(), exec_state)?;
+
+    let face = make_face(solid, face, exec_state, &args).await?;
+
+    Ok(KclValue::Face { value: face })
+}
+
+pub(super) async fn make_face(
+    solid: Box<Solid>,
+    tag: FaceTag,
+    exec_state: &mut ExecState,
+    args: &Args,
+) -> Result<Box<Face>, KclError> {
+    let extrude_plane_id = tag.get_face_id(&solid, exec_state, args, true).await?;
+
+    Ok(Box::new(Face {
+        id: extrude_plane_id,
+        artifact_id: extrude_plane_id.into(),
+        value: tag.to_string(),
+        // TODO: get this from the extrude plane data.
+        x_axis: solid.sketch.on.x_axis(),
+        y_axis: solid.sketch.on.y_axis(),
+        units: solid.units,
+        solid,
+        meta: vec![args.source_range.into()],
+    }))
+}

rust/kcl-lib/src/std/mod.rs

@@ -11,6 +11,7 @@ pub mod constraints;
 pub mod csg;
 pub mod edge;
 pub mod extrude;
+pub mod faces;
 pub mod fillet;
 pub mod gdt;
 pub mod helix;
@@ -306,6 +307,10 @@ pub(crate) fn std_fn(path: &str, fn_name: &str) -> (crate::std::StdFn, StdFnProp
             |e, a| Box::pin(crate::std::planes::plane_of(e, a).map(|r| r.map(KclValue::continue_))),
             StdFnProps::default("std::sketch::planeOf"),
         ),
+        ("sketch", "faceOf") => (
+            |e, a| Box::pin(crate::std::faces::face_of(e, a).map(|r| r.map(KclValue::continue_))),
+            StdFnProps::default("std::sketch::faceOf"),
+        ),
         ("sketch", "extrude") => (
             |e, a| Box::pin(crate::std::extrude::extrude(e, a).map(|r| r.map(KclValue::continue_))),
             StdFnProps::default("std::sketch::extrude"),

rust/kcl-lib/src/std/sketch.rs

@@ -21,7 +21,7 @@ use crate::execution::{Artifact, ArtifactId, CodeRef, StartSketchOnFace, StartSk
 use crate::{
     errors::{KclError, KclErrorDetails},
     execution::{
-        BasePath, ExecState, Face, GeoMeta, KclValue, ModelingCmdMeta, Path, Plane, PlaneInfo, Point2d, Point3d,
+        BasePath, ExecState, GeoMeta, KclValue, ModelingCmdMeta, Path, Plane, PlaneInfo, Point2d, Point3d,
         ProfileClosed, Sketch, SketchSurface, Solid, TagEngineInfo, TagIdentifier, annotations,
         types::{ArrayLen, NumericType, PrimitiveType, RuntimeType},
     },
@@ -30,6 +30,7 @@ use crate::{
         EQUAL_POINTS_DIST_EPSILON,
         args::{Args, TyF64},
         axis_or_reference::Axis2dOrEdgeReference,
+        faces::make_face,
         planes::inner_plane_of,
         utils::{
             TangentialArcInfoInput, arc_center_and_end, get_tangential_arc_to_info, get_x_component, get_y_component,
@@ -1007,7 +1008,7 @@ async fn inner_start_sketch_on(
 
                 Ok(SketchSurface::Plane(plane))
             } else {
-                let face = start_sketch_on_face(solid, tag, exec_state, args).await?;
+                let face = make_face(solid, tag, exec_state, args).await?;
 
                 #[cfg(feature = "artifact-graph")]
                 {
@@ -1026,27 +1027,6 @@ async fn inner_start_sketch_on(
     }
 }
 
-async fn start_sketch_on_face(
-    solid: Box<Solid>,
-    tag: FaceTag,
-    exec_state: &mut ExecState,
-    args: &Args,
-) -> Result<Box<Face>, KclError> {
-    let extrude_plane_id = tag.get_face_id(&solid, exec_state, args, true).await?;
-
-    Ok(Box::new(Face {
-        id: extrude_plane_id,
-        artifact_id: extrude_plane_id.into(),
-        value: tag.to_string(),
-        // TODO: get this from the extrude plane data.
-        x_axis: solid.sketch.on.x_axis(),
-        y_axis: solid.sketch.on.y_axis(),
-        units: solid.units,
-        solid,
-        meta: vec![args.source_range.into()],
-    }))
-}
-
 pub async fn make_sketch_plane_from_orientation(
     data: PlaneData,
     exec_state: &mut ExecState,

rust/kcl-lib/std/sketch.kcl

@@ -2484,3 +2484,29 @@ export fn planeOf(
   /// Find the plane which this face lies on.
   face: TaggedFace,
 ): Plane {}
+
+/// Get the face of a solid.
+///```kcl
+/// @settings(experimentalFeatures = allow)
+/// 
+/// triangle = startSketchOn(XY)
+///   |> startProfile(at = [0, 0])
+///   |> line(end = [2, 0])
+///   |> line(end = [0, 2], tag = $side)
+///   |> line(end = [-2, -2])
+///   |> close()
+///   |> extrude(length = 2)
+/// 
+/// // Get the face of the triangle's side face.
+/// sideFace = faceOf(triangle, face = side)
+/// 
+/// // Create a new sketch, on the triangle's side face.
+/// //sketch(on = sideFace) {}
+/// ```
+@(impl = std_rust, experimental = true, feature_tree = false)
+export fn faceOf(
+  /// The solid that has the face.
+  @solid: Solid,
+  /// Which face of the solid.
+  face: TaggedFace,
+): Face {}