KCL: Add 'factor' arg for scale

`scale(factor = 2)` is equivalent to `scale(x = 2, y = 2, z = 2)`.

Requested by Nick Boone.

Author: adamchalmers

docs/kcl-std/functions/std-transform-scale.md

@@ -14,6 +14,7 @@ scale(
   y?: number(_),
   z?: number(_),
   global?: bool,
+  factor?: number(_),
 ): [Solid; 1+] | [Sketch; 1+] | ImportedGeometry
 ```
 
@@ -39,6 +40,7 @@ look like the model moves and gets bigger at the same time. Say you have a squar
 | `y` | [`number(_)`](/docs/kcl-std/types/std-types-number) | The scale factor for the y axis. | No |
 | `z` | [`number(_)`](/docs/kcl-std/types/std-types-number) | The scale factor for the z axis. | No |
 | `global` | [`bool`](/docs/kcl-std/types/std-types-bool) | If true, the transform is applied in global space. The origin of the model will move. By default, the transform is applied in local sketch axis, therefore the origin will not move. | No |
+| `factor` | [`number(_)`](/docs/kcl-std/types/std-types-number) | If given, scale the solid by this much. Equivalent to setting `x`, `y` and `z` all to this number. Incompatible with `x`, `y` or `z`. | No |
 
 ### Returns
 
@@ -151,4 +153,35 @@ scale(parts, z = 0.5)
 >
 </model-viewer>
 
+```kcl
+// Make one button (i.e. just a cylinder)
+button1 = startSketchOn(XY)
+  |> circle(center = [0, 0], radius = 1.53)
+  |> extrude(length = 1)
+
+// Duplicate it, but use `scale` to make it smaller.
+button2 = startSketchOn(XY)
+  |> circle(center = [0, 0], radius = 1.53)
+  |> extrude(length = 1)
+  |> translate(x = 4)
+  // Make it 50% smaller and gold
+  |> scale(factor = 0.5)
+  |> appearance(color = "#ff9922")
+
+```
+
+
+<model-viewer
+  class="kcl-example"
+  alt="Example showing a rendered KCL program that uses the scale function"
+  src="/kcl-test-outputs/models/serial_test_example_fn_std-transform-scale3_output.gltf"
+  ar
+  environment-image="/moon_1k.hdr"
+  poster="/kcl-test-outputs/serial_test_example_fn_std-transform-scale3.png"
+  shadow-intensity="1"
+  camera-controls
+  touch-action="pan-y"
+>
+</model-viewer>
+
 

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

@@ -268,6 +268,7 @@ pub const TEST_NAMES: &[&str] = &[
     "std-transform-scale-0",
     "std-transform-scale-1",
     "std-transform-scale-2",
+    "std-transform-scale-3",
     "std-units-toDegrees-0",
     "std-units-toRadians-0",
     "std-vector-add-0",

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

@@ -42,16 +42,26 @@ pub async fn scale(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
     let scale_x: Option<TyF64> = args.get_kw_arg_opt("x", &RuntimeType::count(), exec_state)?;
     let scale_y: Option<TyF64> = args.get_kw_arg_opt("y", &RuntimeType::count(), exec_state)?;
     let scale_z: Option<TyF64> = args.get_kw_arg_opt("z", &RuntimeType::count(), exec_state)?;
+    let factor: Option<TyF64> = args.get_kw_arg_opt("factor", &RuntimeType::count(), exec_state)?;
+    let (scale_x, scale_y, scale_z) = match (scale_x, scale_y, scale_z, factor) {
+        (None, None, None, Some(factor)) => (Some(factor.clone()), Some(factor.clone()), Some(factor)),
+        (Some(x), Some(y), Some(z), None) => (Some(x), Some(y), Some(z)),
+        // Ensure at least one scale value is provided.
+        (None, None, None, None) => {
+            return Err(KclError::new_semantic(KclErrorDetails::new(
+                "Expected `x`, `y`, `z` or `factor` to be provided.".to_string(),
+                vec![args.source_range],
+            )));
+        }
+        _ => {
+            return Err(KclError::new_semantic(KclErrorDetails::new(
+                "If you give `factor` then you cannot use  `x`, `y`, or `z`".to_string(),
+                vec![args.source_range],
+            )));
+        }
+    };
     let global = args.get_kw_arg_opt("global", &RuntimeType::bool(), exec_state)?;
 
-    // Ensure at least one scale value is provided.
-    if scale_x.is_none() && scale_y.is_none() && scale_z.is_none() {
-        return Err(KclError::new_semantic(KclErrorDetails::new(
-            "Expected `x`, `y`, or `z` to be provided.".to_string(),
-            vec![args.source_range],
-        )));
-    }
-
     let objects = inner_scale(
         objects,
         scale_x.map(|t| t.n),

rust/kcl-lib/std/transform.kcl

@@ -604,6 +604,21 @@ export fn rotate(
 /// // Scale the sweep.
 /// scale(parts, z = 0.5)
 /// ```
+/// ```kcl
+/// // Make one button (i.e. just a cylinder)
+/// button1 = startSketchOn(XY)
+///   |> circle(center = [0, 0], radius = 1.53)
+///   |> extrude(length = 1)
+/// 
+/// // Duplicate it, but use `scale` to make it smaller.
+/// button2 = startSketchOn(XY)
+///   |> circle(center = [0, 0], radius = 1.53)
+///   |> extrude(length = 1)
+///   |> translate(x = 4)
+///   // Make it 50% smaller and gold
+///   |> scale(factor = 0.5)
+///   |> appearance(color = "#ff9922")
+/// ```
 @(impl = std_rust, feature_tree = true)
 export fn scale(
   /// The solid, sketch, or set of solids or sketches to scale.
@@ -619,4 +634,8 @@ export fn scale(
   z?: number(Count) = 1,
   /// If true, the transform is applied in global space. The origin of the model will move. By default, the transform is applied in local sketch axis, therefore the origin will not move.
   global?: bool = false,  
+  /// If given, scale the solid by this much.
+  /// Equivalent to setting `x`, `y` and `z` all to this number.
+  /// Incompatible with `x`, `y` or `z`.
+  factor?: number(Count) = 1,
 ): [Solid; 1+] | [Sketch; 1+] | ImportedGeometry {}