variant Link

Info about new community or project announcements, implemented features, classes, modules or APIs. Might get technical!
PLEASE DO NOT POST HELP REQUESTS OR OTHER DISCUSSIONS HERE!
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
Zolko
Veteran
Posts: 2213
Joined: Mon Dec 17, 2018 10:02 am

variant Link

Post by Zolko »

Hello,

I have finally managed something that I wanted to do for a long time, and something that has been requested many times in the assembly forums: variant links. This is a link to a part but with varying parameters, meaning that you can isert the same part several times, but adjusting the parameters of each instance of the part. You can find background info here

There are typically 2 use cases:
  • some standard part that can be cut/manufactured to specific dimensions. The most obvious example is an extruded beam
beam.png
beam.png (275.53 KiB) Viewed 13756 times
beams.png
beams.png (433.62 KiB) Viewed 13753 times


  • a sub-assembly that has some kinematics and that can be inserted into the main assembly with different values of the kinematics. A good example is the Theo Janses sandwalker, where a single leg is inserted many times, with different angles on its commanding axis.

    The case of variant assemblies is extremely interesting because only the assembly is duplicated, not the parts that make it, therefore the memory overhead is quite low: mostly, if using master sketches, only the sub-assembly containing the master sketch will be duplicated, and all the App::Links in the variant assembly still point to the same App::Parts that the original non-variant sub-assembly.

The usage is simple (but only in the Assembly4 workbench) :

Image

Objects that can be used as source for a variant link are standard App::Part (Std_Part) that contain a PropertyContainer called "Variables ". All variables of the source object can be set individually for each variant. Such variant links and their individual variables are persistent, meaning that they will be restored when the document is restored.

Unfortunately, there still are some errors, so use with caution
try the Assembly4 workbench for FreCAD — tutorials here and here
paullee
Veteran
Posts: 5092
Joined: Wed May 04, 2016 3:58 pm

Re: variant Link

Post by paullee »

Thanks ! That seems to be useful in building industry :)

Trying to dig in the those other threads to understand the workflow, any example please ?
a.l
Posts: 86
Joined: Thu Apr 09, 2020 7:14 pm

Re: variant Link

Post by a.l »

Brilliant - just what I need! Thanks a lot! :)
Now, first I got discouraged that it only works for Part and not Part Design (as I read the description).
But..., I found a workaround - it seems. Really simple.
I am although not sure how it works in practice since I have only tested it with a simple sketch as template and then using the new variant Link functionality.

So basic steps:
1. In a blank project create just a Part.
2. Go to Part Design and create a Body.
3. Create a Sketch and select some Plane.
4. Create an initial closed sketch using normal geometry (well just like you normally would).
5. Create e.g. a Pad on that sketch.
6. Hopefully everything looks nice and dandy.
7. Make sure to save the project!

8. Now open an existing blank Assembly file (or create one in another project!)
9. Copy its Variables container or whatever we should call it (it is of type App::PropertyContainer).

10. Back in the other project containing the Part activate that part (or go to Assembly 4 Workbench in case of doubt). Right click on Assembly and select "Toggle active part".
11. Paste the Variables container into the Part. If you are a bit unlucky it might end up the wrong place, but then simply drag it into the Part.
12. Create the variable in the part, by doing this:
a. Go to the Variables container by clicking on it.
b. Make sure its Data (sub) tab is selected in the "Property View".
c. Right click and select "Show all"
d. Right click and select "Add property".
e. Under "Group" enter "Variables".
f. Under "Name" enter the name you want to give your variable!
Whether you want to prefix the group name is up to you (I just left it so. So I have not tested it without.)
g. Click "OK".
h. Outside give the variable a default value you want it to have.

13. Open you previous sketch.
14. Add or change an existing constraint and enter a formula for that constraint. It would be called something like: Variables.Variables_"name of your variable"
15. Remember to create a LCS (local coordinate system) using Assembly 4 Workbench in the part!
16. Save the Part again.

17. Create or reuse an existing Assembly.
18. Use the new functionality/Icon where it says "... Create a variant link to a part ..." (that green and yellow Part like looking icon).
19. Insert the part one or several times and obviously set the linked parts (in the Assembly 4 workbench - "Move/Attach a Part in the assembly"/"Place linked part").
20. Click on one of the imported (virtual/variant linked) Parts (not its internal contents - do not expand, because that would be the wrong place - read below).
21. In the Property View scroll all the way down till you get to the "Variant Variables" and change the value in the variable that has the name of your variable! Enjoy - but see the caveats and bug/consequence description below!

