This is the fourth part in the series where we explore the possibility of creating a default assembly workbench for FreeCAD. We started out with a conversation about why we need a default assembly workbench in the program, then reviewed Assembly 2 and A2plus. Now let’s talk about the Assembly 3 workbench.

History​

In 2013, Jonathan Westhues took the FOSS community by surprise releasing the source code of SolveSpace, his parametric 2D/3D CAD software built around a very capable custom solver. Some 4 years later, Zheng Lei aka “realthunder” created a Python binding for the solver, then used it to create his own assembly workbench for FreeCAD.

Further changes in the workbench required patching FreeCAD, so realthunder created a friendly fork of the entire program, which over time became his primary project with many other changes and add-ons not available in upstream FreeCAD by default: the pie menu, transparent docks, and others.

Some of the architectural changes have already been merged to upstream FreeCAD, others are getting there. The Assembly 3 workbench continues to be maintained and is available to users of upstream FreeCAD as an addon and is now part of this larger project, the ‘LinkStage’ fork.

Workflow and ease of use​

Assembly 3 is substantially different from other assembly workbenches in multiple aspects. Here are some of its most significant characteristics.

Project hierarchy. In A3, an assembly consists of constraints, elements, and parts. Elements are the features of parts that are used to create a constraint, e.g. a point of one part and a plane of another part. Assemblies can contain sub-assemblies, in which case each sub-assembly will carry its own set of constraints, elements, and parts. This approach makes navigating a complex project fairly straightforward.

Graber I3 model by Nemesis81

Top-down design model. This approach is technically available in A2 and A2plus, but it is not a recommended way of using those workbenches. Assembly 3 makes the top-down design model a first-class citizen. You can create new parts, then drag them into the Parts section of the project tree, then they will become usable in the assembly.

Bottom-up design model. This is likely how most A3 users approach creating assemblies. The workbench provides two ways to build an assembly from parts saved as external files: importing from STEP files or linking (see below) FreeCAD projects that are already opened in the program.

Links. A3 is not the only assembly workbench to rely on the App::Link API to reference objects instead of copying them, Assembly 4 also does it. But A3 is what this API was designed for in the first place. The general idea is that if you have e.g. 4 screws of the same type to fix a motherboard to a plastic box, you don’t need 4 instances of the same screw geometry. You only need one part that you can reuse via links.

Creating a link, however, is all not at all obvious and requires performing a particular sequence of actions: selecting a part (Body object) in the project tree, then selecting an assembly document in the document tabs, then clicking a Link button in the toolbar. Figuring this out without reading documentation or watching a tutorial or asking on the forum is all but impossible.

Fixing parts and freezing sub-assemblies. While fixing a part in A2plus is a property of a part, the A3 approach is to select a feature and assign a “Locked” constraint to it to eliminate all or some degrees of freedom (this depends on the type of the selected feature). The idea of locking something entirely goes even further. When working on a complex assembly, a particularly useful way to simplify computations is to freeze a sub-assembly. Such a sub-assembly is considered fixed by the solver and is therefore excluded from update calculations.

Features​

Assembly 3 is the most feature-packed of all existing assembly WBs. It comes with over 40 constraint types, various helper tools, means to control workplanes, and more. It also has a dynamic solver, so you can move parts under constraints.

The workbench does its best to keep track of degrees of freedom to avoid overconstraining an assembly. However, in doing so, it doesn’t make it easy to indicate where the problem is exactly. All it does is notifying the user that there are inconsistent constraints. It is up to the user to locate the offensive elements and constraints.

There are more caveats. In particular, the vast amount of features in this workbench raises the expectations for UX/UI. Assembly 3 has an overwhelming UI. It comes with no less than six toolbars, three out of which are different groups of constraints.

There’s the main constraints group and two additional groups of constraints. This takes a lot of getting used to. We’ve seen experienced users of the workbench making really useful elaborate tutorials about it and yet failing to locate the constraint they need on the first attempt.

Things don’t get much better with the ModernUI add-on that creates a Ribbon-like top toolbar. You get readable labels (something the late Jef Raskin would appreciate), but you also get a large scrollable area:

Graber I3 model by Nemesis81

Assembly 3 is not uniquely complex here. Arch, FEM, TechDraw, and a few other workbenches also have a similar or even larger amount of UI to deal with. This suggests that there may be a need for a general UX/UI review and a better strategy for organizing the user interface and designing the interaction — something that would be solved on the core level and then propagated to all workbenches, default and 3rd-party alike.

