modeling-app/rust/kcl-lib/std/prelude.kcl

/// The KCL standard library
///
/// Contains frequently used constants, functions for interacting with the KittyCAD servers to
/// create sketches and geometry, and utility functions.

@no_std
@settings(defaultLengthUnit = mm, kclVersion = 1.0)

// Note that everything in the prelude is treated as exported.

export import * from "std::types"
export import "std::units"
export import * from "std::array"
export import * from "std::math"
export import * from "std::sketch"
export import * from "std::solid"
export import * from "std::transform"
export import "std::turns"

export XY = {
  origin = { x = 0, y = 0, z = 0 },
  xAxis = { x = 1, y = 0, z = 0 },
  yAxis = { x = 0, y = 1, z = 0 },
}: Plane

export XZ = {
  origin = { x = 0, y = 0, z = 0 },
  xAxis = { x = 1, y = 0, z = 0 },
  yAxis = { x = 0, y = 0, z = 1 },
}: Plane

export YZ = {
  origin = { x = 0, y = 0, z = 0 },
  xAxis = { x = 0, y = 1, z = 0 },
  yAxis = { x = 0, y = 0, z = 1 },
}: Plane

export X = {
  origin = [0, 0, 0],
  direction = [1, 0, 0],
}: Axis3d

export Y = {
  origin = [0, 0, 0],
  direction = [0, 1, 0],
}: Axis3d

export Z = {
  origin = [0, 0, 0],
  direction = [0, 0, 1],
}: Axis3d

/// Identifies the starting face of an extrusion. I.e., the face which is extruded.
export START = 'start'

/// Identifies the ending face of an extrusion. I.e., the new face created by an extrusion.
export END = 'end'

/// Create a helix.
///
/// ```
/// // Create a helix around the Z axis.
/// helixPath = helix(
///     angleStart = 0,
///     ccw = true,
///     revolutions = 5,
///     length = 10,
///     radius = 5,
///     axis = Z,
///  )
///
/// // Create a spring by sweeping around the helix path.
/// springSketch = startSketchOn(YZ)
///     |> circle( center = [0, 0], radius = 0.5)
///     |> sweep(path = helixPath)
/// ```
///
/// ```
/// // Create a helix around an edge.
/// helper001 = startSketchOn(XZ)
///  |> startProfile(at = [0, 0])
///  |> line(end = [0, 10], tag = $edge001)
///
/// helixPath = helix(
///     angleStart = 0,
///     ccw = true,
///     revolutions = 5,
///     length = 10,
///     radius = 5,
///     axis = edge001,
///  )
///
/// // Create a spring by sweeping around the helix path.
/// springSketch = startSketchOn(XY)
///     |> circle( center = [0, 0], radius = 0.5 )
///     |> sweep(path = helixPath)
/// ```
///
/// ```
/// // Create a helix around a custom axis.
/// helixPath = helix(
///     angleStart = 0,
///     ccw = true,
///     revolutions = 5,
///     length = 10,
///     radius = 5,
///     axis = {
///         direction = [0, 0, 1.0],
///         origin = [0, 0.25, 0]
///     }
///  )
///
/// // Create a spring by sweeping around the helix path.
/// springSketch = startSketchOn(XY)
///     |> circle( center = [0, 0], radius = 1 )
///     |> sweep(path = helixPath)
/// ```
///
/// ```
/// // Create a helix on a cylinder.
///
/// part001 = startSketchOn(XY)
///   |> circle( center = [5, 5], radius= 10 )
///   |> extrude(length = 10)
///
/// helix(
///     angleStart = 0,
///     ccw = true,
///     revolutions = 16,
///     cylinder = part001,
///  )
/// ```
@(impl = std_rust)
export fn helix(
  /// Number of revolutions.
  revolutions: number(_),
  /// Start angle.
  angleStart: number(Angle),
  /// Is the helix rotation counter clockwise? The default is `false`.
  ccw?: bool,
  /// Radius of the helix.
  @(include_in_snippet = true)
  radius?: number(Length),
  /// Axis to use for the helix.
  @(include_in_snippet = true)
  axis?: Axis3d | Edge,
  /// Length of the helix. This is not necessary if the helix is created around an edge. If not given the length of the edge is used.
  @(include_in_snippet = true)
  length?: number(Length),
  /// Cylinder to create the helix on.
  cylinder?: Solid,
): Helix {}

/// Offset a plane by a distance along its normal.
///
/// For example, if you offset the `XZ` plane by 10, the new plane will be parallel to the `XZ`
/// plane and 10 units away from it.
///
/// ```
/// // Loft a square and a circle on the `XY` plane using offset.
/// squareSketch = startSketchOn(XY)
///     |> startProfile(at = [-100, 200])
///     |> line(end = [200, 0])
///     |> line(end = [0, -200])
///     |> line(end = [-200, 0])
///     |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
///     |> close()
///
/// circleSketch = startSketchOn(offsetPlane(XY, offset = 150))
///     |> circle( center = [0, 100], radius = 50 )
///
/// loft([squareSketch, circleSketch])
/// ```
///
/// ```
/// // Loft a square and a circle on the `XZ` plane using offset.
/// squareSketch = startSketchOn(XZ)
///     |> startProfile(at = [-100, 200])
///     |> line(end = [200, 0])
///     |> line(end = [0, -200])
///     |> line(end = [-200, 0])
///     |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
///     |> close()
///
/// circleSketch = startSketchOn(offsetPlane(XZ, offset = 150))
///     |> circle( center = [0, 100], radius = 50 )
///
/// loft([squareSketch, circleSketch])
/// ```
///
/// ```
/// // Loft a square and a circle on the `YZ` plane using offset.
/// squareSketch = startSketchOn(YZ)
///     |> startProfile(at = [-100, 200])
///     |> line(end = [200, 0])
///     |> line(end = [0, -200])
///     |> line(end = [-200, 0])
///     |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
///     |> close()
///
/// circleSketch = startSketchOn(offsetPlane(YZ, offset = 150))
///     |> circle( center = [0, 100], radius = 50 )
///
/// loft([squareSketch, circleSketch])
/// ```
///
/// ```
/// // Loft a square and a circle on the `-XZ` plane using offset.
/// squareSketch = startSketchOn(-XZ)
///     |> startProfile(at = [-100, 200])
///     |> line(end = [200, 0])
///     |> line(end = [0, -200])
///     |> line(end = [-200, 0])
///     |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
///     |> close()
///
/// circleSketch = startSketchOn(offsetPlane(-XZ, offset = 150))
///     |> circle(center = [0, 100], radius = 50)
///
/// loft([squareSketch, circleSketch])
/// ```
///
/// ```
/// // A circle on the XY plane
/// startSketchOn(XY)
///   |> startProfile(at = [0, 0])
///   |> circle( radius = 10, center = [0, 0] )
///
/// // Triangle on the plane 4 units above
/// startSketchOn(offsetPlane(XY, offset = 4))
///   |> startProfile(at = [0, 0])
///   |> line(end = [10, 0])
///   |> line(end = [0, 10])
///   |> close()
/// ```
@(impl = std_rust)
export fn offsetPlane(
  /// The plane (e.g. `XY`) which this new plane is created from.
  @plane: Plane,
  /// Distance from the standard plane this new plane will be created at.
  offset: number(Length),
): Plane {}