More docs for Plane, Pi, etc. (#6850)

* Document the units of PI

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

* Add links between lang and std references

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

* Change signature of conversion functions

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

* Split foreign imports out of modules docs

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

* More docs for Plane

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

* Update docs/kcl-std/consts/std-math-PI.md

Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

* Update rust/kcl-lib/std/math.kcl

Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

---------

Signed-off-by: Nick Cameron <nrc@ncameron.org>
Co-authored-by: Jess Frazelle <jessfraz@users.noreply.github.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

docs/kcl-lang/foreign-imports.md

@@ -0,0 +1,99 @@
+---
+title: "Importing geometry from other CAD systems"
+excerpt: "Documentation of the KCL language for the Zoo Design Studio."
+layout: manual
+---
+
+`import` can also be used to import files from other CAD systems. The format of the statement is the
+same as for KCL files. You can only import the whole file, not items from it. E.g.,
+
+```norun
+import "tests/inputs/cube.obj"
+
+// Use `cube` just like a KCL object.
+```
+
+```kcl
+import "tests/inputs/cube.sldprt" as cube
+
+// Use `cube` just like a KCL object.
+```
+
+For formats lacking unit data (such as STL, OBJ, or PLY files), the default
+unit of measurement is millimeters. Alternatively you may specify the unit
+by using an attribute. Likewise, you can also specify a coordinate system. E.g.,
+
+```kcl
+@(lengthUnit = ft, coords = opengl)
+import "tests/inputs/cube.obj"
+```
+
+When importing a GLTF file, the bin file will be imported as well.
+
+Import paths are relative to the current project directory. Imports currently only work when
+using the native Design Studio, not in the browser.
+
+### Supported values
+
+File formats: `fbx`, `gltf`/`glb`, `obj`+, `ply`+, `sldprt`, `step`/`stp`, `stl`+. (Those marked with a
+'+' support customising the length unit and coordinate system).
+
+Length units: `mm` (the default), `cm`, `m`, `inch`, `ft`, `yd`.
+
+Coordinate systems:
+
+- `zoo` (the default), forward: -Y, up: +Z, handedness: right
+- `opengl`, forward: +Z, up: +Y, handedness: right
+- `vulkan`, forward: +Z, up: -Y, handedness: left
+
+---
+
+## Performance deep‑dive for foreign‑file imports
+
+Parallelized foreign‑file imports now let you overlap file reads, initialization,
+and rendering. To maximize throughput, you need to understand the three distinct
+stages—reading, initializing (background render start), and invocation (blocking)
+—and structure your code to defer blocking operations until the end.
+
+### Foreign import execution stages
+
+1. **Import (Read / Initialization) Stage**
+   ```kcl
+   import "tests/inputs/cube.step" as cube
+   ```
+   - Reads the file from disk and makes its API available.
+   - Starts engine rendering but **does not block** your script.
+   - This kick‑starts the render pipeline while you keep executing other code.
+
+2. **Invocation (Blocking) Stage**
+   ```kcl
+   import "tests/inputs/cube.step" as cube
+
+   cube
+     |> translate(z=10) // ← blocks here only
+   ```
+   - Any method call (e.g., `translate`, `scale`, `rotate`) waits for the background render to finish before applying transformations.
+
+### Best practices
+
+#### 1. Defer blocking calls
+
+```kcl
+import "tests/inputs/cube.step" as cube     // 1) Read / Background render starts
+
+
+// --- perform other operations and calculations here ---
+
+
+cube
+  |> translate(z=10)                        // 2) Blocks only here
+```
+
+#### 2. Split heavy work into separate modules
+
+Place computationally expensive or IO‑heavy work into its own module so it can render in parallel while `main.kcl` continues.
+
+#### Future improvements
+
+Upcoming releases will auto‑analyse dependencies and only block when truly necessary. Until then, explicit deferral will give you the best performance.
+

docs/kcl-lang/index.md

@@ -5,7 +5,7 @@ layout: manual
 ---
 
 This is a reference for KCL. If you are learning KCL, you may prefer the [guide]() which explains
-things in a more tutorial fashion.
+things in a more tutorial fashion. See also our documentation of the [standard library](/docs/kcl-std).
 
 ## Topics
 
@@ -14,7 +14,8 @@ things in a more tutorial fashion.
 * [Values and types](/docs/kcl-lang/types)
 * [Numeric types and units](/docs/kcl-lang/numeric)
 * [Functions](/docs/kcl-lang/functions)
-* [Projects, modules, and imports](/docs/kcl-lang/modules)
+* [Projects and modules](/docs/kcl-lang/modules)
 * [Attributes](/docs/kcl-lang/attributes)
+* [Importing geometry from other CAD systems](/docs/kcl-lang/foreign-imports)
 * [Settings](/docs/kcl-lang/settings)
 * [Known Issues](/docs/kcl-lang/known-issues)

docs/kcl-lang/modules.md

@@ -1,5 +1,5 @@
 ---
-title: "Modules"
+title: "Projects and modules"
 excerpt: "Documentation of the KCL language for the Zoo Design Studio."
 layout: manual
 ---
@@ -264,102 +264,3 @@ cube
 clone(cube)
   |> translate(x=20)
 ```
-
----
-
-## Importing files from other CAD systems
-
-`import` can also be used to import files from other CAD systems. The format of the statement is the
-same as for KCL files. You can only import the whole file, not items from it. E.g.,
-
-```norun
-import "tests/inputs/cube.obj"
-
-// Use `cube` just like a KCL object.
-```
-
-```kcl
-import "tests/inputs/cube.sldprt" as cube
-
-// Use `cube` just like a KCL object.
-```
-
-For formats lacking unit data (such as STL, OBJ, or PLY files), the default
-unit of measurement is millimeters. Alternatively you may specify the unit
-by using an attribute. Likewise, you can also specify a coordinate system. E.g.,
-
-```kcl
-@(lengthUnit = ft, coords = opengl)
-import "tests/inputs/cube.obj"
-```
-
-When importing a GLTF file, the bin file will be imported as well.
-
-Import paths are relative to the current project directory. Imports currently only work when
-using the native Design Studio, not in the browser.
-
-### Supported values
-
-File formats: `fbx`, `gltf`/`glb`, `obj`+, `ply`+, `sldprt`, `step`/`stp`, `stl`+. (Those marked with a
-'+' support customising the length unit and coordinate system).
-
-Length units: `mm` (the default), `cm`, `m`, `inch`, `ft`, `yd`.
-
-Coordinate systems:
-
-- `zoo` (the default), forward: -Y, up: +Z, handedness: right
-- `opengl`, forward: +Z, up: +Y, handedness: right
-- `vulkan`, forward: +Z, up: -Y, handedness: left
-
----
-
-## Performance deep‑dive for foreign‑file imports
-
-Parallelized foreign‑file imports now let you overlap file reads, initialization,
-and rendering. To maximize throughput, you need to understand the three distinct
-stages—reading, initializing (background render start), and invocation (blocking)
-—and structure your code to defer blocking operations until the end.
-
-### Foreign import execution stages
-
-1. **Import (Read / Initialization) Stage**
-   ```kcl
-   import "tests/inputs/cube.step" as cube
-   ```
-   - Reads the file from disk and makes its API available.
-   - Starts engine rendering but **does not block** your script.
-   - This kick‑starts the render pipeline while you keep executing other code.
-
-2. **Invocation (Blocking) Stage**
-   ```kcl
-   import "tests/inputs/cube.step" as cube
-
-   cube
-     |> translate(z=10) // ← blocks here only
-   ```
-   - Any method call (e.g., `translate`, `scale`, `rotate`) waits for the background render to finish before applying transformations.
-
-### Best practices
-
-#### 1. Defer blocking calls
-
-```kcl
-import "tests/inputs/cube.step" as cube     // 1) Read / Background render starts
-
-
-// --- perform other operations and calculations here ---
-
-
-cube
-  |> translate(z=10)                        // 2) Blocks only here
-```
-
-#### 2. Split heavy work into separate modules
-
-Place computationally expensive or IO‑heavy work into its own module so it can render in parallel while `main.kcl` continues.
-
-#### Future improvements
-
-Upcoming releases will auto‑analyse dependencies and only block when truly necessary. Until then, explicit deferral will give you the best performance.
-
-

docs/kcl-std/consts/std-math-PI.md

@@ -11,7 +11,13 @@ The value of `pi`, Archimedes’ constant (π).
 PI: number(_?) = 3.14159265358979323846264338327950288_?
 ```
 
-
+`PI` is a number and is technically a ratio, so you might expect it to have type `number(_)`.
+However, `PI` is nearly always used for converting between different units - usually degrees to or
+from radians. Therefore, `PI` is treated a bit specially by KCL and always has unknown units. This
+means that if you use `PI`, you will need to give KCL some extra information about the units of numbers.
+Usually you should use type ascription on the result of calculations, e.g., `(2 * PI): number(rad)`.
+You might prefer to use `units::toRadians` or `units::toDegrees` to convert between angles with
+different units.
 
 ### Examples
 

docs/kcl-std/functions/std-units-toCentimeters.md

@@ -8,7 +8,7 @@ layout: manual
 Convert a number to centimeters from its current units.
 
 ```kcl
-units::toCentimeters(@num: number(cm)): number(cm)
+units::toCentimeters(@num: number(Length)): number(cm)
 ```
 
 
@@ -17,7 +17,7 @@ units::toCentimeters(@num: number(cm)): number(cm)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(cm)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-units-toDegrees.md

@@ -8,7 +8,7 @@ layout: manual
 Converts a number to degrees from its current units.
 
 ```kcl
-units::toDegrees(@num: number(deg)): number(deg)
+units::toDegrees(@num: number(Angle)): number(deg)
 ```
 
 
@@ -17,7 +17,7 @@ units::toDegrees(@num: number(deg)): number(deg)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(deg)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-units-toFeet.md

@@ -8,7 +8,7 @@ layout: manual
 Convert a number to feet from its current units.
 
 ```kcl
-units::toFeet(@num: number(ft)): number(ft)
+units::toFeet(@num: number(Length)): number(ft)
 ```
 
 
@@ -17,7 +17,7 @@ units::toFeet(@num: number(ft)): number(ft)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(ft)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-units-toInches.md

@@ -8,7 +8,7 @@ layout: manual
 Convert a number to inches from its current units.
 
 ```kcl
-units::toInches(@num: number(in)): number(in)
+units::toInches(@num: number(Length)): number(in)
 ```
 
 
@@ -17,7 +17,7 @@ units::toInches(@num: number(in)): number(in)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(in)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-units-toMeters.md

@@ -8,7 +8,7 @@ layout: manual
 Convert a number to meters from its current units.
 
 ```kcl
-units::toMeters(@num: number(m)): number(m)
+units::toMeters(@num: number(Length)): number(m)
 ```
 
 
@@ -17,7 +17,7 @@ units::toMeters(@num: number(m)): number(m)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(m)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-units-toMillimeters.md

@@ -8,7 +8,7 @@ layout: manual
 Convert a number to millimeters from its current units.
 
 ```kcl
-units::toMillimeters(@num: number(mm)): number(mm)
+units::toMillimeters(@num: number(Length)): number(mm)
 ```
 
 
@@ -17,7 +17,7 @@ units::toMillimeters(@num: number(mm)): number(mm)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(mm)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-units-toRadians.md

@@ -8,7 +8,7 @@ layout: manual
 Converts a number to radians from its current units.
 
 ```kcl
-units::toRadians(@num: number(rad)): number(rad)
+units::toRadians(@num: number(Angle)): number(rad)
 ```
 
 
@@ -17,7 +17,7 @@ units::toRadians(@num: number(rad)): number(rad)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(rad)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-units-toYards.md

@@ -8,7 +8,7 @@ layout: manual
 Converts a number to yards from its current units.
 
 ```kcl
-units::toYards(@num: number(yd)): number(yd)
+units::toYards(@num: number(Length)): number(yd)
 ```
 
 
@@ -17,7 +17,7 @@ units::toYards(@num: number(yd)): number(yd)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number(yd)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
+| `num` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes |
 
 ### Returns
 

docs/kcl-std/modules/std.md

@@ -11,6 +11,8 @@ Contains frequently used constants, functions for interacting with the KittyCAD
 
 The standard library is organised into modules (listed below), but most things are always available in KCL programs. 
 
+You might also want the [KCL language reference](/docs/kcl-lang) or the [KCL guide](). 
+
 ## Modules
 
 * [`array`](/docs/kcl-std/modules/std-array)

docs/kcl-std/types/std-types-Plane.md

@@ -7,8 +7,25 @@ layout: manual
 
 An abstract plane.
 
-A plane has a position and orientation in space defined by its origin and axes. A plane can be used
+A plane has a position and orientation in space defined by its origin and axes. A plane is abstract
-to sketch on.
+in the sense that it is not part of the objects being drawn. A plane can be used to sketch on.
+
+A plane can be created in several ways:
+- you can use one of the default planes, e.g., `XY`.
+- you can use `offsetPlane` to create a new plane offset from an existing one, e.g., `offsetPlane(XY, offset = 150)`.
+- you can use negation to create a plane from an existing one which is identical but has an opposite normal
+e.g., `-XY`.
+- you can define an entirely custom plane, e.g.,
+
+```js
+myXY = {
+  origin = { x = 0, y = 0, z = 0 },
+  xAxis = { x = 1, y = 0, z = 0 },
+  yAxis = { x = 0, y = 1, z = 0 },
+}
+```
+
+Any object with appropriate `origin`, `xAxis`, and `yAxis` fields can be used as a plane.
 
 
 

rust/kcl-lib/std/math.kcl

@@ -7,6 +7,14 @@ import Point2d from "std::types"
 
 /// The value of `pi`, Archimedes’ constant (π).
 ///
+/// `PI` is a number and is technically a ratio, so you might expect it to have type `number(_)`.
+/// However, `PI` is nearly always used for converting between different units - usually degrees to or
+/// from radians. Therefore, `PI` is treated a bit specially by KCL and always has unknown units. This
+/// means that if you use `PI`, you will need to give KCL some extra information about the units of numbers.
+/// Usually you should use type ascription on the result of calculations, e.g., `(2 * PI): number(rad)`.
+/// You might prefer to use `units::toRadians` or `units::toDegrees` to convert between angles with
+/// different units.
+///
 /// ```
 /// circumference = 70
 ///

rust/kcl-lib/std/prelude.kcl

@@ -5,6 +5,8 @@
 ///
 /// The standard library is organised into modules (listed below), but most things are always available
 /// in KCL programs.
+///
+/// You might also want the [KCL language reference](/docs/kcl-lang) or the [KCL guide]().
 
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)

