Discussions about FOSS issue practices often center around getting issue creation right. Have we set contributors up for success with guidelines and issue templates? Are we asking them to look at existing issues for their proposal first? These are bare minimum requirements.

We act like someone creates an issue and throws it over the wall, after which someone else picks it up to move it forward—all of which hinges on writing a good issue. If the issue goes stale, it wasn't a good issue, right?

But issue creation should be the start of a conversation, and for that, maintainers should be heavily involved in collaborating on issues. Stale PRs get a lot of airtime, but issues habitually going stale is just as bad for open source project velocity. Effective issues—the ones that actually result in meaningful change—invite conversation and encourage action, and maintainers can play more of a role in fostering that type of issue than you might think.

What makes a good issue?​

FreeCAD's contributing document and process for contributions serve a number of goals, such as providing transparency and fairness, and enabling faster inclusion of contributions while preserving code quality. We can extrapolate a lot about what makes a good vs bad issue from the Contribution Requirements.

Well defined issues are like Nerd Sniping. They're hard to ignore and inspire creative problem solving. We can expect issue authors to at least familiarize themselves with a project's contribution guidelines and issue templates and make an effort to provide a complete issue. If an issue isn't getting continuous attention though, that's a sign that the issue needs improvement.

The role of maintainers​

Beyond the usual expectations of maintainers (engage kindly with contributors, respond in a timely manner, give regular updates), we can think about maintainers' responsibilities in two stages:

Before an issue is created​

The discourse around open source project issues tends to focus on this stage, and the common advice is to provide adequate guidelines and issue templates to help contributors create issues that meet requirements.

After an issue is created​

Beyond contribution guidelines, maintainers should use automations to streamline the contribution process and encourage momentum. raycastbot automatically @ mentions contributors who have worked on that specific Raycast extension in the past:

VS Code has a host of Issue Triage GitHub Actions that perform housekeeping tasks like closing stale issues or requesting a translation of issues not written in English.

These practices can relieve some of the burden on maintainers so they have more time to dedicate to the more impactful, vital part of a maintainer's role in issue management:

Proactive involvement and collaboration on issues​

Even with the above practices in place, sometimes even a well defined issue goes stale. It might represent an extreme edge case or an inconvenience that users have found ways to work around. These issues often get overlooked because they aren’t seen as part of a bigger initiative. Maintainers can help by tagging these issues appropriately and adding them to projects where they form part of a bigger context.

For example, an issue describing a minor UI tweak might be widely regarded as a good idea and still might be ignored because it’s always judged as less important than something else. But if the same issue is put into a project for general UI improvements, then its relevance and potential impact is more pronounced.

This is one example of how maintainers can help by making a conscious effort to review and revise issues. Holding regular meetings to walk through and refactor issues can turn non-starter issues into active and actionable discussions, just by:

• Improving the titles to make them more clearly describe the problem to be solved
• Proposing solutions and workarounds
• Requesting clarification from the submitter
• Writing user stories
• Narrowing the scope or splitting the issue into multiple, more manageable ones
• Merging duplicates
• Tagging and labeling
• @ mentioning the right people to get conversation going
• Closing issues that are out of scope or stale

Some of these actions can be automated as described above, but meeting regularly to review open issues lets you catch ones that have slipped through the cracks.

Thinking beyond bugs and problems to solve​

For maximum effect, the scope of issues should extend beyond new features and problems to solve, to housekeeping and project maintenance.

FreeCAD's issue requirements may be thorough, but there are other aspects of the project that aren't managed as well. For example, the project's backporting requests are currently managed in a forum thread, which isn't great for organization or visibility.

If backporting was managed via issues grouped into a project, we'd have better visibility into progress and the status of the release as well as the ability to build release notes easily.

Giving greater status and attention to issues as a primary vehicle through which discussion happens and progress is made also has the effect of bringing forward discussions and debates about value judgments. When these discussions happen early in the cycle, rather than at the PR stage, you're more likely to get changes and new developments that align with your roadmap and move your project forward.

How you can help​

You don't have to be a maintainer to be part of the solution. FreeCAD is experimenting with GitHub projects and could use a lot of help with organizing the issues in line with the improvements outlined above. Your contributions are welcome!

There's a problem with running development FreeCAD builds for actual work and it's going to get uglier soon. Here's the deal.

What's Wrong With The Dev Builds?​

What users want from FreeCAD is a stable, reliable platform that is trustworthy for doing their work. What they also want are various new features and quality-of-life improvements.

But FreeCAD has a relatively long and unpredictable release cycle — typically over a year between major releases, and no one can put a date on a release in advance. This irregular release schedule has historical reasons (“it’s ready when it’s ready”), but also because over the last several years, contributors did a tremendous amount of work that wasn’t split into smaller chunks. And thus there were large gaps between releases when the team ported FreeCAD from Python2 to Python 3, and then from Qt4 to Qt5.

With the current effort to resolve topological naming, FreeCAD development is moving toward a more incremental approach. Large changes are merged incrementally rather than waiting until the whole thing is done. This should accelerate the pace of development and reduce the time between releases. It also implies that the development branch will experience more instability than it has in the past. There’s an obvious conflict between the need for stability and the desire for new features. You can get an increasingly reliable platform by sticking with point releases. Or you can get the latest and greatest by using development builds at the risk of experiencing more glitches or even losing your work due to a crash.

We encourage everyone doing “real work” to use a stable build and avoid the risk, but for people who accept the risk and run dev builds, things are likely to get even worse soon. Once the project releases version 0.21, the next batch of topo-naming issue fixes will start landing to the main development branch. Because of what these fixes do, FreeCAD is expected to take a performance hit until optimizations follow at a later stage of development. Bottom line: the development build is going to get slower for a while.

In our opinion, this is the perfect time for FreeCAD, as a project, to revisit its release policy.

Time-Based Schedule​

The first part of our proposal is for the FreeCAD project to have more frequent and predictable releases. Effectively — a time-based release schedule. This is common for projects with some kind of financial backing for the core team of developers, like Blender. But it also works for large projects that receive little-to-no funding on a regular basis, like Kdenlive (3 releases a year, following the KDE’s release cycle) and darktable (2 releases a year since 2020).

