For what shall it profit a man, if he shall gain the whole world, and lose his own soul? -Mark 8:36

Late last year I was talking with Open Core Ventures about the possibility of starting Ondsel. It was exciting to hear from people outside the FreeCAD community who shared the vision that this software was important and could be so much more than it already is. As the idea of actually starting a company took hold, the first important decision was which legal structure the new company would have. Two things that I read deeply affected me and shaped the final decision.

The first was an article by Jen Barnette that highlighted five considerations for being a public benefits corporation (PBC).

At a time when ambition often clashes with integrity, the formation of Ondsel as a Public Benefit Company (PBC) should stand as a testament to our belief in conscious entrepreneurship. The ethos of open-source software, characterized by collaboration and transparency, frequently finds itself at odds with the profit-driven dynamics of the modern tech landscape. Ondsel's genesis as a PBC exemplifies a commitment to upholding the soul of open-source values, even in the pursuit of success. Open-source software, a cornerstone of the digital age, embodies the spirit of sharing, transparency, and collective betterment. But, as projects mature, they can wrestle with the challenges of sustainability. Developers who once dedicated themselves to a project out of love find their efforts ensnared by financial considerations and proprietary boundaries, straying from the core essence of openness. Ondsel's inception as a PBC is a direct response—a proactive stance to prevent the dilution of these core values. The five points that Jen described meshed well with my own thinking and I made sure to include them in our own handbook. I revisit them often to make sure my thinking doesn’t drift away from the core values we started with.

The second thing I read was Simon Sinek’s book The Infinite Game. He suggests that a company should have a “just cause” that inspires people because it explains why you’re doing what you do.

For me, this one was easy. Human beings are creative and social creatures. Not everyone creates physical things but Everyone is a maker of ideas. We enjoy sharing our ideas, talking about them and improving them. Sometimes those ideas turn into physical things that have beauty, utility, and value. These days, you need tools to express your ideas so others can build on them and we need everyone’s best ideas. People deserve access to tools to help them express their ideas, share them with other people, and use them to produce useful things that benefit all of us. Ondsel wants to make powerful, efficient, and beautiful design tools available to more people.

FreeCAD is commonly criticized for being difficult to get started with.

This criticism, while possibly overstated, is valid.

• Features get more development attention and the UX/UI design is usually an afterthought and “anything goes”. As a result, there’s not much consistency across the program.
• The learning curve for modern CAD systems is a wall. There is even occasionally pushback against simplifying UX, because “CAD programs are supposed to be difficult and take a lot of time to learn". Effort to improve UI is seen as "dumbing it down”.
• The program is trying to be many things at once: a 2D drafting program, a 3D design program, an Arch/BIM program, a CNC program, a structural analysis program — and that’s just a subset of workbenches available by default. All the while not much thought has been given to help users navigate the options when they see it for the first time, or customize FreeCAD for their use cases.
• Terminology used in the program is inconsistent and confusing. Part vs PartDesign is one of the recurring topics in the community. But also “path” could mean a toolpath, a sweep path, or a file path depending on where in the program the word is used. These are just a couple examples.

For a long time there have been calls for a first-run wizard (FRW) as the way to fix some of these problems. If you are not familiar with the concept, the idea behind FRW is a feature that runs the first time a user launches a program and helps orient the user to the software by allowing them to choose how the program will look and behave or by onboarding them in other ways.

While investigating this feature request, we looked into what other programs have to offer, and our conclusion is that while something is needed, this request is problematic and the specific solution has poor consensus.

What’s wrong with the feature request?​

First and foremost, the issue is poorly defined. This issue predates the current contributing policy, it doesn’t start by identifying the problem but jumps immediately to the solution. People have seen similar solutions in other applications and have an intuition about them. But the notion of a first-run wizard brings different ideas to mind. In fact, our research showed that these tools are employed to address at least three different problems:

• User preferences make a big difference to usability but the settings are difficult to find or scattered in many places.
• The optimum configuration of the software varies depending on the specific task the user is undertaking.
• Important features are occasionally overlooked by users leading to frustration and increased support demand on the forum.

These are three very different problems and their solutions are unlikely to be the same thing. It makes sense to address them independently.

Even if we narrow the focus and assume the feature request is only about customizing the software for the user’s needs, we still have a challenge. Consider this bewildering list of things that people have suggested should be configurable when you first run FreeCAD. We call it The Problematic Wishlist:

• Simple vs advanced layout (e.g. don’t show FEM workbench to a newbie, show less buttons in toolbars etc.)
• Which workbenches (WBs) should be visible in the UI, with presets (Mechanical CAD, Arch/BIM etc.)
• What WB is selected on startup
• UI language
• Units and unit schemes
• Theme (dark/light/classic)
• Enabling/disabling Treeview Glass theme
• Icon theme
• Highlight color
• Icon size
• Font size
• Viewport background color
• Navigation style
• Enabling/disabling warnings in weekly builds
• Enabling/disabling “What’s This?” button
• Monitor aspect ratio selection for optimized layouts
• Panel layout options
• Default file storage location
• Autosave and backup policy
• Authoring and license info

While it may be technically possible to implement all this in a first-run wizard, it would be a perfect example of creating a bigger problem by trying to fix a smaller one. It would be overwhelming to the user trying to get started and would complicate development since configuration would have to be maintained in both the FRW and the system preferences.

What other programs do​

As part of the research phase, we looked at what other programs offer in terms of customizing UX the first time you run a program. The question we asked was just this: do other teams solve the same issues by offering a first-run wizard or do they do something else?

We started with CAD programs and then moved to other kinds of applications (3D modeling, image editing, vector graphics editing, audio production). Basically, any sophisticated program with lots of configuration options, aimed at professionals and designed for multiple use cases is worth looking at.

Right off the bat, among non-FOSS CAD packages, only BricsCAD provides something that vaguely approaches a first-run wizard. Every time you launch the program, a dialog asks what kind of work the user wants to do: 2D drafting, 3D modeling, mechanical design, or BIM. The same launcher window also asks whether the user wants metric or imperial units. And this is it.

But you don’t even need a dialog for that. Multiple programs provide a simple choice over the type of project you create. In some cases, it’s just a drop-down list of project types or a library of templates.

The only two programs that do have a first-run wizard are FOSS programs. LibreCAD asks for the default unit, GUI language, and command language. QCad asks for GUI language, default unit, default paper size, decimal point, and background color (black or white). Not too surprising, as the former is a fork of the latter.

The situation is pretty much the same across other industries we looked at.

Blender seems to be the only major 3D modeling package that has a first-run wizard. You can set UI language, shortcuts preset, right-click vs left-click for selection, spacebar behavior, UI theme.

None of the big boys in image editing, like Adobe Photoshop and Affinity Photo, have a first-run wizard. Ironically, GIMP is the program that used to have one, got rid of it, but is likely to have one again. In short, the original wizard asked questions that could be automatically detected from various system settings, and users found it annoying. But then developers made changes to defaults (enforced default dark theme and symbolic/colorless icons, as well as grouped tool icons in the toolbar), and that, too, annoyed half the user base. So they want to reintroduce the first-run wizard at some point in the future.

Similarly, Inkscape seems to be the only vector graphics program with a first-run wizard: you can choose canvas look (transparent checkerboard, white opaque etc.), shortcuts theme, icons theme, dark vs system UI theme.

Among proprietary digital audio workstations Cubase seems to be the only one that bothers users with questions, and even that during installation when you need to select a preferred audio interface. Once again, a FOSS program is an exception: the first time you run Ardour, a wizard asks for GUI and font scaling and the default folder for new sessions. The first part of that, however, is a toolkit limitation. Ardour still uses GTK2 for some part of its UI, and GTK2 is notoriously oblivious of HiDPI displays.

Across many industries, developers recognize that learning to use their software efficiently takes time, so they build links to training materials into the user interface. This is something FOSS developers are beginning to do, too. For example, MuseScore has links to educational videos on YouTube, and FreeCAD has links to the wiki.