Three sorely missing features are collision detection, visual control over degrees of freedom, and the generation of BOM. Collision detection was planned back in 2018, the idea was to use the Bullet physics engine, but this hasn’t materialized yet. Regarding DOF control, it is virtually impossible to find out how many degrees of freedom a part has without trial-and-error by attempting to transform it and — sometimes — looking at the output log in the built-in console (A2plus solves that by optionally displaying an indicator for each part in the viewport). And as for BOM, realthunder already explored in detail the requirements for developing BOM generation two years ago, but there is no code yet.

The wiki page for the assembly at FreeCAD’s website provides some basic documentation on features, and the project’s own wiki explores basic concepts of A3 and provides several tutorials. However, neither can serve as a reference guide, hence finding out what some of the features do will require original research by users. Notably, there’s a lot of YouTube tutorials on using Assembly 3. Some of the most prolific A3 educators are Oficine Robotica and Joko Engineeringhelp.

Consistency​

The workbench is generally consistent with how the rest of FreeCAD operates. In our testing, nothing stands out as particularly peculiar. A3 will also use parts created with other workbenches as long as the imported parts are moved into the Parts section of the assembly’s hierarchy.

Graber I3 model by Nemesis81

Stability​

Assembly 3 currently has over 300 unresolved bugs and feature requests filed to its issue tracker. However, this cannot be used as a sole indicator of the maintainer’s responsiveness: for some reason, it’s fairly common for users to report bugs associated with FreeCAD itself rather than with the workbench in question. Given that the ‘Linkstage’ fork of FreeCAD also has over 300 unresolved bug reports and feature requests, this is obviously too much for one person to handle, even though he gets some help with triaging reports.

None of the currently open bug reports are crash reports for the Assembly 3 workbench. Having said that, we did experience a few random crashes when working with the WB. We also looked at workbench crashes reported in the past and found that realthunder pays a lot of attention to that and typically fixes those within several days.

Performance​

While it’s possible to exclude sub-assemblies from computation by freezing them and thus saving the resources for when they are needed, this will not be sufficient in all use cases. With complex assemblies (over a hundred parts), A3 can become really slow.

Moreover, even in simple use cases (two parts, two constraints), Assembly 3 will often fail to perform an axial rotation smoothly with 1 DOF left, while the rotation increment is as small as 1°.

Development Status​

Although there have been contributions from at least a dozen more people, realthunder remains the author of 92% of all commits to the workbench since project’s inception. The project is maintained, however its active development phase ended in 2019. The last workbench release was tagged in 2020 and the latest internal version is 0.11.4 from November 2022. We also found that the development remains uncoupled from the upstream SolveSpace project: multiple changes and new features related to constraints appear to have never made its way to the workbench.

Legal Status​

Because Assembly 3 relies on a fork of SolveSpace’s source code, it’s available under the terms of GPLv3+. This makes its inclusion in the FreeCAD application problematic. Thus the workbench can only be installed separately in upstream FreeCAD as an addon.

Summary​

Assembly 3 is substantially more advanced than either A2 or A2plus workbenches: generally better workflow, better support for bottom-up design, better-designed project hierarchy, vastly more constraint options, and the list goes on. The project also has an avid user community and the developer is typically fast to respond to reports of severe bugs.

At the same time, A3 has a number of usability issues and important missing features such as BOM generation. The solver’s license also makes this workbench an unlikely choice for a foundation of a potential default workbench in FreeCAD.

Next up​

Now that we’ve explored Assembly 3, we are getting closer to the end of the series. In the next installment, we’ll take a close look at the Assembly 4 workbench developed by Zolko.

We’ve already talked about the need for a default assembly workbench in FreeCAD and reviewed Assembly 2. Now let’s get into the nitty-gritty of the A2plus workbench.

History​

A FreeCAD user kbwbe started working on this project in 2018 following experiments with a new solver developed on top of the pre-existing Assembly 2 workbench:

I developed a small prototype of yet another solver. It is in a very early state now and is only capable of handling plane/circularedge/axis-constraints. But it can easily be extended. It consists only of one file, which is attached. The base concept is inspired by physics. [...] It is just a prototype and many things are still missing. But the idea seems to work. I am working with a refurbished assembly2-workbench. I like the base concepts of it very much and did some bigger projects with it.

Having received initial feedback, kbwbe created a public repository on GitHub and continued hacking on the new workbench publicly.

Despite an activity plunge during the pandemic, A2plus is still being actively developed and receives new features and bug fixes.

Workflow and ease of use​

A2plus follows the same general idea as its predecessor: create parts as separate files, align them with constraints, solve. Just like Assembly 2, this workbench supports sub-assemblies. There are some differences though. The one that stands out immediately is that, rather than creating one constraint object in the project tree, A2plus creates references to the same constraint in both involved parts.