How often should FreeCAD be released? So far, the project has been struggling to do annual releases on time. So shooting for 2 releases a year and working from there seems like a good initial goal. There are existing release policies like the one at OpenStack that have been studied and could be learned from.

Let's say we all agree on bi-annual releases. What does it really mean?

We remove the element of uncertainty for users and developers alike. Users can plan their upgrades and only use a dev build when they need to test a fix. Contributors can plan ahead and don't need to jeopardize their non-FreeCAD commitments.

Much shorter development cycle. This means more focused releases and less urge to include incomplete work, because the next window for merging will open very soon. This also means a much less exhausting period of work for testers and translators.

Especially in the latter case, contributors are typically expected to either follow development closely and update translations all the time or work like madmen during the strings freeze period because there's just so much work to do. Volunteered work should really be more manageable.

More frequent point releases. Once the release schedule is set, users will start counting on point releases happening regularly too (see below on another reason for that).

More focus on building infrastructure and automation. A time-based release schedule is going to require a more rigorous release process and a higher level of automation. Only a very small part of the C++ code is covered by unit tests at the moment, this really needs to change. And there is always, always more work to be done on Conda builds. All that means more DevOps work.

Feature Backports​

The FreeCAD team already backports bug fixes and security patches from the master branch to the release branch. But we could be doing more. We could be backporting some features and improvements to point releases too. Projects like GIMP and Scribus have been doing this for years now because they have release cycles even longer than those of FreeCAD. For them, it helps keeping users engaged, but it still means that larger, much desired changes take a very long time to show up in a stable release, and that’s the part we would rather avoid.

This wouldn't render major releases pointless (pun intended). We are thinking primarily of changes that are typically safe and not too time-consuming to backport. If a new feature, however small, comes with an architectural change (API change, file format change etc.), it’s a no-go. But quick UX fixes and other quality-of-life improvements are often possible.

One way to simplify the process of making this decision is to add a checkbox to the pull request template: “Backportable patch”. The maintainer who does the merge then would see that the PR is supposed to be backportable, check the patch against the backporting criteria, and attempt to cherry-pick the commit(s). Naturally, this implies that the developer who submitted a patch explored how far their change goes and understands whether the fix or the feature can easily be ported to the release branch.

The net outcome is that users would have even less reasons to keep using development builds and risk their work.

What's Next​

So what are the actionable things for contributors to do? First of all, we need to make the release process more regular. Documenting the major and point release processes in the Developer Handbook should be a priority. The current 0.20.3 and 0.21 releases are an excellent opportunity to do this.

More conversation is needed about an appropriate release cadence. Releases that are too frequent will distract from developing new features. Infrequent releases, as we have seen, will push users to the development builds. The goal should be to strike a proper balance between them and increase the value of the stable release with frequent maintenance releases.

Our suggestion is to make major releases twice a year and point releases depending on the amount and severity of bugs we fix. As long as fixes come in small batches and aren’t fixing anything really bad, we can release them on a monthly basis. A fix for a severe bug like data loss would definitely call for an immediate release.

We also need to define a general timeframe within each release cycle: when we open the main development branch for new features, when we do a feature freeze, when we do a strings freeze, etc.

Beyond that, we will also need to revisit our patch inclusion policy to match a much shorter release cycle. This policy would also have to be updated for feature/improvement backports, which means we need criteria of what constitutes an easily portable change.

To discuss all these things, we created a discussion topic on GitHub and invite you to provide your input.

Historically, the development process in the FreeCAD community has been entirely volunteer-driven. This approach served the community amazingly well — up to a point. We got a very capable 3D CA* program out of it, but as the project grew, it became harder and harder to make significant changes.

Case in point: the entire toponaming fix is going to span two major releases (0.21 and 1.0). Why? It involves patching a lot of code and writing a lot of unit tests. It also requires knowing the internals of FreeCAD very well and communicating well with lots of people. It takes a particular kind of mind to sit quietly for weeks on end and hack on a boring architectural fix.

Similarly, improving UX/UI requires specific hands-on experience, as well as ability to cooperate. Fixing one task panel or layout is easy. Making the whole application feel consistent and polished is quite another. And developing a default assembly workbench implies not only being great at many things at once (math, data structure design, UX/UI), but also encouraging a consensus among multiple stakeholders. Doing your own thing is infinitely easier.

Many developers, especially volunteers, join FOSS projects for fun, to learn something new, and to improve their skills. These people play an incredibly important and central role in FreeCAD’s future. Sadly, being an individual contributor has become less fun and harder for these same reasons.

The project is at an inflection point where the old way of working is stifling improvement and new methods are needed. The project is also large and mature enough to attract professional development. Ondsel is only the first company to do so, we have no doubts that more will follow. What’s needed now is an approach to software development that lets commercial partners add value quickly but still lets individuals make significant contributions, influence the overall direction, and most importantly, have fun.

As a commercial company with paid developers, we have the opportunity to encourage a different way of working. We see five areas where the project has outgrown its historical development approach. These are all areas that formally served FreeCAD well but are now holding it back.

1. Project has historically had no roadmap. We introduced a global roadmap and have our own plan.

2. Project works in features. We're beginning to work in the CI methodology.

3. Project drives from pull requests. We drive from issues.

4. Project discusses important topics on the forum. We are using our blog and our GitHub tools to communicate and seek feedback.

5. The project community is mostly individual developers working independently. We work collaboratively and integrate multiple skill sets.

Some of these changes are already finding their way into the upstream project, others will hopefully be adopted by the larger FreeCAD community too. We hope these changes not only speed up the pace of development but also make it easier for volunteers to contribute effectively.

Roadmap​

As a commercial partner, Ondsel isn’t focused only on the short term features and bugfixes. We’ve also got our eyes on the long-term vision. We started by stepping back and looking at the big picture. What are the fundamental limitations that are holding FreeCAD back from widespread adoption?