So what did we learn from this?

• Very few programs actually provide a first-run wizard. Proprietary programs typically enforce a certain choice of defaults even for controversial things like the look and feel, but, to their credit, usually make it rather easy to customize certain things.
• There are obvious polarizing topics. Some of the defaults are things that users just can’t stop arguing about. This is exactly what first-run wizards in FOSS programs like Blender and Inkscape focus on.
• Measure units surprisingly do not cause all that much controversy. Figuring out the right units from locale settings is perfectly doable, so it’s possible that this is why very few CAD programs even bother exposing those when you run them the first time or create a new project. Typically, there is a global configuration that applies to new projects and a simple way to override it on a per-project basis (an unfinished patch for the latter exists for FreeCAD).
• There’s usually a very obvious way to get to the right tools. Applications like Inventor make it very easy to create a 2D design or a 3D model. Usually, it’s just one or two clicks away, and the UI for that is in a very obvious place.
• CAD programs usually have a learning center for newly arrived users. This is something FreeCAD already does, but there are ways to improve it. A topic for another day.

Our proposal​

Based on our findings, we think it’s best to attack the issue of suboptimal first user experience from three angles: minimal first-run wizard, better defaults, and continuous UX/UI improvement.

Minimal first-run wizard​

Let’s learn from the experience of other projects. Right-click selection in Blender was a huge annoyance for new users right up to the point where left-click selection was finally implemented and the first-run wizard started offering the choice between the two options. The lesson here is that there will always be things that users are split over, we are not going to change everyone’s mind, ever.

Therefore the first part of the solution is to build a minimalistic first-run wizard that will cover just that: visual style, navigation style, units, GUI language. We can further refine the wizard based on feedback from users. Designing and implementing the dialog is not too complicated, and there have been several approaches to do so already.

Better defaults​

Certain things on the wishlist above could absolutely be better defaults. For example, we can enable backups by default and set a sensible number of versions to be saved.

The tricky part here is coming up with a definition of what constitutes a sensible default. This is something we will have to further explore.

In our experience, it’s useful to keep each conversation about defaults narrowly focused. For example, we’ve already had a lively if slightly heated discussion over disabling some of the workbenches in the workbench selector by default. Breaking that conversation into several dedicated GitHub issues has helped to keep the discussion productive, so now there is a GitHub project for cleaning up the workbench selector.

This task of making good defaults will likely never be 100% completed as FreeCAD keeps changing. So we should treat it as a continuous effort.

Continuous UX/UI improvement​

This last part of the solution is a lot more interesting. Let’s analyze the rest and see how we can improve the UX/UI to deliver a better initial user experience and maybe remove the need for configuring certain things when users run the program for the first time.

Here is an example. One of the ideas for the first-run wizard is to allow users to configure what workbenches they want visible by default. To reiterate, someone who, for all we know, is probably looking at the program for the first time, is supposed to somehow guess what workbenches they actually need without having ever used them. That doesn’t sound like a very likely scenario.

And then some experienced users could have different uses for the program. You can be an architect who needs Draft, Arch/BIM, and just a few more WBs. But you also tinker with stuff in your spare time, so PartDesign and Path are no strangers to you.

Basically, FreeCAD needs to adapt the UI based on context. There are several established approaches to deal with that. Named workspaces is one of them. But another approach is to improve the start screen. If you create an architectural project, you automatically get a certain set of workbenches available to you. You can further refine that selection, if you want to, but the default user experience will already be streamlined for you to a large extent based on the type of a project you create.

The first step towards that has already been done. Thanks to Qewer, v1.0 will be coming with an update start screen listing several typical new projects that are basically a fast track to a particular workbench.

The full implementation of that would eliminate two items from the wishlist: 1) what WBs should be visible in the UI, and 2) what WB is selected on startup.

This kind of a holistic approach to designing UX/UI should serve the project much better than what we have had so far. We also don’t have to deliver the full UX/UI redesign of FreeCAD for v1.0, this kind of refinement can go on for as many development cycles as we can handle.

What’s next​

Improving the user’s initial experience of FreeCAD is not a single work effort. There has been good work done in this area already including an ongoing discussion about the first-run wizard in the issue tracker, but discrete, solvable issues need to be extracted from that and solutions built for each of them.

The first issue to address is the narrowly defined set of configuration options which users routinely disagree about: language, units, navigation style, and theme.

Tailoring the application to the task should be addressed by improving the start page and providing better defaults whenever possible. As noted above, some work has already been done.

That leaves the more subjective work of explicitly educating the user about FreeCAD conventions, UI tools, shortcuts, and the general UX/UI improvements. Both of these need more research and feedback from the community. This is an area where we need better and more actionable data from community power users and moderators about where users are confused.

There will likely be a GitHub project focusing on UX/UI cleanup. Stay tuned for more news on that.

Why do we see a lot of first-time contributors to the Path Workbench?​

Besides working on Ondsel, I mostly work on the Path Workbench. Path has a unique user base made up of hobbyists and machinists. These people are using Path to generate G-code for the CNC machines and the code almost always has to be tailored for a specific machine. Once you’ve edited the G-code once or twice, it’s natural to want to customize your postprocessor and that means editing a little Python code. Occasionally, one step leads to another and the user wants to contribute their changes ‘upstream’ so they can be used by others. It’s a common story and is, in fact, exactly how I got involved in open-source development.

As a maintainer of FreeCAD, I’ve spoken to lots of first-time contributors. I generally coach them through the PR process rather than doing it for them. Once they get a PR merged, they get a real thrill from it. It feels good to contribute something to a project.

Open-source projects are always encouraging users to step up and become contributors. Getting a contribution merged as an amateur or hobbyist is no small feat, and yet we rarely take the time to acknowledge and celebrate when this happens.

You pay time for free software​

“I sometimes have the feeling that far too much work went into explaining things to people who did not want to learn FreeCAD, but who wanted to have FreeCAD be like their favourite CAD system, which they were not willing to pay for.”—chrisb on the FreeCAD forum

FreeCAD is not just a free to use version of your preferred CAD system. By choosing open source, especially younger projects, you accept that the product or tool may not be fully formed yet.

The experience of using an open-source alternative like FreeCAD vs. a proprietary product can be frustrating. The common objections are the absence of a slick and intuitive UI, and missing documentation. The nature of open-source projects is that they aren’t optimized for attracting new users:

“FreeCAD has no goal of market penetration or profit, nor of training neophytes. FreeCAD has always been a sandbox. What the user sees is the current culmination of sandcastles people have built over the years. It is organic, so the sand castles aren’t necessarily designed to be completely stand alone … There is no holistic design or guidance...it is organic. Many see this as something built on a shifting base, but, somehow thousands of people around the world manage to get things done.

For better or worse, there are no bounds on what or how the sandcastles are built. It takes some time and effort to learn how to navigate the sandcastles, and in some cases the moats around them. Some are willing to put in this effort, others chafe, for many reasons.”—drmacro on the FreeCAD forum

When you get software for free, you pay in effort and time instead. What do you get by making that trade? Whether you’re a hobbyist creator or trying to adopt FreeCAD for your workplace, the greater benefits of FreeCAD include:

• Not being locked into a subscription model from a capricious vendor
• Complete transparency to both inspect the code and see the roadmap for future developments
• You can work on your local machine instead of being tied to a web application
• You can influence the product

You can have an impact on the velocity and trajectory of the project. The inconvenience of an immature feature set or lack of finesse might be uncomfortable at first, but the things you create with FreeCAD are yours, forever. Beyond the practical and tangible benefits, you also might get:

• A sense of ownership
• A sense of accomplishment
• Your name written into the Git history of the project

Contributing to open source isn’t easy​

It’s not my intention to downplay the effort required. Contributing to open source and shaping the direction of a project can be fun and rewarding, but it’s also difficult and can be intimidating for newcomers. A lot of open-source contributors are professional, formally trained developers. As an amateur or hobbyist, contributing is both technically challenging and a feat in overcoming imposter syndrome.