Another difference is that a part in A2plus is a special type of an object. So it’s possible to create a new part from within the workbench and fill it with objects e.g. in the Part Design workbench. But the part will have to be manually converted to an A2plus part to become usable in the workbench. The caveat here is that even then such a part will not be added to the BOM: only the parts imported from external files will be displayed there. Overall, the top-down design approach is not favored by A2plus, as earlier noted by kbwbe in the FreeCAD forum:

Leaving PartDesign bodies within the assembly is not the intended workflow. Best way is to import everything. Converting is also not the preferred way. Even all parametrics of the parts get lost.

Unlike Assembly 2, the A2plus workbench can also load user-selected objects from another FreeCAD project. In this case, the workbench will reference the object from the file, so FreeCAD will pick any changes made to the original project when you click the Update button.

In terms of general user experience, A2plus is a major improvement over Assembly 2. Here are some examples of user-visible changes:

• When features (points, planes etc.) of multiple parts are selected, the workbench automatically makes available only the constraints that can be used with these features. This removes a lot of guesswork for new users.
• Imported parts can easily be opened for editing as separate documents. All edited parts then can be updated with a single click.
• When cleaning up an assembly, it’s possible to easily delete all constraints associated with a part.

Features​

The workbench has a respectable set of constraints: Point-to-Point, Point-on-Line, Point-on-Plane, Sphere-to-Sphere, Circular-Edge, Axis-to-Axis, Axis-to-Plane, Axis-Plane-Normal, Angular Axis-to-Plane, Planes-Parallelism, Planes-Coincident, Angled-Planes, Center-of-Mass. This covers a variety of use cases.

A2plus comes with an autosolver. The way it works, however, is somewhat unreliable. Case in point: select two planes, create a Plane-Coincident constraint, solve, accept. Then select the constraint and change its Offset parameter in the Combo View. The autosolver will not update the position of the object that has the first plane, you will have to click the Solve button for this change to take effect.

There’s a number of convenience features specific to A2plus (as compared to Assembly 2) such as placing labels on parts in the viewport for easier navigation or making parts’ fills transparent. The behavior of A2plus is configurable. Settings are available in the Preferences dialog:

Some features of the original Assembly 2 workbench are unavailable. Notably, the animation of the assembly for collision analysis is missing.

The A2plus workbench has a good reference guide on FreeCAD’s wiki but lacks official tutorials that explain the workflow. The community, however, stepped up and provided a sufficient number of YouTube tutorials on using A2plus for a variety of use cases: mechanical design, woodworking, etc.

Update 2023-03-26: There is at least one documented case where the precision of the A2plus solver was not sufficient to get the job done. The workbench developer explained this by having to find a compromise between speed (responsiveness of the WB) and accuracy due to limited calculation power available to a solver written in Python.¹

Consistency​

A2plus does a few things differently from many other workbenches. The most user-visible difference is how constraint settings are displayed. When a new constraint is being added, FreeCAD displays a floating dialog:

Double-clicking the constraint in the project tree reopens this floating dialog. However, the very same information is displayed in the Combo View. So there’s two competing approaches to editing settings of a constraint.

Similarly, the first button in the Constraint toolbar opens another floating window that duplicates the list of constraints that is already available in that toolbar. This is not a common (although fairly optional-to-use) UI solution for FreeCAD.

As already noted, some objects require a conversion to an A2plus part, like the basic 3D objects created in the Part workbench. At the same time, this assembly workbench has no problem working with parts created in e.g. SheetMetal WB.

One important caveat of A2plus is that it doesn’t use the standard App::Link machinery to reference objects in other documents. Parts added to the document this way cannot be used in an assembly.

Some actions, like adding a part from an external file are not correctly added to the undo buffer so they cannot be reverted in the normal way.

Stability​

As of publishing this overview, there are no reported crashers that aren’t fixed. There haven’t even been many before: the issue tracker only lists 3 bugs in A2plus that ever crashed FreeCAD, and git log likewise lists only a few fixes for crashes. However, we were able to crash the program by pressing Ctrl+Z to undo while moving a part under constraints.

The main developer typically responds to bug reports within the first few days. There’s a small number of bug reports with mild severity from 2019 where either no detailed information was provided by the reporter, or the developer couldn’t replicate the issue, or the report slipped through developer’s fingers. The workbench occasionally exhibits inconsistent or glitchy behavior like failing to delete a conflicting constraint. Other than that, nothing particularly bad stands out.

Performance​

Assemblies are inherently complex beasts. It takes a substantial amount of talent, time, and effort to make a fast solver — a combination that not every volunteer has at their disposal. We’ve definitely seen complaints like this one about performance issues in the A2plus workbench even with fairly simple assemblies. However, in our limited testing, we were unable to come up with conclusive evidence for assemblies “blowing up” after changes. Simple assemblies (up to 40 parts) did not represent a major issue for A2plus. But there was noticeable rendering slowdown when moving parts under constraints.