We strongly believe that working off a roadmap will help the entire community to focus on important things and make faster progress by planning features and setting priorities. So we proposed a roadmap for the core project that covers major topics that are universally acknowledged: model stability, integrated assembly workbench, better UX/UI and streamlined workflow, easier extensibility, better documentation etc.

Some of those items will be picked by volunteers For others, a team like Ondsel will have a better shot at completing a particularly sophisticated task. In the latter case, we can communicate our proposal to the broader community and solicit input from users and contributors to shape the plan.

To that end, we are encouraging the use of Projects functionality on GitHub to keep track of the progress on larger issues that are part of that roadmap.

Continuous Integration​

The project typically moves forward one feature at a time. A developer gets an ‘itch’ that they’d like to scratch and works on a feature until it’s complete. They do this work in a dedicated feature branch and then submit a PR to merge the feature branch. There’s two problems with this.

First, this approach doesn’t work for features or fixes that imply either cooperation of many volunteers or a long solo effort by one contributor. Especially in the latter case, there’s a huge risk that work will be abandoned before it’s completed.

Secondly, complex features and large changes result in massive pull requests that must be evaluated. Going over commits in a large branch can take a long time. Meanwhile, those feature branches must be continuously rebased until they are accepted and merged. All this means extra work for both the project maintainers and contributors. The FreeCAD community has grown to accept this reality as the normal state of affairs, “it’s done when it’s done”. The outcome of this, however, is that contributors burn out and release cycles grow longer, from an average of 200 days to almost 550 days.

A better approach is to work in a continuous integration methodology. We can break up large features into many small, atomic commits that don’t break the master build. We can send pull requests for each of them allowing the work to be merged until the final feature is enabled. This will make the entire process far more manageable, which is especially important for modules where maintainers are volunteers. Here at Ondsel, we have already switched to this methodology as part of the work on fixing the toponaming issue.

Driving from Issues​

Ondsel has been working with the FreeCAD developer community and the FPA to formalize the contribution process. The Developers Guide is one of the outcomes of that.

Unfortunately, many contributions are still received as PRs that have had no prior discussion. The way it usually works is that someone finds a bug or identifies a missing feature and sends a PR to fix the bug or add the feature. This may be the first time ever that the community has heard of it.

Out-of-the-blue patches like that can cause problems:

• The community agrees that the problem exists but disagrees about the solution.
• Sometimes a lengthy debate ensues, whether the feature should be accepted at all, whether the assumed bug is actually a feature etc.
• Sometimes a valid solution needs to be implemented elsewhere in the application but the contributor isn’t interested in doing that work because it doesn’t affect them personally.

There are ways to manage development communication better.

Ondsel will drive from issues. We’ll submit issues for discussion ahead of time to verify that the bug or feature is legitimate. We can use the input provided by users and other contributors to figure out the best way to achieve the goal before we do the actual work. Then when the PR is finally submitted, the only remaining discussion should be about the quality of the code. We believe this will eliminate some conflict as well as late-stage user feedback, result in less patches sitting in the limbo and half cooked features, and let the entire upstream project move forward even faster.

We already started doing so, one example is a proposal for making assembly workbenches compatible on the data structure level.

Moving important conversations off the forum​

The FreeCAD forum has long been the center of the FreeCAD ecosystem. It is where development discussion has happened side-by-side with user support, general community discussion, and work coordination for translation, wiki, etc. As the project has grown, we’ve started to outgrow the forum, and communication has become less productive.

First, the amount of traffic means many important topics get lost. A topic about a bug can rapidly grow to multiple pages and dozens of replies. The conversation often gets off-topic, so it becomes impossible to keep up.

The same topics can get discussed many times in unrelated threads and multiple languages. Useful and important information becomes difficult to extract, and decisions never get recorded or followed up on. Most troubling for a software project, the discussion never gets linked to the source code or a pull request discussion.

The forum still serves an important role but it is less and less effective for technical discussions about the source code and related topics. We think the project should embrace a wide set of communication tools that are each appropriate to the type of conversation needed. Video meetings via Zoom and Jitsi are great for making plans. Real-time chats via Telegram, Gitter, Matrix, and Discord are great for working collaboratively on technical issues.

We encourage the project to keep technical discussion as close to the source code as possible. GitHub issues and pull requests allow a richer conversation in context with the source itself. Using labels and projects keeps conversations relevant and organized. This should help eliminate duplicate discussions and make useful input from users and contributors easy to locate and analyze.

Additionally, we use this blog for sharing ideas that are too broad for issues and pull requests but could serve as a reference on GitHub. The blog lets us take the conversation “up a level” and reflect on topics that deserve more time to consider. We mostly rely on the traditional “problem statement -> research -> analysis -> proposal” approach.

Collaboration​

Most FreeCAD contributors work independently. From time to time, they coordinate their efforts and work together to achieve a larger goal. This requires agreeing on a number of things: what work should be done exactly, who will do which part of it, what time frame for completion should be set etc. This is hard to do as there is little infrastructure or established processes for team work.

Ondsel engineers can work together in a more organized manner. We can set priorities and goals that are consistent with FreeCAD direction and also work with Ondsel’s product strategy. We can include outside experts and volunteer developers when required.

We think this kind of collaboration is the most important thing because it flows from doing all the other things better. By planning, communicating, and working in small discrete steps we can share the burden and collectively move much faster. We also avoid relying on one or two people with special skills to keep the project afloat.

In Conclusion​

Since much of the work we do directly affects the upstream FreeCAD project, we expect that the proposed work methodology changes — planning the work, atomizing large changes, and keeping discussions structured — will result in a more streamlined development process overall.

It is our hope that at least some of these changes will prove to be efficient and will eventually become the standard for the larger FreeCAD community.

As we flesh out the details of new work processes, we will document them in Ondsel’s own developers’ handbook.

Summary/meta: We already have great tools for design. Where VR can really shine is in creating environments to experience those designs in context.

