Assembly 4 workbench

[Zolko]

Hello,

after a lot of brainstorming in the assembly without solver thread, and also some on the Assembly3 preview and New Assembly 4? threads, a new assembly workbench for FreeCAD has emerged, called sequentially in the list Assembly #4.

This thread starter will be updated if new versions of the workbench appear. The main development repository is https://github.com/Zolko-123/FreeCAD_Assembly4

Principle

The basic principle is the one from assembly without solver: FreeCAD's App::Part container serve as basic building blocs, that are inserted into each other using the App::Link interface introduced with FreeCAD 0.19.

The advantage of App::Link feature is that it's possible to link FreeCAD objects between files, seamlessly: a model in a file will appear in the tree of another model in another file, but the data is not copied across. This allows to create many instances of the same object without any overhead, allowing the creation of large assemblies. In other words, this is identical what other CAD systems do when speaking of assembly.

The particularity of Assembly 4 is that the placement of the inserted (linked) part is done by matching corresponding coordinate systems in the parent assembly and in the linked part: therefore, there must be at least 1 coordinate system in the assembly and at least 1 in the part. There can be many coordinate systems in each, and the user can choose which of these coordinate systems — in the assembly and in the part — shall be used. Under the hood, for those interested in the technical details, the ExpressionEngine of the Placement property of the App::Link is used to superimpose the Placement of two coordinate systems — one in the assembly and one in the inserted part — which fixes all degrees of freedom of the inserted part.

Another particularity of Assembly 4 is that there is no difference between a part and an assembly: it's possible to mix datum objects, 2D sketches, 3D geometries and inserted parts at will. This feature can prove to be extremely powerful once a user gets used to it.


Installation

Please bear in mind that Assembly 4 is not compatible with the stable FreeCAD v0.18, it needs the App::Link frame-work originally developed by realthunder and merged into FreeCAD v0.19. Pre-built binaries for this development branch can be downloaded here.

Addon Manager: The preferred method for installing the Assembly 4 workbench is through the Addons Manager (menu > Tools > Addons Manager). It is listed as Assembly4.

Manual install: you can download the Assembly 4 workbench as a ZIP archive here: it must be extracted somewhere, and the Mod_Asm4 subdirectory must be moved to the regular FreeCAD/Mod directory, where all other workbenches reside:

• for Windows it's in C:\Users\********\AppData\Roaming\FreeCAD\Mod
• for Linux it's in ~/.FreeCAD/Mod

You can use the provided example assemblies to experiment with this workbench's features.

Asm4_wb1.png (305.38 KiB) Viewed 86239 times

Quick Start

For the impatient, there are tutorials that guide you step-by-step through the building of simple assemblies :

• https://github.com/Zolko-123/FreeCAD_As ... TORIAL1.md
• https://github.com/Zolko-123/FreeCAD_As ... TORIAL2.md

phpBB [video]

Usage

In order to insert a part in Assembly 4 (and App::Link in general), it needs to be open in FreeCAD. It also needs to be saved to disk, because the App::Link framework needs the file's path. Unfortunately, it seems that when creating a new part and saving it, the App::Link doesn't "see" the file's path. So the surest way to use this workbench is to have files created, saved, closed, and re-opened: this way, the App::Link always sees the files you need. The workflow is then the following:

• create a new (empty) file
• click on the "create Model" button: this creates an App::Part container with all the needed elements
• save
• close
• re-open

The document is then ready to be used, as a part or as an assembly.

Toolbar

The Assembly 4 toolbar has following buttons:

• Create a new Model : creates a new App::Part in the current active document and populates its tree with necessary items to make it ready for Assembly4
• Create a new Body : creates a PartDesign::Body container in the selected App::Part
• Create a new Part : creates an App::Part object in the current document
• Import external Part : this opens a dialog allowing to link external object (the corresponding document must be open in FreeCAD)
• Place linked Part : allows to attach the linked part to LCS in the current assembly
• Insert Fastener : drop-down menu that allows to insert screws, nuts and washers from the Fasteners WB. If this WB is not installed the command is greyes-out
• make Array: creates a linear or circular array of links in the assembly. This feature is as yet experimental.
• Create Sketch : creates a Sketch in the currently selected Part
• Create Datul : creates a new PartDesign::DatumObject (LCS, Plane, Axis, Point) in the currently selected Part
• Import Datum : this opens a dialog allowing to select an existing datum object (LCS or Point) in an existing linked part in the assembly, and creates a datum object of the same type in the assembly placed where the original datum object is. This is useful if one wants to copy into the assembly something from a sub-part. This is parametric, meaning that when the original datum object moves the copied one moves accordingly.
• Place Datum
• Add Variable : adds a variable that can be used in the entire document
• Animate assembly : allows to change a variable between 2 values, and updates the assembly at each step
• Recompute and Update

