Assembly3 Workbench

Introduction
Assembly3 is an external workbench that is used to perform assembly of different bodies contained in a single file or in multiple documents. The workbench is based on several core function changes done for the version of FreeCAD 0.19 (e.g. App Link), so the Assembly3 Workbench can not be used with earlier versions.

The main features of the Assembly3 Workbench are
 * dynamic/interactive solver. This means you can move parts with the mouse while the solver constraints the motion. This allows for example to connect a wheel to an axis and turn the wheel interactively with the mouse.
 * links. This means you can use one single part, e.g. a screw multiple times in an assembly (at different places) without duplicating geometry.
 * external links. It is possible to have a freecad document that only contains an assembly and not parts. All parts could be in single files. The files even could be in a library or anyhwere else in the file system. The only requirement is that the file must be loaded when the link is made. After the link is made, the file must be open to make updates to the links involving the file. Assembly3 solves this by opening files in the background as required.
 * hierarchical assemblies. As is real life a mechanical assembly may consist of sub-assemblies. Those might consists of sub-assemblies again and so on.
 * assembly freeze. As the CPU can handle only so many concurrent constraints in real time, to freeze an assembly allows to use constraints even for large assemblies. By freezing finished assemblies or constraints that are not required to remain dynamic (e.g. welded, bolted or glued parts) those are excluded from update calculations and considered fixed geometry by the Assembly3 solver.
 * Note that other approaches offer different solution to this problem, e.g. the Assembly4_workbench_icon.svg Assembly4 Workbench.

top

Toolbars
As of 2020 the Assembly3 workbench features the following toolbars.


 * The Constraints tool bars will be the main interface used when assembling parts. They are greyed out by default but are activated once at least one face, line or point of a part is selected. Generally you select the Elements that should be joined and then select the constraint type. The different colored frames mark different characteristics of the constraints: whether 2D/3D of if more than 2 Elements can be added. A detailed description can be found in the Gibhub wiki.

As usual you can modify the tool bars and add or remove single tools. Be sure to check the menu Assembly3 for functions that may not be present in the tool bars.

top

Constraints
The designer uses constraints to achieve the desired result for the relation of two parts. The art is the selection of the right constraints best suited to deal with each problem. Each eliminated DOF should in theory only be eliminated once between two objects, but in practice with many CAD tools selected constraints cause over-constraint combinations, often compensated by complex algorithms, sometimes not. Assembly3 does use algorithms to detect and compensate over-constraints, but clearly they are not very matured yet. So in practice for Assembly3 constraints avoid trouble by being aware of how many degrees of freedom (DOF) have been used and which ones are still to be locked down by constraints. No part should have a connection by constraints usind more than 6DOF.


 * Note: If the solver meets a combination that can not be solved, it will give an error. It is very difficult for the solver to find out what caused the problem, so typically from this error given it will not be clear where the problem is. In larger assemblies this can lead to complex problem searches. Unfortunately there is no easy way to avoid this. However, it helps to be fully aware how the system works (.e.g see Elements below), use clear names for all components involved and only ever add additional constraints when the solver solves the current assembly. Very helpful to track down a problem is the "ContexMenu/Deactivate" function of each Constraint.

Assembly3 Constraints define restrictions in the position or orientation between two Elements. Some constraints even work with more than two Elements. An Elements can be a face, a line or edge or a point of a part. Generally constraints are defined by selecting the desired Elements and then select the constraint from the Constraints toolbar.