VR CAD is usually portrayed like Tony Stark designing Iron Man suits, putting the emphasis on VR as an evolution of design tools. This is Hollywood stupid. VR design/UI isn't mature enough for that. Instead, we should be thinking about VR as a sharing environment where a designer can demonstrate a model in context.

VR for design is a long way from being useful​

The current discourse around VR and CAD potential focuses too much on using VR for design: gamifying the experience and building things with goggles on. Design takes time—sometimes a LOT of it. Wearing VR gear for any period of time gets uncomfortable quickly and is both physically and mentally fatiguing.

We do however have existing tools and applications for design work that already work well (and have decades of investment and optimization to leverage). Our keyboards, mouses, and monitors are still the best tools for this job and still have their place.

The real opportunity: Experiencing design in the metaverse​

By getting swept up in ideas about moving to VR for design work, we risk overlooking the more realistic, near-term potential of VR: creating an environment to experience a design in context.

Beyond visual twins​

A digital twin is a virtual copy of something physical: an environment, system, asset, or process. It’s also dynamic, connecting real-world data to the twin, to help not just with visualization but with understanding and forecasting how the real thing will interact with its environment. For example:

“Leaning on Omniverse, Ericsson created a digital twin of an entire city to determine the optimal deployment for their 5G rollout, using Omniverse to judiciously select and configure sites to maximize coverage and signal quality with minimal cost and complexity. To do so, Ericsson’s digital twin city tracks the physical world, with buildings and foliage 100% accurate, down to their surface materials and texture. In that world, Ericsson can accurately assess signal quality at any point in the city with a given deployment. And re-working sites— either upfront or at a later date for upgrade—can easily reveal how the coverage would improve (or not) in real time.” — Alex Herrera, The Metaverse: Separating the Wheat from the Chaff, from a CAD Perspective

So far though, the concept of digital twins tends to be limited to what we see, but with VR and AR (augmented reality) there’s great potential to take the concept of a digital twin beyond the visual.

“What I've always been interested in is this idea of, how do we experience more of the things we're designing when it's on the other side of the glass? … What I long for is, for example, taking the many facets of a design and being able to see them work together … we should be able to take an object and, for example, turn it on. And we should see lights flash and you press a button and you understand how it operates. You should hear what it sounds like. … If I was a designer, I want to really understand the scale and proportion. I want to understand what it feels like, I want to see what happens as I interact with it. So these products that we design and make are so much richer.” — Carl Bass, former President and CEO of Autodesk

Where VR and AR really shine is in providing context for what the user is experiencing when previewing or interacting with a design. The obvious use case is architecture, where you would be able to walk through a design in scale:

The same is true for other physical designs. You could show how a part fits into a model (think about an exhaust system under a car).

You don’t just see the thing, you see the thing in context. You hear ambient sound, feel immersed, and can even interact with other people in a shared context. This is an ideal environment for discussing physical designs.

Immersive remote collaboration​

There’s also an obvious use case in enabling the people working on such designs to collaborate remotely with one another in a shared context. Site visits and to get stakeholders in the same room to look at a prototype, while still useful, would no longer be necessary.

This benefit extends beyond design though, to any remote collaboration. Imagine a FreeCAD HQ room in VR, for contributors to meet, have discussions, and make plans in real time. Whiteboards and issue boards on the walls would add context to those meetings in a way that is otherwise hard to recreate with remote meetings.

Making 3D designs more accessible​

3D designs are like the source code of the design world: read much more than they are written. While source code is mostly read by programmers and compilers though, 3D designs are read by many different people across many roles… and other systems. Because 3D designs need to be read by so many, the long-term opportunity here is to make them more accessible by enabling people to experience them from anywhere, in context, and outside of a dedicated application.

If done well, the user experiencing the context doesn’t need to understand the controls of the software. They can look behind them by moving their head. They get an intuitive sense of scale because it’s related to their own bodies. The design becomes more useful by enabling people to access and experience it easily, in a range of different contexts.

This is another area of rapid innovation and Ondsel doesn’t have all the answers. What we want to do is enable the community of FreeCAD users to explore these ideas—o find new ways to collaborate, create, and share their designs with each other.

100 Days​

It’s hard to believe that it’s been just over three months since Ondsel started operations. One hundred days, in fact. I thought it would be fun to take a moment and consider what we’ve been able to accomplish in that time.

First, we built a team. Besides myself, Ondsel now has five people working on the future of FreeCAD. We were able to recruit, interview, hire, equip, and onboard five exceptionally talented people who hit the ground running and started contributing to FreeCAD.

We attended FOSDEM in Brussels in February where we got to meet with project leaders. We heard from many users who both love FreeCAD but are frustrated with the lack of progress on some big problems. We learned a ton and we were able to build consensus on a path forward.

From that, we laid out a plan for finally resolving the topo-naming problem. One of our people, @JohnDupuyCOMO refined the plan to incorporate RealThunder’s algorithm, and the developer community not only accepted it but started working with blazing speed to accomplish it. The first phase was completed in only a couple of weeks. Now we’ve started phase two.

We started building the Ondsel brand. We got a logo designed, put up a website, and established accounts on Twitter, Facebook, LinkedIn, and other platforms. We’ve taken our Twitter following from zero to almost two hundred followers.

We built relationships with some outstanding creators including Rebecca Dodd and Alexandre Prokoudine who are helping to create our blog content and communicate our vision.

We worked with Reedy Designs and to reskin the website in just over a week.

We initiated the FPA Handbook and contributed content to it.

We initiated the new Developer’s Handbook and are continuing to add new content to it as well.

We started our own handbook which will be an indispensable part of our company culture.

We published more than a dozen blog posts including a seven-part series on Assembly.

Our Assembly series started a community-wide discussion about an integrated assembly workbench — a much-needed core capability of FreeCAD. The discussion has had more than fifteen thousand views and hundreds of comments. We got some great insights that helped us shape the vision for this feature.

Another of our developers @ajinkyadahale completed our contract to improve spline construction in sketdcher for the Open Tool Chain Foundation.

Yet another of our developers @amrit3701 has been building the infrastructure to support our eventual product — a subject you will hear much more about in the coming months.