3D geometry

After the root App::Part container — called 'Model' in Assembly 4 — has been created , there are 2 ways to have 3D geometries in a part:

• import or copy an existing Body from an existing FreeCAD document into the 'Model'. This allows easy re-use of your existing FreeCAD designs
• create a Body in the root 'Model' and use the PartDesign workbench as usually in this Body

LCS - Local Coordinate Systems

As said before, the principle of Assembly 4 is to match coordinate systems in the assembly and in the part. Therefore, coordinate systems need to exist in both the assembly and in the part. Technically, they are FreeCAD objects of type PartDesign::CoordinateSystem. When such an LCS is first created, it is placed at the origin of the part. In order to be useful, an LCS must be located and oriented at a position where something is attached: a hole, an edge, offset ... For that, use the MapMode of the LCS object:

LCS_Attachment.png (291.13 KiB) Viewed 87913 times

There are basically 2 methods :

• either create the 3D geometry first, and then place the LCS on top of the useful features
• or create first a functional skeleton of the part, using datum object and sketches at the root of the Model, and then build the 3D geometry around the datum objects

The first method will be mandatory if you import the 3D geometry (from STEP files for example, or from pre-existing FreeCAD objects), but it can be subject to the infamous topological naming of FreeCAD of you modify the geometry later. Therefore, if you create the 3D geometry in FreeCAD itself I strongly recommend to use the second method. The first method will produce a geometrical assembly, the second a functional assembly.

Assembly

In order to insert an Assembly 4 'Model' into another Assembly 4 'Model, use the command 'Insert External Part' : this will allow you to chose one part in any of the open documents, and will ask you the name under which the instance of the part shall appear in the assembly tree. It is important to note that this name must be unique in the tree. By default, the insert part dialog will propose the same name for the instance as the name of the document where the part is located, but you can choose any name of your liking. If you choose a name that already exists, FreeCAD will modify it to something unique (and which may be un-nice to you)

Once inserted, the instance is placed using the command 'Place an Instance' (or 'Move an Instance'). This will show a dialog in 2 columns: the left column shows all coordinate systems in the linked part that can be used to attach to part, and the right column shows all other parts in the assembly and their coordinate systems that can be used to attach the instance-to. Use the 'Show' button to pre-visualize where the part's going to be placed. 3 rotation buttons allow the instance to be rotated by steps of 90° around the 3 axes X, Y and Z

A part can be attached either to an LCS in the assembly itself ("parent assembly"), or to an LCS in a part already inserted in the assembly ("sister part"). But only coordinate systems directly at the root of a 'Model' container — in the parent assembly or in a sister part — can be used for attachment, and not, for example, coordinate systems from a Body in the part tree.


Nested assemblies

This workbench allows the assembly of assemblies: since there is no difference between parts and assemblies, the 'Insert External Part' allows to chose a part that has other parts linked to it. The only difference will be for the coordinate systems in the inserted assemblies: in order to be used with Assembly 4, a coordinate system must be directly in the root 'Model' container, meaning that a coordinate system inside a linked part cannot be used to attach the assembly to a higher-level assembly.

Therefore, in order to re-use a coordinate system of a part in an assembly, a coordinate system must be created at the root of the 'Model', and the placement of this coordinate system must be 'copied' over from the coordinate system that the user wants to use. This is done by inserting a coordinate system and using the 'Place LCS' command, which allows to select a linked part in the assembly and one of it's coordinate systems: the 2 coordinate systems — the one at the root of 'Model' and the one in the linked part — will always be superimposed, even if the linked part is modified, allowing the placement of the assembly in a higher level assembly using a linked part as reference. It sounds more complicated than it actually is.

————————————————
EDIT (2020.02.11): Added section about tutorials.

EDIT (2019.10.09): this Assembly 4 workbench is now in the FreeCAD addon manager, and can be installed as any other module.