It takes courage to propose changes and improvements, especially to code contributed by people who do it for a living. Nobody wants to be shot down and told to go fork the project. We’ve discussed the responsibility of project maintainers in fostering a more welcoming environment on this blog before, and there’s an equal responsibility on the contributors to be humble and receptive to feedback.

Still, I have seen firsthand how meaningful and satisfying it is for newcomers to get their contributions merged.

Come to solve your own problems, stay for the legacy​

For people used to working with proprietary software and hardware, it’s novel to be able to contribute a solution to a problem you’re having, and also make that solution available to others. Beyond the immediate dopamine hit of getting your fix merged for you and other FreeCAD users to enjoy, there’s a lasting impact.

For most of human history, when people worked together to build something, they had to be in the same place at the same time. They left behind traces of their work and archeologists study those traces to understand what life was like. We’re in the very earliest days of remote collaborative work—where hundreds or thousands of people contribute to creating something. They span cultures, languages, time, and place.

The nature of the Git repo is that the commit history is permanent and there’s a million copies of it. We’ve only been working on software like this for a few decades and with the millions of copies, some of them are likely to survive for a very, VERY long time.

In the far distant future, the equivalent of archeologists will sift through old data to reconstruct the history of what happened in the past. Just like William Rathje studies modern garbage, someone will eventually get the idea to systematically study Git histories to understand the culture of distributed work and collaborative software development.

Our contributions may be more timeless than we realize.

Addendum: Here’s something I would love to see...​

If there’s anyone from GitHub or GitLab reading, you could make it easier for open-source projects to reward contributors. As a maintainer of FreeCAD I would love to be able to push a button and send a coupon to a first-time contributor. They could redeem the coupon for a sticker with the FreeCAD (Ondsel) logo. This sticker wouldn’t be available to just anyone. Nope. The only way to get one is to contribute to the project. It’s special.

FreeCAD 0.21 has just been released with numerous new features and improvements. Some of the Ondsel team members have been regular contributors to FreeCAD for many years, but this is the first time we participated in a development cycle as a commercial entity. Let’s take this opportunity to step back and reflect on it.

Working with the FreeCAD community​

We’ve known people who are active in the community for many years, and our interactions have been great for the most part. But at the back of our minds there was this nagging thought: can we keep it that way as a company?

Now that we’ve had this (however short) run with 0.21 development and release, it looks like the answer is a very definite ‘yes’. The user community has been nothing short of awesome. The maintainers have been professional, supportive and responsive, same as usual.

Concerns and Response​

As a commercial company, our biggest concern was predictability in the development process. We wanted to know … needed to know… that effort we spend on development wouldn’t be wasted. We also had to have some assurance that releases would happen in time to support our corporate goals.

Early on, we raised our concern that the development methodology was too unpredictable. It wasn’t clear which pull requests would be accepted or even who would make the decision. Pull requests would often get stuck in limbo or even denied after significant work was done. For a new startup, the risk of that happening was too great. The core developers and maintainers responded by implementing a clear policy for contributing to the FreeCAD source and defined how those contributions would be handled.

Another major concern was how dependent the project had become on individual expertise. Many important things were not documented and only lived in the minds of key people. In some cases only a few people knew how to do key tasks, and losing those people from the project was a major risk. The community agreed, and that’s one of the reasons we are heavily invested in building the Developer’s Handbook in collaboration with Chris Hennes, WandererFan, and other FreeCAD contributors and members of the FreeCAD Project Association.

I think as a team we made tremendous strides during the 0.21 cycle, particularly in formalizing the role of a maintainer and setting clearer expectations about what maintainers are responsible for. The creation of the Developer Handbook was a major step forward for all of us, as was the creation of CONTRIBUTING.md. We still have more work to do actually implementing the ideals in those documents, but at least having the goals written down is a big step forward. — Chris Hennes, FreeCAD maintainer, the FPA board member and founder

Implementing the policies and starting the handbook helped, but even with the best intentions and tools, development is hard. The FreeCAD project has a lot of contributors, just keeping track of the release, issues, and pull requests was taxing everyone.

We started investigating the functionality GitHub provides to manage projects and discussions. We used this first for the toponaming project and then, with the addition of Milestones, we started the Release Dashboard to give everyone a clear picture of where we are on the current release.

The dashboard is helping to focus attention but PRs still sit too long. Even with clear accountability for maintainers, it is often difficult to know if a given PR should be merged. Nobody is expert on everything, and merge decisions often come with a certain amount of risk. Lately the maintainers have started addressing this by reviewing the outstanding PR queue as a group in live meetings. Individual PRs are discussed and decisions made in realtime. Often PRs get merged immediately. Others get flagged for followup or moved to a later milestone. The decision about how to proceed is shared with many people contributing wisdom.

Now we have a much, much clearer, predictable, foreseeable and transparent process that can be (and has been) undertaken by more people. This is a very important step towards having more regular releases in the future. — Yorik Van Havre, Arch and BIM maintainer, the FPA chairperson and founder

What FreeCAD truly needs is… a shared vision​

FreeCAD development still has its challenges. We still don’t have broad consensus on where the application goes from here. Since its beginning, the project has proceeded forward with developers working on whichever features they were interested in. That’s part of the appeal of an open-source project, and we hope it never changes. A clear roadmap, however, would give some structure and help avoid conflict. There are some humble beginnings of a roadmap, but it still needs further work.

Lots of discussion happened during the 0.21 development cycle that helped clarify the road to v1.0. Some of these topics we’ve already written about extensively on this blog, including assembly and materials. Other ideas, like a first-run wizard, have gotten some preliminary attention but need more planning and discussion. We are looking forward to the upcoming hackathon in Vancouver as an opportunity to further refine the roadmap.

Wins and challenges for the entire FreeCAD team​

The FreeCAD community is getting bigger and more spread-out. We now have a wide range of experts on many topics, which is great for a better understanding of problems users have and thus finding better solutions. At the same time, it’s now harder to get consensus and to get the word out about initiatives.

There were several high points for me in 0.21. One of those was the help I got from members of the community: some contributed code, some did testing, some explained the arcania of technical drawing. — WandererFan, TechDraw maintainer, the FPA board member and founder

The FPA really came into its own. Donations from end users have been strong and reflect how much the greater community wants to see FreeCAD succeed. But an important challenge for the FPA going forward is managing these donations effectively. There’s no doubt that paid-development and contract work will be part of the future.

I think we are making a better work of organizing for a release. The presence of the FPA and the development grants are opening up opportunities that where previously not there and it’s giving some good initial results, I expect this to only get better next cycle! — Adrián Insaurralde Avalos, maintainer and release manager of FreeCAD

The project is getting better at taking feedback. Improving the contribution process made us focus much more on getting good feedback from users: Conversations are now happening increasingly often in pull requests and issues on GitHub. The team also did a very successful complaints session at FOSDEM this year. Overall, the improvement is in the quality of discussions. Once you formulate an issue as a problem to be solved, you end up with atomic tasks that are easier to accomplish. The inevitable challenge here is that now the project has a backlog of existing issues that need to be refactored and tailored to this new way of dealing with issues.

What Ondsel is doing and what’s next​

Ondsel is building a service that makes FreeCAD more usable and useful to commercial users and teams. We absolutely need FreeCAD to be the kind of software that people rave about and can’t recommend enough. So we spend a lot of time improving it for users.

Our visible contributions to v0.21 were mostly improving the user interface and workflow. We made contributions to the Preferences dialog, improved the UX/UI of Fillet, Chamfer, Draft, and Thickness tools in the Part Design workbench. We redesigned the image plane settings and fixed bugs in the core and the Path workbench.

Many of our contributions are less visible. We have also been working on larger projects that will also benefit the entire ecosystem but will take longer to bear fruit.