At least one of the reasons for possible performance issues according to the main A2plus developer is the inefficient use of memory. This is how he explains it and goes on to give very useful hints about ways a programmer could deal with Python limitations:

Memory management using Python as a programming language is not that easy and some memory leaks cannot be completely avoided. Python is keeping a lot of internal lists, which are immortal and their memory is not given back to the system during the lifetime of the program. So it is not possible to delete no more used objects from memory directly, as it is possible with "C/C++". Every object, which is not used anymore, is deleted (or sometimes it is not for various reasons), from Python's garbage collector. The code can only be optimized in order to reduce memory consumption. (using slots, avoiding string concatenation etc). I will have a look at this next time, where it is possible. But this is a bunch of work and will need a lot of time. And it will never be perfect.

Development​

The main developer responds to proposed contributions rather fast: many PRs by drive-by contributors are merged within days of submission, sometimes on the same day. Just 1 out of 452 pull requests is sitting unapplied on GitHub.

In the fall of 2022, a new regular contributor joined the project. His activity now rivals that of kbwbe.

Unlike with the original Assembly 2 workbench that had zero releases, the main developer of A2plus regularly tagged releases until November 2022 (a total of 101 tags so far). Releases mostly represent one or two bug fixes.

Community​

A2plus has one of the longest dedicated threads in the forum. However, since 2021, the activity of discussions has noticeably decreased: just 16 messages in the main thread in 2021, and 12 messages in 2022. The reason for this is unclear but might indicate that the interest towards the workbench has been decreasing as users move to other options.

Summary​

A2plus represents a major improvement over the original Assembly 2 workbench in terms of both workflow, features, and usability. It has more types of constraints, more convenience features, and better supports single-user workflows. It’s also sufficiently stable and has two developers who actively merge patches from other contributors. At the same time, the workbench has some unconventional UX/UI solutions and is reportedly prone to performance issues that are not easily resolved.

Next up​

In the next installment, we’ll take a close look at Assembly 3, a workbench that actively uses a solver from another free/libre CAD program, SolveSpace.

This is part two of our series on the need for an integrated default assembly workbench for FreeCAD. Part One gives and introduction and explains our methods. In this part, we take a closer look at Assembly 2, one of the early approaches to adding this feature set to FreeCAD.

History​

A FreeCAD user publicly known as Hamish started this project in late 2014. This is the original announcement:

I have written an assembly workbench for FreeCAD v0.15, which I am posting here for everyone's perusal. [...] I realize that there is mostly likely heavy development on FreeCAD's inbuilt assembly wb, which i could have just used for my assembly needs. However since FreeCAD provides such an excellent environment for building custom wbs, I decided to rather write my own wb exactly tailored to my needs [...] Hope someone else finds the assembly2 wb useful

2015 was the most active year for the project. However, in 2016, the original developer stopped writing new code and the next maintainer, Roland Frank, passed away in 2017. Hamish and another contributor, kbwbe, continued merging occasional pull requests: bug fixes, a Newton solver, and a port to Python 3 to make the workbench generally supported by newer versions of FreeCAD.

Assembly2 Commit History

However, in 2018, kbwbe started working on a rewrite of Assembly 2 and eventually dropped out of contributing to this workbench. There have been no changes in the git repository since 2019.

Workflow and ease of use​

Assembly 2 only supports the bottom-up approach where you design and save parts as files and then import them for an assembly into a new FreeCAD project. It will read both FreeCAD, OBJ, IGES, and STEP files. The workbench expects that the user either enables the visibility of just one body in the design file or creates files with single-body parts. Sub-assemblies are possible, however.

Graber I3 model by Nemesis81

After importing, spatial constraints need to be added and solved. Imported parts can be manually updated when the linked original file changes. Overall, it’s a straightforward workflow: import multiple parts from respective files, select parts’ features, add constraints, solve, done.

Problems begin to arise when a change is required. Assembly 2 does not have a dynamic solver. So once you change something like a distance or an angle, you have to create a constraint anew. Moreover, only some features in the workbench support undo/redo.

Features​

Constraints available in Assembly 2 are limited to circular edge, plane, axial, angular (for planes), and spherical surface. There are a few tools to work with constraints like flipping their directions.

Once constraints are done and solved, you can animate degrees of freedom to check for clearances and collisions in any combination of their respective positions. Additionally, it’s possible to check the entire assembly for overlapping parts.

Assembly 2 also allows creating a list of parts, for which it uses the Drawing Dimensioning workbench by the same original developer. Which, in return, only works with page objects created with the Drawing workbench. It’s also possible to create one object from all or just the selected parts in an assembly to display them in a drawing. Notably, the Drawing workbench is now deprecated and replaced by the TechDraw workbench.

