Document Toponaming

[pieterhijma]

Proposal description

The essence of the proposal is to write extensive documentation on how the toponaming algorithm and implementation works and compares to LinkStage3. The output will be a report with said documentation. This will benefit the FreeCAD community, both developers and users; developers because they can gain an understanding of the toponaming system, and users because with the newly gained knowledge it is possible to explain the capabilities and limitations of the toponaming sytem helping them with their modeling.

Deliverables

The main deliverable is a report that documents the toponaming system. It will have the following sections:

1. a description of the algorithm,
2. a description of how the algorithm compares to the state-of-the-art,
3. an investigation to what extent the algorithm has been implemented in LinkStage3, and
4. an investigation to what extent the algorithm has been implemented in the FreeCAD main branch highlighting differences with LinkStage3.

Other forms of deliverables are potentially:

• test-cases that highlight differences with LinkStage3, and
• small PRs that help debugging element mapping.

Timeline

Depending on other tasks (FreeCAD/Lens integration, Variant Parts implementation, see FEP-0010), I would like to start in February/March 2025. I expect to work on this for 4 weeks full time spread over a period of about 3 months.

Risks and mitigation

The main risks lie in the complexity of the topic, the complexity of the code and the fragmentation of knowledge. Topological naming is a problem that can never be solved fully, so it depends on heuristics. The complexity of the code stems from the fact that this project will study two code bases that should be equivalent but are most likely not, due to various pre-existing differences and a porting process. The code itself is very complex as well. Finally, the knowledge about the topological naming implementation is scattered with various versions of documentation from realthunder, forum discussions, and papers.

Mitigations for this risk is having proper priorities. For example, Section 2, a comparison of the algorithm to state-of-the-art has less priority than a description of the algorithm, so this section may become a broad and shallow comparison instead of a detailed comparison.

Compensation

I would like to carry out this work with for a total of 8000 EUR for an hourly rate of 50 EUR. This amounts to 4 weeks full time.

About you

My name is Pieter Hijma (pieterhijma on the forum and pieterhijma on GitHub). I'm an independent contractor (https://pieterhijma.net) that focuses on developing open source software and in particular on developing in FreeCAD.

My experience on working on toponaming comes from another FPA project documenting the App package that is almost finished. While documenting element mapping, I noticed that the code is very complex, difficult to document, and that there are differences between LinkStage3 and FreeCAD.

I've worked on various projects within the FreeCAD ecosystem, such as documentation of the App package, Improving the user experience of VarSets, Researching Variant Parts, and Ondsel-Lens/FreeCAD integration, and OSH Autodoc.

[pieterhijma]

More detailed background information

Topological naming is important feature of FreeCAD. Its introduction was one of the main reasons to release FreeCAD as 1.0. Topological naming is also very complex as evidenced by the amount of time it took to port realthunder's code to FreeCAD's main branch.

Firstly, I would like to acknowledge @realthunder for his initial and extensive work on topological naming. Additionally, I would like to acknowledge @JohnAD for his role in creating a project plan for the port, @CalligaroV, @chennes, and the late @bgbsww for porting realthunder's code to FreeCAD's main branch (I may miss other contributors who I would like to acknowledge as well).

However, in my humble opinion, FreeCAD is now in an intermediate state where FreeCAD has topological naming mitigations that should be equivalent to LinkStage3 but probably aren't because of differences that already existed between FreeCAD and LinkStage3 or mistakes that may have been inadvertently introduced during porting. Currently, most likely, there is noone that really has a complete picture of the current state of toponaming mitigations in the FreeCAD main branch.

As a result of this intermediate state, although I would have liked to document more about element mapping, I noticed that this held me back in documenting more. In addition, it also prevents us to make progress on this important issue that requests documentation/tutorials for users in collaboration with developers. However, since it is unclear in what state topological naming exactly is, it is very difficult to make progress on this.