We’re leading the project to integrate RealThunder’s fix for the notorious toponaming issue. The first 2 phases out of 5 are now complete (see this recent blog post about it).

After researching existing options for creating and solving assemblies in FreeCAD, we settled on writing a solver of our own. Dr. Aik-Siong Koh has made significant progress towards a assembly solver based on his existing code originally written in Smalltalk. So far, the new solver can create an assembly and perform kinematics of a piston-crank system. We are also looking for ways to integrate MBDyn for multi-body dynamics.

Ajinkya Dahale has a working prototype of a native custom data elements system, one that doesn’t require using 3rd party workbenches or abusing PropertyBag from the Path workbench (see our original research for an overview of available options).

In conclusion, what we can say with absolute certainty is that, as a company, we feel that working on FreeCAD is fulfilling and rewarding. We hope that more companies creating FreeCAD-based products and services will join the development. There is no shortage of things to do and a lot to gain for everyone.

How you can contribute to v1.0 development​

There are many ways users, developers, and companies which rely on FreeCAD can help make the next phase possible:

• You can donate to the FreeCAD project association. Funds will be spent on getting grants to developers who improve the software and its ecosystem.
• If you are a developer in the Vancouver area, interested in making FreeCAD better, please come to the hackathon that is taking place on August 11-13.
• There’s always a lot of work to moderate discussions in the community, translate and test the program, write documentation, and make video tutorials. Here is an introduction for people who can provide non-programming help.

Finally, if you are a company that uses FreeCAD, you can join the community. Much of FreeCAD’s progress until now has been made by individuals. Commercial users are becoming increasingly important. Their needs and expertise will drive the next phase of development even faster.

At Ondsel, we would be excited to talk to you and better understand what problems and frustrations you have with the software. Please reach us at contact@ondsel.com.

Back in February, we posted an explanation of the toponaming issue in FreeCAD and a proposal of getting this fixed in the upstream project, with RealThunder’s LinkStage3 fork as a guideline. Since then, we’ve made a lot of progress, but even more work is yet to be done.

In this post, we’d like to explain how we are separating this work into stages, why FreeCAD 0.21 is not going to be much different from previous releases in terms of toponaming, and what our plan for the next development cycle is.

While this progress is cause to celebrate, we also caution users to understand that models can (and will) break for reasons besides toponaming even after this project is done.

What’s this toponaming thing anyway?​

As models evolve, their geometry changes. Doing a boolean sum of the same object with a different object will create new faces and vertices. So if a feature is attached to an element that no longer exists, the model will break. Topological naming is a way to store all element names in a persistent manner to avoid that scenario. You can read a much more detailed explanation in the previous post. The important thing here is that making topology names persistent implies changing FreeCAD’s source code in many places and the changes are not trivial. This is not a fix you can do on a lazy Sunday afternoon.

The TNP team​

Before we go any further, let's introduce the team that has been working on the fix all year so far.

John Dupuy is an Ondsel employee. He’s project coordinator, does code review, as well as his own share of programming.

Chris Hennes is FreeCAD maintainer who also writes code and does code review from other contributors. He did a large part of programming in phases 1 and 2 of the TNP fix (more on that below).

Pesc0 is a new arrival to FreeCAD. When the call for participation at fixing the TNP issue was posted, he picked a few tasks he was interested in, started hacking and — most importantly — didn’t drop the ball. He also turned out to be really great at communication with the team.

Zheng Lei aka RealThunder (or RT) developed the fix for the toponaming issue in his fork of FreeCAD. His patchset made it possible for the upstream team to study the issue in much more detail, explore possible solutions, and come up with a roadmap. The TNP team uses a lot of his code and the classes he developed. RealThunder was involved in a consulting role and provided some really useful insight.

Ajinkya Dahale is an active contributor to the project, and employee at Ondsel. His involvement so far is creating the fix for sketch objects.

Staging the fix​

After studying the issue and the existing fix in RealThunder’s fork, we came up with a plan to introduce topological naming in five phases.

Phase 1: To begin, we need a way to store and manipulate short references names of elements and names serialized from the element mapping. We also need a way to handle element naming as a whole and store all descriptive elements in one place for easy reference. So this is where we wrote several classes — IndexedName.cpp (save the name of an element), MappedName.cs (store and manipulate the more-complex mapped-name used by elements and the toponaming algorithm), MappedElement.cpp class (save the name parts of an element), ElementMap.h (store all descriptive elements in one place for easy reference).

Phase 2: The main objective of this phase is to create a way to generatively express the history of an item, create new names and mappings, but not actually rely on them. This phase mainly touches Sketch and Part workbenches.

This is where we are now. Version 0.21 is coming out soon with stage 1 and stage 2 implemented. Some smaller items remain to be completed.

Phase 3: This is where we will start applying new names and mappings to geometry elements. We expect that at this point, until optimizations are done, FreeCAD will become somewhat slower. This expected performance regression is one of the main reasons we are not waiting for the entire work to be done to release a new FreeCAD version.

Phase 4: At this stage, we are planning to start using the new names when recalculating objects in all workbenches.

Phase 5: This final stage is where we do all the optimization to make FreeCAD fast and snappy while toponaming-safe.

The plan is to do phases 3 through 5 in the next development cycle leading up to releasing v1.0 some time next year.

Will toponaming solve all the problems with models breaking? Nope.​

There are multiple other opportunities for models to break even when toponaming is not involved. A common reason for that is using relative rather than absolute references when constraining elements of sketches. With relative references, FreeCAD will likely try to solve constraints in a different order, which will change geometry.

A certain combination of parameters can cause inversion of a part of a sketch. So when you e.g. change a parameter driven via spreadsheet, it will break your model forever, and you won't be able to undo and/or recompute.

FreeCAD also does no validation of user input by itself. It will obediently do whatever the user asks it to do, even if it makes the model explode. This can be worked around by using conditional expressions to normalize user-submitted values that don't make sense.

Brodie Fairhall covered these and a few other cases in a video for FreeCAD User Conference 2023. We highly recommend watching it!

How work on the TNP fix changed the project​

As a developers community, we’ve already made complex changes to FreeCAD in the past, like switching from Python 2.7 to Python 3, or porting the user interface from Qt 4 to Qt5. But the way we planned that work wasn’t great. Fixing the toponaming issue rivals past challenging projects in virtually every aspect, so it was time to change our approach to planning our work. To do that, we decided to use GitHub’s projects feature, break the entire project into phases, and, most importantly, avoid trying to complete the entire project within one development cycle.

Another major change was making unit tests the norm. Until fairly recently, FreeCAD had zero unit tests. It was really bad, because it made discovering and fixing regressions quite a bit of a nightmare. Some work on that had started shortly before our work on TNP began, but we made it the rule that all new code should come with unit tests.

In conclusion​

Seeing a new contributor pick up rather complex tasks and work on them until the job is done has been one of the most rewarding experiences in this project so far. We would definitely appreciate more people following in the footsteps of Pesc0.

Here is what you can do. Most of the project conversation is taking place in a dedicated Telegram group. The group has be-weekly teleconferences discussing progress and issues. The task list is discussed and built in GitHub issue 8432 and new issues are made for each task. You can volunteer for one of those, create a PR, copy in the code from the toponaming branch, then start writing tests to build your understanding of what the code is doing, and iteratively accomplish the task.

This isn’t the easiest project to accomplish, and as FreeCAD v1.0 release is directly dependent on finalizing the toponaming fix, we encourage all interested developers to join us!

Bounties don’t help users fund FOSS projects​

Funding free/libre software projects is difficult. For the last 5+ years, the knee jerk reaction has been to say “just do what Blender Foundation does, they got everything right”. But contributors come with different backgrounds. Some are perfectly fine about thinking like entrepreneurs, others would rather stick to programming, or designing interfaces, or bug triaging, or writing documentation etc.