Other
 * Fixes 6 DOF, leaves 0 DOF:
 * Lock: The lock constraint fixes all DOFs for a face. It should be used for one base part in each assembly. You may also want to enable the "MoveLock" function (in the tool bar) so that the part can not be moved accidentially. Normally it does not matter which face/line/point you use to fix a part. Also note that the lock is only valid for the direct assembly, i.e. in case of a sub-assembly the parent assembly would still require a locked part on its own.
 * Attachment: Makes both elements coordinate systems equal for all axes. This is computation wise the most inexpensive function and should be used where ever possible. Note that you could use the element properties to compensate for offsets and angles if the two elements are not perfectly aligned.
 * Fixes 5 DOF, leaves 1 DOF:
 * Plane Coincident: fixes Tx,Ty,Tz, Rx,Ry. Only Rz is free. There remains the rotation around the normal passing through the ‘‘center of the plane’’.
 * Fixes 4 DOF, leaves 2 DOF:
 * Axial Alignment: fixes Tx,Ty, Rx,Ry. Only Tz, Rz are free. There remains the rotation around the axis of the shape and the translation along this same axis. Two PointOnLine constraints (if the two points are different) give the same result. The '‘Colinear'’ constraint too.
 * PointOnLine: This eliminates the translation and rotation along the normals to the reference line. Only the translation and rotation along the line axis is allowed.
 * Fixes 3 DOF, leaves 3 DOF:
 * Same Orientation: fixes Rx,Rz,Rz. All T's remain free.
 * Points Coincident: fixes Tx,Ty,Tz. All R's remain free.
 * PointOnPoint constraint eliminates the 3 translations.
 * Plane Alignment: fixes Tz, Rx,Ry. In plane motion and Rz. This eliminates the translation along the normal to the reference plane and the two rotations around the axes of this plane.
 * Fixes 2 DOF, leaves 4 DOF:
 * Multi Parallel: fixes Rx,Ry. all T's and Rz remain. This eliminates the two rotations around the axes of the reference plane.
 * Fixes 1 DOF, leaves 5 DOF:
 * Points in Plane: Fixes Tz. This eliminates the translation along the normal to the reference plane.
 * Points Distance: fixes the distance between the Element origins.
 * This gives you more freedom than Points in Plane
 * Points on Circle: fixes Tz and partially Tx,Ty. Freezes the point translation (or several points) on a circle or disk area. You must pick the circle second. This leaves all rotations free and gives limited translation in the circle reference plane.

'': Note: In the following list Tx,Ty,Tz and Rx,Ry,Rz are used to describe translations and rotations about the reference coordinate systems of the involved Element's. This is not always exact or fully defined, e.g. when a line is involved it is not defined if it runs in X, Y or any angle in betweeen. The system is used for bevity and easy comparison in favour of a correct but more complex definition. So Z is generally the normal direction of any faces involved. Please feel free to modify this with a better approach with improved readability.''

top

Elements
Elements is a specific term used in the Assembly3 workbench and it is important to understand Elements for understanding how Assembly3 should be used.

It is helpul to think of an Element as a general word for a 'selectable item' of a part, i.e. a face, an edge, a circle or a corner or other point. The items you select to constrain them, are those Elements. In the tree an Assembly folder has three sub-folders. Beside 'Parts' and 'Constraints' there is a folder named 'Elements', which is emtpy as long as there are no constraints added. When adding a constraint the constraint itself gets two (or more) leafs, these are the selected 'Elements'. Also these get added in the 'Elements' folder which is just a list of all Elements used in the assembly. Its a good idea to change their names (with F2 key), especially in bigger assemblies.

Lets look at an example
 * Create a new file and add from the Part workbench a cube and a cylinder. We will stack the cylinder onto the tube. First we fix the base part, in out case the cube. Select the bottom face of the cube and select the "Locked" constraints (first icon in the Constraints toolbar). Select the top face of the cylinder and the top face of the cube. Then select the "Plane Coincident" constraint. Now the cylinder is moved into the cube and in the tree a new leaf with two childe nodes was added under 'Constraints'. Additionally the same two child nodes were added under 'Elements'. If you cylinder is inside the cube instread of on top of the cube, lets correct that first: select the child node under 'Constraints' that shows the cylinder face and with a right click in the context menu select 'Flip Part'. Now the cylinder is stacked onto the box.

The key think to understand is that the constraint operates on links to Elements in the list in the 'Elements' tree folder. This allows to keep the constraint structure intact while changing the parts. This is very difficult to see without an example.