Consistency​

The way the user interface is organized is in line with the rest of FreeCAD. However, for people new to assemblies, watching a few tutorials on YouTube will be really helpful. Unfortunately, the documentation on the workbench in the FreeCAD’s wiki is scarce: it only lists available features and doesn’t provide any information on them that you wouldn’t be able to see in the tooltips of the actual user interface.

Assembly 2 can work with parts created in other workbenches like SheetMetal or parts created with ‘importer’ workbenches like KiCadStepUp or Fasteners. However, because it demands just one body to be visible in an imported project and does not allow choosing which body to import, placing an entire board into an enclosure will require a lot of time and patience.

The workbench also doesn’t follow the more recent trend of making 3rd party workbenches translatable.

Graber I3 model by Nemesis81

Stability​

Because this assembly workbench is not maintained, the issue tracker has been deactivated on GitHub. So there’s no aggregated information on bugs and their severity. When used with a recent version of FreeCAD, the workbench has various glitches. The general recommendation appears to be keeping a copy of an older FreeCAD version (typically, v0.16 or v0.17) around to open old files that use this assembly workbench. For new users, the recommendation is to try one of the newer assembly workbenches.

Performance​

Despite its simplicity, Assembly 2 can be very slow on medium-to-complex projects. One of the recommendations to deal with that is by creating sub-assemblies: effectively saving an assembly as a FreeCAD project, then importing it to another assembly. This removes some complexity from the project but reportedly does not solve all performance issues.

Moreover, the interference checker takes the simple road of trying all possible pairs, and this can go on for a very long time.

Development Status​

There have never been official versioned releases of Assembly 2. Active development on this workbench ceased in 2016-2017. This workbench has been unmaintained since 2019. One of its features (list of parts) depends on another unmaintained 3rd party workbench by the same original developer, and another feature (consolidation of objects) depends on a deprecated official workbench (Drawing).

Summary​

Assembly 2 is a fairly straightforward yet very barebone solution for creating assemblies. It imposes a particular way of organizing a project, has a limited set of constraints, requires either a lot of planning or a lot of manual work because of lacking a dynamic solver, relies on obsolete workbenches for some of its features, and has been unmaintained since 2019. As such, it has served its purpose well and is now generally considered superseded by A2plus, Assembly 3, and Assembly 4.

Next up​

In the next installment, we’ll take a close look at the major iteration of this workbench called A2plus.

FreeCAD is an inherently modular program where major features can be developed by 3rd parties as workbenches. This is great for creating a healthy ecosystem of add-ons and catering to a diverse group of users: tinkerers, professional mechanical engineers, architects, furniture designers etc. The obvious benefit of that is that creating and deploying a solution for a particular user group does not require syncing with FreeCAD’s release cycle that can be as long as a few years. Since v0.17, FreeCAD makes it very easy to install and update various workbenches developed by its passionate community.

Why a Default Assembly Workbench?​

The drawback of developing major features as 3rd party workbenches is that these features are not part of the out-of-box user experience and thus tend to be niche-oriented, less tested, have more bugs, lack documentation etc. Meanwhile users expect major features to be immediately available and be specialization-agnostic, easy to use, robust, performant, and well-documented.

Creating an assembly is one of those essential features. It‘s commonly required when designing something more complex than a simple replacement part. However in FreeCAD, this feature is only available as a separately installed workbench. In fact, there are 3 competing workbenches and 1 more workbench that has been unmaintained for almost 4 years now. And then there are several more workbenches like Manipulator or Part-o-magic, that can be used to align parts in some way.

This effectively means that instead of launching FreeCAD, creating an assembly, and loading parts into it for aligning, users are expected to first explore at least half a dozen options by trial and error. The expectation that this much choice is good for them seems unrealistic.

Moreover, having this many competing solutions leads to development fragmentation, makes following tutorials confusing, and makes progress on the core slower as developers have to consider the impact on multiple approaches to assembly. Moreover, there is a strong demand for technical design tools where collaboration is easy. But collaboration implies using the same tools and standards. Having multiple competing assembly options is the opposite of that.

Our intention is to start a broad conversation. We want to highlight the need and build consensus that a single default workbench is in the best interest of our users. We're also proposing criteria for evaluating the current assembly workbenches. Our goal should be to identify the best foundation and feature set required for an assembly workbench to be included in the core FreeCAD distribution. Such a solution doesn't need to meet everyone's needs. Rather, it should strive to be a general-purpose solution for at least 80% of the use-cases.

We do understand the implications of carrying out and publishing this research and calling for a default. Whatever default assembly workbench FreeCAD gets, it automatically moves into focus and gets more tutorials, more testing, more bug reports, more improvements etc. And the non-default workbenches will automatically get less attention and their developers will likely have to cater to more niche areas. So this requires careful treatment. Part of that is being objective when evaluating the existing options.