So there are various ideas on how to work around that and still help teams earn a living. One idea we come across really often is bounties. The general idea of a bounty is this: someone identifies an issue and offers some money to fix it, other people can bring more money, then someone implements a fix or a feature and takes the money.

FreeCAD has a mixed history with bounties. People absolutely mean well when they suggest bounties as a way to foster development of free and open-source software (FOSS), but bounties fail way too often. Nevertheless, there's a popular notion that they are actually great. And thus bounties distract people from trying more realistic solutions.

Let's talk about why bounties fail and what approaches to funding FOSS developers are better and why.

What are the bounties and where do they actually work?​

First and foremost, let’s clarify that the bounties we are referring here to are the bounties typically proposed by users. The bounties paid by corporations for finding e.g. security vulnerabilities in their products are a whole different topic.

The unsophisticated look at bounties, that you can find on forums and elsewhere, is basically this: we think there’s a great feature to implement, we are willing to pay what we think is a fair amount of money to cover the cost of its development, someone will absolutely volunteer, because, well, here is our money for the taking.

As far as these simple agreements go, it works in a limited amount of scenarios:

• Small bug fixes. Many large software projects have hundreds of small issues that the core team just never has the time to fix. It could be incomplete file format support or a number of sorely missing settings. In other words, nothing that requires digging a ten thousand feet deep hole into the source code just to find out that half of the application needs to be rewritten, possibly in a new fancy programming language.
• Small features. Similarly, a new feature that doesn’t affect workflows in any major way and doesn’t impose major internal redesign, could be subject to a bounty.
• 3rd party add-ons. Developing an add-on or a macro that automates a daunting task could be a bounty material, especially if the use case in question is not a typical one and thus would likely not be covered by what a program does by default.

Everything else typically becomes a problem with bounties. Here is why.

What’s a more realistic scenario?​

When you start treating anything as a bounty material, in a large project like FreeCAD, the bounty scenario needs to be more like this:

1. Someone singles out an issue that could be fixed with a bounty.
2. The stakeholders agree that it is indeed a bounty material.
3. Someone spends time to evaluate the cost of a project, with a realistic error margin.
4. The evaluation is then adjusted for the time spent on the preliminary evaluation before any real work starts.
5. Both the stakeholders and the community agree that the evaluation is ok.
6. The community puts their money where their mouth is.
7. Work gets done.
8. The community accepts the results after some or no development iterations.
9. The evaluation is then adjusted for actual development expenses, and the community accepts that and pays for it too, because the developer shouldn't be punished for things out of their control.

You’ll notice that in this scenario, real-life expenses are taken into account (and paid in full), because figuring out the right solution is often 80% of the entire work. Moreover, everyone seems to agree on everything, which is so often not the case. An even more unthinkable thing happens: the bounty is adjusted for actual expenses — most bounty platforms don’t even handle that, and the protocol of the adjustment is pretty much unheard of.

So why do bounties fail exactly?​

There are so many reasons. Let’s dig into some of them.

Financial reasons​

Things start to break at the very beginning. When a bounty is initiated by a user, their idea of development cost will likely be way off. It takes a certain amount of familiarity with the source code in question to be able to make a fair estimation, and even then there’s no guarantee that larger underlying issues won’t be discovered.

One example here would be canvas rotation in GIMP. This feature was originally implemented in a fork called GIMP-Painter. A popular online platform BountySource had a bounty for that exact feature, with close to EUR 75.00 waiting for someone to backport the patch. But when one of GIMP developers started looking into this, he found out he would have to pretty much write that feature from scratch — it was that much easier than normalizing the patch. What looked like a ‘git cherry-pick’ material turned out to be a hack lasting several days and looking more like a EUR 750.00 job. So when he, an experienced developer, picked the bounty, it was less than minimum per-hour wage in his country of residence. That is simply not sustainable.

An even more staggering example of a financial failure of a bounty are MIDI tracks in Ardour. This essential feature was available as a bounty and was eventually developed over the course of two Google Summer of Code seasons, with multiple people participating (GSoC student, his mentor and lead developer of the project, a UX/UI designer). They spent close to 3 years working on this on and off. How much money was pledged? $1,380.

Organizational reasons​

Bounties rarely scale. While some patches only need understanding the source code and being able to design a solution, others require getting more people like UX/UI architects involved.

Efforts can be duplicated. With bounties, developers are asked to take all the risks. Several people can work on the same solution at once, only one of them will be paid.

Payment is not guaranteed. We already mentioned it above, but this is worth repeating: with bounties, a lot of the research work has to be done upfront. If you are willing to do that, you better be prepared to cover the research expenses somehow.

Decision-making can be paralyzing. Teams where decision-making among stakeholders is broken generally have a much bigger fish to fry. Still, with multiple stakeholders who rarely agree on anything, who will make the decision whether a bounty patch should be accepted?

Communication issues​

Part of the problem is also in finding the right words. Even when developers themselves set bounty ideas, they still tend to have a hard time communicating the amount of work it takes to do something and therefore the cost of it. Non-technical users have a very vague idea about the implications of writing new code or even reusing existing code. A very common request is to add a new feature by “just reusing” code written in Python in a program written in C++, because “it’s open source, so you already have everything you need”. This isn’t anyone’s fault, it’s just explaining technical intricacies to people with less or no programming experience takes some time and practice.

Technical reasons​

Bounties typically start from one person's use case and thus commonly don't take the big picture into account. The idea might work for this one person, but could it be done better? Or is it even an actual problem? The use case might be stupid, because the user is trying to do something in a non-orthogonal way while easier solutions already exist and would work just as well. Or the workaround that is requested in the bounty might have a better implementation as a core feature. And the list goes on.

Bounties don’t encourage incremental solutions. The very idea of bounties is that someone does the entire work in one go, as a quick solution, takes the money, and leaves. But when the feature implies digging into the architecture, this basically means two things: either the developer works on a deep fix for a very long time and thus has a hard time rebasing to changes in the upstream branch (think of RealThunder’s LinkStage branch), or they have to submit work in small batches over a long period of time, but that’s not what bounties are generally expected to be.

Bounties favor outcomes that maximize bounty for minimum effort. So they don’t encourage elegant, testable code or unit testing. In the end, this bites everyone in the neck — both users and developers.

If not bounties, then what?​

Finally, let’s talk about some of the better approaches at community funding of development. No single way is perfect, but that’s not the point. By trying things that actually work we all can come up with new, better solutions. We are not talking about the “paid support” model here though, plenty has already been said about that over the past few decades.

One of the very basic ideas here is that — especially in large projects — development ideas in any form should be verified by respective core teams. So it's best when the project has a process of idea verification between multiple stakeholders.

Crowdfunding and stretch goals​

One example of idea verification is what the Krita team does whenever they run a crowdfunding campaign (it’s been a while though). They collect user requests, sit down, go through each of them, take the ones that make sense, figure out how much time each would take to implement, then take the ones that passed validation as relatively easy fixes/features and group them into stretch goals and set a price to it. That price is already adjusted for the time it took them to do the verification. So far, their estimations have been very close to actual expenses.

If they would not get sponsoring for stretch goals, the verification expenses would be covered by other sources of income like sales on Steam and Microsoft Store. This means that any team following in their footsteps better have a stable source of income to cover the expenses of the work they do upfront. This works best in teams that organized themselves into a non-commercial organization and have a diversified pool of income sources (think Blender Foundation and, well, FreeCAD now).

Developer fund​

A developer fund can be created and used in multiple ways. It can be very similar to crowdfunding, especially if you look at what the Kdenlive team has been doing.

They chose who would be working on features and decided to hire people who are already active in the project and had the opportunity to devote part of their time to this work without jeopardizing their other obligations.

Then they came up with a short list of really useful features to implement. They balanced them between roadmap items and things that users requested in their discussion rooms. They also only chose tasks that they knew they would be able to solve based on their team’s expertise.

Then they estimated the price by decomposing proposed features into smaller tasks and deciding to fund 50% of the time that accomplishing that work would require.

The campaign was launched with KDE e.V. and their Donorbox-based system. Funds were collected within the first month of the campaign, while it was supposed to run for three months. Some of their 2023 goals outlined on the fund page have already been reached.

But a fund can also be used to hire full-time developers or issue part-time development grants. Blender Foundation famously does both. Blender’s fund is also filled from multiple sources — both corporate sponsorships and personal donations, one-time as well as recurring.

Grants​

The idea behind a grant is that an organization behind a FOSS project builds a relationship with one or more community members by hiring them to do a specific one-time job: implement a feature, modernize an aging part of the source code, write documentation, design new UI etc.

We’ve already mentioned Blender Foundation as one of the organizations that issue grants, but there’s obviously more. The Inkscape team has recently hired a full-time senior developer to work on the GTK4 port of the vector graphics editor for several months. And the FreeCAD Project Association is no stranger to grants either: two grants were issued last year, to RealThunder (the toponaming fix) and to Ajinkya Dahale (spline handling in Sketcher).

Contract development​

There’s a certain peace-of-mind element in doing contracted work as compared to working for a bounty. It’s easier to discuss scope, you can charge for the work in a time-and-materials fashion etc. You still have to wrangle stakeholders — there’s no way around that (and there likely shouldn’t be), but all your extra expenses will typically be covered by a clause in the contract.

If you want an example, look no further: the Path workbench in FreeCAD was originally the subject of a contracted job. This project involved a lot of upfront conversation with FreeCAD maintainers about changing the core to allow for rendering toolpaths. The core features were specifically implemented in a way that would allow 3rd-party workbenches and alternative user interfaces to be created for CNC-related use cases.

The paid binaries model​

To some extent, the Ardour project pioneered this approach to funding development: they came up with an idea that users who can’t build Ardour for themselves (it’s more difficult on Windows and macOS) can pay a small monthly fee that is a fraction of what users pay for proprietary digital audio workstations. This alone pays the bills of two full-time developers and some occasionally helpful contributors.

Two more similar projects, Zrythm and Radium, use the same funding model — most likely with less success. But this has more to do with oversaturation of the digital audio workstation market.

The open-core model​

Finally, core team members can start an LLC and provide a fork/modification of the original project with added value.

Some of the very obvious if geeky examples here are GitLab, Redis, and Docker. On a less technical side, that would definitely be the MuseScore.com service built for the community of MuseScore users, or the audio.com cloud storage service that has been integrated into Audacity. We are doing a very similar thing with Ondsel, except we don’t own FreeCAD but merely contribute to it.

In conclusion​

Bounties are a lousy foundation for sustainable development of large projects like FreeCAD. They typically represent a gross underestimation of real work required to solve a problem, commonly miss a bigger picture, and encourage worst software development practices.

Growing larger is fun but also really overwhelming. Most ambitious projects that aim to stay afloat will have to experiment with different approaches to getting funded on a regular basis and come up with their own mix of solutions. It’s that or perish.

One of the sorely missing features in FreeCAD is a convenient system for creating custom data elements and interacting with them.

A common use case is constraining multiple features in a sketch to the same value. Instead of tweaking every instance of a horizontal distance constraint, you would create a custom data element (or property) called “Length” and then reference it via the Expression Engine. Then every time you change the value of that custom element, the entire sketch is updated automatically.

This is an extremely handy feature, so there is a strong community demand for this. Most recently, it was brought up twice during the "Complaint Session" at FOSDEM. And even a quick glance at the larger CAD market suggests that it’s useful for more than just a group of FreeCAD users: Inventor, SolidWorks, NX, Creo all have a way to create a custom data element and use it with expressions.

Much like with assemblies, the community made several attempts to create a solution, but all of them have various shortcomings which we’ll discuss below.

Fixing this benefits the entire FreeCAD ecosystem. Users would get a convenient tool for manipulating their designs, it would be immediately available and maintained as an inherent part of the project. For companies like Ondsel who want to build around FreeCAD, this system is the prerequisite for integrating it into external services.

A large part of this system is therefore parameters introspection. This is a complicated topic that probably deserves a separate discussion. But the basic idea is this. When you design a real-life part, some of the custom data elements you create are convenience tools like in the use case above. They contribute to making the design truly parametric yet do not need to be accessed and manipulated externally. But when FreeCAD is used in headless mode in a pipeline, whatever external tools you rely on better be able to tell which properties they need to expose to the user (dimensions, color, material etc.) and which ones have to be omitted. Essentially, custom parameters need to carry some useful context.

So let’s talk about existing options, where they shine and fail, and what we think a sensible solution would look like based on what we learned.

In this post, we are also introducing another new author. Ajinkya Dahale has been a FreeCAD contributor since 2016. His contributions are mostly in the Sketcher, PartDesign, and FEM workbenches. Ajinkya’s latest major involvement, improving B-spline constraints and construction, was sponsored by the FreeCAD community both directly and via the FreeCAD Project Association. He also received a grant from the Open Toolchain Foundation. Since early 2023, he has been working for Ondsel and continues hacking on FreeCAD.

Elements or Properties?​

Before we get to the gist of the topic, we need to explain why we use the terminology “custom data elements” and not “custom properties” when we talk about the future system. Calling this type of data a property implies a particular solution — storing this data in the project tree and making it accessible for editing in the Combo View dock. But we are not yet certain this is exactly the way to do this. For now, we are using the term “custom data elements”.

Benchmark​

To understand how well various existing solutions work, we need a kind of a benchmark — a realistic workflow that allows working with custom data elements efficiently. We can describe it with a user story:

1. The user begins to set the constraint and realizes they would like to make the value a custom field. The constraint panel would have a button to add a custom field.
2. The button would allow the user to add a new item to a collection of custom data elements.
3. The result would be returned and inserted via the Expression Engine.

This workflow obviously applies to the Sketcher workbench, but there are many more use cases for custom data elements. You could be using them when designing a house, a 3D-printable part, or a part for CNC milling, or a thousand more things. So this better be a core feature. There are multiple possible approaches to exposing custom data elements to users in the UI — pressing a shortcut to activate a floating window, editing an object in the document tree, or editing a value in a new tab in the property viewer. But for now, let’s call this a benchmark and see how existing solutions stack up against it.

Existing solutions​

We found 4 attempts to implement this feature.

The Spreadsheet workbench​

This WB was designed for many uses, so it’s not entirely fair to call it a custom data elements system. The workbench has two major benefits: it’s both powerful (e.g. cells in the spreadsheet can contain expressions) and it’s already part of FreeCAD, available immediately after program’s installation.

The way spreadsheets work in FreeCAD, this is the assumed workflow:

1. The user exits Sketcher
2. Switches to the Spreadsheet workbench
3. Creates a spreadsheet
4. Double-clicks the spreadsheet in the tree
5. Selects a cell and enters a value
6. Selects the cell a second time
7. Clicks the button to set an alias
8. Types in the alias name and presses OK
9. Double-clicks the sketch icon in the tree to reopen Sketcher
10. Selects the constraint and uses the Expression Engine to reference the aliased cell

Compared to the benchmark above, this isn’t very user-friendly. FreeCAD contributors attempted to make their life easier by simplifying alias creation, but that fixes only a small portion of issues with spreadsheets. While we definitely can improve its subpar performance and UX/UI, tables are still not very convenient for extracting values without launching FreeCAD and using its GUI.

Property Bag in Path​

This feature is part of the default FreeCAD’s Path workbench. You can create groups of properties, which is convenient when you have a lot of those, and there is a sensible choice of property types available.

But while custom properties in the “bag” are perfectly accessible from other workbenches via the Expression Engine, you can only create and modify properties when you are in the Path workbench. So it’s not competitive against the benchmark. This feature is also written in Python, so it’s entirely possible it would have to be ripped out of Path and rewritten in C++.

The DynamicData workbench​

This is a 3rd party add-on that allows creating project-level custom properties accessible through the Expression Engine from any workbench. You can create any number of containers of properties, one per each object if you like. There is a very long list of property types available.

Workflow-wise, this is not a very convenient solution. There are some cosmetic UX issues (e.g. you have to switch to this workbench first for the toolbar to show in other workbenches), but we can deal with those. What’s worse is that properties can’t be added on the fly, while you are sketching in 2D.

Theoretically, DynamicData could work as a foundation for a better solution. However:

• The WB is written in Python, but FreeCAD needs this as a core feature, hence it should most likely be C++ code.
• The entire feature set is only accessible via GUI, which is not great for running FreeCAD in headless mode.

UserData in Assembly 4​

The variables system in the Assembly 4 workbench is designed primarily for creating animations in the viewport. Here is how it works:

1. Create a variable like “rotation”
2. Pick a part, set its rotation value to use the variable via the Expression Engine
3. Open the animation dialog, set start/end values, set step size
4. Run the animation

The core system behind this feature is capable. The list of possible data types can (and should) be extended, but it’s good for a start. There are some small issues. E.g. there’s no way to edit an existing variable, the user can only create and delete them.

A much larger issue is that the feature is workbench-specific and written in Python. Thus, it would have to be extracted from the Assembly 4 code and most likely rewritten in C++. Then we’d have to write an entirely new UI on top of it.

Summary​

Reusing any of the existing solutions we explored seems unlikely for the following reasons:

1. For the most part, they are not part of the FreeCAD core. The DynamicData and Assembly 4 workbenches need to be installed separately, and in case of Property Bag, the functionality needs to be moved out of the Path workbench and generalized.

2. None of the 4 solutions here are accessible from C++ code, so no core feature can use custom data elements. So far, this hasn't really been an issue, but it’s best to build future-proof core features.

3. For the Python interface, there should be some sort of keyword-based system to set these values to these custom data elements. This way users can skip certain parameters like description.

4. Custom data elements in existing solutions carry no context. This makes it difficult for an external tool to sift through available parameters and pick the ones that should be exposed to users in the UI of that external tool. This can be resolved by making the user create a specific kind of document object or name it a certain way, but it would put an unnecessary cognitive burden on users.

5. The Spreadsheet workbench is the only core feature among the ones we studied. Spreadsheet serves and important role and isn’t going anywhere. However its UX is so far from the assumed workflow and so inaccessible from CLI that we shouldn’t try to force it to serve this purpose. In fact, Spreadsheet may be come even more useful in conjunction with a core data element feature.

In a nutshell, there’s no existing solution that can be used as-is.

What The Solution Should Look Like​

After analyzing existing solutions (including those of proprietary CAD programs), some obvious use cases, as well as user requests, we came up with the following list of requirements for a native custom data elements system in FreeCAD.

Architecturally, there should be a single container with a possibility to create groups of data elements inside it. Secondly, there’s the topic of element types. The system should support all core data types: Length, Angle, Enum, String etc.

When we start thinking about this from users’ standpoint, this is where things get a little vague. There are benefits to having elements as properties in the project tree, but a kind of a dedicated registry or central management tool (SolidWorks-style) makes about as much sense. What we are certain of is that:

• Adding new data elements from Sketcher and other WBs should be simple and obvious.
• Tooltips for data elements should be possible so that collaborators could figure out your project easily.
• Expression Engine should be supported.

When we talk about adding data elements easily, what we mean is that users should be able to create those from anywhere in the application and in the middle of a transaction like editing a sketch. Think of the way you can create named parameters in Inventor by just typing “Length=530mm” in the constraint input box to create a linked “Length” property and setting it to 530mm.

Moreover, users should be able to create and access custom data elements through CLI so that models could be adjusted when FreeCAD is running remotely, and possibly automated as macros. Example: load a gridfinity template, set the number of height units, choose a color, output an STL, send it to OctoPrint.

Finally, on a more technical note, users should be able to create and access custom data elements from code in either C++ or Python. That is, the feature should be accessible for core features, default workbenches, and 3rd party workbenches. This can be ensured by creating the framework in C++ and adding Python bindings.

Our Proposal​

We see this as a multi-stage project with work on expanding the FreeCAD file format accordingly, programming a C++ class and Python bindings, as well as designing and implementing the user interface. We have already settled on the document structure for our proposal — a single container with custom data elements, just like we mentioned above. 3rd-party developers would be able to use C++ or Python to access custom data elements: get a list of them, create a new data element, or get an existing one and then set a value to it. This is how we picture the custom data elements can be accessed through Python:

my_doc = App.ActiveDocument()
my_doc.CustomData # The container for Custom Data elements
my_doc.CustomData.setProperty(“App::PropertyFloat”, name=”myDim”, 1.23) # Setting a double
my_doc.CustomData.getProperty(“myDim”) # Getting the value of the property
my_doc.CustomData.setProperty(“App::PropertyString”, “myText”, “hello”, desc=”Text to be printed on name plate”) # Setting a string with description
my_doc.CustomData.setProperty(“App::PropertyEnum”, “myEnum”, value=0, enum_values=[“Option1”, “Option2”, “Option3”]) # Setting an enum along with the values it can take. Selected value is “Option1”.
my_doc.CustomData.setProperty(“App::PropertyEnum”, “myEnum”, value=”Option1”, enum_values=[“Option1”, “Option2”, “Option3”]) # Setting an enum along with the values it can take (alternative)

An (incomplete) example implementation is available in this branch. We think that users who rely on external tools for interacting with FreeCAD projects should be able to make a choice which custom data elements should be seen as private and which should be seen as public. This distinction is somewhat artificial, because everything is open in FreeCAD files. But it provides a simple way for external tools to expose only a subset of custom data elements — the ones that are supposed to be interacted with in UI. This is what we want Ondsel’s cloud service to do when it comes to mass customization of designs.

We are still figuring out the interaction model and the UI. The quick and dirty solution is to add those to a new tab called “Custom” right next to “View” and “Data” in the left dock. This can work as a simple temporary solution, but we think the View/Data separation is a superficial one and needs to be done away with (a story for another day). When a user uploads a document to our web view and sets only one dimension of the project to ‘public’ (e.g. only the length of a box but not its width or height), we expect that other users viewing this document would get to control only that dimension.

Here is an early UI wireframe:

There are other approaches to designing the interaction, like what Inventor and Fusion 360 do with the properties table.

How You Can Get Involved​

We are interested in general feedback about our proposal, but we are also specifically looking for your input on these two topics:

• What are your use cases for custom data elements? What kind of problems do you try to solve with those?
• What are your frustrations with both existing solutions in FreeCAD and other CAD programs?

This would help us build a sensible interaction model and user interface for custom data elements in FreeCAD. Please provide your feedback in the issue tracker.

FreeCAD has a basic implementation of a materials system. While it works in some use cases, we think it can be vastly improved to become a lot more useful. Let’s discuss what’s already available, what’s missing, and what’s a possible way forward with this. But first, why are we even discussing it?

We are introducing a new co-author in this post. Dave Carter has been a FreeCAD user since v0.16 (primarily for rocketry and 3D printing). He worked over 40 years as a software developer in government, supply chain, and automotive industries. He is the main person behind the Rocket workbench that helps design model and amateur rockets and components for them. Dave volunteered to lead the effort creating an updated materials system for FreeCAD and has been actively working towards that goal for the past several weeks.

Why A Good Materials System Is Important​

Materials are a lot more than the color of solids in the viewport. As engineers, we need basic mechanical properties like density to calculate mass. We need advanced mechanical properties, as well as thermal and electrical properties to run various simulations (think finite element analysis). We need vendor-specific data to make an estimation of material cost. We also need materials to make commercial-grade rendering easy.

So a good materials system needs a database of materials with mechanical, thermal, electrical, architectural, and other properties. But it goes even further than that.

We know that materials behave differently depending on environment conditions. For example, we know that Young's modulus of metals decreases when temperature increases. So a materials system has to provide tools to build relationships between different material properties. Otherwise simulations won’t provide usable results.

Is that all? Nope. A concrete wall will have a first coat and then a finish. A model rocket will have a primer paint on top of the body, and then a coat of spray paint on top of parts of the primer paint. So a good materials system has to be able to deal with compound materials / multi-materials.

It’s also a great idea to have a more or less uniform UX/UI for working with materials in different scenarios. An architect by trade can be a tinkerer in their spare time, making Arduino-based devices, small home automation projects, and the like. They would appreciate not having to re-learn everything just because it’s a different set of tools in the same CAD system they use.

So What’s Wrong With What We Already Have?​

Let’s take a closer look at what’s currently available in FreeCAD. A major part of the existing materials system is the Material Editor:

It relies on a small catalog of materials (slightly over 100) available throughout FreeCAD. For each material, it’s possible to set properties in several categories:

• Mechanical
• Thermal
• Electrical
• Architectural
• Rendering
• Vector Rendering (hatching)
• Cost (vendor-specific)
• User-defined

Custom properties can be added to the user-defined category to accommodate for workflow specifics.

The existing materials system is currently used in FEM and Arch workbenches that are available by default, as well as in 3rd-party workbenches like Rocket and Render.

All this is a great start. But there are also various issues. Here are just some of the more obvious ones:

• It is impossible to set a different material to every face of a part. You can have a piece of metal or block of concrete with a coating on one side and nothing at all on the other one.
• Multi-materials are only possible in the Arch workbench, but that is not enough. Any metallic or plastic solid and a paint job already make it at least two materials.
• It should be possible to override properties set in the material card in a more or less uniform way. Maybe a variation of a material has slightly different mechanical or thermal properties, or maybe a building materials supplier is setting a different cost on a per-project basis.
• Material cards do not account for real-life behavior of materials, e.g. some physical properties may vary with temperature. A common use case is describing different CTEs at different temperatures for FEM. Moreover, the existing system only allows for isotropic materials that behave consistently regardless of direction. Orthotropic materials, such as wood, have different characteristics depending on direction: against the grain is stronger than with the grain.
• Texture mapping is separate from the material settings and only allows loading a texture file, with no positioning settings.
• Material information is not accounted for when importing/exporting from/to some file formats.
• There are no built-in functions to use the material data to make basic calculations such as weight, or cost.
• There’s no easy way to tell which part of an assembly doesn’t have an assigned material.
• The material editor has no UI for categories. It works as long as the list of materials is relatively small, but this will become a problem once the list is expanded.

This is just scratching the surface.

Previous Attempt at Fixing The Materials System​

The topic of improving the existing materials system has been brought up before. Around 2016, a contributor named Eivind Kvedalen attempted to fix some of the issues, in particular: arbitrary properties, per-face materials, infrastructure for a material database. He made two commits in a public fork on GitHub, and continued the discussion. But eventually this initiative went into slumber. Right now, the fork needs further work to even compile.

As is usual in the FreeCAD ecosystem, people also attempted to come up with various workarounds. The 3rd-party Arch Textures workbench exists solely to work around the limitations of the built-in texture mapper. The FCinfo macro helps make basic calculations based on mechanical properties.

What The Updated Materials System Should Be Like​

Having studied the subject, here’s the gist of what we think the new system should be like.

FreeCAD needs a way to store materials data in the project. If you created an assembly and used materials with custom properties (even if it’s just the material cost because you got a discount from your supplier), your team or contractors should be able to open that file and see assigned materials and related data.

There have to be per-face / per-solid materials and multi-materials. This shouldn’t be an Arch-specific feature like it is now, it has to be available for all workbenches.

There needs to be a more uniform UX/UI for selecting material and overriding its properties one way or another. The set of properties may vary between workbenches, but UI for overriding should follow the same design pattern.

It would be an absolute must to have an easily accessible calculation of basic part properties. Users should be able to easily see the weight of one part or an entire assembly.

We definitely see interest in having texture mapping and probably hatching as part of a material, with advanced settings. Advanced UV editing could be done by 3rd-party tools, but the basics of texture mapping should be there.

The material editor has to be enhanced: materials should be pre-organized into categories, have tags, rendering preview etc. The list of materials should be searchable.

There’s a strong requirement to be able to set relationships between properties for realistic simulations. There are multiple approaches to do that. We can do it with curves (like SolidWorks does) or by making multiple entries with an associated temperature range (or pressure, or whatever).

It’s generally a good idea to have easy access to up-to-date vendor data on materials where possible. There are many existing materials systems, here are just some of those in the architecture department. We know that accessing up-to-date information won’t be easy. When APIs even exist, they are typically not public or documented. And even there we’d be extremely cautious, because setting cost implies responsibility, and FreeCAD needs to be very clear where that responsibility is.

The Way Forward​

Because of how far-reaching the implications of the materials system are, we think bringing it to the state of the art needs to be a community project with all major stakeholders involved.

There’s a small task force building around this project.

Ondsel made a start on analyzing what makes a materials system great, explored implementations in various other CAD programs (SolidWorks, Inventor, Onshape, Revit, Archicad), studied the existing implementation in FreeCAD, and put together an initial list of requirements.

Dave Carter, the developer behind the Rocket workbench, volunteered to lead the effort and already made good progress towards designing a better material editor and replacing the old material cards storage system with human-readable YAML files.

The first stage of this project is just that: new materials editor UI, new file format for material cards, and over 600 categorized materials. It’s a work in progress, you can see the updated material card UI on the screenshot above.

The second stage will involve physical properties, relationships between those, and appearance settings.

After that, work has to be done on finalizing the UI, polishing icons, writing documentation etc.

There are also a number of considerations to be made, depending on feedback from users and developers. More on that below.

Once we collect more information, we will analyze it and submit a public proposal in FreeCAD’s issue tracker for everyone to see and comment on. We’ll then do our best to help all interested parties to complete this project. We discussed it with the FPA, and a grant is possible.

What’s Ondsel’s Interest In A Materials System​

There are multiple reasons for Ondsel to be involved with (and lead) this initiative.

Ondsel’s platform is primarily FreeCAD users, so the better FreeCAD is, the more users it has, the more customers the company gets (and thus the more Ondsel can invest into improving FreeCAD further). So the company needs FreeCAD to be excellent in every aspect. A great materials system is part of that.

Ondsel is also considering implementation of some features like commercial-grade ray-tracing in the online service that will directly depend on a materials system.

Thus the company is interested in working with anyone willing to implement a better materials system and support them as much as we can. Dave made an impressive start on revamping the entire system, but he will need help.

What You Can Do​

There definitely are ways you can be part of this initiative.

If you are a user, we are interested to know more about your workflow specifics:

• How do you use materials in FreeCAD or elsewhere?
• What materials-dependent simulations do you run? What material properties do they rely on?
• What type of materials do you deal with on a daily basis? What’s their variety? How often do you add custom materials?
• Are there specific material vendors you deal with? Do they make it easy to access materials data?
• Do you use the Appearance dialog to change the look of parts? How would replacing it with something actually based on materials’ appearance settings affect your workflow?
• What file formats do you import/export that require materials support?
• What are your appearance/texturing requirements for materials?
• What are your sources of material physical properties?
• Would you be more comfortable with a purely offline materials database, an online materials database like Materials Project, or a combination of both?

If you are a workbench/macro developer, what specific requirements for a materials system does the materials team need to know about? If you are a developer with experience programming materials’ look and feel, please contact Dave.

We’d love to have you join the discussion. If you agree that better materials will help make FreeCAD great and don't have any feedback to offer, please consider donating to the FPA so that more contributors get support for improving FreeCAD.

And last but not least, Dave Carter’s initiative to take matters into his own hands is precisely the kind of practical approach to improving FreeCAD that we’d love to see more of. If you are a user who shares this view, please consider donating to FreeCAD Project Association’s developer fund, so that active contributors getting funding would become the norm.

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.