Add Surface
add_surfaceUse this when you need an organic, freeform, or swept shape — a body shell, panel, fairing, ergonomic curve, lens, or sculpted form — authored as a NURBS Surface into the user's .kcad.ts, OR when you need to finish surfaces into a watertight solid or taper faces for moldability. One authoring/finishing path, selected by kind:
'nurbs' — insert a nurbsSurface(...) / surfaceFromCurves(...) call. Pass either { controls, degree, weights?, knots?, periodic? } for direct construction, OR { section_sketch_ids } for skinning. Weights are honored: supply rational weights to build exact circles/cylinders/spheres/conics (the surface becomes rational); omit weights for a non-rational surface.
'boundary' — insert a surfaceFromBoundary([c1,c2,c3,c4], opts?) call: one NURBS face through 4 boundary Curve3D refs (bottom, right, top, left in loop order; adjacent endpoints must coincide within 1e-6 mm).
'trim' — insert a
<surface>.trimTo(<by>)or<surface>.split(<by>)call. Passsurface_binding(the Surface variable name),by_binding(the cutter Surface variable name; Shape/Curve3D cutters are deferred to a later slice), andop: 'trim'(keep the largest imprinted piece) orop: 'split'(return both halves as a[Surface, Surface]tuple).'sew' — insert a
sew([s0, s1, ...], opts?)call to stitch N surfaces into a closed watertight solid. Passsurface_bindings(array of Surface variable names). Use after trim/boundary to close patches into a solid: trim → sew → solid pipeline. Optionaltolerance(mm, default 1e-6) andrequire_closed(emits feature.surface-sew.open-shell if result is not watertight).'draft' — insert a
<shape>.draft(angleDeg, { face, neutralPlane?, pullDir? })call to taper the selected face(s) for mold release. Passshape_binding,angle_deg(0–90), andface(canonical name, label, or FaceQuery descriptor). Lowering emits feature.draft.failed on invalid geometry. The returned Surface produces no Shape until you chain .thicken(t) or .toShape() (do that via add_feature on the binding name). Returns the modified code + diagnostics. Each kind fails closed on its own missing required params.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | No | kind:'trim' — 'trim' discards the smaller half (calls .trimTo()); 'split' retains both halves (calls .split()). | |
| code | Yes | Current .kcad.ts source. | |
| face | No | kind:'draft' — face selector for the face(s) to taper. Accepts a canonical name (top/bottom/front/back/left/right), a user label declared via faceLabels, or a FaceQuery descriptor string. | |
| kind | Yes | Which surface-construction or surface-finishing path to use: 'nurbs' | 'boundary' | 'trim' | 'sew' | 'draft'. | |
| knots | No | kind:'nurbs' — optional explicit knot vectors; missing => clamped uniform inferred. | |
| degree | No | kind:'nurbs' — degrees in U and V; each in [1, nU-1] / [1, nV-1]. | |
| weights | No | kind:'nurbs' — optional rational weights, same grid shape as controls. Ignored in slice-1. | |
| controls | No | kind:'nurbs' — control-point grid for direct construction (controls[u][v] = [x, y, z], mm). | |
| periodic | No | kind:'nurbs' — optional periodic flags per parametric direction. | |
| pull_dir | No | kind:'draft' — demoulding direction as [x, y, z]. Defaults to the face normal at lower time. | |
| sampling | No | kind:'boundary' — points sampled along each boundary (default 15). | |
| angle_deg | No | kind:'draft' — draft angle in degrees [0, 90]. The face is tapered outward by this angle relative to the pull direction. | |
| tolerance | No | kind:'sew' — edge-merging tolerance in mm (default 1e-6). Edges within this distance are merged. | |
| by_binding | No | kind:'trim' — JS variable name of the cutter Surface (must be declared in source). Shape/Curve3D cutters are deferred. | |
| continuity | No | kind:'boundary' — continuity grade applied to every edge ('C0' | 'C1' | 'C2'), or an array of 4 grades (one per edge, bottom/right/top/left order). Default 'C0'. | |
| binding_name | No | JS const name for the new binding (kind:'nurbs' default surface_<N>; kind:'boundary' default _surface_<N>; kind:'trim' default _trimmed_<N>; kind:'sew' default _sewn_<N>; kind:'draft' default _drafted_<N>). | |
| neutral_plane | No | kind:'draft' — parting-line face (the plane where drafted faces remain fixed). Defaults to `face` if omitted. | |
| shape_binding | No | kind:'draft' — JS variable name of the Shape to taper (must be declared in source). | |
| curve_bindings | No | kind:'boundary' — tuple of 4 existing Curve3D variable names (bottom, right, top, left) declared earlier in the source. | |
| require_closed | No | kind:'sew' — when true the lowerer emits feature.surface-sew.open-shell if the stitched result is not a watertight solid. | |
| surface_binding | No | kind:'trim' — JS variable name of the Surface to trim/split (must be declared in source). | |
| surface_bindings | No | kind:'sew' — JS variable names of the surfaces to stitch into a solid (each must be declared in source). | |
| section_sketch_ids | No | kind:'nurbs' — existing sketch FeatureIds (2 or more) to skin a surface through, in order. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||