Methodology​

To make a fair assessment, we need to settle on a set of evaluation criteria that cover most, if not all aspects. There is one important disclaimer we want to make here though: as much as maintenance and responsiveness of developers matter, we evaluate software, not people. Here is what we came up with.

Ease of use It’s difficult to design software that is compelling to both users who are new to solid parametric modeling and experienced users of competing products. However, it’s natural to expect a workbench that has a merit of its own and provides an obvious path to creating an assembly from start to finish, with as little friction as possible. We also expect the best workbench to be efficient in team work where parts can be submitted by different users and can be iterated upon.

Consistency This is a multifaceted topic. Because FreeCAD is highly modular, developers have a lot of freedom in how they implement features. Ideally, the assembly workbench should follow roughly the same UI conventions as the rest of FreeCAD. This means that a user who is already familiar with designing parts with FreeCAD should have little-to-no problems figuring out how to make assemblies. Additionally, an assembly workbench should function well with other workbenches, including add-on workbenches. For example, it should be able to work with enclosures designed with the SheetMetal workbench. It should conform to the same standards for translation and macro scriptability as other core workbenches.

Features We are looking at the set of available constraints, how picking edges, faces and other features for alignment works, how imported parts can be managed in complex assemblies etc. However, having the most features doesn’t necessarily translate to the best user experience. A much better indication is how well a workbench serves the purpose it was designed for.

Stability There are multiple factors at play when you evaluate stability of software. First, there’s the severity of issues. You can stumble upon a warning that doesn’t prevent you from accomplishing a task but is a mild annoyance. Or you can run into a crasher that loses unsaved changes or corrupts the model, which is a really bad user experience. This is not a problem for our evaluation: we can easily separate minor issues from crashers in reports.

Then there’s the number of users. If one workbench has 100 users and 10 unresolved crash reports, and another workbench has 10,000 users and also 10 unresolved bug reports, this likely means that the latter is more thoroughly tested and has less undiscovered issues. However, we have no way of knowing how many users each assembly workbench has. The amount of stars for a GitHub repository doesn’t sound like a fair way to judge on popularity, especially since visiting a GitHub repository is not how you install a FreeCAD workbench these days. We can get some sense of the user base from looking at how many unique users participated in discussing this or that assembly workbench on the forum. But this should be taken with a grain of salt as this approach doesn’t account for the part of users who stay in the shadows.

Also, reporting a bug should be simple enough. If it’s too difficult to do, that’s how you get bugs that continue to be unresolved for years, outside of developers’ radar. Fortunately, all four assembly workbenches are hosted on GitHub and thus have the same fairly sensible UX/UI for reporting bugs. That gives us some baseline. Thus, given the limitations, we draw conclusions from unresolved stability issues reported to GitHub and relevant posts to the FreeCAD Forum.

Speed Just like with stability, it’s hard enough to be a good judge of performance. Hardware specs vary wildly between users, and so does the complexity of assemblies. But if there is a significant amount of complaints about the performance in case of fairly simple assemblies (let’s say, 10 to 20 parts), something is obviously wrong.

There is one more aspect that we considered as well and ultimately decided against — code quality and extensibility. It is important to focus on the code that needs as little effort as possible to extend the feature set and maintain it. However, all four existing workbenches are between 7,600 and 14,900 lines of code. This is perfectly manageable in terms of time spent on potential refactoring. That said, having an engaged community grown around a particular workbench and willing to take action is a lot more important. You can do anything with an experienced, passionate team.

What Now​

In the next installments, we will evaluate Assembly2, A2plus, Assembly 3, and Assembly 4 by the criteria explained above. Then we will come up with a proposal and continue the discussion with the FreeCAD community. We invite feedback on this issue and our approach.

Part 2: Assembly 2​

Should hiring managers base a decision on someone’s GitHub profile? No. But will it ever hurt to have a robust GitHub account? Also no.

I’m a hiring manager for a new open core company, and I watched the discussion under @manuel_frigerio’s tweet blow up with amusement. The debate about using people’s GitHub profiles to make hiring decisions isn’t new. The typical backlash ensued and Manuel has since made his tweets private. And sure, using someone’s GitHub profile, particularly their contribution graph, to judge their skills as a developer is flawed.

How not to evaluate a candidate based on their GitHub account

Plenty of talented programmers are writing code that never makes it to GitHub¹ because they’re working exclusively on closed source software or have climbed the ladder to a management position. There are also plenty of bad actors who can fudge their contribution graph by “updating a readme file multiple times a day” or even faking their Git commit history.

