KCL: new 'hole' module for mech-eng

docs/kcl-std/functions/std-hole-blind.md

@@ -0,0 +1,29 @@
+---
+title: "hole::blind"
+subtitle: "Function in std::hole"
+excerpt: "The hole has the given blind depth."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+The hole has the given blind depth.
+
+```kcl
+hole::blind(
+  depth: number(Length),
+  diameter: number(Length),
+)
+```
+
+
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `depth` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `diameter` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+
+
+

docs/kcl-std/functions/std-hole-counterbore.md

@@ -0,0 +1,74 @@
+---
+title: "hole::counterbore"
+subtitle: "Function in std::hole"
+excerpt: "Cut a straight vertical counterbore at the top of the hole."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+Cut a straight vertical counterbore at the top of the hole.
+
+```kcl
+hole::counterbore(
+  diameter: number(Length),
+  depth: number(Length),
+)
+```
+
+
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `diameter` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `depth` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+
+
+### Examples
+
+```kcl
+// `hole` module is still experimental, so enable experimental features here.
+@settings(experimentalFeatures = allow)
+
+// Model a cube
+cubeLen = 20
+bigCube = startSketchOn(XY)
+  |> startProfile(at = [-cubeLen / 2, -cubeLen / 2 + 10])
+  |> line(end = [cubeLen, 0], tag = $a)
+  |> line(end = [0, cubeLen], tag = $b)
+  |> line(end = [-cubeLen, 0], tag = $c)
+  |> line(end = [0, -cubeLen], tag = $d)
+  |> close()
+  |> extrude(length = cubeLen, symmetric = true)
+  |> translate(x = 5)
+
+  // Add a hole to the cube.
+// It'll have a drilled end, and a counterbore (vertical hole that emerges from a larger hole)
+bigCube
+  |> hole::hole(
+       face = a,
+       cutAt = [0, 5],
+       holeBottom = hole::drill(pointAngle = 110deg),
+       holeBody = hole::blind(depth = 5, diameter = 8),
+       holeType = hole::counterbore(diameter = 12, depth = 3.5),
+     )
+
+```
+
+
+<model-viewer
+  class="kcl-example"
+  alt="Example showing a rendered KCL program that uses the hole::counterbore function"
+  src="/kcl-test-outputs/models/serial_test_example_fn_std-hole-counterbore0_output.gltf"
+  ar
+  environment-image="/moon_1k.hdr"
+  poster="/kcl-test-outputs/serial_test_example_fn_std-hole-counterbore0.png"
+  shadow-intensity="1"
+  camera-controls
+  touch-action="pan-y"
+>
+</model-viewer>
+
+

docs/kcl-std/functions/std-hole-countersink.md

@@ -0,0 +1,74 @@
+---
+title: "hole::countersink"
+subtitle: "Function in std::hole"
+excerpt: "Cut an angled countersink at the top of the hole."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+Cut an angled countersink at the top of the hole.
+
+```kcl
+hole::countersink(
+  diameter: number(Length),
+  angle: number(Angle),
+)
+```
+
+
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `diameter` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `angle` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+
+
+### Examples
+
+```kcl
+// `hole` module is still experimental, so enable experimental features here.
+@settings(experimentalFeatures = allow)
+
+// Model a cube
+cubeLen = 20
+bigCube = startSketchOn(XY)
+  |> startProfile(at = [-cubeLen / 2, -cubeLen / 2 + 10])
+  |> line(end = [cubeLen, 0], tag = $a)
+  |> line(end = [0, cubeLen], tag = $b)
+  |> line(end = [-cubeLen, 0], tag = $c)
+  |> line(end = [0, -cubeLen], tag = $d)
+  |> close()
+  |> extrude(length = cubeLen, symmetric = true)
+  |> translate(x = 5)
+
+  // Add a hole to the cube.
+// It'll have a drilled end, and a countersink (angled tip at the start).
+bigCube
+  |> hole::hole(
+       face = a,
+       cutAt = [0, 5],
+       holeBottom = hole::drill(pointAngle = 110deg),
+       holeBody = hole::blind(depth = 5, diameter = 8),
+       holeType = hole::countersink(diameter = 14, angle = 100deg),
+     )
+
+```
+
+
+<model-viewer
+  class="kcl-example"
+  alt="Example showing a rendered KCL program that uses the hole::countersink function"
+  src="/kcl-test-outputs/models/serial_test_example_fn_std-hole-countersink0_output.gltf"
+  ar
+  environment-image="/moon_1k.hdr"
+  poster="/kcl-test-outputs/serial_test_example_fn_std-hole-countersink0.png"
+  shadow-intensity="1"
+  camera-controls
+  touch-action="pan-y"
+>
+</model-viewer>
+
+

docs/kcl-std/functions/std-hole-drill.md

@@ -0,0 +1,25 @@
+---
+title: "hole::drill"
+subtitle: "Function in std::hole"
+excerpt: "End the hole in an angle, like the end of a drill."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+End the hole in an angle, like the end of a drill.
+
+```kcl
+hole::drill(pointAngle: number(Angle))
+```
+
+
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `pointAngle` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+
+
+

docs/kcl-std/functions/std-hole-flat.md

@@ -0,0 +1,20 @@
+---
+title: "hole::flat"
+subtitle: "Function in std::hole"
+excerpt: "End the hole flat."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+End the hole flat.
+
+```kcl
+hole::flat()
+```
+
+
+
+
+
+

docs/kcl-std/functions/std-hole-hole.md