We got eight pull requests merged into the FreeCAD master branch, including PRs for topo-naming and many quality-of-life improvements by @pierrelouisboy: 9173, 9172, 9143, 9117, 9080, 9026, 9010, 8990.

We did all that in one-hundred days and I’m sure I’m missing many more things we did along the way.

I’m incredibly grateful, humbled, proud and excited. I’m grateful for the support of our investors Open Core Ventures and Sid Sijbrandij. I’m humbled by the support of the FreeCAD community and leadership. I’m proud of the stellar work of our people and partners.

I hope you follow us because I’m excited to see what we can do when we REALLY get rolling!

We started this series with the assumption that there is a strong community demand for a default assembly workbench in FreeCAD. The community discussion that followed that article confirmed our belief. We then researched existing options — Assembly 2, A2plus, Assembly 3, and Assembly 4 — and even quickly studied related workbenches and macros.

Our research had a number of limitations though. We avoided exploring the earliest solutions such as the original workbench by Jürgen Riegel and FreeGCS because they were incomplete. We also decided against studying both Exploded Assembly and Animation workbenches because this type of feature deserves dedicated attention.

From this research and the discussion that followed, we came away with a handful of important takeaways. We suggest that these ideas should influence the direction of the FreeCAD project.

In this article, we’ll describe what we learned. We’ve taken the liberty of making some specific recommendations for a way forward and we also discuss what we believe is Ondsel’s role.

Key Insights​

The Long-Term Vision​

We started this conversation by calling for a solution that covers 80% of use cases. Based on our research and community feedback, we conclude that there is strong consensus around the higher-level characteristics of this integrated assembly workbench:

• Both top-down and bottom-up approaches equally first-class citizens
• Simple enough to make quick alignments, but powerful enough for complex projects with nested sub-assemblies
• Ability to resolve assembly constraints automatically and eventually simulate multi-body dynamics
• An easy way to animate the assembly and detect collisions
• Built-in BOM generation
• PDM-ready
• Compatible with other parts of FreeCAD and alternative assembly workbenches
• Same license as FreeCAD (LGPL v2.1)

The Need for a Common Data Structure​

The existing assembly workbenches for FreeCAD are not mutually compatible. It isn’t possible for a user to switch between the options without losing data. This kind of compatibility is important and it starts with the data structure. Early in the forum discussion, Zolko noted the need for a standard, and we think he’s exactly right:

…what we need is a default assembly DATA FORMAT that every assembly workbench can use. You can design solids in Part and PartDesign workbenches, where you begin with one, continue with the other, use Draft en-passant, and finish with some Part Booleans. You can even mix this with Curved Shape surfaces, Sheet Metal bending, and they all COOPERATE! Why should it be different for assemblies? What IS needed is to say: to be called a FreeCAD assembly workbench it needs to use the following data structure […] and then let people implement the best approaches for that.

We see the development of the common data structure as a priority requirement for an integrated solution. Users should be able to move between existing workbenches or migrate to newer ones without redoing an entire project.

A standardized data structure would also simplify developing in-house niche solutions where you need to run some extra simulations.

Why We Should Talk About Solvers Separately​

Past discussions about an assembly workbench have lumped the solver and the workbench into the same conversation. Separating the discussion has been helpful since these are, in fact, very different things. It is the solver which has been the most controversial part of previous discussions. Assembly 4 and Manipulator workbenches have demonstrated that, at least for some use cases, a solver isn’t even needed at all.

Among those who emphasize the need for a solver, agreement about requirements has been hard to find. The real world is messy and complex and full of unique problems that require custom solutions. One solver cannot possibly handle the variety of use cases that exist (think combined mechanical-thermal-electromagnetic simulations).

Some problems can be handled by 2D solvers, and we have some very nice options, including the one in the Sketcher workbench.

Other problems require a capable 3D solver and if we want FreeCAD to be competitive, it needs one. Unfortunately, we currently have no options at all. SolveSpace comes closest but its licensing (GPL v3+) makes it an unlikely choice for FreeCAD (LGPL v2.1). The development of solvers, both open and proprietary, is an area of rapid innovation. We have no way of knowing what will be available even five years from now.

Our insight is that the future integrated assembly workbench should have the following three essential characteristics with respect to a solver:

• Minimally functional and easy-to-use without any solver at all
• Capable of using a solver if one exists
• Solver-agnostic, with a possibility to use new solvers in the future

Building the assembly workbench to be solver-independent provides the greatest flexibility for the project as a whole, users, and partners like Ondsel. It also provides the most options in the future.

Why People are Passionate About Existing Solutions​

From past experience, we understood that this discussion might get emotional at times. Users are very passionate about the existing options. What we noticed was that their passion stems from two sources.

Investment in climbing the learning curve. With three actively developed assembly workbenches today, users first have to learn enough to make a choice. Having made that choice, they don’t want to revisit it. Some users refuse to invest in even making the choice. They give up and move on. Here are a few examples from discussions about our initial proposal:

• “As a fairly new freeCAD user I have spent an innumerable amount of time attempting to choose which assembly workbench to use and more importantly learn how to use” (FC forum)
• “I tried switching to FreeCAD a couple of years ago and the plethora of conflicting assembly solutions prevented me from doing so” (FC forum)
• “I haven’t explored any of the assembly benches as there is a big curve to even selecting one of them” (Reddit)
• “It's painful to train anyone if there are four different assembly plugins and they all work slightly or drastically different” (Reddit)

Users who made a choice also made a significant investment to become proficient, because they saw the benefits of the tool they use. As a result, they often have little or no knowledge of the other options and no interest in learning if the current option meets their needs. At the risk of oversimplifying:

• A2plus users think it has a simple, natural, and straightforward workflow
• A3 users think it’s the most feature-complete workbench of all
• A4 users like how robust the LCS-based workflow is

Investment in their current models and assemblies. Users also have a large collection of projects that are built using one particular workbench. They are naturally reluctant to switch solutions if it means losing or redoing that work from scratch. Basically, they made a huge investment in their assembly WB of choice, and because of the lack of compatibility, they are now in an unintended vendor lock-in situation.