rust/kcl-lib/std/types.kcl

@@ -165,8 +165,25 @@ export type tag
 
 /// An abstract plane.
 ///
-/// A plane has a position and orientation in space defined by its origin and axes. A plane can be used
+/// A plane has a position and orientation in space defined by its origin and axes. A plane is abstract
-/// to sketch on.
+/// in the sense that it is not part of the objects being drawn. A plane can be used to sketch on.
+///
+/// A plane can be created in several ways:
+/// - you can use one of the default planes, e.g., `XY`.
+/// - you can use `offsetPlane` to create a new plane offset from an existing one, e.g., `offsetPlane(XY, offset = 150)`.
+/// - you can use negation to create a plane from an existing one which is identical but has an opposite normal
+/// e.g., `-XY`.
+/// - you can define an entirely custom plane, e.g.,
+///
+/// ```kcl,inline,norun
+/// myXY = {
+///   origin = { x = 0, y = 0, z = 0 },
+///   xAxis = { x = 1, y = 0, z = 0 },
+///   yAxis = { x = 0, y = 1, z = 0 },
+/// }
+/// ```
+///
+/// Any object with appropriate `origin`, `xAxis`, and `yAxis` fields can be used as a plane.
 @(impl = std_rust)
 export type Plane
 

rust/kcl-lib/std/units.kcl