Lets get back to the example above
 * Note: make sure you added the "Lock" constraint to the cube or this will look confusing
 * In the CAD window select another face of the cube. Now we only work in the tree view. Go with your mouse in the tree where the cube should be selected. Drag&Drop the cube to the 'Elements' folder. Drop it on the 'Elements' name, not anywhere else in the folder - why we see later. You should see that another Element is added to the 'ELements' list. Now select in the 'Constraints' folder the child node of the cube face in out "Plane Coincident" constraint and delete it. The Constraint will show an exclamation mark since its missing one Element. Note that by deleting the Element in the Constraint we did not delete it in the list. That is because in the constraint was only a link to the Element in the list. Now take the newly added Element in the 'Elements' list and drag&drop it onto the "Plane Coincident" constraint. Now the cylider moves to the other face we selected. We might need to select 'context menu/flip part' again if the cylinder is again inside the cube.

The example showed that without removing the constraint we can change the Elements that are used for the constraint. The same way we can move the cylinder to a totally different part. After playing around with this example a bit more, you will note some additional things as
 * If you rename an Element in the list, the name will be changed in all Constraints.
 * you can use one Element in the list in several constraints.
 * You can use the Property Window of an Element to add Offsets. In the example this could move the cylinder around on the cube face.
 * you can use the "Show Element Coordinate System" button in the main toolbar to see what 'ContextMenu/Flip Part' and 'ContextMenu/Flip Element' are doing. Be sure to look what happens in the Property Window.
 * you can add a constraint in a totally different order: First add some Elements to the 'Elements List' (naming is useful, e.g. "Cube Top Face" or "Cube Front Face"), then add a constraint without selecting anything - it will be an empty constraint. Then drag Elements from the 'Elements' list. The result is the same than what we did in the first example. After doing that exercise the nature of how constraints work with Elements should be clear.
 * you can change an existing constraint between existing elements by just select a different item in the PropertyWindow/ConstraintType property.

top

Compatibility
Assembly3 was inspired by Assembly2, but it is not compatible with it. If you have older models made in Assembly2, you should stay with FreeCAD 0.16 and use Assembly2 there.

New models developed with Assembly3 should only be opened and edited with this workbench.

Although they may have similar tools, Assembly3 is not compatible with A2plus nor Assembly4. Models created with these workbenches should be opened only with their respective workbench.

top

Testing
The Assembly3 Workbench is under development and is not yet available (April 2020) through the Addon Manager, but it is expected that this will happen at some point.

You can test it in two ways:
 * A special fork of FreeCAD made by realthunder; see FreeCAD_assembly3 releases. This fork is based on a particular commit of the master branch of FreeCAD, but it also has additional features currently not present in the master branch. Due to this fork being based on a particular development snapshot, it does not have the latest features merged daily to the master branch.
 * The development AppImage; this is based on the current master branch, and includes the dependencies needed for working with Assembly3 such as the SolveSpace solver.