This seems obvious, but based on the discussion from last week it bears saying again: If you’re a hiring manager and you’re judging an applicant’s skills and experience by how many green squares they have (or how dark they are), this is the most superficial way to look at it, and it won’t tell you anything about whether this person makes valuable contributions or is pleasant to work with.

But if you’re recruiting engineers to work on an open source or open core project (as I am), engaging with open source is an intrinsic part of the job and someone’s GitHub account gives extremely valuable insight into a candidate’s suitability for that role. And if you’re in the job market and don’t have an active GitHub profile, you could be missing out on opportunities by overlooking FOSS.

What you can actually judge from someone’s GitHub profile

Do they have exposure to FOSS at all?​

First, we have to acknowledge the difference between hiring for a closed-source, proprietary product and open source software: If you’re a hiring manager for the former, basing your hiring decisions on someone’s OSS contributions is short sighted and could be harmful. (And if you’re a candidate with no interest in working full time on FOSS, by all means, focus on your proprietary work instead.)

If however you’re in the business of FOSS, and you receive applications from one candidate with a GitHub account and one without, you are going to have a lot more to go on when assessing the first. I am always going to lean towards working with people who already engage with open source in some manner and are used to working transparently and engaging with a community. Having a GitHub account and forking even one project is the bare minimum someone can do to show they have experience here. Of course that’s going to influence my hiring.

What are their interests?​

There are plenty of TikToks out there showing people how to optimize their resumes with keywords from the descriptions of jobs they’re applying for. It’s easy to stuff your CV with recruiter bait. Of course there are ways to uncover grifters in your hiring process. What is much harder to fabricate is a history of following open source projects, submitting issues, bug reports, and pull or merge requests, and engaging with communities. I’m looking for team members who share my vision for making design tools accessible and it’s much easier to establish whether someone cares about this mission if they’re following and interacting with related project.

If you’re hiring someone to do this kind of work on your project, you couldn’t ask for better signal than that.

How do they collaborate with others?​

Beyond any code they contribute, a candidate who participates in OSS will have a history of code review, discussion, and engaging with feedback. Do they take suggestions on board, do they offer feedback and coaching to others? Sure, this requires a bit more attention than simply scanning a contribution graph, but it’s hard to replicate this kind of window into a candidate’s experience and conduct from interviews alone.

Do they have something to offer other than code?​

Let’s revisit this idea of “updating a readme file” reflecting in someone’s GitHub graph. We’ll leave aside for now that they could automate updates using a cronjob or script (which, depending on the role you’re hiring for, could actually show the initiative and creativity that you’re looking for). Editing and updating documentation is a contribution that takes work and initiative, and we should encourage this too. Having non-programmers participate in your open source project is valuable and we only make it more intimidating when we assign greater value to code contributions than other activities that result in green squares.

It’s never going to hurt to have a robust GitHub contribution history

I got applications from the US, India, Ukraine, South Africa, France, Paraguay… all over. I found it interesting that there was a stark difference between US applicants and international ones. Almost all of the international applicants had active GitHub accounts while perhaps 1 in 15 of the US ones did. There are many reasons why this might be, including a lack of exposure to open source at schools and institutions where FOSS is not widely adopted.

If you’re a jobseeker reading this and feeling like I’m suggesting you do more work because you aren’t active in open source yet, then the jobs I’m referring to are probably not for you. If the idea of participating in open source sounds burdensome, why would you seek out a full-time role in it anyway? If you are curious though, and want to give yourself the best chance of being considered seriously for work in FOSS, showing an active interest and engagement with projects is never going to hurt.

To help us make FreeCAD better and build the Ondsel product, consider joining us.

FreeCAD's 'topological naming problem' is legendary. It's frequently cited as the number one reason holding back widespread adoption of FreeCAD for commercial use.

Developer RealThunder introduced a fix to the problem years ago, but it has never been fully incorporated into the core product.

Will FreeCAD ever have a solution? Yes. But it’s going to take time.

Let’s back up a bit.

What is topological naming, and why is it a problem in FreeCAD?

Topological naming is the process of giving persistent names to elements of a solid model, such as faces, edges, and vertices. By naming these elements, we can attach features, dimensions, and other attributes to them.

The hard part of topological naming is making the names persistent even if the model is modified. Modern parametric designs are built up through a series of modifications which change the elements in the model. Faces may merge or be split. Edges may be chamfered, turning into multiple edges. If the computer is unable to maintain correct persistence of the naming—even when the underlying topology changes—the model breaks and recovery is difficult. Maker Tales has a good explanation here.

The problem is ubiquitous in CAD. All applications suffer from it to some extent. The problem cannot be solved in the traditional sense. It can only be mitigated and most applications do a good job of avoiding the problem by either limiting the user’s actions or algorithmically tracking changes to the named features.