Another notable PR that is proposed but can currently not move forward is #17768 by @kadet1090 where @CalligaroV and @kadet1090 both agree that this could be a way forward, but at the same time it "frightens" them as well. I believe that the only path forward is to gain a deeper understanding of the exact algorithm and how cases like discussed in this PR should be handled. As of now, it remains a question of whether the LinkStage3 algorithm cannot handle this in a fundamental way or whether the implementation lacks behind of what the algorithm should do.

Additionally, since the mentioned PR is a conceptual change, it would also be useful to compare LinkStage3's algorithm and this conceptual change to the state-of-the-art, giving us more context to make informed decisions on how to move forward.

Finally, questions could be raised on whether I would be the right person to work on this not having worked directly on topological naming. However, in my humble opinion, the topological naming mitigations in the FreeCAD main branch are now more or less a black box and as a relative outsider, I could try with my experience as a researcher to shine a light inside this black box and to write as clearly as possible how the topological naming system works. This has the benefit that at least one more developer becomes familiar with the inner workings of toponaming and hopefully many more after reading the documentation. In a sense, you can consider it opening up the source code as should happen in open source projects.

To give a sense of how scattered the information is, I provide a list of pieces of documentation below:

• Realthunder's Topological naming documentation (10 revisions), and his sources of inspiration:
  • Forum topic 1: Python Topological Namer/Tracker
  • Forum topic 2: Proposal for GSoC - jnxd
  • Document with a proposed topological naming implementation
  • Paper: Implementation of persistent identification of topological entities based on macro-parametrics approach
• Realthunder's description of the algorithm (7 revision)
• Notes from the team porting toponaming
• Realthunders' forum post
• Topological naming on the wiki
• Forum topic: The TNP is not fixed and that's OK
• Topological Journal Methodology
• Generic Naming Overview

Finally, the examples below in realthunder's documentation don't work well in the FreeCAD main branch.

• In Element mapping cube.Face2.ElementMap has no entries in FreeCAD's main branch.
• In the algorithm description, the test example does not work well in the FreeCAD main branch, in terms of the refine operation and in terms of face coloring:
  • Test example

[Reqrefusion]

It's a great project that we all want to see, but it's very difficult to afford large compensions, do you have the opportunity to divide it?

[kaiwas]

Linkstage3? What is this? Why don't I care what the difference is between Linkstage3 and the main branch?

If I'm correct, it's something related to Realthander. I don't want to sound ignorant, but I think most FreeCAD users (myself included) don't know anything about Linkstage1-2-3.

we all

we all?
You can speak for the majority, but you certainly cannot speak for everyone.

[kaiwas]

My personal opinion is that RealThunder is a unintentional sabotage.

Yes, he does a lot of useful and interesting things, pursuing his own interests. But by doing this "on the side," he's sowing discord among users.
I can't understand why he's posting all his work that's incompatible with the main branch.
He's giving people hope with features that will likely never see the light of day in the main branch, and what's more, they might never be finished. I would call it selfishness.

All this is just discord and dividing users into groups that don't understand each other because of different capabilities.
It would be better if RealThunder never showed his work to anyone.

RealThunder, if you're reading this, know that your actions are actually very harmful (even though they only partially solve some problems).