What about features? Surprisingly, one thing we didn’t hear much was users championing one solution or another because it offered specific features. While the different solutions had strengths and weaknesses, all of the options offer similar capabilities.

Our key insight is that protecting the investment users have made is extremely important. Change will be hard, but we believe users will be willing to adopt an integrated solution if it is robust, relatively easy to learn, well documented, and if existing models can be migrated to it with minimal rework. They shouldn’t be forced to make the change before they are ready or before an integrated solution is mature enough for their needs.

What About the Workflow and UX/UI?​

Once solvers and data format are removed from the discussion, what’s left to discuss is the workflow. Regardless of how passionate the users are, the reality is that none of the existing assembly workbenches has a perfect workflow or user interface:

• A2plus requires conversion of parts created with other WBs.
• A3 has so many constraint types that even experienced users get confused.
• A4 requires time to set up local coordinate systems for all features that should be attached.

There are ideas to borrow from all of them, but we don’t consider the workflow and UX/UI of any of the existing options, in their present form, to meet the long-term goals. Assembly 4, by virtue of its simplicity and solid design, would be a good starting point.

Recommendations​

Integrated Assembly Workbench​

We suggest that FreeCAD must commit itself to an integrated assembly workbench — with great UX, documentation, translations, and compatibility with the rest of FreeCAD.

While the first iteration of the workbench can be feature-incomplete, this WB should support both simple and complex workflows. It should provide a solid foundation for future development of PDM integration, BOM extraction, collision detection, exploded assembly views, and animations.

Ondsel’s role. We can participate in the planning, help organize the work, contribute code, test, and refine the solution. We can also contribute to the documentation and other essential parts of the project.

Standardized Data Structure​

We already explained the importance of having a common data structure earlier. Our recommendation is simply that this should be the first step, and it should involve all key stakeholders: core developers, maintainers of the other Assembly workbenches (kbwbe, Realthunder, and Zolko), and Ondsel. This should be undertaken and completed early enough that other workbenches can either support the standard directly or provide migration tools.

The approach in Assembly 4 is a serious contender for a starting point. Zolko has some very sensible ideas like having only one root assembly element in the project, wrapped into a Part container, with parts and sub-assemblies available as child elements.

The working group should also investigate what ISO 10303 has to offer but regardless of what is found, the focus should be on providing the best solution for FreeCAD and its users.

Ondsel’s role. Again, we can participate but we can’t impose a standard unilaterally. In this case, we feel Ondsel’s participation not only represents our own interests but the interest of other future partners.

Powerful, Performant, 3D Solver​

Let’s reiterate: a 3D solver is critical to make FreeCAD competitive for professional and commercial work. No viable solutions that are license-compatible currently exist.

The solver has to be written in C++ or another compiled language for acceptable performance. The development of a 3D solver is a massive, time consuming, and expensive endeavor. It is, by far, the hardest part of doing assembly right.

For ease of distribution, it’s best to make the solver part of the core FreeCAD. This also gives us a better shot at maintaining it and also makes it available for use in other workbenches (think Robot).

Ondsel’s role. We want a solution that is fast, powerful, and supports future functionality like multi-body dynamics. Ondsel intends to begin developing such a solution, release its code under an appropriately permissive license, and submit PRs to include it in the FreeCAD source. Based on our understanding of the ‘Buyer-Based’ Open Core Model, we think this is the right decision.

Having said that, it is essential to understand that Ondsel is a for-profit company and we are not profitable yet. We might fail before a solution is available. The project should not bet its future on our success. Moreover, the need to survive might force us to make the 3D solver or specific features available as paid options. This is also a risk area for the FreeCAD project. The community should prudently take steps to minimize the impact and ensure the viability of the integrated assembly workbench.

This aligns with our recommendation that the assembly workbench should be solver-agnostic, usable in solverless mode, supporting less powerful 2D solvers, but also able to take advantage of more powerful technology — including commercial options — if and when they are available.

Shipping the MVP​

We believe that a minimum viable assembly workbench (proof-of-workbench, if you will) should be shipped as part of FreeCAD as soon as possible to become a platform for testing the new 3D solver. The goal shouldn’t be feature completeness. Rather, we should focus on simplicity and stability and then iterate upon that to improve the workflow and user experience.

Ondsel’s role. Once again, we can participate by providing leadership, organization, code, testing, and documentation but we cannot do it alone. We’re ready to start immediately.

In Conclusion​

We thank everyone who participated in the discussion. Being able to test our ideas and expectations against feedback from avid users of existing assembly workbenches is priceless.

We know that the road to a world-class assembly system won’t be short and there will be plenty of bumps along the way. We also know we can’t do it alone. We look forward to collaborating with the FreeCAD community to bring this vision to life.

We are interested to hear your feedback on this plan. Please let us know what you think by commenting in the forum or on GitHub. We will create a project in the GitHub tracker to plan the work and coordinate the many people it will require. Please let us know if you want to contribute to this effort.

In the previous posts in this series we’ve already discussed reasons to create a default assembly workbench and then explored existing options: Assembly 2, A2plus, Assembly 3, and Assembly 4.

There are several more tools that provide a subset of their features, and these tools regularly come up in discussions on creating assemblies: the BodyBuilder macro, the Manipulator workbench, and the Part-o-magic workbench. Since none of them can realistically serve as a foundation for a potential default assembly workbench, in this review, we’ll focus on their interaction models to see what we can learn from them.

But before we do that, let’s quickly discuss the topic of exploded assemblies — a representation of the assembly design where parts are roughly in the right position, but at a certain distance from each other. We considered looking at the Exploded Assembly workbench in this post, because creating such a view is a very common use case. However, after a quick study we found the following.

First of all, it’s done differently across available commercial CAD offerings. It’s a part of the assembly toolset in Dassault Systèmes SolidWorks, Siemens NX, Ansys SpaceClaim, and BricsCAD Mechanical. It’s an additional default tool in PTC Creo and Onshape. And it’s part of the animation feature set in Autodesk Inventor, Autodesk Fusion 360, and T-FLEX CAD. So there’s no one right way to do that.