EDIT (2019.10.05): the Asm4 workbench has been updated to work with FreeCAD v0.19-preview. The main difference is in the syntax of the ExpressionEngine

EDIT (2019.03.11): the git repository should now work as it's supposed-to

EDIT (2019.03.12): cosmetic change: moved actual Python code to Mod_Asm4: this is the directory to be moved/copied/linked inside ~/FreeCAD/Mod. Added some more examples to experiment

EDIT (2019.07.16): added location for Mod_Asm4 subdirectory in Windows and Linux

EDIT (2019.07.18): added loads of new explanations

[Zolko]

I prefer to use git in a GUI interface, I learned it so much faster that way. I made a page on the wiki dedicated to it (though the app is proprietary, it is free to use for FOSS activities : Gitkraken

thanx for the info. I tried GitKraken, seemed to mostly work, but I didn't like the licensing. Looking at other Git clients, I found Guitar, opensource, native Qt based. Doesn't ask about any passwords, seems to work. May-be I'll get to git somehow ...

[triplus]

GitHub has a rather good documentation. When it comes to tasks like forking, cloning, creating branches, pushing and keeping the fork in sync. Instructions usually don't involve any special GUI client. Therefore in my opinion best if you don't involve any GUI clients at first, maybe just a GUI tool like gitk, for browsing the history and changes.

P.S. If it is about your repository, basically you can get away with learning just the cloning, committing and pushing tasks first. And worry about the rest if and when the need arises.

[Zolko]

If it is about your repository, basically you can get away with learning just the cloning, committing and pushing tasks first

yep, that's what I have in mind also. There is this "staging" thing also. So for every change you have to do : stage → commit → push. I'm sure that with some imagination, they could have added some more intermediate steps: select → stage → queue → commit → stack → push ... grrrrrrrrr

There is another git client that seems not too bad: git-cola, written in Python3-Qt5 ... room for thoughts

[triplus]

OK i won't discuss this further in this thread, as it's off topic.

Staging area is an area for preparing the commit. You don't always want to add all modified files from the working directory to the staging area. Therefore indeed you are able to select something specific, like an individual modified file and add just that to the staging area. You can do things like stashing staged and modified files from working directory for latter. And this things for sure aren't cons.

[Zolko]

I've added a new example to the Assembly 4 repository. It's my previous V4 engine, but updated to the latest Asm4 workbench. It's actually much faster than before, I don't know what brought this speed increase. This one has assemblies of sub-assemblies saved in sub-directories, and some fancy constructions using sketches and linked datum points across documents.

Asm4_V4.gif (952.67 KiB) Viewed 90742 times

[triplus]

Such things for sure look impressive, but ATM we don't need that all that much. Castles are usually build stone by stone. Therefore please prepare a detailed tutorial, here in this thread, on how to assemble two such stones, using Assembly 4 workbench. And please add comments, on what you feel is missing, or could still improve in the future. That is, if we would add such way of Assembling to FreeCAD 0.19 or likely early in FreeCAD 0.20 development cycle. Currently therefore you are utilizing expression engine as a solver, LCS feature as an interface and Part::Link extensively. From user interaction point of view a dialog is provided.

Thanks.

[Zolko]

Castles are usually build stone by stone.

Thank-you for your comparison.

May-be I took the problem from the wrong edge, but what I wanted to show is that we can build "castles" with this method, therefore it was worth to invest some time and intelligence to be familiar with it.

As opposed to : "look, we can assemble 2 cubes, yoohey ! We can do assemblies"

But I think I understand your remark, and I'll try to provide more scolar examples

[triplus]

Thank-you for your comparison.

You're welcome.

May-be I took the problem from the wrong edge, but what I wanted to show is that we can build "castles" with this method, therefore it was worth to invest some time and intelligence to be familiar with it.

As opposed to : "look, we can assemble 2 cubes, yoohey ! We can do assemblies"

Well, but that is the point, isn't it? We are not after 1% being able to assemble in such way, the other 99% of people should be able to do that too.

But I think I understand your remark, and I'll try to provide more scolar examples

Thanks.

[bill]

I've added a new example to the Assembly 4 repository. It's my previous V4 engine, but updated to the latest Asm4 workbench. It's actually much faster than before, I don't know what brought this speed increase.

Speed increase, probably because of your short circuited firing-order!

It would be a bit more aesthetic if cylinders 3 and 4 fired separately!