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>
This commit is contained in:
99
docs/kcl-lang/foreign-imports.md
Normal file
99
docs/kcl-lang/foreign-imports.md
Normal file
@ -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.
|
||||
|
@ -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)
|
||||
|
@ -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.
|
||||
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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)
|
||||
|
@ -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
|
||||
to sketch on.
|
||||
A plane has a position and orientation in space defined by its origin and axes. A plane is abstract
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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)
|
||||
|
@ -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
|
||||
/// to sketch on.
|
||||
/// A plane has a position and orientation in space defined by its origin and axes. A plane is abstract
|
||||
/// 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
|
||||
|
||||
|
@ -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
|
||||
}
|
||||
|
Reference in New Issue
Block a user