From c9f332efec9ad385b487b6ad4ffe491154766103 Mon Sep 17 00:00:00 2001 From: Ryan Barton Date: Tue, 18 Aug 2026 12:40:47 -0400 Subject: [PATCH] Correct what imported geometry can and cannot do The Import page told users imported geometry "Can be used as boolean tools (subtract imported geometry from KCL-created solids)" and "Can serve as extrusion targets". Neither is true. An import has type `ImportedGeometry` and every boolean is typed `[Solid]`, so both argument positions fail: subtract([cube], tools = [t]) -> requires one or more `Solid`s, but found an array of `ImportedGeometry` subtract([base], tools = [cube]) -> tools requires an array of `Solid`s `startSketchOn` rejects it too, so "extrude to face" is out as well. This was verified against kcl-lib 0.2.177 for fillet, shell, patterns, and sketch-on-face, and it holds for mesh and BREP files alike. The child STEP page already said all of this correctly, so the accurate bullets move up to the parent as a format-agnostic "Editing imported geometry" section and the STEP page links to them, which stops the two pages contradicting each other again. Also on the Import page: - Adds STL, OBJ, PLY, and SLDPRT, which the product accepts and kcl-lang/foreign-imports documents, but this page never listed. - Fixes `import bracket from "./parts/bracket.stp"`. Foreign files import whole, so the form is `import "parts/bracket.stp" as bracket`. - Corrects Unit Handling, which claimed Zoo interprets STEP unit metadata. The STEP page says the opposite, and the STEP page is right. Adds a "What Zookeeper Can't Do Yet" section to the Zookeeper page, leading with imported CAD files, so there is somewhere to point a user who asks the agent for an edit it cannot make. Refs KittyCAD/text-to-cad#3969 Co-Authored-By: Claude Opus 5 (1M context) --- .../features/data-management/import.mdx | 134 ++++++++++++++---- .../features/data-management/import/step.mdx | 16 +-- .../docs/zoo-design-studio/zookeeper.mdx | 27 ++++ 3 files changed, 141 insertions(+), 36 deletions(-) diff --git a/content/pages/docs/zoo-design-studio/features/data-management/import.mdx b/content/pages/docs/zoo-design-studio/features/data-management/import.mdx index 3930630a..7125b978 100644 --- a/content/pages/docs/zoo-design-studio/features/data-management/import.mdx +++ b/content/pages/docs/zoo-design-studio/features/data-management/import.mdx @@ -22,6 +22,26 @@ Zoo Design Studio supports the following file formats for import into projects: - For STEP-specific syntax, export settings, and troubleshooting, see [STEP Import](/docs/zoo-design-studio/features/data-management/import/step) +**SolidWorks part (.sldprt)** +- Native SolidWorks single-part format +- Useful when a supplier ships the original part rather than a neutral export + +### Mesh Formats + +**STL (.stl)** +- Triangle mesh, the standard interchange format for 3D printing +- Carries no unit metadata; defaults to millimeters, overridable with the + `lengthUnit` import attribute +- Holds no BREP surfaces, so it is best used as a shape reference + +**OBJ (.obj)** +- Wavefront mesh format, widely supported across 3D tooling +- Supports the `lengthUnit` and `coords` import attributes + +**PLY (.ply)** +- Polygon mesh format, common for scanned geometry +- Supports the `lengthUnit` and `coords` import attributes + ### 3D Model Formats **glTF/GLB (.glb)** @@ -85,41 +105,84 @@ Supported URL formats: Reference existing project files from within KCL code: ```kcl -// Import STEP file -import bracket from "./parts/bracket.stp" +// Import a STEP file. Foreign files import whole, so alias with `as` +// rather than naming items inside them. +import "parts/bracket.stp" as bracket -// Import other KCL file -import utils from "./library/utils.kcl" +// Import items from another KCL file +import utils from "library/utils.kcl" -// Import GLB visualization -import reference from "./reference/concept.glb" +// Import a GLB for visual reference +import "reference/concept.glb" as reference ``` +Paths are relative to the project directory. See +[Importing geometry from other CAD systems](/docs/kcl-lang/foreign-imports) for the full format +list, length-unit and coordinate-system attributes, and performance notes. + The `Insert` command (available via Command Bar) provides a UI workflow for the same functionality: 1. Select file from project directory 2. Specify local variable name for the imported geometry 3. KCL import statement is automatically generated -## Imported Geometry Behavior +## Editing imported geometry + +Imported CAD files are references, not editable models. Zoo Design Studio can place, inspect, and +measure them, but it cannot change their geometry. This applies to every non-native format — +STEP, STL, OBJ, PLY, glTF/GLB, FBX, and SLDPRT — whether the file holds precise BREP surfaces or a +triangle mesh. + +Imported geometry: + +- appears as external CAD geometry in the Scene +- can be inspected, measured, and used as a visual reference while you build native KCL geometry +- can be transformed and styled with [`clone`](/docs/kcl-std/functions/std-clone), + [`translate`](/docs/kcl-std/functions/std-transform-translate), + [`rotate`](/docs/kcl-std/functions/std-transform-rotate), + [`scale`](/docs/kcl-std/functions/std-transform-scale), and + [`appearance`](/docs/kcl-std/functions/std-solid-appearance) +- **cannot be edited directly after import**; change it in the source CAD system and reimport the + file, or recreate the geometry natively in KCL +- **cannot be used for boolean operations** (`subtract`, `union`, `intersect`), sketch-on-face, + fillet, chamfer, shell, or patterns + +The reason is the KCL type system. An imported file has type +[`ImportedGeometry`](/docs/kcl-std/types/std-types-ImportedGeometry), while every modeling function +listed above is typed to take a [`Solid`](/docs/kcl-std/types/std-types-Solid). There is no +conversion between the two, so handing an import to `subtract` fails before anything is modeled: + +``` +The input argument of `subtract` requires one or more `Solid`s (`[Solid; 1+]`), +but found an array of `ImportedGeometry` +``` + +This is a current limitation of the geometry engine rather than a property of your file, and it is +tracked in [Known Issues](/docs/kcl-lang/known-issues). + +### If you need to change imported geometry + +Two workflows are supported: + +1. **Recreate it natively in KCL.** Keep the import visible as a reference, rebuild the shape with + native features, then hide or remove the import. The result is fully parametric and can be + filleted, shelled, and booleaned like any other KCL solid. +2. **Model a new part around it.** Leave the import untouched and build a separate part that mates + to it, positioning the new geometry with `translate` and `rotate`. + +[Zookeeper](/docs/zoo-design-studio/zookeeper) works under the same constraint. It can measure an +imported file and recreate it as native KCL, but it cannot cut, fillet, or boolean the import +itself. -### Non-Native Formats (STEP, GLB, FBX) +### Imported KCL files -Imported CAD geometry from external formats: -- Appears as reference geometry in the Scene -- Can be measured, visualized, and used as construction references -- Can be **used as boolean tools** (subtract imported geometry from KCL-created solids) -- Can serve as **extrusion targets** ("extrude to face" with imported surfaces) -- Geometry is **not directly editable** (no feature history) -- To edit parametrically, manually recreate using KCL/native tools +Native `.kcl` imports are not subject to any of the above. They are: -### Native KCL Format +- fully parametric and editable +- preserved with their feature tree +- adjustable by changing parameters +- editable directly in the Code Editor +- reusable, including their functions and variables -Imported KCL files: -- Fully parametric and editable -- Feature tree is preserved -- Parameters can be modified -- Code can be directly edited in Code Editor -- Functions and variables can be reused ## Import Workflow Best Practices @@ -148,10 +211,24 @@ When importing files into version-controlled projects: ### Unit Handling -STEP files include unit metadata: -- Zoo automatically interprets STEP file units -- If units are ambiguous, verify scale after import -- Use `Scale` transform if unit conversion is needed +Zoo Design Studio does not rescale imported geometry from a file's unit metadata. STEP numeric +values are interpreted in the current KCL file or scene unit, so a part authored as 50 mm measures +50 in when the file unit is inches. Verify scale after import and correct it with `scale` if +needed — for example, `scale(x = 1/25.4, y = 1/25.4, z = 1/25.4)` for a millimeter part in an +inch scene. + +Formats that carry no unit metadata at all (STL, OBJ, PLY) default to millimeters and accept an +explicit override: + +```kcl +@(lengthUnit = inch) +import "scan.stl" as scan +``` + +See [STEP Import](/docs/zoo-design-studio/features/data-management/import/step) for STEP-specific +scale behavior and +[Importing geometry from other CAD systems](/docs/kcl-lang/foreign-imports) for the full list of +supported length units and coordinate systems. ### Performance Considerations @@ -171,3 +248,8 @@ Large imported files affect performance: | Animation pipeline | FBX (.fbxb) | Supports complex scenes and animations | | Supplier-provided models | STEP (.stp) | Most common neutral format from vendors | | Internal library components | KCL (.kcl) | Maintains parameter definitions and editability | +| 3D-print or scan reference | STL (.stl) | Mesh-only, but the common output of slicers and scanners | + +Any non-native format in this table imports as reference geometry. See +[Editing imported geometry](#editing-imported-geometry) for what can and cannot be done with +it afterwards. diff --git a/content/pages/docs/zoo-design-studio/features/data-management/import/step.mdx b/content/pages/docs/zoo-design-studio/features/data-management/import/step.mdx index 6626879e..d83194a0 100644 --- a/content/pages/docs/zoo-design-studio/features/data-management/import/step.mdx +++ b/content/pages/docs/zoo-design-studio/features/data-management/import/step.mdx @@ -106,15 +106,10 @@ browser. It does not support importing 2D drawings from STEP files. In the brows into Project Files; the `Add file to project` Local Drive picker is available only in the desktop app. -Imported STEP geometry: - -- appears as external CAD geometry in the scene -- can be inspected, measured, translated, rotated, scaled, styled, and cloned -- can be used as a visual reference while building native KCL geometry -- cannot be edited directly after import; make changes in the source CAD system and reimport the file, - or recreate the geometry natively in KCL -- cannot be used for boolean operations, sketch-on-face, or other modeling operations that require - interaction with other scene geometry +Imported STEP geometry behaves like every other non-native import: it can be inspected, measured, +transformed, styled, and cloned, but it cannot be edited, booleaned, or sketched on. See +[Editing imported geometry](/docs/zoo-design-studio/features/data-management/import#editing-imported-geometry) +for the full list of what is and is not supported, and for the two ways to work around it. +## What Zookeeper Can't Do Yet + +Zookeeper models in KCL, so it inherits KCL's and the geometry engine's current limits. The most +common surprise: + +**It cannot modify imported CAD files.** A STEP, STL, OBJ, PLY, glTF/GLB, FBX, or SLDPRT file you +add to a project is reference geometry. Zookeeper can render it, measure it, position it, and +recreate it as native KCL, but it cannot cut into it, fillet it, or boolean it — those operations +require a KCL `Solid`, and an imported file is `ImportedGeometry`. There is no conversion between +the two, for mesh and BREP files alike. + +If you want a change to an imported part, ask for one of these instead: + +- *"Recreate this part in KCL, then add a 10 mm slot."* Zookeeper rebuilds the shape natively, + which makes every feature editable afterwards. +- *"Model a bracket that bolts onto this imported flange."* The import stays untouched as a + reference and Zookeeper builds a separate part around it. + +See [Editing imported geometry](/docs/zoo-design-studio/features/data-management/import#editing-imported-geometry) +for the full picture. + +Two smaller limits worth knowing: + +- Zookeeper responds in text and cannot drive the Zoo Design Studio UI for you. +- KCL has no dedicated tooling for modeled text, so lettering and engraving requests need a CAD + workaround rather than a text feature. + ## What's Coming Next The agent described above is only the beginning. An upcoming capability will extend both its reach and its usefulness.