Sketch on normal of face (#7886)

This work updates `startSketchOn` to enable sketching on a plane normal to the selected face. You can now specify an axis of the face that will become the x axis of the new plane, with the normal of the selected face becoming the y axis of the new plane. This extension creates the plane and begins sketching as usual.

Author: benjamaan476

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

@@ -170,6 +170,7 @@ pub const TEST_NAMES: &[&str] = &[
     "std-sketch-startSketchOn-3",
     "std-sketch-startSketchOn-4",
     "std-sketch-startSketchOn-5",
+    "std-sketch-startSketchOn-6",
     "std-sketch-angledLineThatIntersects-0",
     "std-sketch-angledLine-0",
     "std-sketch-arc-0",

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

@@ -1,4 +1,4 @@
-use std::ops::{Add, AddAssign, Mul};
+use std::ops::{Add, AddAssign, Mul, Sub, SubAssign};
 
 use anyhow::Result;
 use indexmap::IndexMap;
@@ -561,6 +561,15 @@ impl Plane {
     pub fn is_standard(&self) -> bool {
         !matches!(self.value, PlaneType::Custom | PlaneType::Uninit)
     }
+
+    /// Project a point onto a plane by calculating how far away it is and moving it along the
+    /// normal of the plane so that it now lies on the plane.
+    pub fn project(&self, point: Point3d) -> Point3d {
+        let v = point - self.info.origin;
+        let dot = v.axes_dot_product(&self.info.z_axis);
+
+        point - self.info.z_axis * dot
+    }
 }
 
 /// A face.
@@ -1062,6 +1071,34 @@ impl AddAssign for Point3d {
     }
 }
 
+impl Sub for Point3d {
+    type Output = Point3d;
+
+    fn sub(self, rhs: Self) -> Self::Output {
+        let (x, y, z) = if rhs.units != self.units {
+            (
+                rhs.units.adjust_to(rhs.x, self.units).0,
+                rhs.units.adjust_to(rhs.y, self.units).0,
+                rhs.units.adjust_to(rhs.z, self.units).0,
+            )
+        } else {
+            (rhs.x, rhs.y, rhs.z)
+        };
+        Point3d {
+            x: self.x - x,
+            y: self.y - y,
+            z: self.z - z,
+            units: self.units,
+        }
+    }
+}
+
+impl SubAssign for Point3d {
+    fn sub_assign(&mut self, rhs: Self) {
+        *self = *self - rhs
+    }
+}
+
 impl Mul<f64> for Point3d {
     type Output = Point3d;
 

rust/kcl-lib/src/execution/geometry.rs

@@ -2167,6 +2167,49 @@ notPipeSub = 1 |> identity(!%))";
         // let notInfinity = !Infinity
     }
 
+    #[tokio::test(flavor = "multi_thread")]
+    async fn test_start_sketch_on_invalid_kwargs() {
+        let current_dir = std::env::current_dir().unwrap();
+        let mut path = current_dir.join("tests/inputs/startSketchOn_0.kcl");
+        let mut code = std::fs::read_to_string(&path).unwrap();
+        assert_eq!(
+            parse_execute(&code).await.unwrap_err().message(),
+            "You cannot give both `face` and `normalToFace` params, you have to choose one or the other.".to_owned(),
+        );
+
+        path = current_dir.join("tests/inputs/startSketchOn_1.kcl");
+        code = std::fs::read_to_string(&path).unwrap();
+
+        assert_eq!(
+            parse_execute(&code).await.unwrap_err().message(),
+            "`alignAxis` is required if `normalToFace` is specified.".to_owned(),
+        );
+
+        path = current_dir.join("tests/inputs/startSketchOn_2.kcl");
+        code = std::fs::read_to_string(&path).unwrap();
+
+        assert_eq!(
+            parse_execute(&code).await.unwrap_err().message(),
+            "`normalToFace` is required if `alignAxis` is specified.".to_owned(),
+        );
+
+        path = current_dir.join("tests/inputs/startSketchOn_3.kcl");
+        code = std::fs::read_to_string(&path).unwrap();
+
+        assert_eq!(
+            parse_execute(&code).await.unwrap_err().message(),
+            "`normalToFace` is required if `alignAxis` is specified.".to_owned(),
+        );
+
+        path = current_dir.join("tests/inputs/startSketchOn_4.kcl");
+        code = std::fs::read_to_string(&path).unwrap();
+
+        assert_eq!(
+            parse_execute(&code).await.unwrap_err().message(),
+            "`normalToFace` is required if `normalOffset` is specified.".to_owned(),
+        );
+    }
+
     #[tokio::test(flavor = "multi_thread")]
     async fn test_math_negative_variable_in_binary_expression() {
         let ast = r#"sigmaAllow = 35000 // psi

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

@@ -25,7 +25,7 @@ pub async fn plane_of(exec_state: &mut ExecState, args: Args) -> Result<KclValue
         .map(|value| KclValue::Plane { value })
 }
 