@@ -11,32 +11,32 @@
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 
 /// Convert a number to millimeters from its current units.
-export fn toMillimeters(@num: number(mm)): number(mm) {
+export fn toMillimeters(@num: number(Length)): number(mm) {
   return num
 }
 
 /// Convert a number to centimeters from its current units.
-export fn toCentimeters(@num: number(cm)): number(cm) {
+export fn toCentimeters(@num: number(Length)): number(cm) {
   return num
 }
 
 /// Convert a number to meters from its current units.
-export fn toMeters(@num: number(m)): number(m) {
+export fn toMeters(@num: number(Length)): number(m) {
   return num
 }
 
 /// Convert a number to inches from its current units.
-export fn toInches(@num: number(in)): number(in) {
+export fn toInches(@num: number(Length)): number(in) {
   return num
 }
 
 /// Convert a number to feet from its current units.
-export fn toFeet(@num: number(ft)): number(ft) {
+export fn toFeet(@num: number(Length)): number(ft) {
   return num
 }
 
 /// Converts a number to yards from its current units.
-export fn toYards(@num: number(yd)): number(yd) {
+export fn toYards(@num: number(Length)): number(yd) {
   return num
 }
 
@@ -54,7 +54,7 @@ export fn toYards(@num: number(yd)): number(yd) {
 ///
 /// example = extrude(exampleSketch, length = 5)
 /// ```
-export fn toRadians(@num: number(rad)): number(rad) {
+export fn toRadians(@num: number(Angle)): number(rad) {
   return num
 }
 
@@ -72,6 +72,6 @@ export fn toRadians(@num: number(rad)): number(rad) {
 ///
 /// example = extrude(exampleSketch, length = 5)
 /// ```
-export fn toDegrees(@num: number(deg)): number(deg) {
+export fn toDegrees(@num: number(Angle)): number(deg) {
   return num
 }