There are caveats:
* After changing the variable in the imported (variant linked) part then the part gets (e.g. resized), but you will have to save and close the assembly and open it again to get alignment at the specified attachment point right (e.g. to get parts centered to one another). (Not a big problem necessarily in a static assembly where you are not making many changes).
* Should any consider to dive into the part (open the variant linked virtual part) and modify its Variables "variable" then the value will not be saved (it is also the wrong way to handle it (since you need to do that directly on the virtual variant part), but you can modify its formula(!) and then the value or specific formula you may enter gets saved! Just remember it is an anti-pattern (it is the wrong place/way of doing it! Read above!)

But there seems to be a bug/consequence of my 'hack':
When the folders in /tmp/ called "FreeCADStartThumbnails" + "random characters" are deleted then at following startups in FreeCAD loading an assembly triggers this output (error is printed in red in the "Report view"):

Code: Select all

16:32:49  Exception opening file: /tmp/FreeCAD_Doc_3e6cdd91-522f-4709-9335-6d66db370d38_da39a3_10317 [File '/tmp/FreeCAD_Doc_3e6cdd91-522f-4709-9335-6d66db370d38_da39a3_10317' does not exist!]
16:32:49  Exception opening file: /tmp/FreeCAD_Doc_052373ee-e232-4725-bae8-be6d728472b7_da39a3_10317 [File '/tmp/FreeCAD_Doc_052373ee-e232-4725-bae8-be6d728472b7_da39a3_10317' does not exist!]
, which is true, but there are some other of these directories:
"FreeCAD_Doc_" + "random characters"
This seems to be the "Transient Dir" of the project (whatever that is used for).

Anyway the 'hack' still seems to work despite the bug/consequence of my 'hack'.
Enjoy!
Thanks Zolko for your work! :)

OS: Ubuntu 20.04.3 LTS (MATE/mate)
Word size of OS: 64-bit
Word size of FreeCAD: 64-bit
Version: 0.19.
Build type: Release
Branch: unknown
Hash: 0d9536ed3e8c7f40197b5606e1b7873625e1d6fe
Python version: 3.8.10
Qt version: 5.12.8
Coin version: 4.0.0
OCC version: 7.5.2
Locale: Danish/Denmark (da_DK)
Attachments
SomePart.FCStd
(11.62 KiB) Downloaded 109 times
SomeAssembly.FCStd
(6.81 KiB) Downloaded 117 times
User avatar
Zolko
Veteran
Posts: 2213
Joined: Mon Dec 17, 2018 10:02 am

Re: variant Link

Post by Zolko »

a.l wrote: Fri Dec 10, 2021 4:26 pm 9. Copy its Variables container or whatever we should call it (it is of type App::PropertyContainer).
...
11. Paste the Variables container into the Part. If you are a bit unlucky it might end up the wrong place, but then simply drag it into the Part.
12. Create the variable in the part, by doing this:
there is an easier way: create a Part (yellow icon), select it, and click on "Add Variable" and this should create the Variables container inside the Part and add the new variable to it.

There are caveats:
* After changing the variable in the imported (variant linked) part then the part gets (e.g. resized), but you will have to save and close the assembly and open it again to get alignment at the specified attachment point right
if this is true then it's a bug. Did you try to update/recalculate the entire assembly ? This should do it for all variant links