In FreeCAD, there are at least two 3rd-party workbenches for animation that have tools for exploding an assembly, Exploded Assembly and Animation. Another workbench, Movie, suggests using a fork of the Exploded Assembly workbench. And there are other workbenches that deal with animating moving parts.

On one hand, this indicates that the FreeCAD community is leaning towards seeing this as part of the animation feature set. On the other hand, there are perfectly sensible use cases like technical illustrations where you might want to place an isometric view of an exploded assembly onto a TechDraw page, and that’s probably outside the animation workbench’s jurisdiction. So it makes sense to revisit this topic later when we can give it our full attention.

And now let’s get on with additional assembly-like tools.

BodyBuilder macro​

According to the macro developer, ‘freedman’, the rationale behind this project is this:

I think many times new users and some of us need a model with just a few parts held together, we don't need the full assembler that does everything [...].

Getting started with this tool can be a challenge. There is no step-by-step tutorial. There’s a forum thread with a couple of GIFs and a few test files, only. Here is how it works.

The general idea is that, while the BodyBuilder macro is running, you select an object in the viewport, then a sketch in the tree view. As soon as you do that, the object in the viewport gets centered at that sketch’s origin.

But the points in sketches that you align objects to don’t all sit at (0;0;0) exactly, typically they are all over the place. So what you do when you create a sketch is you start it at the origin and then you use the Position property in Attachment Offset to move the sketch in the three dimensions. Once you set it up, you can align a body to that sketch.

Doing that means that the body’s Position (Placement) value changes to the point in space defined by the sketch's attachment offset.

You have several options for what to do next when you want to move that object.

• You can use the Positioning menu of the macro to set a relative offset that will increment the absolute values.
• You can set its position in absolute values, and for that the Properties dock is fairly sufficient.
• Or you can use the on-canvas Transform tool.

The macro has a kind of a menu, but really, it’s a different set of controls in generally the same space. The main menu allows looking at the reference sketch’s origin (has to be selected), setting X-Ray mode to the selected body to look through it, and switching to positioning settings. The positioning menu has offset, rotation etc. controls for the attached body. And the binding menu is where you initiate the binding of a body to a sketch or delete an existing binding.

Left to right: main menu, positioning menu, binding menu.

Once you get the hang of it, the macro works. It’s three clicks away if you have the Macro toolbar present, or a few more, if you have to use the menu. Workflow-wise, the main problem is repositioning the sketch origin, which takes some extra work. The trick is to open the macro menu, go to Positioning, double-click the sketch to start editing it, then add a point where the offset should be, enable the “Reposition Sketch origin” checkbox, then click on that newly added point. This will get you the desired attachment offset value.

So much like Assembly 4, BodyBuilder is built on top of existing core features, but it takes time to set everything up as compared to using constraints in Assembly 2/2+/3 workbenches.

The Manipulator workbench​

This workbench focuses on moving and aligning objects and does not allow creating permanent attachments with fixed degrees of freedom. The three major groups of tools are Mover tools, Align tools, and Measure tools. All three have floating palettes that can be docked.

The Mover toolset is how you move and rotate selected objects along the selected axis using numeric input. All changes are relative and affect the absolute position of the object: e.g. if your part is already shifted and rotated, further changes will increment existing displacement and rotation.

If it wasn’t for the option to align the view to a selected face and then rotate around this custom axis, the entire set of Mover tools could be considered a duplication of the existing Placement functionality that allows to adjust absolute values with expressions.

The Align tools allow attaching objects by points, edges, centers, and planes to each other. The user has control over a number of options, such as:

• whether the bounding box or the center of mass of the reference object should be used;
• whether the alignment normal is inverted;
• which axis the object should be centered on (any combination is possible).

And then there’s the Measure tool that can get the radius of an arc or a circle, the length of an edge, the angle between two edges, and more. It works pretty much the same way as in other software: you need to select the first and the second elements when measuring distances between two objects or an angle between two edges. A single click on an arc or a circle will get you the radius, and a single click on an edge will get you its length. The extra label is optional and can be disabled.

This Measure tool has been modified and repurposed for the Assembly 4 workbench, so if you see similarities between them, this is not a coincidence.

The part of the feature set that deals with transforming and aligning objects has documentation and 3rd party video tutorials. Work with datum objects (points, lines, planes, LCSs), however, is entirely undocumented.

In a nutshell, despite its basic feature set and a certain overreliance on icons, the Manipulator workbench is a handy toolbox for making quick alignments. Moreover, the tools it provides are accessible in other workbenches like Sketcher, Part, and PartDesign. All you need to do is docking the floating palettes for your convenience.

Part-o-magic workbench​

The main point of this workbench is saner automatic management of the project hierarchy. PoM plugs into the core of FreeCAD and makes sure that all new objects are added to the active container no matter what workbench is currently used.

But there are other features like autohiding all parts and bodies other than the one you are currently editing until you are done. Or duplicating objects, transferring them from one container to another, locating dependencies etc. All that has its use when working on complex assemblies, particularly with the top-down approach to designing.

As FreeCAD starts gaining some of the features that PoM provides, the workbench is likely to grow obsolete.

Summary​

The main takeaway from exploring BodyBuilder and Manipulator is that there is a demand for making quick attachments of a small number of parts. So further work on a default assembly workbench should include research focusing on two things. First of all, it’s useful to understand the exact reasons people try to avoid using full-blown assembly workbenches for such tasks. Given that the UX/UI of BodyBuilder and Manipulator are not particularly easier than those of all assembly workbenches we reviewed earlier, this has to do either with project hierarchy, or with using constraints and solvers, or both. Secondly, the future default assembly workbench should be designed in a way that would keep the workflow lightweight and straightforward for these “simple” use cases.

As for Part-o-magic, some of the tools, like the deep copy of containers, look like features that belong to upstream FreeCAD.