-async fn inner_plane_of(
+pub(crate) async fn inner_plane_of(
     solid: crate::execution::Solid,
     face: FaceTag,
     exec_state: &mut ExecState,

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

@@ -1,5 +1,7 @@
 //! Functions related to sketching.
 
+use std::f64;
+
 use anyhow::Result;
 use indexmap::IndexMap;
 use kcmc::shared::Point2d as KPoint2d; // Point2d is already defined in this pkg, to impl ts_rs traits.
@@ -20,13 +22,15 @@ use crate::execution::{Artifact, ArtifactId, CodeRef, StartSketchOnFace, StartSk
 use crate::{
     errors::{KclError, KclErrorDetails},
     execution::{
-        BasePath, ExecState, Face, GeoMeta, KclValue, ModelingCmdMeta, Path, Plane, PlaneInfo, Point2d, Sketch,
-        SketchSurface, Solid, TagEngineInfo, TagIdentifier,
+        BasePath, ExecState, Face, GeoMeta, KclValue, ModelingCmdMeta, Path, Plane, PlaneInfo, Point2d, Point3d,
+        Sketch, SketchSurface, Solid, TagEngineInfo, TagIdentifier,
         types::{ArrayLen, NumericType, PrimitiveType, RuntimeType, UnitLen},
     },
     parsing::ast::types::TagNode,
     std::{
         args::{Args, TyF64},
+        axis_or_reference::Axis2dOrEdgeReference,
+        planes::inner_plane_of,
         utils::{
             TangentialArcInfoInput, arc_center_and_end, get_tangential_arc_to_info, get_x_component, get_y_component,
             intersection_with_parallel_line, point_to_len_unit, point_to_mm, untyped_point_to_mm,
@@ -810,8 +814,11 @@ pub async fn start_sketch_on(exec_state: &mut ExecState, args: Args) -> Result<K
         exec_state,
     )?;
     let face = args.get_kw_arg_opt("face", &RuntimeType::tagged_face(), exec_state)?;
+    let normal_to_face = args.get_kw_arg_opt("normalToFace", &RuntimeType::tagged_face(), exec_state)?;
+    let align_axis = args.get_kw_arg_opt("alignAxis", &RuntimeType::Primitive(PrimitiveType::Axis2d), exec_state)?;
+    let normal_offset = args.get_kw_arg_opt("normalOffset", &RuntimeType::length(), exec_state)?;
 
-    match inner_start_sketch_on(data, face, exec_state, &args).await? {
+    match inner_start_sketch_on(data, face, normal_to_face, align_axis, normal_offset, exec_state, &args).await? {
         SketchSurface::Plane(value) => Ok(KclValue::Plane { value }),
         SketchSurface::Face(value) => Ok(KclValue::Face { value }),
     }
@@ -820,9 +827,43 @@ pub async fn start_sketch_on(exec_state: &mut ExecState, args: Args) -> Result<K
 async fn inner_start_sketch_on(
     plane_or_solid: SketchData,
     face: Option<FaceTag>,
+    normal_to_face: Option<FaceTag>,
+    align_axis: Option<Axis2dOrEdgeReference>,
+    normal_offset: Option<TyF64>,
     exec_state: &mut ExecState,
     args: &Args,
 ) -> Result<SketchSurface, KclError> {
+    let face = match (face, normal_to_face, &align_axis, &normal_offset) {
+        (Some(_), Some(_), _, _) => {
+            return Err(KclError::new_semantic(KclErrorDetails::new(
+                "You cannot give both `face` and `normalToFace` params, you have to choose one or the other."
+                    .to_owned(),
+                vec![args.source_range],
+            )));
+        }
+        (Some(face), None, None, None) => Some(face),
+        (_, Some(_), None, _) => {
+            return Err(KclError::new_semantic(KclErrorDetails::new(
+                "`alignAxis` is required if `normalToFace` is specified.".to_owned(),
+                vec![args.source_range],
+            )));
+        }
+        (_, None, Some(_), _) => {
+            return Err(KclError::new_semantic(KclErrorDetails::new(
+                "`normalToFace` is required if `alignAxis` is specified.".to_owned(),
+                vec![args.source_range],
+            )));
+        }
+        (_, None, _, Some(_)) => {
+            return Err(KclError::new_semantic(KclErrorDetails::new(
+                "`normalToFace` is required if `normalOffset` is specified.".to_owned(),
+                vec![args.source_range],
+            )));
+        }
+        (_, Some(face), Some(_), _) => Some(face),
+        (None, None, None, None) => None,
+    };
+
     match plane_or_solid {
         SketchData::PlaneOrientation(plane_data) => {
             let plane = make_sketch_plane_from_orientation(plane_data, exec_state, args).await?;
@@ -860,20 +901,93 @@ async fn inner_start_sketch_on(
                     vec![args.source_range],
                 )));
             };
-            let face = start_sketch_on_face(solid, tag, exec_state, args).await?;
+            if let Some(align_axis) = align_axis {
+                let plane_of = inner_plane_of(*solid, tag, exec_state, args).await?;
+
+                let offset = normal_offset.map_or(0.0, |x| x.n);
+                let (x_axis, y_axis, normal_offset) = match align_axis {
+                    Axis2dOrEdgeReference::Axis { direction, origin: _ } => {
+                        if (direction[0].n - 1.0).abs() < f64::EPSILON {
+                            //X axis chosen
+                            (
+                                plane_of.info.x_axis,
+                                plane_of.info.z_axis,
+                                plane_of.info.y_axis * offset,
+                            )
+                        } else if (direction[0].n + 1.0).abs() < f64::EPSILON {
+                            // -X axis chosen
+                            (
+                                plane_of.info.x_axis.negated(),
+                                plane_of.info.z_axis,
+                                plane_of.info.y_axis * offset,
+                            )
+                        } else if (direction[1].n - 1.0).abs() < f64::EPSILON {
+                            // Y axis chosen
+                            (
+                                plane_of.info.y_axis,
+                                plane_of.info.z_axis,
+                                plane_of.info.x_axis * offset,
+                            )
+                        } else if (direction[1].n + 1.0).abs() < f64::EPSILON {
+                            // -Y axis chosen
+                            (
+                                plane_of.info.y_axis.negated(),
+                                plane_of.info.z_axis,
+                                plane_of.info.x_axis * offset,
+                            )
+                        } else {
+                            return Err(KclError::new_semantic(KclErrorDetails::new(
+                                "Unsupported axis detected. This function only supports using X, -X, Y and -Y."
+                                    .to_owned(),
+                                vec![args.source_range],
+                            )));
+                        }
+                    }
+                    Axis2dOrEdgeReference::Edge(_) => {
+                        return Err(KclError::new_semantic(KclErrorDetails::new(
+                            "Use of an edge here is unsupported, please specify an `Axis2d` (e.g. `X`) instead."
+                                .to_owned(),
+                            vec![args.source_range],
+                        )));
+                    }
+                };
+                let origin = Point3d::new(0.0, 0.0, 0.0, plane_of.info.origin.units);
+                let plane_data = PlaneData::Plane(PlaneInfo {
+                    origin: plane_of.project(origin) + normal_offset,
+                    x_axis,
+                    y_axis,
+                    z_axis: x_axis.axes_cross_product(&y_axis),
+                });
+                let plane = make_sketch_plane_from_orientation(plane_data, exec_state, args).await?;
 
-            #[cfg(feature = "artifact-graph")]
-            {
                 // Create artifact used only by the UI, not the engine.
-                let id = exec_state.next_uuid();
-                exec_state.add_artifact(Artifact::StartSketchOnFace(StartSketchOnFace {
-                    id: ArtifactId::from(id),
-                    face_id: face.artifact_id,
-                    code_ref: CodeRef::placeholder(args.source_range),
-                }));
-            }
+                #[cfg(feature = "artifact-graph")]
+                {
+                    let id = exec_state.next_uuid();
+                    exec_state.add_artifact(Artifact::StartSketchOnPlane(StartSketchOnPlane {
+                        id: ArtifactId::from(id),
+                        plane_id: plane.artifact_id,
+                        code_ref: CodeRef::placeholder(args.source_range),
+                    }));
+                }
 
-            Ok(SketchSurface::Face(face))
+                Ok(SketchSurface::Plane(plane))
+            } else {
+                let face = start_sketch_on_face(solid, tag, exec_state, args).await?;
+
+                #[cfg(feature = "artifact-graph")]
+                {
+                    // Create artifact used only by the UI, not the engine.
+                    let id = exec_state.next_uuid();
+                    exec_state.add_artifact(Artifact::StartSketchOnFace(StartSketchOnFace {
+                        id: ArtifactId::from(id),
+                        face_id: face.artifact_id,
+                        code_ref: CodeRef::placeholder(args.source_range),
+                    }));
+                }
+
+                Ok(SketchSurface::Face(face))
+            }
         }
     }
 }

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

@@ -181,12 +181,36 @@
 ///  |> close()
 ///  |> extrude(length = 3.14)
 /// ```
+///
+/// ```kcl
+/// sketch001 = startSketchOn(XY)
+///   |> startProfile(at = [-5, -5])
+///   |> xLine(length = 10)
+///   |> yLine(length = 10, tag = $b)
+///   |> xLine(length = -10)
+///   |> close()
+/// 
+/// cube001 = extrude(sketch001, length = 10)
+///   |> rotate(roll = 10, pitch = 20, yaw = 30)
+/// 
+/// sketch002 = startSketchOn(cube001, normalToFace = END, alignAxis = Y)
+///   |> circle(radius = 2, center = [0, 0])
+/// cube002 = extrude(sketch002, length = 4)
+/// 
+/// subtract(cube001, tools = cube002)
+/// ```
 @(impl = std_rust)
 export fn startSketchOn(
   /// Profile whose start is being used.
   @planeOrSolid: Solid | Plane,
-  /// Identify a face of a solid if a solid is specified as the input argument (`planeOrSolid`).
+  /// Identify a face of a solid if a solid is specified as the input argument (`planeOrSolid`). Incompatible with `normalToFace`.
   face?: TaggedFace,
+  /// Identify a face of a solid if a solid is specified as the input argument. Starts a sketch on the plane orthogonal to this specified face. Incompatible with `face`, requires `alignAxis`.
+  normalToFace?: TaggedFace,
+  /// If sketching normal to face, this axis will be the new local x axis of the sketch plane. The selected face's normal will be the local y axis. Incompatible with `face`, requires `normalToFace`.
+  alignAxis?: Axis2d,
+  /// Offset the sketch plane along its normal by the given amount. Incompatible with `face`, requires `normalToFace`.
+  normalOffset?: number(Length),
 ): Plane | Face {}
 
 /// Start a new profile at a given point.

rust/kcl-lib/std/sketch.kcl

@@ -0,0 +1,10 @@
+sketch001 = startSketchOn(XY)
+  |> startProfile(at = [-5, -5])
+  |> xLine(length = 10, tag = $a)
+  |> yLine(length = 10, tag = $b)
+  |> xLine(length = -10, tag = $c)
+  |> close()
+
+cube001 = extrude(sketch001, length = 10)
+
+sketch002 = startSketchOn(cube001, normalToFace = a, face = a)

rust/kcl-lib/tests/inputs/startSketchOn_0.kcl

@@ -0,0 +1,11 @@
+sketch001 = startSketchOn(XY)
+  |> startProfile(at = [-5, -5])
+  |> xLine(length = 10, tag = $a)
+  |> yLine(length = 10, tag = $b)
+  |> xLine(length = -10, tag = $c)
+  |> close()
+
+cube001 = extrude(sketch001, length = 10)
+
+sketch002 = startSketchOn(cube001, normalToFace = a)
+

rust/kcl-lib/tests/inputs/startSketchOn_1.kcl

@@ -0,0 +1,11 @@
+sketch001 = startSketchOn(XY)
+  |> startProfile(at = [-5, -5])
+  |> xLine(length = 10, tag = $a)
+  |> yLine(length = 10, tag = $b)
+  |> xLine(length = -10, tag = $c)
+  |> close()
+
+cube001 = extrude(sketch001, length = 10)
+
+sketch002 = startSketchOn(cube001, alignAxis = X)
+