Everything You Need to Know About Onshape FeatureScript

Adam shows you how to use FeatureScript for Onshape, and possibly also how to be Mr. Handy Pants around the house. But mostly FeatureScript.

Quick side note: SolidSmack has a lot of great sponsors, including several of the biggest CAD companies on earth. That’s awesome. One of those sponsors is Onshape.

This post, however, is not sponsored by anyone. This one’s all me.

As of a quiet rollout last night, FeatureScript is live.

FeatureScript is, in my opinion, the single most important feature of Onshape. It could very well be the killer app that brings Onshape into the mainstream. It’s a core piece of the Onshape architecture, and as of today it’s available to everyone.

(The follow-up tutorial mentioned in the video is available here.)

FeatureScript is a scripting language for writing features. (Awkward pause.) If the moniker sounds kinda like “Javascript” or “Actionscript,” that’s appropriate. It’s syntactically similar to Javascript, but it’s ultimately a proprietary language with a powerful built-in IDE, much like Actionscript worked within Flash. These attributes have the advantage of feeling familiar to coders, readable to normal humans, and–because it’s a purpose-built language–much more concise than a general-purpose language like JS or Python could ever be.

The features you write in FeatureScript appear in the Onshape UI just like any other feature, right alongside Extrude and Revolve and Sweep and Loft. The UI for your feature will look and work just like every other feature in Onshape. You can add your features to the toolbar and use them in all of your projects. You can even share your features with others so that they can ~~see how clever you are~~ take advantage of them.

One of the first tools I built in FeatureScript was a one-step tongue and groove feature. It’s designed so that one T&G feature can create grooves in as many boards as you like, and tongues on as many cross members as you need, all in one fell swoop. It also automatically centers the groove and sets the width to 1/3 the board width–but that can be customized, of course.

Things you can do with FeatureScript

The first thing most people will try to do in FeatureScript is essentially a macro-style list of existing Onshape features: run an extrude, then another extrude, then a fillet, then a boolean, then another boolean, etc.

For example, I like the SolidWorks “Cut With Surface” command, but Onshape doesn’t have it. I wrote my own in FeatureScript by implementing a split command, followed by a delete bodies command. Easy peasy.

Taking us one level deeper, every feature in Onshape was written using FeatureScript. That means that by definition, FeatureScript is capable of literally everything Onshape can do. If you’ve seen an Onshape feature do it, you can do it in FeatureScript.

So, for example, instead of using Onshape’s “extrude” command (the one you see in the Onshape UI), you can use the deeper opExtrude function, providing deeper, richer access to the internal workings of an extrude. Using this method I built an extrude command that can extrude multiple profiles at the same time, each normal to its own sketch plane (instead of all going the same direction, as in Onshape’s extrude). This is a trivial example, but there are many more.

I’ve written quite a few FeatureScripts at this point, and I’ve learned a lot in the process. Once you start building features to automate common tasks, you quickly find you want more and more of them. At this point I can do in ten features what used to take a hundred, and I’m only getting started.

Then you can do a lot of stuff that Onshape features can’t currently do, too. For example, there’s no 3D spline tool in Onshape, but FeatureScript gives us access to a spline that we can run through a selection of 3D points, essentially rolling our own 3D spline tool.

In experimenting with FeatureScript, I focused mainly on carpentry tools: lumber, plywood, dado cuts, mortise & tenon, tongue & groove, pegs, rabbets, and lap joints. I made custom features that can perform multiple joinery operations in a single feature, and one that can create an arbitrary number of standard boards around a perimeter.

The beauty of FeatureScript is that things don’t have to be linear: we can add conditional statements like “if distance x is further than 16 inches, add another joist”. You could dynamically generate staircases, railings, ribs, bosses, grilles, perf patterns, or even irregular structures like Voronoi patterns and generative architecture. The possibilities are really exciting.

This feature runs a series of standard boards around the perimeter of a sketch. The sketch can be any shape or size, and the ends can be extended so that they overlap enough to make room for joinery. In this case, one feature is generating 17 boards. Imagine using something like this to frame a house. You could build the basic framing for an entire floor in one feature, then have opening features to generate doors and windows, stairwell features, rafters, etc. What I’m showing here is simple, but the possibilities are huge.

Things you can’t do with FeatureScript

FeatureScript is fantastic, but there are a lot of things it will never be able to do.

First of all, despite having the word “Script” in the name, FeatureScript isn’t really a scripting system, at least not in the traditional desktop sense of the word. It is a script for the creation of features, which have a very limited and specific meaning in Onshape. Specifically, features exist within Part Studios, and help to define the geometry that is generated there.

For example, you cannot write a FeatureScript that creates a Part Studio or an Assembly. Features exist within Part Studios, so they certainly can’t create them. You can’t use FeatureScript to generate a drawing or a rendering. FeatureScript can’t email an administrator via email if Part 12345R6 changes, or run a cost analysis across an entire project. In short, FeatureScript is intended for creating geometric features within a Part Studio, and not much else.

As a proof of concept, this simple feature throws points and tangent planes at user-defined intervals across the U and V parameters of a surface. The reason the points are all bunched up on one side is that, just for fun, instead of a regular grid I’m using an exponential one (see line 28 of the code below, where I square the grid locations). In theory I could use this feature to drive other pattern-oriented features, gradually building up a Grasshopper-like generative modeling tool set.

This is the entirety of the code for the surface grid feature shown above, and it’s more complex than it needs to be. I hacked this together in just a few minutes as a curiosity. Imagine what we could do with a little more time and energy.

There are lots of esoteric programmy things it can’t do, too. For one thing, it can’t create new geometry types. For example, you couldn’t use FeatureScript to create a subdivision surface modeling tool, or to manually generate degree-739 NURBS surfaces. You can’t build a voxel system or interact with the GL meshes rendered on screen.

As with any cloud system, security is extremely important within Onshape. As such, FeatureScript can’t make calls to external web addresses of any kind. So you can’t, for example, have a feature that spells out your most recent tweet in block letters.

Also, as you probably know, Onshape allows multiple users to work on the same document simultaneously, so it’s very important that all feature results be purely deterministic. In other words, a feature should always have the same result with each and every rebuild. This might seem obvious, but there are some important limitations that come up when you realize this.

For one thing, FeatureScript has no date or time functions. If it did, you could make features that rebuild differently based on the day of the year or time of day. This might seem like a humbug, but remember: you might not be the only one seeing it. If you’re looking at an Onshape document with a user in Japan, whose day or time should it use? That’s a superficial problem, but there are deeper ones. Suffice it to say that date functions in FeatureScript would be problematic, so there aren’t any.

Similarly, FeatureScript cannot generate truly random numbers. If it could, each rebuild could result in wildly different things. Your collaborator in Japan would be seeing something entirely different than what you’re seeing, and neither would be “true” to the file. Export would be entirely unpredictable. Instead you can use psuedo-random numbers generated using a seed value. These are random enough for most users, but without the problem of being non-deterministic.

Can other CAD tools do this?

Sort of.

Most CAD systems have some sort of macro system for stringing together sequences of tool operations. Most also have some sort of scripting system for automating tasks, typically using a non-proprietary language like Python or–in the case of SolidWorks–Visual Basic (Adam projectile vomits across the office). Some even have GUI interfaces for storing or recording macros, known variously as Macros, Library Features, User Defined Features, or Power Copy, depending on your tool. Grasshopper lets you create logic-driven geometry using a nodal system that’s essentially a visual programming language. All decent options.

Most CAD tools also have some sort of API for developing richer plugins, usually in c++, but you’re going to put on your Big Kid Pants for those, as they’re typically written and maintained for use by professional developers, not your average user.

All of these options are great, but FeatureScript is a bit different. As with any walled-garden, it comes with both advantages and disadvantages. On the upside, FeatureScript lets you write first-class features in Onshape that look and feel just like the features that ship with the product, and do it with surprisingly little code. Downsides include learning (another) proprietary language, no system-wide automation, and very limited access to the deep inner-workings of the system.

All in all, having written many plugins for other apps over the years, FeatureScript is really exciting. For me, the benefits vastly outweigh the limitations.