Next Up​

We are concluding the series. In the next post, we will summarize our findings, as well as the takeaways from the public discussion, and suggest a way forward.

In the previous posts in this series, we talked about the need for a default assembly workbench in FreeCAD and reviewed Assembly 2, A2plus, and Assembly 3. Let’s talk about Assembly 4.

History​

The project was started by Zolko in 2019 after some experiments with building assemblies without solvers. Zolko came to the community with extensive knowledge of other CAD programs such as Pro/E, Catia, and T-Flex, but he was very (and probably needlessly) humble about his programming skills.

Just like with other assembly workbenches, much of the development has been affected by the user community, and a number of features have been contributed by other developers. So far, A4 is the only assembly workbench where the development pace is about the same as it was when the project started, and Zolko isn’t done yet.

Workflow and ease of use​

Assembly 4 relies on several core principles.

First off, it is built around the App:Link API that we already mentioned in previous posts in the series. In a nutshell, rather than creating a full copy of a part, FreeCAD will reference it. This makes models cleaner, and you always work with up-to-date geometry. The workbench also has the concept of a variant link which allows referencing the same object multiple times and using different parameters for each of the linked instances.

Secondly, rather than aligning characteristics of two parts (e.g. vertex to vertex), the workbench maps one local coordinate system (LCS) to another. Each body in a part can have multiple local coordinate systems. For example, the part on the screenshot below has 5 of them:

When an LCS is originally created, it is attached to a very specific feature of a part. However, if the geometry of that part changes, the LCS stays where it was. Which makes it unaffected by the dreaded toponaming issue (now being finally taken care of in upstream FreeCAD). The kind of a feature an LCS is attached to defines what attachment options are available.

Then when a new part is inserted into an assembly, the user specifies the parent part (which part to attach to), the source LCS (from the newly inserted part), and the target LCS (from the parent part):

Once both LCSs are aligned, all six degrees of freedom are fixed, and thus parts stay attached no matter what. It is, however, possible to “release” a DOF by using the attachment offset property and expressions.

We’ve seen multiple testimonials that the approach to assembling a model through LCS proves to be more predictable and robust.

On the flip side, the process of setting all LCSs is rather tedious, and attaching one part to another means you have to make more clicks than what you typically get with regular constraints.

Finally, Assembly 4 supports both top-down and bottom-up design models. We do need to point out though that with the bottom-up approach, it is impossible to insert a part from an external file without opening it as a document.

Features​

Because of how the workflow is implemented, Assembly 4 doesn’t have rows and rows of buttons to go through when you need to align one part with another. A large part of the feature set is about managing your assembly: creating new bodies and groups, inserting parts (there’s also a simple integration with the Fasteners workbench), mapping LCSs to each other etc. Apart from LCS, A4 allows creating more datum types: plane, axis, and point. Internally, those are all PartDesign objects.

A4 comes with its own tools for creating mirrored, linear, and circular arrays, as well as a measure tool:

For animation, Assembly 4 uses variables and expressions. For example, if you need to rotate a part, what you do is create a new variable and set it e.g. to 0, then use that variable in the Angle placement property of your part, then open the animation dialog, select the variable to animate, set min and max values to feed into the variable, as well as the increment value, and run the animation.

Theo Janssen’s strandbeest, model by Zolko (CC0-1.0 license)

The implementation is somewhat technical, but it works. The downside of all this is that due to the incomplete multithreading support in FreeCAD you can’t really stop the animation until the current cycle is over. Unfortunately, while animation does the trick in some cases, collision detection would still be really useful.

Despite the initial idea to not use a solver that got the entire Assembly 4 adventure going, Zolko did end up creating a solver to recompute all the links and placements in an assembly. In fact, as user ‘aapo’ explained in a recent discussion, A4 has multiple solvers and can use custom external ones. Even more, there’s a branch called ‘solver’ waiting to be completed and merged. It brings the A2plus solver to Assembly 4.

The workbench has good if somewhat scattered documentation. There are instructions for new users that explain features, basic concepts, and workflow. There are also several tutorials written by the principal developer in a dedicated GitHub repository. And some of the user documentation is in the Examples folder of the main GitHub repository.

Consistency​

Assembly 4 does nearly everything in dialogs in the Combo View, which is a fairly standard practice. No surprises there.

The workbench can work with parts created by other assemblies, although in our testing it seems like a good idea creating local coordinate systems in those parts prior to inserting them for simplicity’s sake.

There have been a number of problems getting A4 to work well with the TechDraw workbench. Most of them reportedly have been fixed.

Stability​

From the Issues section on GitHub and the forum it appears that Assembly 4 is very stable. Users mostly have problems with the Bill of Materials feature (there have been recent fixes to address some of the issues). In our limited testing, A4 crashed a few times — mostly, when editing datum objects. The number of actual bug reports (rather than feature requests) on GitHub is very low (just 1 as of March 27). However, a number of bugs are known and reported to the forum.

Performance​

We found some complaints about A4 being slow with complex assemblies. One workaround that appears to improve the situation is disabling the preselection highlight (Edit > Preferences > Display > Colors).

Development Status​

Assembly 4 is an active project with a growing share of new contributors. There have been multiple tagged releases, and the latest internal version update was in February 2023. Collectively, the community around Assembly 4 keeps the number of pull requests to an absolute minimum (just 3 open out of 245 ever submitted, as of March 27). Zolko responds to most of the bug reports within a day or two, although fixing some of the bugs may take longer than that.

Summary​

Assembly 4 relies on local coordinate systems to attach parts to each other. The workbench is fairly robust, there are very few severe issues reported by users. However, the LCS approach — as implemented in A4 — is low-level and implies a somewhat tiresome process of setting everything up.

The project has a small active team of contributors who keep the amount of unresolved issues and unmerged patches as low as possible. We also found the user community to be really enthusiastic and passionate about the project.

Next up​

In the next installment, we’ll take a slight detour and explore several assembly-like solutions: the Manipulator and Part-o-Magic workbenches, as well as the BodyBuilder macro.

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.