* Should any consider to dive into the part (open the variant linked virtual part) and modify its Variables "variable" then the value will not be saved (it is also the wrong way to handle it (since you need to do that directly on the virtual variant part), but you can modify its formula(!) and then the value or specific formula you may enter gets saved! Just remember it is an anti-pattern (it is the wrong place/way of doing it! Read above!)
I don't understand this point. All variant variables should be saved in the assembly, and restored when the file is opened. Can you please explain ?

Code: Select all

16:32:49  Exception opening file: /tmp/FreeCAD_Doc_3e6cdd91-522f-4709-9335-6d66db370d38_da39a3_10317 [File '/tmp/FreeCAD_Doc_3e6cdd91-522f-4709-9335-6d66db370d38_da39a3_10317' does not exist!]
16:32:49  Exception opening file: /tmp/FreeCAD_Doc_052373ee-e232-4725-bae8-be6d728472b7_da39a3_10317 [File '/tmp/FreeCAD_Doc_052373ee-e232-4725-bae8-be6d728472b7_da39a3_10317' does not exist!]
Yes, this is normal, I must find a way to intercept that error at the opening of an assembly containing a variant link.
try the Assembly4 workbench for FreCAD — tutorials here and here
a.l
Posts: 86
Joined: Thu Apr 09, 2020 7:14 pm

Re: variant Link

Post by a.l »

Hi Zolko,

Thanks!
a.l wrote: Fri Dec 10, 2021 4:26 pm 9. Copy its Variables container or whatever we should call it (it is of type App::PropertyContainer).
...
11. Paste the Variables container into the Part. If you are a bit unlucky it might end up the wrong place, but then simply drag it into the Part.
12. Create the variable in the part, by doing this:
there is an easier way: create a Part (yellow icon), select it, and click on "Add Variable" and this should create the Variables container inside the Part and add the new variable to it.
You are right. I must have been messing around with either some old parts or be confused back then when I tried it out. Thanks for clearing that one up!
There are caveats:
* After changing the variable in the imported (variant linked) part then the part gets (e.g. resized), but you will have to save and close the assembly and open it again to get alignment at the specified attachment point right
if this is true then it's a bug. Did you try to update/recalculate the entire assembly ? This should do it for all variant links
I did try that, but it did not work however today I found a way to handle that as mentioned below by using "Recompute object" on the specific variant link. However also mentioned below it only works on some problems.

So I have made a demo to show the problems that arise when using the experimental variant link functionality.
I have tried to make the example so minimalistic so that it should be easier to grasp.
I have updated to the recently released Assembly 4 with version 0.11.6 and build the demo example there.
Unfortunately I am currently using Freecad 0.19.2 (Version: 2:0.19.2+dfsg1~202107210810~ubuntu20.04.1), because I haven't seen the package repo having an update for 0.19.3 yet.

The example
------------------
So there are 4 files consisting of 2 parts and an intermediary and a main assembly (that gathers everything in the end).
PartA is a "template" part consisting of a bent arc.
It can be used to dynamically generate specific parts that correspond to a level which actually in this case means an angle offset over the horizontal axis. These parts when puzzled together will then form something that looks like a dome.
Notice that to avoid problems with dynamically altering angles inside sketches I instead alter the attachment offset on the z-axis of the sketch itself!
PartA.png
PartA.png (136.28 KiB) Viewed 11629 times
PartB is a simple rod.

Aggregate (intermediary assembly) puts PartA and PartB together.
The level (angle offset) is controlled by a Variables variable called Level.
Aggregate 1. Normal.png
Aggregate 1. Normal.png (134.08 KiB) Viewed 11629 times
MainAssembly puts several Aggregates together using variant links and each of these aggregates has a unique level set!

Now, there are two - three problems (which might be same problem - I am unable to tell).
1. In the Aggregate assembly when the Level variable gets set then very often PartA jumps to some irregular positions instead of staying visually linked with PartB.
Aggregate 2. Level changed causing jump of PartA_var.png
Aggregate 2. Level changed causing jump of PartA_var.png (136.41 KiB) Viewed 11629 times
2. (Continuing from 1.) If the Level parameter gets set several times then PartA often jumps further around to what seems to be unpredictable locations.
Note: Both 1. and 2. can often be fixed (not by "Update Assembly" but) by right clicking on the PartA_var (in the Aggregate assembly) and selecting "Recompute object". Well it works most of the times, because...
Aggregate 3.1 Level change again causing jump and rotation of PartA_var.png
Aggregate 3.1 Level change again causing jump and rotation of PartA_var.png (139.75 KiB) Viewed 11629 times
Aggregate 3.2 Recompute object.png
Aggregate 3.2 Recompute object.png (212.14 KiB) Viewed 11629 times
End of the first part of this message due to amount of attachments limitation.
a.l
Posts: 86
Joined: Thu Apr 09, 2020 7:14 pm

Re: variant Link

Post by a.l »

Second part of my message.
Aggregate 3.3 After Recompute object.png
Aggregate 3.3 After Recompute object.png (151.48 KiB) Viewed 11613 times
3. ... As can be more easily seen in the MainAssembly then some of the Aggregates have their "PartA"s flipped 180 degrees. I haven't found out how to prevent this or workaround this.
This problem can also happen inside the Aggregate assembly. As mentioned the problematic cases can sometimes be fixed using "Recompute object" works, but not always.
MainAssembly 1. Some PartA_vars are strangely rotated upside down.png
MainAssembly 1. Some PartA_vars are strangely rotated upside down.png (184.5 KiB) Viewed 11613 times
I hope I made myself somewhat understandable.
I always consider the topological naming problem, but in this case I am unable to say if it should be the case, because here the setup is so simple that I must overlook the real problem if topological naming problem is the cause of the issue.

(As mentioned above I have on purpose NOT used a dynamic angle inside the sketch "Sketch-base-NOTICE-Attachment-is-adjusted-by-Variables.Level-around-z-axis", because that could lead to problems with what I guess is either the solver messing up or the topological naming problem giving problems. At least that is my previous experience in a more complicated setup. This seems NOT to be an Assembly 4 issue obviously, but annoying anyway.)

On a note basis:
1. Okay I do not have a ready made example for this so you might want to ignore it for now, but my previous experience with a more advanced Assembly 4 variant link example is that when you have nested assemblies using variant links then if the part (meaning the inner most portion of the Aggregate and MainAssembly) has e.g. a sketch that fails then you are unable to adjust e.g. the variant linked parts/assemblies if you try to alter their Variables in the "Property View" of that linked part. The variant linked part seems stuck/locked. Now this is obviously only a minor issue, but may confuse some people I guess. It did confuse me in the beginning.

2. So another "problem" is that in an assembly it is not possible to link a normal part to a variant linked part.
The normal part is in this case the left hand side of the "Move/Attach a Part in the assembly" (yellow part symbol with the blue crossed direction arrows) dialog window whereas the variant linked part is found in the drop down menu "Attach to".
I have been able to workaround that somehow for now, but if possible I guess some people would find such a "link normal part to variant link part" feature nice to have.

3. Re.
* Should any consider to dive into the part (open the variant linked virtual part) and modify its Variables "variable" then the value will not be saved (it is also the wrong way to handle it (since you need to do that directly on the virtual variant part), but you can modify its formula(!) and then the value or specific formula you may enter gets saved! Just remember it is an anti-pattern (it is the wrong place/way of doing it! Read above!)
I don't understand this point. All variant variables should be saved in the assembly, and restored when the file is opened. Can you please explain ?
You are right. It deserves some screenshots and a better explanation! Please see the file names of these screenshots as explanation:
Variables inside the variant linked part is selected to the left
whereas the value is changed in the Property View to the right!
Variables 1. value change inside variant link not possible - system rolls it back after variant link gets recomputed.png
Variables 1. value change inside variant link not possible - system rolls it back after variant link gets recomputed.png (202.23 KiB) Viewed 11613 times
Variables 2. formula change inside variant link possible - system does not try to override the formula entered.png
Variables 2. formula change inside variant link possible - system does not try to override the formula entered.png (227.86 KiB) Viewed 11613 times
Variables 3. formula change inside variant link stays.png
Variables 3. formula change inside variant link stays.png (206.39 KiB) Viewed 11613 times
But as mentioned it is just what I would consider an anti-pattern to do these internal changes unless someone tries to be "smart" in a desperate situation maybe. ;)

Thanks a lot for your continued efforts Zolko!
Assembly 4 is such a great tool!

I am going to upload the FreeCAD project files in just a moment in the following message...
a.l
Posts: 86
Joined: Thu Apr 09, 2020 7:14 pm

Re: variant Link

Post by a.l »

And here follows the project files for the messages right above.
Attachments
PartB.FCStd
(11.4 KiB) Downloaded 95 times
PartA.FCStd
(21.8 KiB) Downloaded 86 times
MainAssembly.FCStd
(19.75 KiB) Downloaded 92 times
Aggregate.FCStd
(9.6 KiB) Downloaded 91 times
User avatar
Zolko
Veteran
Posts: 2213
Joined: Mon Dec 17, 2018 10:02 am

Re: variant Link

Post by Zolko »

Thank-you for testing and reporting on this experimental target

a.l wrote: Thu Jan 13, 2022 10:51 pm So there are 4 files consisting of 2 parts and an intermediary and a main assembly (that gathers everything in the end).
I don't understand how you built your model: it seems to me that the agregate already uses PartA as variant link. So if you insert the agregate into the main assembly, what result do you expect ?

a.l wrote: Thu Jan 13, 2022 10:51 pm PartA is a "template" part consisting of a bent arc. It can be used to dynamically generate specific parts that correspond to a level which actually in this case means an angle offset over the horizontal axis. These parts when puzzled together will then form something that looks like a dome.
I don't understand what the "level" variable is doing: if it's an angle, shouldn't this be a float ?

In your case, I'd include each of the dome's variant part individually to the main assembly, and if necessary do the same for the rods.
try the Assembly4 workbench for FreCAD — tutorials here and here
a.l
Posts: 86
Joined: Thu Apr 09, 2020 7:14 pm

Re: variant Link

Post by a.l »

Thank you for your follow-up Zolko. :)

I admit I should have explained myself a bit better. Too many things got accumulated in the messages above so it got too messy. I am sorry about that!

Let me start with the "level":
The "Level" is used as to have a more easy representation of some part at a specific level (/place in the model). So to say a part at level 3 (in the dome/orb/sphere) is used instead of referring to it as "the part that starts at e.g. 30 degrees", because I have also experimented having parts at odd degrees (at steps) of e.g. 11 or 12 degrees (instead of 10 degrees as in the demo).
In that way it becomes easier just saying level 1, 2, 3, 4, ...

Again it is to have one "easy" parameter to reuse in a variant part (or variant linked assembly used as a part in another assembly), so just by adjusting one parameter it is possible to generate several variant linked parts (that are generated by being bend around an orb/sphere/dome using an AdditivePipe, a path and a sketch that gets its z-axis attachment rotated a bit accordingly to the selected level).

The main idea behind having 2 parts and 2 (or 3) assemblies is to lower the amount of repetitions when inserting into an assembly or in this case several assemblies.

Let us say I want to make a dome. Each part covers horizontally 90 degrees. (The reason for 90 degrees is if you make those parts a bit different in a more advanced design - e.g. about positioning and other things, but I will not go into details about that).
Meaning to cover a whole dome four (4) of these parts are needed. But that is only at one level!

In this case we have two parts per level - part A and part B.

Since in this example there are 9 levels the maths becomes something like:
2(part links) x 4(per level) x 9(levels) = 72 part links

So to save some (a lot of) manual insertions (but also very relevant as well) keep the maintenance required so simple as possible I would like to keep the amount of insertions down by trading some of the manual part insertions with some intermediary assemblies.

It could be something like:
* 2 parts
* They are put together into the aggregate assembly
* The aggregate assembly is used as variant linked part inside a main assembly that creates levels 1, 2, ..., 9
* And perhaps another step where the main assembly is used as a variant linked part inside a "north, south, east, west" kind of assembly completing the dome.

In total that would generate the following amount of part links used
2 + 9 + 4 = 15

So the difference for insertion and maintenance is 72 - 15 = 57 part links!
This is a huge win to not insert and maintain 57 part links!
Even though it costs 2 - 3 extra assemblies it makes it easier to grasp and maintain. Also because it saves us from creating extra sketches and lines and LCS coordinate systems etc. that also requires maintenance if something is changed somewhere.

What I mean is that your tool makes it really flexible and easy to accomplish using nested assemblies (meaning an assembly that relies on another variant linked assembly that relies on another variant linked assembly).
So if the strange behaviour regarding the upside down parts could be fixed/worked around somehow without loosing the benefit of only using 15 part links then that would be great. :)
It would also be great if an update to a variant linked part or assembly triggers a coherent update to the current assembly (the model as a whole) so a manual update is not required using "Recompute object".

Thanks once again for your time and efforts!
User avatar
Zolko
Veteran
Posts: 2213
Joined: Mon Dec 17, 2018 10:02 am

Re: variant Link

Post by Zolko »

a.l wrote: Mon Jan 17, 2022 5:18 pm Let me start with the "level":
In that way it becomes easier just saying level 1, 2, 3, 4, ...
I'm sorry, I still don't understand these "levels". Could you describe it with a model tree ?

So if the strange behaviour regarding the upside down parts could be fixed/worked around somehow without loosing the benefit of only using 15 part links then that would be great.
yes, that sounds reasonable, but I'd need to understand the structure of your model
try the Assembly4 workbench for FreCAD — tutorials here and here
Post Reply