The current state of FreeCAD is weak in this regard. For simple models, the problem is fairly easy to avoid and a broken model is easy to repair. As models get more complicated, only a very disciplined approach to design will keep models intact. This requires experience that many new and casual users don’t have. That is why the problem is so frustrating—it bites you when you’ve already invested a lot of time learning the tool and building the design.

RealThunder’s fix works. Why not use it?

It seems obvious. We have a working branch of FreeCAD that isn’t plagued by the topological naming problem. Why wouldn’t we just merge it in and be done with it?

“The fact that this solvable topology naming problem is so serious yet so long-standing, tells me that this is really a people problem in the FreeCAD project. Because of this, as much as I want to use it, I simply can not afford this "free" software. The community needs to push out whomever is standing in the way of progress. And crowd-source some funds to hire a pro to fix the topology-naming issue as well as do some much-needed integration work.” — agnichatian on YouTube

This opinion is understandable and certainly not unusual. As much as we relate to the frustrations expressed here, it’s not as simple as just merging in RealThunder’s branch or bringing in one paid developer to do it once and for all. Why?

It’s important to appreciate how pervasive feature naming is within FreeCAD—or any CAD. Identifying features and attaching attributes to them is what modern parametric design is all about. Implementing a solution is not a straightforward task and implementing it incorrectly would cause user models to break irreparably. Even a properly implemented solution is guaranteed to have bugs and border-cases for a long time.

For all these reasons, the project leaders have chosen to move cautiously and to allow the solution to stabilize and be proven before merging it into the main branch.

Why is it so hard to merge?​

There are two factors:

First is the sheer size and number of code changes necessary to implement this solution. Many, if not most, files in FreeCAD need to be modified to incorporate the solution. Second is the pace of other development work. The rest of FreeCAD’s development has only accelerated in recent years. Work is being done by many developers in many parts of the application.

Before new code can be merged, it has to be rebased onto the current version of source code. If there are conflicts, they have to be resolved manually. With a large, pervasive change like this, there are always conflicts. By the time rebasing is complete, the master branch has moved ahead and the process has to start again.

One solution could be to freeze the master branch and block any further changes until the topological naming solution is merged, but this might take many months to accomplish and just isn’t practical. There are many more features other developers are working on, and, more importantly, problems they are fixing. If we were to freeze the master branch in favor of one fix, other features will again have the same rebasing issue.

Of course, users could switch to using RealThunder’s branch exclusively. Some users who are particularly sensitive to the problem have done so successfully. For commercial users this may be hard to sell to leadership because RealThunder’s branch isn’t able to keep pace with the development of new features in the upstream FreeCAD application. They have to make a choice between relatively stable models and having access to the new and advanced features being developed throughout the rest of FreeCAD.

What’s the path forward?

At the FreeCAD Day meetup in Brussels in February 2023, Ondsel and other project leaders proposed a different strategy for resolving the issue: Instead of attempting to merge RealThunder’s solution as a monolithic unit, we would, instead, consider it a proof-of-concept. The solution has been running in RealThunder’s LinksStage3 branch for two years and can be considered proven. Now we need to treat it as a roadmap to guide us towards implementing the solution in FreeCAD itself without disrupting current functionality or slowing down development.

Progress without regression​

Rather than merging the code directly, our proposal is to break the code into functional pieces, each of which can be merged directly into the master branch without breaking the current functionality. This will require additional testing at each step and might require additional code to permit the merging without regression.

With this approach, each piece will be merged directly to master along with the relevant unit tests. This will avoid the need for a long-lived feature branch that requires constant rebasing. There will be no single point where suddenly the problem is ‘fixed.’ Instead the necessary changes will be merged gradually and model stability will increase over time.

Laying the foundation for long-term change​

The first pieces to be merged may not provide any value to the end-user but will provide a solid foundation that later pieces can build on. As each piece is added, additional unit tests can be developed and better code conventions adopted for implementing the actual name resolution.

This path isn’t fast. It will take time and the collective expertise of many developers. It will take cooperation throughout the community and patience from our users.

What is Ondsel’s role in all this? Is Ondsel going to solve the toponaming problem?

Ondsel has already started a thorough survey of RealThunder’s solution in order to build a roadmap for integrating it.

Ondsel will help coordinate the change and will participate in delivering a resolution. We can bring professional engineering talent to the problem but we cannot do it alone. It will take time and the expertise of many software engineers across the community.

There’s no “one and done” fix, which means the FreeCAD development community needs broad institutional knowledge of the solution. The toponaming problem belongs to FreeCAD and, therefore, so must the solution.

For more context and to follow developments as we work on breaking down and gradually merging RealThunder’s fix, subscribe to the GitHub issue.

To help us make FreeCAD better and build the Ondsel product, consider joining us.