Beta Testing KCL 3.0

KCL 3.0 is a major improvement to the language that includes greatly improved fillets and the ability to define named views.

In addition to the new features, KCL 3.0 changes a few language rules and simplifies some standard library parameters. This page lists every change and shows how to update a program written in KCL 2.0. Each section has a "before" example that runs under KCL 2.0 and an "after" example that runs under KCL 3.0.

KCL 3.0 is available as a preview for testing. Behavior will change without notice before the final 3.0 release, including breaking changes that can make a model invalid or silently different. We do not recommend building real models with 3.0-preview. It's only intended to get a glimpse of new functionality.

To use it, declare the version as the string "3.0-preview", with the quotes, in the settings attribute at the top of the file you execute:

The version declared by the file you execute governs the whole program, including every file it imports. A program cannot run partly under KCL 2.0 and partly under KCL 3.0, so migrate a project as a unit.

Migration steps

1. Change kclVersion to "3.0-preview" in the file you execute and in every file it imports that declares a version. See All files must declare the same version.
2. Run the program and fix each error using the sections below. Most changes produce an error that points at the code to update.
3. Check the resulting geometry. Some changes alter a model without an error: fillet and chamfer run in order with other operations and follow tangent chains by default, and sweep no longer moves the profile to the path by default.

Summary of changes

return exits the function immediately

In KCL 2.0, return recorded the function's result, but execution continued to the end of the function body. Statements after the return still ran. In KCL 3.0, the first return that executes terminates the function. Statements after it do not run. A return inside an if branch returns from the enclosing function.

If a function has statements after a return that you rely on, move them before the return. Otherwise, delete them.

KCL 2.0:

KCL 3.0:

Variables declared in if branches stay in the branch

In KCL 2.0, a variable declared inside an if, else if, or else branch was visible after the if expression, and giving a branch variable the same name as an outer variable was an error. In KCL 3.0, each branch body has its own scope. A variable declared in a branch is visible from its declaration to the branch's closing brace and never outside it, and it may shadow a variable from an enclosing scope.

If code after an if uses a variable declared inside a branch, use the value of the if expression instead, or declare the variable before the if.

KCL 2.0:

KCL 3.0:

The object is evaluated before the index

In KCL 2.0, a member expression like a[b] evaluated the index b before the object a. In KCL 3.0, it evaluates a first, in source order. This only matters when both sides do something observable, such as calling functions that create geometry or report errors. The geometry is the same, but the operations run in a different order, which changes their order in the feature tree and which error is reported first when both sides fail.

KCL 2.0:

KCL 3.0:

fillet and chamfer run in order with other operations

In KCL 2.0, fillet and chamfer were deferred until certain other modeling commands or the end of the program. In KCL 3.0, they are sent to the engine immediately, in order with the other operations.

This has two consequences:

• Cutting an edge replaces it with a new face. Looking up an edge that a fillet or chamfer has already consumed, for example with getOppositeEdge or getNextAdjacentEdge, is an error. Look up the edges you need before the cut and store them in variables.
• Operations that follow a fillet or chamfer, such as a boolean or a sketch on one of its faces, now see the cut solid.

KCL 2.0:

KCL 3.0:

fillet and chamfer follow tangent chains

KCL 3.0 adds the tangentChain parameter to fillet and chamfer. When it is true, the cut also applies to edges that are tangent to the selected edges, so selecting one edge of a smooth loop, such as the top edge of a slot, cuts the whole loop. It defaults to true. KCL 2.0 cut only the edges you listed.

To keep the KCL 2.0 result, pass tangentChain = false.

KCL 2.0:

KCL 3.0:

sweep positions the profile with two flags

KCL 3.0 removes the relativeTo parameter of sweep. Use translateProfileToPath and orientProfilePerpendicular instead:

• translateProfileToPath moves the profile to the start of the path before sweeping. It defaults to false.
• orientProfilePerpendicular turns the profile so that it is perpendicular to the path before sweeping. In KCL 3.0, it defaults to the value of translateProfileToPath, so a profile that is moved to the path is also turned to face along it unless you say otherwise.

The default behavior changed as well. In KCL 2.0, a sweep with no positioning arguments turned the profile to face along the path. In KCL 3.0, a sweep with neither flag leaves the profile where it is, in its current orientation. When the profile is not already at the start of the path and perpendicular to it, this gives a different shape. To reproduce a KCL 2.0 sweep, remove relativeTo, pass translateProfileToPath = true, and check the result.

KCL 2.0:

KCL 3.0:

legacyMethod is removed

The legacyMethod parameter of fillet, chamfer, union, intersect, subtract, and split opted back into an older engine algorithm. It was deprecated in KCL 2.0 and is removed in KCL 3.0. Passing it is an error. Remove the argument.

KCL 2.0:

KCL 3.0:

patternLinear2d requires a region

In KCL 2.0, passing the sketch produced by a sketch block directly to patternLinear2d was deprecated with a warning. In KCL 3.0, it is an error. Select the profile to pattern with region and pass the region instead.

KCL 2.0:

KCL 3.0:

defaultAngleUnit is removed

The defaultAngleUnit setting was deprecated in KCL 2.0 and is removed in KCL 3.0. Declaring it is an error. Remove it from the settings attribute and write the unit on every angle, like 90deg or 1.57rad.

KCL 2.0:

KCL 3.0:

All files must declare the same version

In KCL 2.0, each file ran under the version it declared, so a program could mix files declaring 1.0 and 2.0. In KCL 3.0, the version declared by the file you execute governs the whole program. Every imported file that declares a kclVersion must declare the same version, and an imported file that declares no version uses the executed file's version. Declaring the version in every file is recommended, so that opening an imported file on its own does not run it under the default of 1.0.

The check works in both directions. A file that declares "3.0-preview" can only be imported by a file that declares "3.0-preview", so migrating only some files of a project is an error either way.

KCL 2.0:

KCL 3.0:

If you update main.kcl but not dimensions.kcl, executing main.kcl reports an error like this:

Recommended: replace deprecated sketch functions with sketch blocks

This step is not required, but strongly recommended. The pipeline-style sketch functions from KCL 1.0 have been deprecated since KCL 2.0. The functions such as startSketchOn, startProfile, and close, and the segment functions used in those pipelines, such as line, xLine, angledLine, arc, tangentialArc, circle, rectangle, and polygon, still work in KCL 3.0 and report a deprecation warning. The functions of the same name used inside a sketch block, such as line and arc, are not deprecated. While you are updating a file, consider rewriting these profiles as sketch blocks and selecting the profile to extrude with region so that you can take advantage of geometric sketch constraints.

KCL 1.0:

KCL 3.0: