Look, there are good reasons why the price of a software product could go up: rising R&D and maintenance costs, market saturation, rising inflation rate etc. But Autodesk’s latest announcement of bumping the Fusion 360 price yet again makes people—especially small businesses—cringe and it’s easy to see why. It’s about what you do and how you communicate that to users:

Source: Lemmy.World

Isn’t it just a fancy way of saying “We know you love Fusion, so we think we’ll get away with making you pay more for it”?

This isn’t the first time. In 2020, they ripped useful features out of the free tier and moved it to the paid tier while promising to “continue to make Fusion 360 the most affordable end-to-end product development tool in the market”. Or, as one user at Lemmy.World said:

They pulled the rug out from underneath users years ago with F360.

This was later followed by a price tag bump from $495 to $545. And now come January 1, 2024, Fusion users will start paying $690, a 130% increase over 10 years.

Removing features from the free tier and continuously raising the price of the paid tier — it’s a hard pill to swallow. People have a deeply rooted desire to be in control of their life in general, and their software and data in particular. And this is where free and open-source software has the upper hand. Hence the influx of Fusion refugees that the FreeCAD community has been seeing since September 2020.

We think the industry is tired of playing by Autodesk’s rules. There are dozens of big and small software vendors that are chipping away at its market domination. Ondsel is happily contributing to the effort of making CAD software actually affordable for students, hobbyists, and professionals alike. We are pretty open, if not vocal about the work we do, and now you can test the latest and greatest by downloading our ‘playground’ build of FreeCAD. When you get tired of Autodesk’s ‘rebalancing’, why not see what life is like for our users?

We have just published our own build of FreeCAD with built-in Ondsel Solver and the new integrated assembly workbench. Now everyone can take an early look at the assembly workflow coming in FreeCAD v1.0.

Download the Playground

Download a completed assembly to test

In this post, we’ll guide you through the workflow and set some expectations.

For starters, we’ve prepared a short video that demonstrates the workflow.

Quick FAQ​

What is it?​

This is the Ondsel build of FreeCAD with the new Ondsel Solver and the WIP assembly workbench enabled.

What can I do with it?​

You can create assemblies, either by linking existing parts from other files or by creating new parts using Part Designer.

What to expect?​

Bugs! Seriously, this is very ‘fresh’ code. Bugs are a certainty.

Confusion. Documentation hasn’t been written yet, and it’s likely too early for that. Some things that look like bugs might be correct behavior and vice versa.

Missing functionality. Some basic things work, some basic things don’t, and all advanced features simply haven’t been developed yet. Exciting times!

Concepts​

Assembly introduces some new concepts and re-uses some concepts from other parts of FreeCAD. Let’s learn them in a tutorial fashion.

Assembly container​

The assembly is a top-level object. It contains:

• the parts that are assembled together,
• the joints (see below) that establish relationships between parts,
• a local coordinate system.

Let’s switch to the Assembly workbench and create a new assembly:

For now, you can have multiple assemblies in a document but, at most, only one can be active at a time. Activating assemblies is just like activating bodies — double-click or right-click and choose ‘Toggle Active Part’ at the top of the menu:

Adding parts to an assembly​

Before you can assemble a set of parts, you have to add them to the assembly. Select them in the tree and drag them onto the Assembly node:

Dragging parts around​

The workbench introduces a new interaction in the GUI window. It is meant to simplify repositioning parts within an assembly. Rather than using the transform tool or other positioning tool, you can just single click them in the 3D window and drag them:

A few things to remember:

• Dragging only works inside an active assembly.
• You can’t drag parts that aren’t part of the assembly
• The more joints you add to a part, the less degrees of freedom it has

Joints​

The heart of the Assembly WB are the joints. These define how parts are connected together. Right now, the workbench offers only a small subset of joint types that will become available over time.

Grounding a Part (GroundedJoint)​

A grounded part or body is one that cannot translate or rotate; in other words, it has zero degrees of freedom. The solver will not execute if there isn’t at least a single grounded part in the assembly. Select a part and toggle the GroundedJoint by clicking the respective button in the toolbar.

Adding a Joint​

Select the type of joint you want to create from the toolbar. This will open a task panel. Then select geometry from the parts. Apply the joint by clicking OK.

Joint Coordinate System (JCS)​

When a joint is being added, you’ll see the Joint Coordinate System overlaying the part. You can toggle the visibility of these off by selecting the joint in the tree and pressing the spacebar.

When you’re selecting the geometry for a joint, pay attention to where the joint indicators land. This depends on the mouse position. If you are applying a cylindrical joint, for example, you probably want to make sure the JCS is in the center of the circle and not on the edge.

Available Joints​

Only a small number of joints are currently working. This will increase in time.

	Grounded
	Fixed
	Slider
	Revolute
	Cylindrical
	Ball

ASMT files​

There’s a tool on the toolbar to export an .asmt file — an internal file format used by Ondsel Solver.

It’s a very simple plain-text file format that represents the assembly structure. Right now, we need it to help us debug the solver, because it allows us to look at how the assembly is constructed without asking for the entire project file (which could be someone’s intellectual property). Once both the Assembly WB and Ondsel Solver are stable, we will likely remove this feature entirely or reduce it to a menu item.

Known bugs and limitations​

This wouldn’t be an early preview if it wasn’t for bugs, quirks, and other slightly annoying things! Here are the things we already know about!

• So far it only works on simple solids from the Part workbench and Bodies. Other types of geometry like Part, groups, 2D geometry, etc are untested and likely to break.
• You can’t delete joints from an active assembly. To delete it, you have to deactivate the assembly, delete the joint, and then reactivate (bug)
• Part links work, but links in a link group don’t.
• Distance Joint is currently disabled, re-enabling it requires a newer version of the solver, this is work in progress.
• Assembly doesn’t work on Part object containers yet.
• There’s no visual indicator of which part in the assembly is grounded.
• To ground a part you need to select it first, then click the toolbar button. It’s the other way round for all other types of joints.
• Transforming an assembly causes an error.
• It’s very easy to break the assembly by dragging parts around in the tree.
• Dragging a part out of the assembly does not automatically remove the related joints.

Where to report your findings​

This is definitely not a one-off build, we have a lot more things in progress (think of recent Sketcher improvements, some of them still pending review). We’ll soon start adding more of those changes for early preview. Hence it makes sense to have a convenient communication channel where you can poke us about bugs or things we probably missed. So we created a Discord server where you can discuss bleeding edge changes in our build of FreeCAD. Come join and talk to us!

Free and Open-Source Software has a reputation for poor usability and user experience (UX). FreeCAD is no exception. Some of the most common complaints raised by users are about the steep learning curve, inconsistent workflow, and ugly, confusing user-interface (UI). There are dozens of threads on the forum going back years where someone has come forward with a vision to ‘fix’ the usability problem. These efforts always devolve into bike-shedding, and nitpicking. Nothing changes.

Why does this keep happening? After all, UI/UX is an established discipline. There are books and published research about it. There are consultants and ‘best practices’. Why is it so hard to make progress?

The answer is that like other parts of the umbrella discipline called ‘human factors’, UI/UX is all about humans and humans are messy. Unlike source code that either works or doesn’t, there are many ways to skin the usability cat. Most of us use software all the time with no appreciation or understanding of why it’s good or bad. We know good design when we see it but most of us can’t say why it’s good. When we use software that we like, we attribute our positive perception to whichever UI elements we notice. We overlook the thousands of other elements that don’t catch our attention because they just work right.

Mary likes the way DoodlyCAD uses ribbon bars. FreeCAD doesn’t have ribbon bars and that’s why she hates FreeCAD. She didn’t notice that DoodlyCAD has consistent task panels, great use of screen real estate, and excellent discoverability of features.

“Ok, smart guy”, I hear you say. “Is the situation hopeless? Can we possibly make progress in this area?”. Yes, dear reader, I think we can. In fact, I think we are! A small but industrious team led by Obelisk on the FreeCAD Discord server has started an initiative that aims to avoid the pitfalls of the past and move us in a direction that is data- and research-driven, productive, and sustainable.

The approach they are taking starts with first principles of UI/UX design. If you spend time reading the channel, you’ll hear terms like Fitts law, Doherty threshold, Hick-Hyman, and Usability-Heuristics. Rather than focusing on individual features, they are establishing an overarching conception of how the user experience should be organized. This isn’t a bold new vision with grand unattainable goals. It first seeks to understand and document how the FreeCAD experience works when it works well. That documentation is the Design Guide.

As the design guide matures, we can use the guidelines to review the user experience when it doesn’t work well and improve it without introducing new inconsistencies.

The project has larger goals. They’re spending considerable time talking about zones of the UI, task flow, and what the default configuration should be. They’re also thinking about how UI templates can be created that make it easier for developers to implement new functionality without needing to reinvent the wheel every time. Effort has been spent on recommendations for color use, code structure, and other details that will help addon developers make their contributions feel like a native part of FreeCAD.

"After more than 20 years of development by a global community of volunteers, an incredibly complex and advanced set of features is available in FreeCAD. My hope is to leverage all of the incredible time and effort invested by that community to present a coherent vision for both beginner and advanced users that is based on strong principles. With the highly anticipated 1.0 release on the horizon an opportunity to help provide a positive 'out-of-the-box' experience and improve general productivity is extremely exciting." -Joe Sardos (Obelisk)

Yet, it’s the short-term objectives that are likely to make the biggest difference soon. Identifying the easy fixes where user pain can be alleviated fast doesn’t just fix the problems, it gives new developers an easy on-ramp to start contributing code that will get merged. Documenting the glossary helps with documentation, translation, and the design of future features. Clear guidelines on UI elements makes it easier to develop features and it also speeds up the review and approval process which takes load off of the maintainers. It also makes documentation easier to write and faster to translate.

If our enthusiasm for this project isn’t clear, let me give you a few more reasons why we’re so excited this is happening and so honored to participate. First, the data-driven and research based approach helps eliminate the toxic in-fighting on the forum. That’s something we can all get behind. The effort is community-led but not developer driven. In our opinion, it’s wonderful to see other kinds of experts getting involved in open-source work. We would love to see FOSS being a place for UI/UX experts to build experience and ultimately a career. And finally, it provides another opportunity for the FPA to financially advance the project. The FPA is now offering grants to train UI/UX contributors who commit to work on this for an extended period.

Unlike other development efforts like the Material system overhaul or the Assembly Workbench, improving the UI is a long-term commitment. It’s many, many small improvements over time and not a single major push from a few people. It will take time but it will work. We’re on our way to a great user experience. Forward!

The basics of an integrated assembly workbench in FreeCAD are now functional and will be ready for for wider testing once another pull request is merged. This means you can play with it now in the development version of FreeCAD and when version 1.0 is out, you will be able to create or link parts, create joints between them, and solve the assembly — in just a few clicks, out of the box, without installing any add-ons.

This quick video by Pierre-Louis Boyer demonstrates all that:

This is by no means the complete implementation that we have in mind for FreeCAD, but it’s a solid foundation. And because we like to be open about our process, let’s talk about how we got to this point, how we made design decisions, what’s already available, and what else is in the pipeline.

The research​

Users have been asking for an integrated assembly workbench for a very long time. And because writing add-ons has always been the preferable way to implement major new features in FreeCAD, people did just that: multiple 3rd-party options, each with its own workflow, incompatible with one another.

Doing extensive research of multiple assembly workbenches is really a lot to ask. And thus, users got more than what they bargained for: a solution wrapped up in confusion. Whenever a new user arrived and asked for recommendations, a very common response would be along the lines of “I don’t really know about those other workbenches, I only bothered to learn this one”.

This gave us three basic options:

1. Pick one existing workbench, improve it, make it the default
2. Create a new workbench based on one or more of the existing alternatives
3. Create a new workbench entirely from scratch

We started with a deep dive into four popular workbenches — Assembly 2, A2plus, Assembly3, and Assembly4 — and then looked at a few assembly-like add-ons. If you missed that series, this final post has all the links and discusses our plan forward at the time.

The most important takeaway from the research was that every available option had some kind of workflow and/or UX/UI problem deeply rooted into its design. So we came up with the following recommendations:

1. Agree on the data structure with stakeholders to help making all assembly workbenches mutually compatible
2. Create or reuse an existing performant 3D solver
3. Build a clean new solution that could be iterated upon later to add advanced features
4. Ship a working basic implementation as part of the next big release after v0.21

Assembly data structure​

After the research, we proceeded with standardization of the data structure. So far, only Zolko (Assembly4) has been up to discussing this. Both A2plus and Assembly3 developers haven’t yet responded to an invitation to talk about it. With luck we’ll get all major stakeholders to agree on something and/or provide conversion scripts for existing assembly projects.

We ended up designing the assembly as a Part container, just like in Assembly 4. However, multiple assemblies can be created in one document. We are not married to this design decision though and will happily reconsider if users speak up.

Workflow considerations​

Before designing the new workbench, we looked at existing implementations in various proprietary CAD programs. We were mostly interested in how the workflow is organized and what program demands the least amount of clicks and learning from users.

There are two major approaches to constraining parts in 3D: either you select geometric features and mate them directly, or you create a local coordinate system (LCS) per each feature involved and then align those LCSs. Our implementation is a bit of both: the user does choose a pair of geometric features to connect, but FreeCAD also creates (and displays) a local joint coordinate system (JCS) for each feature.

We also found that, regardless of the workflow approach, developers of other programs indeed try to reduce the amount of clicks to an absolute minimum and make it easy to move parts under constraints.

Since we decided in favor of LCS (kinda), we’d be better off looking at something like T-FLEX CAD rather than Assembly4 for workflow tips. And in most proprietary CAD programs, moving a part means you just grab it and then drag it, whereas in Assembly3 you have three movement options in the toolbar (and it’s the least of your problems there).

The most approachable assembly workflow that we discovered was the Onshape’s one, hence much of our interaction design is loosely based on it.

So what can the integrated assembly workbench do?​

Our intention with this project is to create a solution that Just Works™ nine times out of ten. For the things it can’t do, the addon workbenches are still available and still good choices. The current state of the integrated workbench is a lean, minimally functional solution. It is, however, a solid foundation for building future functionality.

First off, it will support both top-down and bottom-up design approaches. Right now, you can create the assembly project, then proceed linking parts from existing FreeCAD projects. Or you can switch to Part Design and start building your parts, then go back to Assembly to constrain those parts.

Once you have all the parts you need in the project, choose a joint type in the toolbar.

So far, available joint types are:

• Fixed joint: zero degrees of freedom, parts are permanently locked together
• Revolute joint: allow rotation around a single axis between selected parts
• Cylindrical joint: allow rotation along one axis and movement along the same axis between two parts
• Slider joint: allow movement along one axis between two parts
• Ball joint: allow unrestricted movement of two parts as long as their connection points remain in contact
• Planar joint: two selected features must be in the same plane, movement is restricted to that plane
• Parallel joint: constrain relative movement of selected features to parallel translations
• Tangent joint: forces two geometric features to be tangent, restrict movement to smooth transitions along their contact surface.

When you select a joint type and hover a geometric feature of a part, FreeCAD displays a joint coordinate system for that feature:

So all you need to do is click on the hovered feature to add it to the selection (displayed in a floating dialog on the right), then pick a geometric feature of the second part and click OK.

Once all parts are connected with joints, you can move them under constraints. You don’t need an extra tool for that. Just grab a part and drag it.

Project organization​

We were really pleased with the way the TNP project operated, so we decided to model the assembly workbench project after it: public project board on GitHub (done), a mix of Ondsel employees and FreeCAD contributors (done), and atomic pull requests into the main development branch (done).

Our lead developer for the assembly workbench project is Pierre-Louis Boyer (‘Paddle’ on the FreeCAD forum) who already has a lot of experience improving UX/UI in FreeCAD.

Something we were missing was expertise in 3D solvers. We hired Dr. Aik-Siong Koh who has decades of experience in programming kinematic and multi-body dynamics solvers. He also has an existing solver originally written in Smalltalk. Dr. Koh ported his solver to C++ and made it available under the terms of LGPL 2.1+.

Another Ondsel employee (and co-founder) John Dupuy contributed to turning Ondsel Solver into a shared library and fixing build issues on supported platforms.

Outside of Ondsel, FreeCAD maintainers Werner Mayer and Chris Hennes have been doing code review of all the pull requests we submitted.

We were also fortunate to receive contributions from the design review team early on: Qewer contributed icons for joints and improved the appearance of JCS previews. Additionally, Tobias Falk and howie-j have been participating in the UX/UI discussions and providing patches.

Based on our experience with the TNP and the assembly projects so far we are confident suggesting that this collaboration model should be used more in FreeCAD. Hopefully, more companies will adopt it.

What’s next​

Our attention right now is focused on completing the use of Ondsel Solver and cleaning up the rest. If the intention to release FreeCAD 1.0 around FOSDEM 2024 is still strong among maintainers, that gives us close to three months of leeway.

Implementing major new features in the workbench in time for v1.0 seems unlikely to happen, although minor enhancements like easily inserting fasteners is a possibility. So we will mostly be finishing what we have already started to deliver a lean, minimalistic, well-tested integrated assembly workbench in the v1.0 release.

After that the floor will be open to all sorts of things: BOM generation, collision detection, assembly explosion, animation etc. We are particularly excited about the possibilities that the new materials system by Dave Carter will bring to us. If you ever needed to calculate the weight of an entire assembly or locate its center of mass, you definitely know why.

We invite everyone to help us test and improve the new workbench. There is a public kanban board on GitHub where assembly-specific tasks are managed. Right now, we need testers even more than we need programmers. So come talk to us. Report a bug or pick a card you would like to work on and comment on the related issue to get things going.

And finally, we believe this workbench will become an important part of the FreeCAD design kit. We are confident that many great things can be built on top of this foundation and we’re not wasting time. We have already started an internal project to expand the feature set beyond what you would expect from an assembly workbench with a kinematic solver. Stay tuned for updates!

We’ve already introduced some improvements to sketching with constraints before, when Pierre-Louis Boyer implemented contextual constraints. But there are more usability gaps there, and we are targeting them one by one. There’s another major change currently undergoing code review: on-viewport tool widgets to create fully constrained sketches and tool settings to set various properties and choose drafting behavior.

Drafting fully constrained sketches​

Thanks to Ondsel’s developer Pierre-Louis Boyer and FreeCAD maintainer Abdullah Tahiriyo, the Sketcher workbench is now getting UX/UI improvements that aim to improve drafting fully constrained sketches. Pierre-Louis shot a quick video for internal use that we are sharing with you.

Here is a quick explainer of what’s coming in version 1.0 here.

The usual workflow for creating a sketch is drawing shapes, then constraining them. That takes quite a while, if you intend to fully constrain a shape. Let’s say we draw just a line. To fully constrain it, we then have to:

• Select its start and constrain its distance to X and Y coordinate origins (for XY plane)
• Select the line and constrain its distance
• Add another constrain to define its angle to X (for XY plane)

Of course, there are several more ways to fully constrain a line, but the general idea is the same: draw a line in roughly the right spot, then “fix” it.

If we are drawing more complex shapes (e.g. polygons), getting them fully constrained takes even more time and effort, though contextual constraints help with that somewhat. Can we speed it up? Yes, that’s the point of this coming improvement.

Now when you select a shape-drawing tool and hover the viewport, FreeCAD will display numeric entry widgets right in the viewport. When you type in a new value and press the Tab key, FreeCAD applies a constraint, updates the shape in the viewport, and moves the focus to the next entry widget. This is how it works for a line:

Currently supported objects are points, lines, rectangles, circles, and polygons. It’s possible to add support for more object types.

Tool settings​

The second user-visible part of the patch is introducing tool settings in the Tasks panel. This helps build more expressive tools.

Different ways to define a shape will now be easily accessible: e.g. a line can be defined by the position of two points or by a combination of the start point’s coordinates, the length of the line, and the angle.

Another possibility is different shape styles. A rectangle with rounded corners can now be an option of the regular rectangle tool. Similarly, rectangles can have a frame around them with user-defined thickness.

Finally, you can use it to set an inherent property of a shape, such as the amount of sides in a polygon.

The same can be applied to arcs and conics later on.

Further work​

This is still an early implementation undergoing review, so there will be both minor tweaks and new features further down the road. Here are some of the ideas we have:

• Enabling expressions in the spinboxes
• Adding Rotate, Scale, Translate tools with on-viewport widgets
• Adding a Chamfer tool to Sketcher

Another thing we are planning to do is make full constraining an optional feature for users who want to be able to decide how many degrees of freedom they need for each particular shape. This could be a global preference setting or a quick toggle in the toolbar when you need to mix both approaches in the same project.

We are looking forward to reading your feedback. Until the patch has been merged, the best place to provide it is the pull request.

It’s common for vendors to make free licenses available to educational institutions, and while this can be helpful for enabling students to learn the tools of the trade, it can also set them up to learn some hard lessons about vendor lock-in once they go out on their own.

To add context to this piece we’ve included insights from Dr Lukas du Plessis, Senior Lecturer in the Department of Mechanical and Aeronautical Engineering at the University of Pretoria (specializing in Machine Design and Manufacturing). Dr du Plessis introduced FreeCAD to his second-year curriculum back in 2020.

Why is proprietary CAD software the default at universities?​

“Corporations offer ‘student’ and ‘community’ licenses because they hope that these will lead to users getting jobs where they will ask their employers to purchase these tools. They do not do this because they want to nurture the hobbyists or craftspeople.” – BrightBlueJim on Hackaday.com

It’s not an act of charity or goodwill for vendors to make their software free to use for educational purposes: the entrenchment of tools like SOLIDWORKS and Fusion 360 at these institutions is a key part of their pipeline as students graduate, enter the workforce, and advocate to use familiar tools at work.

These tools then become entrenched in workplaces, making it difficult for graduates to onboard if they don’t know how to use the software already:

“Not choosing Autodesk is a career ending mistake in many cases, too.” – emteycz on Hacker News

This is fine for students joining a big firm with plenty of budget for their seat. But good luck to graduates who want to start their own businesses and suddenly can’t afford the license.

This pattern is hard to shift, as educators can (understandably) be resistant to the burden of learning and then teaching a new tool. It’s tricky to coordinate across a department and align on what software is being used and taught in different years and modules. Even where educators are willing to bring in free alternatives (like FreeCAD), their lack of polish can be off putting to students.

Your students deserve better​

“F360 is probably the easiest to learn, but... I strongly recommend also learning FreeCAD so you have a backup plan if you aren’t made of money.” – LightStormPilot on r/Fusion360

As educators, your students are your customers. Your responsibility is to set them up for success by teaching them design principles, not one specific tool. Including exposure to open source solutions in curricula gives students a number of benefits:

Flexibility​

“It’s like a teacher teaching students to write a letter. The emphasis should be on the communication and writing skills—not on the tool. The teacher can’t teach the students to use Microsoft Word in order for them to write the letter.” – Dr Lukas du Plessis, Senior Lecturer in the Department of Mechanical and Aeronautical Engineering at the University of Pretoria

Of course, it is important to introduce students to industry-standard, commercial software so that they’re prepared for the workforce, but it’s a disservice not to at least expose them to the alternatives. Students who go into industry will be working in environments with mixed software, and educators should anticipate and include interoperability in the curriculum. They should be skeptical of software provided by corporations that doesn’t support data portability.

Students should at least understand that the choice of which software they use has long-term implications:

• Will they be able to switch to something else later if it becomes too expensive or no longer serves their needs?
• Will it work on their own computer when they don’t have access to their current setup?

Open source software unlocks far greater flexibility and customization for different use cases: for example, the guitar workbench presented at the FreeCAD User Conference earlier this year. “There’s no commercial package that will develop such a workbench, it’s far too niche,” says Dr du Plessis.

Performance​

This aspect of the open source vs proprietary conversation doesn’t always get a lot of airtime, but it’s especially pertinent for educational institutions: commercial CAD software is often extremely hard wearing and resource intensive, and requires bleeding-edge hardware to perform at its best. Educational institutions rarely have access to the kind of hardware needed to make the software run effectively.

FreeCAD however is better suited for this environment, according to Dr du Plessis: “I introduced FreeCAD at the University of Pretoria and it’s not very hardware intensive—we’ve had no issues in the computer labs.”

Institutions can be the change​

It’s encouraging to see some educators taking initiative to change the course. Dr du Plessis, as mentioned above, has been advocating for students to get exposure to and learn FreeCAD at the University of Pretoria.

The university historically has taught SOLIDWORKS to students from their first year. As he started learning FreeCAD himself, Dr du Plessis has been introducing FreeCAD to his second-year students since 2020. “It doesn’t make sense to have access to free software, but then only afterwards the students need to start paying for exorbitant licenses.”

In 2019, Dr du Plessis received funding from the UK’s Royal Academy of Engineering to develop a separate workbench inside FreeCAD. One of the deliverables was to introduce FreeCAD in the university’s undergraduate program, which helped give credibility to the initiative.

“I make students very much aware of the fact that commercial packages come at a premium,” says Dr du Plessis. “I also push hard for them to understand that there is a free version. Yes, it’s not as refined, but it’s good enough for 95% of what they want to do.”

Dr du Plessis also has a vision for what he calls FreeCAD Free Labs to make FreeCAD more accessible to more makers.

What educators and students can do​

Yes, there is a burden to learning new technology and then teaching it to your students, but there are a lot of free resources out there that you can point students to. You can lean on educational creators like FreeCAD Academy on YouTube and the FreeCAD community so you can focus on teaching design principles.

To any students reading this, it’s also up to you to take responsibility for your own education. Be wary of any educator that requires a particular tool rather than teaching you the principles of use that can be generalized. You don’t need permission to explore alternative tools.

The FreeCAD Project Association is interested in broadening the use of FreeCAD in education. They’ve set up a brief survey to gather feedback and start building a network of interested people. They’d love to hear from folks in academia but also non-traditional educators making YouTube content or paid courses.

Take The Survey​

How to build 3rd-party addons for FreeCAD that don’t suck There’s well over 200 various addons for FreeCAD available just in the official add-on manager. Many more possibly flew under the radar or simply never have been shared with anybody.

For some developers, creating an add-on is a way to test ideas and see if they resonate with a larger audience. For others, it’s the first step towards contributing to FreeCAD itself. The add-on ecosystem is hugely important for the community at large.

But many great ideas die because the add-on implementation suffers from one or more common and avoidable mistakes:

• Not designed to make contributions from other developers easy.
• Built with implementations of things that are core FreeCAD features.
• Not built with good software practices in mind, think modular code, unit tests, separation of UI and non-UI logic.

This isn’t a criticism of the addon developers. Nobody is expert in everything for many open-source contributors, writing an Add-on is their first experience contributing to a large project.

Over the last decade, I patched other people’s add-ons and wrote some of my own. In this post, I’d like to share what I think are best practices of developing 3rd-party add-ons for FreeCAD. There’s a technical and a design aspect to this.

Technical advice​

Design the UI with QT Creator and use the .ui files directly.​

There are several reasons why this is a great idea. First off, this makes the code simpler. Hundreds of lines of Qt code are replaced with a single line to load the .ui file like:

Form = FreeCADGui.PySideUic.loadUi(dialog.ui)

The UI logic becomes much cleaner and more testable. Secondly, UI designers are used to working with visual tools. They can often improve the look and feel of a dialog or task panel quickly. Using the UI files directly rather than hand-coding Qt or converting the .ui file to python makes it much easier for UI designers to contribute. The wiki has lots of information about designing and using .ui files.

Separate the UI logic from the application logic.​

From the beginning, FreeCAD was designed to run without the GUI at all. It’s amazing how much you can do with FreeCAD by calling it from external scripts. So it’s really frustrating to find a great piece of addon functionality that won’t work this way.

Ideally, the UI logic is separated from the rest of the application code. Designing software this way doesn’t come naturally to amateur programmers but it isn’t too difficult and is worth learning. Even a very simple addon or workbench should have at least two Python modules, one with the logic for managing the UI, getting input from the user, and displaying it. The second module does all the interesting stuff, and it should not import FreeCADGui.

Stick with rules of thumb​

There are some very simple rules that help keep the code clean, readable, and testable. Like all heuristics, they aren’t written in stone and there are times to ignore them. That said, take the time to understand why they exist.

No function longer than 200 lines of code. There are various recommendations regarding the length of a function, but 200 LOC seems like a reasonable maximum. The general idea is that a function should do just one logical thing and could be explained in one sentence. This list of red flags for when a function is too long should serve you well (thanks to Ryan Delucchi).

No module longer than 1K lines of code. For pretty much the same reason — readability, maintainability etc. — Python modules shouldn’t be too long. Keeping python modules short has a subtle effect on code organization. It naturally encourages better encapsulation and separation of concerns, two key concepts in software development.

Write pythonic code. Unlike communities around other programming languages, the Python community, is very opinionated about code conventions. Adhering to these conventions makes Python code more readable and more efficient. Here is a very good overview by Xiaoxu Gao of what makes code in Python “pythonic”.

Use Black formatting. Code formatting is sometimes a contentious issue. Part of being ‘pythonic’ is adhering to a community standard for formatting. The standard is formalized in PEP 8 which asserts a number of code style conventions. Pycodestyle will check your code against those standards (and complain when you break them). Black automatically reformats your Python code to comply with those conventions.

Write unit tests first. Nobody likes writing unit tests but everyone likes having them. Regressions are easy to introduce and difficult to catch. Unit tests invert that by making regressions harder to introduce and easier to solve. They also have a subtle effect on how you program. When you have to write unit tests, you start to write more testable code. So write unit tests early on to stay on top of it.

Make UI translatable from day 1. Popular addons tend to get translated into other languages. Designing an addon with localization in mind from the beginning means you free yourself from redesigning it later on to introduce UI translation support.

Make user-facing objects parametric. If the addon adds document objects to the project and expects the user to interact with them after creation, the important attributes of the object should be exposed through properties. We’ve seen good ideas implemented in such a way that if the user makes an error during the creation of an object, the only recourse is to delete the object and restart. If the creation of an object involves a task panel, double-clicking on the object in the tree should re-open the same task panel and allow the user to change settings. FreeCAD wiki has an article that explains how to write FeaturePython objects the right way.

Be on the lookout for things that belong in the core​

Occasionally features developed in a workbench really should exist in the core. A good example of that is the Sheetmetal workbench. There’s an interesting bit of logic that unfolds a shape to produce a flattened version. The unfolder is computationally intense and would benefit from being implemented in C++ rather than Python. A powerful and efficient unfolder might also have utility in other workbenches. It sure takes more time and effort to communicate with other developers, get these things written correctly and merged, but it makes addons simpler, faster, and more maintainable.

On the other hand, be on the lookout for things that already are in the core. Inexperienced developers often reinvent the wheel and do it poorly. Experienced developers communicate a lot. So when you design an addon, talk to your peers and discuss your design. It could very well be the case that something you need or already exists and works just right for you.

Design advice​

FreeCAD has the beginnings of a style book. While work on it is ongoing, here are some important considerations.

Don't make the user think. In free and open-source software, the concepts of usability and discoverability are often overlooked. Do your best to design an addon with a straightforward workflow that gets users from A to Z in the least possible amount of time. Give the user a result with the minimal amount of input and let them revise and improve the result incrementally. A feature that requires the user to do many things exactly right before outputting anything at all is confusing and will be ignored by most users.

Chunking. If there’s one thing you can do to make your user-interface and workflow better it is to group controls together so users can process them efficiently.

• Toolbars should have neither too many nor too few buttons. Seven, plus or minus two, is a guideline often invoked.
• The buttons should be grouped logically. Consider that the user may hide the toolbar or drag it to another part of the screen. Menus should use separators to make them easier to process.
• Dialogs should use group boxes, frames, and tabs to allow efficient recognition of controls.

Don’t just gravitate to workbenches. There seems to be a popular idea that a workbench is the right kind of addon for anything. And so there are some 3rd-party workbenches that should have been a non-workbench addon, an extension of an existing workbench, or even a core feature. But workbenches are destinations, if you build one, you should expect that people will park there for a while and will be unwilling to jump between workbenches all the time. So when you choose what type of an addon you are creating, think primarily of workflow and tasks.

What to do next​

If you are planning to write a new FreeCAD addon or improve one you have already created, I recommend paying close attention to FreeCAD Developer Guide. This is where the team formalizes both programming and design conventions, as well as provides actionable advice. If the guide is missing the information you need, I encourage you to file an issue against the guide on GitHub.

One of the hallmark features of FreeCAD is that various parts of its UI have a lot of similar options, which means a lot of cognitive load, especially for beginners. A very popular “offender” here is the geometry constraints toolbar in Sketcher. It has 18 different constraint options, more than most popular commercial CAD offerings like Fusion 360, Onshape, and Creo. That's not a bad thing on its own, but it adds a lot of mileage when you need to dimension an entire complex sketch.

Before joining Ondsel, Pierre-Louis Boyer (@paddle) started implementing a feature called contextual constraints to help users constrain faster. Since joining Ondsel, he has finished the patch, and after some discussion and code review it was merged to become part of future FreeCAD 1.0. This new feature is quite nice and surpasses what many commercial CAD applicaitons are able to do. So let’s take it for a drive and kick the tires!

When you select a geometric feature in a sketch, there’s a finite number of constraints you apply once you select the second feature. For example, if you select a line and then an endpoint of another line, your most meaningful option is a distance constraint. But if you select a line and then another line that’s at an angle to the first one, the angle constraint is the most meaningful option, and your other option is to make those lines equal.

Once you know that, you can devise a system that looks at the selected features, suggests the most sensible option by default, and allows switching between possible options easily. This is what the new contextual constraints system does. It helps apply constraints based on the context of what the user has already done. You select the new Dimension option (D shortcut) and go over your entire sketch to constraint and dimension various parts of it.

The new option combines various pre-existing other ones: constraining distances, radii, diameters, angles, and a constraint lock.

Here is a quick example. Take two lines that have different length and are at a random angle and distance to each other:

Then select the Dimension option and set the length of the first line:

Set a distance between the two lines by clicking the line and then the closer endpoint of the second line:

Constraint their angle by clicking the first line and the second line:

And finally make both lines equal by clicking the first line and the second line and then pressing M to switch to the second contextual constraint option:

You can constrain this sketch further by clicking on an end point of one of the lines and setting a lock, all with the same Dimension option. Most importantly, all of the steps above are completed without needing to choose a different tool in the toolbar.

For cases, when you absolutely need to have quick access to individual constraint options (just like in v0.21 and earlier), you can continue using keyboard shortcuts or selecting those options in the drop-down list:

Preserving that possibility was one of the requests from users.

The new option also allows switching between complementary angles depending on the position of the mouse:

This implementation was possible thanks to active discussions both on the forum and in the issue tracker. More improvement is still possible. Join us if you want to be part of making FreeCAD awesome and many thanks to users and contributors for their input!

Pull request rot is a quick way to turn off first-time and long-time contributors. The merge meeting is one way to get PRs moving again.

“It isn’t just about the license, but the way that Hashicorp has maintained the Terraform project. … there are open issues and pull requests that just get ignored as Hashicorp clearly doesn’t see value in open source contributors.” – tedivm on Hacker News

Tensions around the application of open source philosophy have been discussed a lot in recent weeks, and I want to touch on one of the objections to the recent Hashicorp news here. We’ve talked about stale issues on this blog before, and we can see in the above quote that ignored issues and PRs do have a real impact on contributor motivation and sentiment towards a project. There are a lot of reasons why some PRs slip through the cracks, but there are things you can do to catch them.

Why some PRs fail to get merged​

PRs can suffer death by neglect or by a thousand cuts. Maintainers that ignore PRs or let them get tangled up in dozens of comments (debating the right way to address a problem or implement a feature) can expect one-time or burned-out contributors, slower releases, and a lot of wasted effort on rebasing.

The PR is too large to effectively review​

PRs that do too many things or touch too much of the codebase at once pose a risk of unforeseen side effects. They’re just too unwieldy to review thoroughly (sometimes even GitHub won’t render the entire diff in the PR), so the reviewer doesn’t feel comfortable taking responsibility for merging.

The goals of the PR are too obscure​

Some PRs don’t explain the original problem sufficiently for someone to be able to test their behavior. That’s one end of the spectrum—at the other, not everyone contributing to a project has the same use cases, goals, or needs. Once the project evolves beyond its initial purpose and scope, you can end up with PRs that touch or implement an obscure feature that maintainers don’t understand or feel confident in reviewing.

Competing solutions exist​

There are usually multiple ways to solve a problem. A PR that implements one solution can devolve into a debate about the merits of that approach over others, because no consensus on direction was reached ahead of time. Sometimes there is no precedent for the reviewer to fall back on, or they lack the institutional knowledge or context to make the call.

There’s a lot of overlap with our discussion of why RealThunder’s branch with a topological naming fix for FreeCAD hasn’t been merged yet.

Solutions​

Bring alignment forward​

Better issues → better PRs. If you can find alignment (if not consensus) at the issue stage, you avoid a lot of the agonizing over philosophy and implementation in PRs. Documenting best practices and approaches in a project charter or requiring design documents upfront can help with alignment that preempts endless debate.

Set realistic expectations​

Maintainers—even of small projects—need to communicate the expectations and process for successful contribution.

“If you have no plans to maintain hobby code, you should discourage usage. Say it right up front: ‘TagTree is unsupported and not meant for use in a production Dart application, unless you're willing to fork the code and fix any bugs you find yourself.’

Or if a project is widely used but difficult to contribute to, you should say so up front, like this: ‘Contributing code is one of the more difficult ways to contribute to Guava, and is almost never what the project really needs most [...] We know it's tempting to submit code before the feature is accepted, but this is not always a good use of your time.’” - skybrian on Hacker News

A contributing policy should, at the very least, tell contributors when to expect reviews and how to give their PR the best chance of getting merged.

Reduce the burden of reviewing​

You want reviewers to be able to focus on big-picture factors like the performance impact of a PR or alignment with project direction, not spending time on undifferentiated gruntwork. You can do this by ensuring you have extensive test coverage and automation wherever possible.

Communication​

The PR (and related issue) is an act of communication. Both the contributor and the maintainers have a responsibility to communicate effectively.

Contributors should make very few assumptions about what the maintainers already know, and make it extremely easy to understand the context of the PR, the original problem, how the solution works, and any concerns. Maintainers should ensure that communication is ongoing. Using bots to bump PRs for updates helps to remind reviewers that a PR is outstanding, but also reassures the PR author that it hasn’t been forgotten (for example).

Progress over perfection​

You can always iterate after merging. If you spend too much time trying to get the PR perfect, a new contributor may get discouraged and never come back.

The merge meeting​

Even if you implement all of the above tactics successfully, sometimes knowing whether or not to merge a PR is hard. When people are uncertain, they will defer to others. Everyone can end up differing and nobody takes action.

To combat PR stagnation, FreeCAD has started having synchronous merge meetings including maintainers and contributors to discuss next steps on outstanding PRs. This live session is important and serves a number of purposes:

• Teasing out concerns and unspoken worry
• Multiple contributors share the risk of merging a PR
• Multiple perspectives put concerns into proper context
• Multiple perspectives offer novel and productive outcomes

Maintainers are referees in the meeting, making sure each contribution is evaluated according to the process. Did it start with an issue? Was there some consensus on the solution? Is the code passing CI?

We won’t hesitate to kick something back if a contributor blatantly ignores the process, but we try not to be militant and will merge good-faith contributions. Sometimes this means merging things we are (mildly) uncomfortable with because the contributor did everything by the book. When that happens, process says you merge.

What does this look like in practice?

• “Let’s ask [another contributor] for a code review, she knows about this module”
• “This PR is really doing two different things. Let’s ask the author to split”
• “This PR and that other one are in conflict. Let’s get those two people talking”
• “This is low risk. Let’s merge it and see if anyone complains”
• “This is a major feature and we’re close to a release. Let’s push this to the next milestone”

Merge meetings help us move faster now and in the future​

The value of these meetings is multifold. We clear a lot of our PR backlog quickly, avoiding the bystander effect that sometimes arises from having multiple reviewers assigned to a PR. We rely on early issues and the contributing policy to ‘push back’ on poorly implemented fixes and rushed code.

Apart from the immediate effects of getting more PRs merged faster, there are longer-term effects.

The merge meeting naturally encourages more discussion of milestone and release goals. We learn which maintainers have a ‘bigger picture’ of the project and community, and the ones who don’t get coaching by participating in the process. As you build consensus as a group, you expose and codify the implicit rules and standards that more experienced reviewers use in their assessment of PRs. By working together to agree on standards of what is acceptable, everyone builds their confidence.

The merge meeting is a good place for maintainers to learn:

• About the codebase
• About the project’s policies and why they exist
• To take appropriate risks
• How to think about a contribution (maintainers learn from each other how to be better at evaluating code)
• About the tools available in the platform

It’s also a good place for contributors to learn about how merge decisions get made and to weigh in on others’ PRs (not just advocate for their own).

Join us!​

The merge meetings are listed on FreeCAD community calendar and are open to anyone. Join the next merge meeting.

Historically, the duration of FreeCAD development cycles has been uneven, anywhere between a few months and 2+ years.

We already talked about reasons and ways to make releases more predictable in one of the recent posts. But the truth is, this is a much older conversation that has been going on in the community for years now: at FOSDEM, in the forum, and in various other venues and social channels. The hackathon in Vancouver was a perfect opportunity for the developers community to set some boundaries for v1.0.

We ended up formalizing a list of 4 major items for the v1.0 roadmap that we think are a must-have to constitute the next release. None of these items are big news, we’ve all known about them for a while: the complete topological naming fix, a default Assembly workbench, a new implementation of a materials system, and the first-run wizard.

So let’s cast a quick glance at these items and talk about respective challenges.

The toponaming fix​

We’ve already discussed this topic in the past, the latest post from July covers the current state of affairs in detail. It looks like we’ve already done a very difficult part of this project. Further work is not going to be easy, but the foundation for the next phases of the fix is sound.

The team is now approaching the third phase of the fix (out of five), there’s an initial plan available. As the third phase is where FreeCAD actually starts using the new toponaming infrastructure, this will be a perfect opportunity for new contributors to get involved. The dedicated Telegram chat is the right place to start.

The default Assembly workbench​

This is one of the more challenging items on the list of v1.0 deliverables. We think FreeCAD should have a capable assembly workbench and that really means two things:

1. A workbench where the user configures the assembly, adding parts and establishing relationships between them.
2. A solver capable of resolving those relationships and moving the parts of the assembly appropriately.

All that should be the default experience, no third-party add-ons.

Dr. Aik-Siong Koh, who is an employee at Ondsel, published the source code of his solver during the hackathon. This will be one of the foundations of the coming Assembly workbench.

For the user-facing assembly workbench, a lot of work remains. One of the challenges will be coming up with a user interface and workflow that are both discoverable, straightforward, and expandable. It doesn’t need to cover every use case. Remember that the existing assembly options are still viable and may serve different users well. Rather the integrated solution should strive to be robust, simple to use, consistent with the rest of FreeCAD, and an excellent platform for future expansion.

The main challenge here will be building a team similar to the one we have for the TNP fix — a mix of Ondsel employees, FreeCAD maintainers, and 3rd party contributors. This has proven to be a great balance between interested parties, and we want to replicate that success.

The project will be managed as a GitHub project in the FreeCAD organization, with cards and issues. Similarly to the toponaming project, we’ll work in small incremental pull requests and merge the changes directly to the master branch rather than wait until the workbench is fully functional. An initial barebone implementation has already been merged to the main development branch.

Materials​

The existing materials system in FreeCAD is overly simplistic, all over the place, and doesn’t even scratch the surface of what users really need it to do. So the program absolutely needs a solid foundation.

Earlier this year, we posted an implementation proposal for a new materials system written in collaboration with Dave Carter who volunteered to actually do the work. Dave is, in fact, knee-deep in that project and has made a lot of progress (the branch with his code is public). Moreover, users have been very supportive of his effort.

The first pull request has already been filed and is undergoing review. Further plan with materials is to apply the toponaming development model: break all further work down into small pieces, so that any developer could be part of that effort. Once the initial patch has been merged and further work has been decomposed into small items, more developers can join the effort. All further work will be done in pull requests. This will make it possible to deliver the minimum viable implementation in time for v1.0.

First-run wizard​

FreeCAD has a difficult learning curve. Improving the initial user experiences is a topic that resurfaces regularly. We even covered that in a recent blog post. Here is the gist of the issue.

First of all, people can’t really agree on the scope of the first-run wizard. There are literally dozens of settings that users requested to be editable when you run the program for the first time. But when you dig deeper into the reasoning, several things become obvious.

First there are configuration settings for which a single default will never suffice. Language and the unit system are the two that come to mind.

Some configuration options appear to be personal preference but might also have more significant usability implications. For example themes and colors are personal preference, but they become extremely important if you suffer from color deficiency. Users will never agree with each other about that, so those have to be easily configurable.

Other things that people want to configure should probably be solved in other ways. A great example of this is configuring which workbenches are available and active for a new user. Should the system present a bewildering array of workbenches to a new user or should it hide potentially useful tools in an effort to be streamlined? Reasonable people disagree. In this case, the right answer might be to improve the Start workbench. This would provide a fast track to the workbench based on that task that they need to accomplish. Initial mockup was created and then turned into a pull request by Qewer during the hackathon. This patch has already been accepted and will be part of v1.0.

On yet another level, this is a conversation about terminology. A much-discussed example here is the distinction between Part and PartDesign — users inevitably learn to understand the difference, but they are off to a rocky start, and there are some technical issues to take care of on the developers’ part.

Hence the plan is to come up with a minimal implementation of the first-run wizard, one that would deal with things that users are split over regardless of how sensible defaults are, and then see take a holistic approach to dealing with the rest.

And now the fun part: can we get v1.0 out by FOSDEM 2024?​

We think that these goals are within reach and it should be possible to release FreeCAD 1.0 in time for the next FOSDEM. Here’s our thinking behind this goal.

The TNP fix and the new Materials system are at the stage where the nature and the amount of work yet to be done are fairly predictable, and a large part of the heavy-lifting has already been done.

The initial Assembly workbench will be a challenging project, but now that we have a solver, we can start working on designing UX/UI around common use cases.

The design and the implementation of the first-run wizard itself would be a minor development effort, and there are people in the community who already spent a considerable amount of time creating mockups and even writing code. The challenging part will be taking a holistic approach to dealing with configuration and improving initial user experience, but we can make this effort span across multiple releases, there is so much to improve anyway.

To reiterate, v1.0 will definitely have changes apart from these 4 items. What we are aiming for is to start making development more predictable. Gaining some focus will help the team with both planning their work and managing expectations of FreeCAD users.