Declare appearance function in KCL (#7220)

Move appearance to KCL

Signed-off-by: Nick Cameron <nrc@ncameron.org>

rust/kcl-lib/std/solid.kcl

@@ -920,3 +920,224 @@ export fn subtract(
   /// The tolerance to use for the subtraction operation.
   tolerance?: number(Length),
 ): [Solid; 1+] {}
+
+/// Set the appearance of a solid. This only works on solids, not sketches or individual paths.
+///
+/// This will work on any solid, including extruded solids, revolved solids, and shelled solids.
+///
+/// ```kcl
+/// // Add color to an extruded solid.
+/// exampleSketch = startSketchOn(XZ)
+///   |> startProfile(at = [0, 0])
+///   |> line(endAbsolute = [10, 0])
+///   |> line(endAbsolute = [0, 10])
+///   |> line(endAbsolute = [-10, 0])
+///   |> close()
+///
+/// example = extrude(exampleSketch, length = 5)
+///  // There are other options besides 'color', but they're optional.
+///  |> appearance(color='#ff0000')
+/// ```
+///
+/// ```kcl
+/// // Add color to a revolved solid.
+/// sketch001 = startSketchOn(XY)
+///     |> circle( center = [15, 0], radius = 5 )
+///     |> revolve( angle = 360, axis = Y)
+///     |> appearance(
+///         color = '#ff0000',
+///         metalness = 90,
+///         roughness = 90
+///     )
+/// ```
+///
+/// ```kcl
+/// // Add color to different solids.
+/// fn cube(center) {
+///    return startSketchOn(XY)
+///    |> startProfile(at = [center[0] - 10, center[1] - 10])
+///    |> line(endAbsolute = [center[0] + 10, center[1] - 10])
+///     |> line(endAbsolute = [center[0] + 10, center[1] + 10])
+///     |> line(endAbsolute = [center[0] - 10, center[1] + 10])
+///     |> close()
+///    |> extrude(length = 10)
+/// }
+///
+/// example0 = cube(center = [0, 0])
+/// example1 = cube(center = [20, 0])
+/// example2 = cube(center = [40, 0])
+///
+///  appearance([example0, example1], color='#ff0000', metalness=50, roughness=50)
+///  appearance(example2, color='#00ff00', metalness=50, roughness=50)
+/// ```
+///
+/// ```kcl
+/// // You can set the appearance before or after you shell it will yield the same result.
+/// // This example shows setting the appearance _after_ the shell.
+/// firstSketch = startSketchOn(XY)
+///     |> startProfile(at = [-12, 12])
+///     |> line(end = [24, 0])
+///     |> line(end = [0, -24])
+///     |> line(end = [-24, 0])
+///     |> close()
+///     |> extrude(length = 6)
+///
+/// shell(
+///     firstSketch,
+///     faces = [END],
+///     thickness = 0.25,
+/// )
+///     |> appearance(
+///         color = '#ff0000',
+///         metalness = 90,
+///         roughness = 90
+///     )
+/// ```
+///
+/// ```kcl
+/// // You can set the appearance before or after you shell it will yield the same result.
+/// // This example shows setting the appearance _before_ the shell.
+/// firstSketch = startSketchOn(XY)
+///     |> startProfile(at = [-12, 12])
+///     |> line(end = [24, 0])
+///     |> line(end = [0, -24])
+///     |> line(end = [-24, 0])
+///     |> close()
+///     |> extrude(length = 6)
+///     |> appearance(
+///         color = '#ff0000',
+///         metalness = 90,
+///         roughness = 90
+///     )
+///
+/// shell(
+///     firstSketch,
+///     faces = [END],
+///     thickness = 0.25,
+/// )
+/// ```
+///
+/// ```kcl
+/// // Setting the appearance of a 3D pattern can be done _before_ or _after_ the pattern.
+/// // This example shows _before_ the pattern.
+/// exampleSketch = startSketchOn(XZ)
+///   |> startProfile(at = [0, 0])
+///   |> line(end = [0, 2])
+///   |> line(end = [3, 1])
+///   |> line(end = [0, -4])
+///   |> close()
+///
+/// example = extrude(exampleSketch, length = 1)
+///     |> appearance(
+///         color = '#ff0000',
+///         metalness = 90,
+///         roughness = 90
+///        )
+///     |> patternLinear3d(
+///         axis = [1, 0, 1],
+///         instances = 7,
+///         distance = 6
+///        )
+/// ```
+///
+/// ```kcl
+/// // Setting the appearance of a 3D pattern can be done _before_ or _after_ the pattern.
+/// // This example shows _after_ the pattern.
+/// exampleSketch = startSketchOn(XZ)
+///   |> startProfile(at = [0, 0])
+///   |> line(end = [0, 2])
+///   |> line(end = [3, 1])
+///   |> line(end = [0, -4])
+///   |> close()
+///
+/// example = extrude(exampleSketch, length = 1)
+///   |> patternLinear3d(
+///       axis = [1, 0, 1],
+///       instances = 7,
+///       distance = 6
+///      )
+///   |> appearance(
+///       color = '#ff0000',
+///       metalness = 90,
+///       roughness = 90
+///      )
+/// ```
+///
+/// ```kcl
+/// // Color the result of a 2D pattern that was extruded.
+/// exampleSketch = startSketchOn(XZ)
+///   |> startProfile(at = [.5, 25])
+///   |> line(end = [0, 5])
+///   |> line(end = [-1, 0])
+///   |> line(end = [0, -5])
+///   |> close()
+///   |> patternCircular2d(
+///        center = [0, 0],
+///        instances = 13,
+///        arcDegrees = 360,
+///        rotateDuplicates = true
+///      )
+///
+/// example = extrude(exampleSketch, length = 1)
+///     |> appearance(
+///         color = '#ff0000',
+///         metalness = 90,
+///         roughness = 90
+///     )
+/// ```
+///
+/// ```kcl
+/// // Color the result of a sweep.
+///
+/// // Create a path for the sweep.
+/// sweepPath = startSketchOn(XZ)
+///     |> startProfile(at = [0.05, 0.05])
+///     |> line(end = [0, 7])
+///     |> tangentialArc(angle = 90, radius = 5)
+///     |> line(end = [-3, 0])
+///     |> tangentialArc(angle = -90, radius = 5)
+///     |> line(end = [0, 7])
+///
+/// pipeHole = startSketchOn(XY)
+///     |> circle(
+///         center = [0, 0],
+///         radius = 1.5,
+///     )
+///
+/// sweepSketch = startSketchOn(XY)
+///     |> circle(
+///         center = [0, 0],
+///         radius = 2,
+///         )              
+///     |> subtract2d(tool = pipeHole)
+///     |> sweep(path = sweepPath)
+///     |> appearance(
+///         color = "#ff0000",
+///         metalness = 50,
+///         roughness = 50
+///     )
+/// ```
+///
+/// ```kcl
+/// // Change the appearance of an imported model.
+///
+/// import "tests/inputs/cube.sldprt" as cube
+///
+/// cube
+///    |> appearance(
+///        color = "#ff0000",
+///        metalness = 50,
+///        roughness = 50
+///    )
+/// ```
+@(impl = std_rust)
+export fn appearance(
+  /// The The solid(s) whose appearance is being set.
+  @solids: [Solid; 1+] | ImportedGeometry,
+  /// Color of the new material, a hex string like '#ff0000'.
+  color: string,
+  /// Metalness of the new material, a percentage like 95.7.
+  metalness?: number(Count),
+  /// Roughness of the new material, a percentage like 95.7.
+  roughness?: number(Count),
+): [Solid; 1+] | ImportedGeometry {}