@@ -0,0 +1,125 @@
+---
+title: "hole::hole"
+subtitle: "Function in std::hole"
+excerpt: "From the hole's parts (bottom, middle, top), cut the hole into the given solid, at the given 2D position on the given face."
+layout: manual
+---
+
+**WARNING:** This function is experimental and may change or be removed.
+
+From the hole's parts (bottom, middle, top), cut the hole into the given solid, at the given 2D position on the given face.
+
+```kcl
+hole::hole(
+  @solid: Solid,
+  face: TaggedFace,
+  holeBottom,
+  holeBody,
+  holeType,
+  cutAt: [number(Length); 2],
+)
+```
+
+
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `solid` | [`Solid`](/docs/kcl-std/types/std-types-Solid) | Which solid to add a hole to. | Yes |
+| `face` | [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) | Which face of the solid to add the hole to. | Yes |
+| `holeBottom` |  | Define bottom feature of the hole. E.g. drilled or flat. | Yes |
+| `holeBody` |  | Define the main length of the hole. E.g. a blind distance. | Yes |
+| `holeType` |  | Define the top feature of the hole. E.g. countersink, counterbore, simple. | Yes |
+| `cutAt` | [`[number(Length); 2]`](/docs/kcl-std/types/std-types-number) | Where to place the cut on the given face of the solid. This controls how far up/down/left/right the hole is placed. | Yes |
+
+
+### Examples
+
+```kcl
+// `hole` module is still experimental, so enable experimental features here.
+@settings(experimentalFeatures = allow)
+
+// Model a cube
+cubeLen = 20
+bigCube = startSketchOn(XY)
+  |> startProfile(at = [-cubeLen / 2, -cubeLen / 2 + 10])
+  |> line(end = [cubeLen, 0], tag = $a)
+  |> line(end = [0, cubeLen], tag = $b)
+  |> line(end = [-cubeLen, 0], tag = $c)
+  |> line(end = [0, -cubeLen], tag = $d)
+  |> close()
+  |> extrude(length = cubeLen, symmetric = true)
+  |> translate(x = 5)
+
+  // Add a hole to the cube.
+// It'll have a drilled end, and a countersink (angled tip at the start).
+bigCube
+  |> hole::hole(
+       face = a,
+       cutAt = [0, 5],
+       holeBottom = hole::drill(pointAngle = 110deg),
+       holeBody = hole::blind(depth = 5, diameter = 8),
+       holeType = hole::countersink(diameter = 14, angle = 100deg),
+     )
+
+```
+
+
+<model-viewer
+  class="kcl-example"
+  alt="Example showing a rendered KCL program that uses the hole::hole function"
+  src="/kcl-test-outputs/models/serial_test_example_fn_std-hole-hole0_output.gltf"
+  ar
+  environment-image="/moon_1k.hdr"
+  poster="/kcl-test-outputs/serial_test_example_fn_std-hole-hole0.png"
+  shadow-intensity="1"
+  camera-controls
+  touch-action="pan-y"
+>
+</model-viewer>
+
+```kcl
+// `hole` module is still experimental, so enable experimental features here.
+@settings(experimentalFeatures = allow)
+
+// Model a cube
+cubeLen = 20
+bigCube = startSketchOn(XY)
+  |> startProfile(at = [-cubeLen / 2, -cubeLen / 2 + 10])
+  |> line(end = [cubeLen, 0], tag = $a)
+  |> line(end = [0, cubeLen], tag = $b)
+  |> line(end = [-cubeLen, 0], tag = $c)
+  |> line(end = [0, -cubeLen], tag = $d)
+  |> close()
+  |> extrude(length = cubeLen, symmetric = true)
+  |> translate(x = 5)
+
+  // Add a hole to the cube.
+// It'll have a drilled end, and a counterbore (vertical hole that emerges from a larger hole)
+bigCube
+  |> hole::hole(
+       face = a,
+       cutAt = [0, 5],
+       holeBottom = hole::drill(pointAngle = 110deg),
+       holeBody = hole::blind(depth = 5, diameter = 8),
+       holeType = hole::counterbore(diameter = 12, depth = 3.5),
+     )
+
+```
+
+
+<model-viewer
+  class="kcl-example"
+  alt="Example showing a rendered KCL program that uses the hole::hole function"
+  src="/kcl-test-outputs/models/serial_test_example_fn_std-hole-hole1_output.gltf"
+  ar
+  environment-image="/moon_1k.hdr"
+  poster="/kcl-test-outputs/serial_test_example_fn_std-hole-hole1.png"
+  shadow-intensity="1"
+  camera-controls
+  touch-action="pan-y"
+>
+</model-viewer>
+
+

docs/kcl-std/functions/std-hole-holeGeometry.md

@@ -0,0 +1,35 @@
+---
+title: "hole::holeGeometry"
+subtitle: "Function in std::hole"
+excerpt: "Build a hole's geometry from its top, bottom and depth. Can be subtracted from a solid to cut a hole into it."
+layout: manual
+---
+
+Build a hole's geometry from its top, bottom and depth. Can be subtracted from a solid to cut a hole into it.
+
+```kcl
+hole::holeGeometry(
+  @solid,
+  face,
+  holeBottom,
+  holeBody,
+  holeType,
+  cutAt,
+)
+```
+
+
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `solid` |  |  | Yes |
+| `face` |  |  | Yes |
+| `holeBottom` |  |  | Yes |
+| `holeBody` |  |  | Yes |
+| `holeType` |  |  | Yes |
+| `cutAt` |  |  | Yes |
+
+
+