(This is my personal opinion, but if you think about it for a second, it's not hard to understand.)

Linkstage has its positive advantages and some disadvantages.
The main branch has its positive advantages and some disadvantages.

In summary, users have two different branches that cannot be considered fully functional.
I am very sorry that the development effort for ONE product is split into several independent streams.

UPD/ This is just my opinion on the realthunder's work.
It's just sad that people (like pieterhijma) have to waste their energy on reverse engineering.

[Reqrefusion]

@kaiwas you may be right in what you say, but this issue is for toponaming documentation, of course it has something to do with linkstage, but basically the main purpose is to document the main branch.

[furgo16]

@kaiwas the very first sentence on #70 (comment) sounds fairly harsh, you might want to consider toning it down to avoid misinterpretation. I know from your other feedback here and on the forum that you are very direct, but always respectful. You also often mention that you use online translation for your messages, so perhaps this was not what you intended to convey (or at least not so strongly). => (update: sentence reworded, thank you)

The rest is a valid opinion that some might agree with or not, which is fine. Thanks!

[kaiwas]

@kaiwas the very first sentence on #70 (comment) sounds fairly harsh

Yes. I'm not a native speaker and I'm not sure the translation is accurate.
The first sentence can be summarized as follows: "I consider this sabotage that wasn't intended to be sabotage." You can interpret these words however you like. It's just worth knowing that not everyone views Realthander's actions entirely positively. I believe there's a dark side to everything. (But I want to emphasize that I didn't mean to limit anyone. I can only regret it, that's all. Despite the general idea, which may be perceived negatively, I don't wish anyone harm. Perhaps this will simply motivate someone to stop and think for a second.)

[pieterhijma]

It's a great project that we all want to see, but it's very difficult to afford large compensions, do you have the opportunity to divide it?

Since this is essentially a deep dive where all the gained knowledge in the first phases is reused in later phases, I would prefer not to split this work up and risk that a later stage is not funded. Of course, if you have suggestions on a division, I'm open to discuss these.

[pieterhijma]

As the OP, I would like to share my perspective after some opinions have been shared here.

I have tremendous respect for @realthunder, an amazing developer with a productivity that you rarely witness. I also have great respect for the ones reviewing realthunder's code, probably mostly Werner Mayer, code that typically involved very complex topics such as links, variants/configurations, topological naming, and rendering.

The situation FreeCAD is in, is from my perspective simply a mismatch between realthunder's productivity and the ability to review code. As I understand, realthunder has always wanted to eventually merge his code into FreeCAD and he has always been helpful towards that goal from what I witnessed.

However, I think this project is not about individual developers. There were many users that were very happy with realthunder's work, especially the topological naming mitigations, and for years, there have been requests to acquire topological naming mitigations into FreeCAD's main branch.

And actually, in part because of funding from users, through the FPA, has the toponaming project had opportunity to proceed and be merged into the main branch, a milestone that was passed with a release that we called 1.0.

However, this doesn't mean that the work is done. FreeCAD/FreeCAD#17937 is very much on point, but before we can make progress on that issue, it is necessary that more FreeCAD developers become familiar with the topological naming part of the code.

So, from my perspective, this project is motivated by 1) the many users who value topological naming and 2) the goal where the FreeCAD community can be proud of how FreeCAD handles topological naming issues.

[Reqrefusion]

It's a great project that we all want to see, but it's very difficult to afford large compensions, do you have the opportunity to divide it?

Since this is essentially a deep dive where all the gained knowledge in the first phases is reused in later phases, I would prefer not to split this work up and risk that a later stage is not funded. Of course, if you have suggestions on a division, I'm open to discuss these.

I don't have a problem with the work done here, the problem here is not related to you, in general, I don't want FPA to give big grants. My opinion about grants is to give as many as possible and as small as possible to different people. We also asked him to divide it for everyone who has made grant proposals above a certain amount in the past.

[Reqrefusion]

The FPA's voting on grant proposals for the Quarter 4 2025 has been completed, and I regret to inform you that this grant funding was not selected.

No negative things were said about the proposal, and it was even greeted with joy. Toponaming and documentation are always among the top priorities of FPA. However, FPA is redesigning the grant system due to the end of the year. And in this direction, it wants the grant program to be used by more people and to be more competitive. Although these are not valid for this quarter, this request has made it difficult to approve proposals above a certain amount.

The rejection of the funding of a proposal for a quarter by the FPA does not mean that the relevant project has been rejected by FreeCAD management. If you wish, you can proceed with your proposal without funding. Additionally, the rejection of your proposal for this period does not prevent you from submitting the same or a similar proposal in future periods, nor does it create any bias against its acceptance.