Since the AppImage only works for Linux, for Windows users at the moment the only option to test Assembly3 is the first option (realthunder's fork).

top

Get Started
There are many ways to create an assembly with Assembly3. Here is the most simple one you can do.


 * Assembly3_Example-GettingStarted.jpg
 * Final Result of the Getting Started Example. In the image the Assembly3 Worksbench is selected, so its multiple toolbars are visible. Note that the vertical "TabBar" left of the tree view is an AddOn Workbench that is not contained in standard FreeCAD (but can be installed with the Addon-Manager).


 * Create a new FreeCAD file
 * Select assembly Workbench. Select CreateAssembly (first icon)
 * Select Part Workbench and add a cylinder and a cube
 * Save the file with any filename you like. Close and open and the file.
 * The tree view should look like this


 * Now Draw&Drop with the mouse both Cylinder and Cube onto the Parts folder. They are moved into that folder.
 * That is the quickest way. Please note that a better way is to open the Context menu on both and select ContetxMenu/LinkActions/MakeLink. This adds two link files. Then Drag/Drop the link files to the Parts folder. For simple cases like this it does not really matter.
 * Click both top surfaces of Cylinder and Cube (keep Ctrl pressed)
 * Select assembly Workbench. Select "PlaceCoincident" from the Constraint Toolbar.
 * Now the parts should be joined into each other and your tree should look like this

We omitted one important step that should be done in larger assemblies: locking a base part. That means define one part that should not be moved by constraints. In your case we use the cube for that: Done. If you like you can move the "Locked" constraint upwards in the tree. Use the "MoveItemUp" button on the Main Toolbar for that.
 * Right click "_Element" (any of the two) and select "Flip Part".
 * Now the Cylinder should be on top of the box. If the whole thing is upside down, go back and select "Flip Part" on the other Element.
 * Select the lower face of the cube. Only the lower face, not the whole cube.
 * select the "Lock" constraint from the constraint tool bar
 * The finished assembly tree should look like in the image above

Note: all new external files must be saved, closed and re-opend at least once, so that Assembly3 can find it. Without doing that FreeCAD can not give a file handle to the Assembly3 Workbench and it can not find the new part. When all parts are in the same file, you should save and re-open the file.

top

Add an Offset
Assembly3 does not offer Offset with the constaints in the way the A2plus Workbench or other CAD tools do. Instead it offers a more general and flexible system to add offsets translations but also angles.


 * Add the offset in the properties of one Elements of a Constraint.
 * you can choose which one of the two you want to use.

Example:
 * Add 2 cubes to an assembly and select their side faces.
 * select "PlaneCoincident". The cubes will be attached inside each other.
 * select one Element and ContextMenu/Flip Part. The cubes will be attached side-by-side.
 * select one Element property Offset/Position/Zz and set to 5mm. The cubes will be 5mm apart.
 * Test with other axes or the angle/axis fields. Also verify that you get the same result when using the other Element.

This is the same approach for all other constraints.

top

Solve a Solver Failure
This often happens when parts are over-constraints, i.e. more than 6 DOF are locked.

The easiest way to find the problem is to click relevant constraints in the tree and select ContextMenu/Disable and re-calculate. It is helpful to know the last added constraints before the solver failed and just undo them.

Note: as Assembly3 tries to compensate for over-constraint parts behind the scenes, sometimes the problem is just triggered by a new constraint but the root cause is somewhere different. Before deleting all and starting again, remember that you can re-use Elements. If you named them you can identify the required elements and re-build the constraints without using the 3D view at all. See Elements seciton above.

top

Replace a part or rename a filename
When a part is removed or when a filename changes, the assembly breaks, it can not longer be solved and the solver will issue the message "Inconsistent constraints". The solver marks invalid Elements and Constrains with a question mark in the tree.

One way to solve this is to just delete all invalid constraints and elements, import the new part and redo everything. But there is a better way:


 * Rename a file
 * Use a file manager and copy the file you want renamed. Then give the new name to the copy.
 * Open the copy in FreeCAD. The assembly and the old file should also be open
 * Select the old object in the tree and click to change the propery "Linked object" (it does contain the old filename)
 * A list dialog will open containing all open parts. It shows the filenames and objects of each part. The old part and object is selected. Locate the renamed part in the tree and select the same object in the new part. Then confim the selection.
 * Delete the old part in the tree. Also the file can be deleted now.
 * Constraints and elements of te old part became invalid. Open the constraint or Elements list in the tree. Then sequentially
 * select each element surface on the new part. An item in the tree will be highliged.
 * Take that item and drag&drop it over the old element (either in the element list or in one of the constraints where it was used). That element should become valid.
 * Repeat the procedure for the remaining elements. Often a single element is enough to allow Assembly3 to identify the remaining elements of the part automatically.
 * If an element was assigned to the wrong surface by accident, just repeat with the correct surface.
 * Change the object name in FreeCAD, if desired


 * Replace a part with another part
 * which is simular enough to the original part that the original constraints still make sense, of course
 * Delete the old part in the tree. Also the file can be deleted.
 * Constraints and elements of te old part became invalid. Open the constraint or Elements list in the tree.
 * Select an element surface on the new part. An item in the tree will be highliged.
 * Take that item and drag&drop it over the old element (either in the element list or in one of the constraints where it was used). That element should become valid.
 * repeat the procedure for the remaining elements.
 * If an element was assigned to the wrong surface by accident, just repeat with the correct surface.
 * Change the object name in FreeCAD, if desired

''Notes ''
 * They are not as complicated as it may seem here. After 2-3 times they should become second nature and feel really easy to do.
 * Its not only usually ways quicker than deleting and re-doing constraints, its also safer because an element could have been used in a parent assembly. Deleting the original would destroy that link, re-assingning would keep it.
 * Also this procedure becomes really quick and easy to do if constraints and elements are named. There is no guessing where the surfaces should be dragged&dropped to because the names tell it (see Tips & Tricks).

top

Tips & Tricks

 * Using hierarchical assemblies helps in avoiding solver issues and keeping you model fluid. You can freeze a subassembly with one click and save CPU resources easily (use the context menu in the tree). When loading an assembly Assembly3 does not need to open external files for frozen subassemblies which keeps the tree compact.
 * Is very helpful to make it a habit to name the elements and constraints. Use the key to do this quickly in the tree. You will find the tree sorting tools in the main toolbar very useful. An assembly with fully named constraints and elements is very easy to understand for other people or for oneself when looking at an older file.
 * Examples for constraint names for a table could be "Align_FrontLegs", "Align_FrameBottom-LegTops" and element names could be "Leg1_Top" or "TableTop_Front", "TableTop_Left".
 * Please note that once external files are opened by an assembly its not possible easy to close them again without closing the assembly. Since the assembly keeps open those files in the backgound, the tab may disappear but the file remains visible in the tree. If you have several layers of subassemblies it becomes close to impossible to close single files. This behaviour may change, but until then a possible approach could be to regulary use the commands File/Save All and File/Close All to clean up the tree before working on another sub-assembly.
 * ''Example: consider you have a large CNC machine with a main assembly and a subassembly for each module. Once you have the main assembly open it may open literally hundreds of files down to a single ball bearing. Before working on the subassembly of the electronics cabinet of the machine it is a good idea to save and close all files to get an empty tree. Then open just the subassembly for the electronics cabinet. This will open all file it needs but ony those.
 * Using external files makes it easier to re-use a parts or do part versioning with systems like git or subversion. The workflow in FreeCAD with Assembly feels quite the same as with files that have all parts in the same file. For exchanging files often with other parties, single files might be more convenient.
 * Multiply linked parts. If you added a link into the assembly, it will have a property value named "Element Count", default 0. If you set this to 3 you get 3 instances of that part. They will be added into a subfolder and can be used like fully separte parts. Use this feature to keep the data footprint of your file low, because the part is saved only once. Each instance only contain the differences.
 * Insert multiple parts, e.g. Screws, with one click. Check out the Assembly3 Wiki on the Github site. This is not only a stunning function (even a bit magic), but really really useful.


 * Using the TabBar Workbench speeds up working with assembly. This adds a Toolbar with one button for each workbench. You can sort the toolbar and can put it where every you want it. Many people put it vertically on the left side just beside the tree view. Of you have Assembly3, Part, PartDesign and other often used workbenches close to the top switching between them becomes extremely easy.

top

Links

 * App Link object that makes Assembly3 work.
 * FreeCAD_assembly3 repository and documentation.
 * Assembly3 preview, big discussion thread.
 * Test tutorial for Assembly 3 WB by jpg87.
 * Current Assembly Status
 * External workbenches
 * Old Assembly project development plan, to get acquainted with the history of the issue.